qt: QtWebSocketBackend drops contextKey on a blocking private registration, disagreeing with its own async path

[Yaraslaut]

Found while fixing #587 in morph::net. Not folded into that PR: it lives in include/morph/qt/qt_websocket_backend.hpp / src/qt/qt_websocket_backend.cpp, which the open PR #585 holds, and it is a different backend.

The finding

QtWebSocketBackend disagrees with itself about whether a private registration carries contextKey:

• QtWebSocketBackend::sendRegisterAsync — src/qt/qt_websocket_backend.cpp:196 — carries it:

  auto env = ::morph::wire::makeRegister(typeId, std::string{contextKey});

• QtWebSocketBackend does not override registerModelWithContext at all. grep -n "registerModel" include/morph/qt/qt_websocket_backend.hpp lists registerModel, registerModelAsync, registerModelShared and registerModelSharedAsync — no registerModelWithContext. So it inherits IBackend's default (include/morph/core/backend.hpp:162), which does (void)contextKey;.

Which of the two runs is decided by QtWebSocketBackendConfig::asyncRegistrationEnabled, and that defaults to false. Bridge::registerHandlerImpl (include/morph/core/bridge.hpp:1799) tries registerModelAsync first; QtWebSocketBackend::registerModelAsync returns false immediately when the flag is off (src/qt/qt_websocket_backend.cpp:161), so Bridge takes the fallback at bridge.hpp:1853:

if (!started) {
    binding->currentId.store(
        backend->registerModelWithContext(binding->typeId, binding->modelFactory, binding->contextKey).v);

…which is the dropping default.

Two further sites reach the same default:

• Bridge::switchBackend's re-registration, bridge.hpp:1308, calls registerModelWithContext directly — so a reconnect/backend swap drops the key even for an embedder that enabled the async flag.
• IBackend::bindModel's default dispatches the empty-primary shape to registerModelWithContext (backend.hpp, BindRequest's table), and QtWebSocketBackend does not override bindModel.

Why it matters

Same mechanism as #587. RemoteServer::attachLogIfConfigured (include/morph/core/remote.hpp:704) returns before consulting the LogProvider when the envelope's contextKey is empty:

void attachLogIfConfigured(::morph::model::detail::IModelHolder& holder, const ::morph::wire::Envelope& env) {
    if (env.contextKey.empty()) {
        return;
    }

So this is not "an audit entry missing its entity key". No log is attached, and a privately-registered instance produces no audit record at all. It fails open.

Two consequences worth stating separately:

1. The default configuration of the Qt WebSocket transport does not journal private registrations, while SimulatedRemoteBackend (remote.hpp:1849) and — as of net: SocketBackend::bindModel drops contextKey on a private registration, unlike SimulatedRemoteBackend #587 — morph::net::SocketBackend both do. Backends documented as interchangeable disagree.
2. asyncRegistrationEnabled silently changes audit behaviour. Its doc comment (qt_websocket_backend.hpp:42) is entirely about blocking versus not blocking the Qt event loop; nothing says that flipping it is also what decides whether the instance is journalled. An embedder who turns it on for WASM gets journaling as a side effect, and one who leaves it off does not.

backend.hpp:155's own doc comment on the default already states the rule this violates:

"Backends whose model instances live behind a wire protocol (SimulatedRemoteBackend) override this to carry @p contextKey across — see wire::Envelope::contextKey and RemoteServer::setLogProvider."

QtWebSocketBackend is a wire-protocol backend that does not.

Verification status

Inferred from reading the code. Not reproduced. Stated plainly because the distinction matters here: #587's triage was in the same position for morph::net, and when I actually stood the transport up the defect was real and worse than the reading suggested — but that is evidence about morph::net, not about this.

• What I did: read the four call sites above on 992b190c plus my net: SocketBackend::bindModel drops contextKey on a private registration, unlike SimulatedRemoteBackend #587 branch, and confirmed by grep that no registerModelWithContext or bindModel override exists in include/morph/qt/qt_websocket_backend.hpp.

• What I did not do: build the Qt transport (MORPH_BUILD_QT=ON) or run anything against a QtWebSocketServer. Every claim about runtime behaviour here is a reading of the dispatch chain, not a measurement.

• Corroboration that is already in the tree, and is not my inference: docs/spec/core/backend.md:1215 documents the drop as current behaviour —

  "registerModelWithContext is not overridden — the default drops the contextKey, so this transport does not carry a context key to the server's LogProvider."

  and tests/test_action_log_phase2.cpp:347 is a passing test pinning the server-side half (makeRegister("P2_Model") with no key ⇒ REQUIRE_FALSE(providerCalled)), which is byte-for-byte the envelope the blocking path sends.

• Not measured: whether any shipped rung or example registers privately over QtWebSocketBackend with a non-empty contextKey today. If none does, this is latent rather than active — which changes priority, not validity.

What would close it

The Qt analogue of the test #587's PR added for morph::net (tests/net/test_socket_backend.cpp, "a private registration carries contextKey to the server's log provider"): stand up a QtWebSocketServer over a RemoteServer with a LogProvider installed, register privately through QtWebSocketBackend with a non-empty contextKey, and assert the provider was consulted with that key — with asyncRegistrationEnabled left at its false default, since that is the path in question.

Per AGENTS.md's "would this still pass if the feature did nothing": assert on providerCalled/entityKey, not on the registration succeeding. It succeeds today. That is exactly the assertion that failed for morph::net ({ } == { "SbEchoModel:acct-587" }) while registration itself passed.

The fix is then the same two lines #587 took: override registerModelWithContext to build makeRegister(typeId, std::string{contextKey}), and have registerModel forward to it with an empty key.

What would change the verdict

• Close this if the Qt transport is deliberately excluded from journaling private registrations — but then the disagreement with SimulatedRemoteBackend and SocketBackend is the bug instead, backend.hpp:155 needs rewriting, and asyncRegistrationEnabled still must not be what decides it.
• Close this if a reproduction attempt shows the key does arrive — in which case my reading of the Bridge fallback chain is wrong and I would want to know where.

Sequencing

Touches files held by the open, blocked PR #585 (qt_websocket_backend.hpp / .cpp) and would need the same docs/spec/core/backend.md edit #587's PR is already waiting on. Should be sequenced after #585 clears.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GS5K2vqZtC4xbRiGJHT7jH

[Yaraslaut]

Triage: valid — the internal disagreement is confirmed, and so is the "default configuration" claim

Verified by reading on current master be64026a. Like the report, I did not build the Qt transport or reproduce this end to end — see the verification status below for exactly where the line falls.

The two paths disagree, as reported

Async path carries the key — src/qt/qt_websocket_backend.cpp:196:

auto env = ::morph::wire::makeRegister(typeId, std::string{contextKey});

Blocking path drops it. QtWebSocketBackend has no override of registerModelWithContext — the only occurrences in the Qt sources are two calls to it (qt_websocket_backend.cpp:335, :350) and one doc-comment mention (qt_websocket_backend.hpp:204). With no override it inherits IBackend's default at core/backend.hpp:162, which does (void)contextKey;.

So one backend contradicts itself depending on which registration path runs. That is a sharper finding than #587's was: #587 was SocketBackend disagreeing with SimulatedRemoteBackend, across two classes. This is one class disagreeing with itself.

The severity claim holds — I checked the part that carries it

The report's real weight is the assertion that this is the default, not an edge case. Both halves check out:

include/morph/qt/qt_websocket_backend.hpp:57:    bool asyncRegistrationEnabled = false;

and the fallback that then runs, include/morph/core/bridge.hpp:1853:

if (!started) {
    binding->currentId.store(
        backend->registerModelWithContext(binding->typeId, binding->modelFactory, binding->contextKey).v);

registerModelAsync is gated on that flag, so with the shipped default started is false, the fallback takes the inherited dropping default, and the out-of-the-box Qt transport does not journal private registrations. A flag whose documentation is entirely about blocking versus non-blocking behaviour silently decides whether an audit record exists. That is worth the bug label it carries.

The consequence is the stronger one established by #595's reproduction rather than the weaker one in this issue's framing: RemoteServer::attachLogIfConfigured (core/remote.hpp:704) returns early on an empty contextKey, so the provider is never consulted and no log attaches at all — it is not a log with a missing key. #595 measured that over a real transport (REQUIRE(entries.size() == 1) → 0 == 1), so the server half is no longer inference.

The fix is already written, next door

#595 (merged as f1000e2f) solved the identical problem for SocketBackend: override registerModelWithContext and carry the key. Mirror it. backend.hpp:155 already states the rule — "Backends whose model instances live behind a wire protocol override this to carry @p contextKey across" — and QtWebSocketBackend is a wire-protocol backend that does not.

#595 also found the surface was wider than its ticket's title: registerModelShared and attachModel degrade to registerModelWithContext when primary is empty, so they drop the key too and one override fixes all of them. Check whether the same is true here (:335 and :350 look like exactly that shape) rather than fixing only the path the title names.

The report's second claim — that switchBackend's re-registration at bridge.hpp:1308 drops the key even for an embedder who enabled the flag — I have not verified. It is a separate call site in a file this fix would not otherwise touch; treat it as unconfirmed until someone reads or exercises it.

Sequencing — this is blocked, and not on anything technical

include/morph/qt/qt_websocket_backend.hpp and src/qt/qt_websocket_backend.cpp are held by PR #585, which is itself blocked on #593, a design decision at the #567/#571 level with no timetable.

I am recording that rather than dispatching against it. If #593 stays undecided for long, this should be revisited — an unjournaled default configuration waiting on an unrelated architectural decision is a bad trade, and the fix here is small and independent of #593's outcome. Reopening that question is a scheduling call, not a technical one.

Verification status

• Verified by reading, on be64026a: both code paths, the absence of an override, the asyncRegistrationEnabled = false default, and the bridge.hpp:1853 fallback. Quoted above.
• Not reproduced: I did not build the Qt transport, stand up a QtWebSocketServer with a LogProvider, or observe a missing journal entry. The report says the same of itself, and states it plainly — which is why I weight it.
• Corroboration that already exists in the tree, as the report notes: docs/spec/core/backend.md:1215 records that QtWebSocketBackend does not override the verb, and tests/test_action_log_phase2.cpp:347 pins the server-side half.

What would close it

A test that registers privately through QtWebSocketBackend with asyncRegistrationEnabled at its default against a server with a log provider, asserting the provider was consulted with the key. Per AGENTS.md, assert on providerCalled/entityKey — not on registration succeeding, which it does today either way.

What would change the verdict

Close this if the Qt transport deliberately excludes blocking private registrations from journaling — but then its own async path is the bug, the two must still agree, and backend.hpp:155 needs rewriting.

[Yaraslaut]

Fixed in #585 (commit 49bd5b8b), batched with #593 because both live in files that PR already holds.

Two things this issue asked to be checked, checked

1. "Inferred from reading the code. Not reproduced." — now reproduced. The reading was right, including which sections would fail. tests/qt/test_qt_websocket.cpp now stands up a QtWebSocketServer over a RemoteServer with a LogProvider installed, exactly as the "what would close it" section specifies. Before the fix:

tests/qt/test_qt_websocket.cpp:2504: FAILED:
  CHECK( requestedFor == std::vector<std::string>{"WsEchoModel:acct-594"} )
with expansion:
  {  } == { "WsEchoModel:acct-594" }

tests/qt/test_qt_websocket.cpp:2523: FAILED:
  CHECK( requestedFor == std::vector<std::string>{"WsEchoModel:acct-bind"} )
with expansion:
  {  } == { "WsEchoModel:acct-bind" }

test cases:  1 |  0 passed | 1 failed
assertions: 15 | 13 passed | 2 failed

Byte-for-byte the shape #587 produced for morph::net ({ } == { "SbEchoModel:acct-587" }), and the assertion is on the provider rather than on the registration, as this issue insisted: 13 of the 15 assertions passed, because registration itself worked before the fix too.

2. "If your #593 fix changes the dispatch chain such that #594's mechanism no longer applies, say so." — it does not. Measured rather than reasoned: the reproduction above was run on a tree that already had #593's fix applied. #593 changes whether registerHandlerImpl waits for the bindModel completion; it does not change which verb the blocking bindModel routes an empty-primary/zero-current request to, which is still registerModelWithContext. The mechanism was untouched.

The fix

The two lines this issue specified: override registerModelWithContext to build makeRegister(typeId, std::string{contextKey}), and have registerModel forward to it with an empty key. A third section pins the other direction — plain registerModel still sends no key, so the provider is not consulted, and tests/test_action_log_phase2.cpp's server-side pin stays true.

docs/spec/core/backend.md:1489-1491, which documented the drop as current behaviour, is replaced with a description of the override and of the three call sites that reached the dropping default (blocking bindModel's private branch, Bridge::switchBackend's re-registration, and registerModelShared/attachModel's empty-primary degradation).

Not verified

• "Whether any shipped rung or example registers privately over QtWebSocketBackend with a non-empty contextKey today" — still not audited, so whether this was latent or active in shipped code remains unknown. It is now correct either way.
• No sanitizer or Valgrind run locally; the full suite is green at 100% tests passed out of 1836 on a GCC 16.2.1 Debug build with MORPH_BUILD_QT=ON MORPH_BUILD_NET=ON.
• The switchBackend/reconnect re-registration path now carries the key, but it still calls the blocking verb unconditionally, which for an asyncRegistrationEnabled backend is the nested-QEventLoop block qt: move QtWebSocketBackend onto the structural registration surface and delete the WASM special case #568 exists to remove. That is a separate defect and is filed as core: Bridge::switchBackend and installReconnectHandler still call the blocking registration verbs, so a backend that says kCallerMustNotBlock is blocked there anyway #615, not fixed here.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AbwhcguQFkhvVi2AH19sWk