core: Bridge::switchBackend and installReconnectHandler still call the blocking registration verbs, so a backend that says kCallerMustNotBlock is blocked there anyway

[Yaraslaut]

Found while fixing #593. Not folded into that PR (#585): #593 is about the one call site that acquires a model for a new handler; this is about the two that re-acquire one for handlers that already exist, and they are a different change.

The finding

Bridge has four places that register a model on a backend. After #585 and #593, two of them go through the structural surface and honour IBackend::bindWaitPolicy(); the other two still call the blocking legacy verbs directly, with no policy check and no structural path at all:

• Bridge::switchBackend, phase 1 (include/morph/core/bridge.hpp, the staging loop):

  auto newId = binding->shared
                   ? newShared->registerModelShared(
                         binding->typeId, binding->modelFactory,
                         {.contextKey = binding->contextKey, .primary = binding->primary})
                   : newShared->registerModelWithContext(binding->typeId, binding->modelFactory,
                                                         binding->contextKey);

• Bridge::installReconnectHandler's reconnect callback, which runs the same two verbs on the backend's transport thread.

Both run under std::scoped_lock const lock{_mtx, _attachMtx}.

For a QtWebSocketBackend with Config::asyncRegistrationEnabled set — the WASM configuration — those verbs are sendSync, which pumps a nested QEventLoop on the Qt thread. That is precisely the block #568 exists to remove, and #593 has just given the interface a way to say "do not do this to me" that these two sites do not consult. So a WASM client that never blocks on its first registration can still block on a reconnect or a backend swap.

docs/spec/concurrency_and_lifetimes.md already names the reconnect half as an open hazard, from the lifetime angle rather than the WASM one:

installReconnectHandler's reconnect callback. Left as a liveness() check […] The handler runs on the backend's transport thread and calls registerModelWithContext/registerModelShared, which blocks on a nested QEventLoop for QtWebSocketBackend. […] No safe mechanical fix is known for this site; it remains open, tracked as the residual scope of issue #489.

A second, smaller finding inside the first

The two sources disagree about who owns the reconnect half. docs/spec/core/backend.md's migration table assigns it to #570:

| morph#570 | The example GUIs and the WASM spike; Bridge::installReconnectHandler onto bindModel. | Open |

…but #570's own body scopes itself to examples/ only, listing eleven example files and three docs, and never mentions bridge.hpp. Whichever is right, one of them is wrong, and the work is currently owned by nobody in writing. switchBackend is named by neither.

Why it matters beyond WASM

switchBackend is documented as atomic — phase 1 stages every re-registration and rolls back on a throw. Moving it to bindModel is not a one-line substitution, because the structural surface reports failure through a Completion rather than a throw and the rollback is built on the throw. That is the substance of this ticket, and it is why it should not be done inside a PR about something else.

Verification status

Inferred from reading the code on 48195d0e (#585's branch with #593's fix). Not reproduced. Stated plainly because the distinction is load-bearing here:

• What I did: read both call sites and confirmed by grep that neither names bindModel, promoteModel or bindWaitPolicy; confirmed QtWebSocketBackend::registerModelWithContext/registerModelShared both reach sendSync and that sendSync parks a nested QEventLoop; confirmed the spec/issue mismatch above by reading both.
• What I did not do: build or run a WASM client, force a reconnect against a QtWebSocketBackend with asyncRegistrationEnabled set, or observe a deadlock. Every claim about runtime behaviour here is a reading of the dispatch chain.
• Not measured: whether any shipped example currently sets asyncRegistrationEnabled and relies on reconnect or switchBackend. If none does, this is latent rather than active — which changes priority, not validity.
• The full suite (1836 cases, MORPH_BUILD_QT=ON MORPH_BUILD_NET=ON, GCC 16.2.1 Debug) is green on that revision, so nothing in the tree exercises this today.

What would close it

Both sites reaching bindModel/promoteModel, with switchBackend's atomicity preserved — its rollback must key on a rejected Completion rather than on a thrown exception — and a test that a reconnect on a kCallerMustNotBlock backend does not park the calling thread. Per AGENTS.md's "would this still pass if the feature did nothing": that test must fail, by hanging, if the call is put back on the blocking verb, which is how #585 proved the equivalent claim for the first-registration path (examples/common/testkit/test_wasm_registration_path_native.cpp).

Also: decide whether the reconnect half is #570's or this ticket's, and make docs/spec/core/backend.md and #570 agree.

What would change the verdict

• Close this if Bridge is deliberately allowed to block on a re-registration that it may not block on for a first registration — but then docs/spec/core/backend.md's migration row for ladder: move the example GUIs and the WASM spike onto the structural registration surface #570 needs deleting, and the reason wants writing down, because the two paths currently differ for no stated reason.
• Close this if a reproduction shows a reconnect on an asyncRegistrationEnabled backend does not park the Qt thread, in which case my reading of sendSync is wrong and I would want to know where.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AbwhcguQFkhvVi2AH19sWk

[Yaraslaut]

Triage: valid, with a scope correction

The structural claim is confirmed, and it is the part that matters — the runtime claim is correctly labelled as unreproduced and I did not reproduce it either.

Verified on 49bd5b8b (#585's head) by enumerating every call in bridge.hpp to a blocking registration verb, a structural verb, or the new policy, with the enclosing function:

  796  BLOCKING VERB   | in: void ensureBound(...)                    <-- NOT named by this issue
 1394  BLOCKING VERB   | in: void switchBackend(...)
 1397  BLOCKING VERB   | in: void switchBackend(...)
 2005  bindModel       | in: registerHandlerImpl's bind path
 2006  bindWaitPolicy  | in: registerHandlerImpl's bind path          <-- the ONLY consultation
 2096  BLOCKING VERB   | in: void installReconnectHandler(...)
 2101  BLOCKING VERB   | in: installReconnectHandler's reconnect cb
 2104  BLOCKING VERB   | in: installReconnectHandler's reconnect cb

So: bindWaitPolicy() is consulted at exactly one site, and both sites this issue names do reach the blocking verbs without consulting it. Confirmed.

Correction — there is a third site, not two

Bridge::ensureBound (bridge.hpp:790-799 on that branch) is a third non-structural registration, and this issue's "four places… the other two" arithmetic misses it:

/// @brief Gives @p binding an anonymous instance if it does not have one yet.
void ensureBound(const std::shared_ptr<detail::HandlerBinding>& binding) {
    std::scoped_lock const lock{_attachMtx};
    if (binding->currentId.load() != 0U) {
        return;
    }
    auto newId = loadBackend()->registerModelShared(binding->typeId, binding->modelFactory,
                                                    {.contextKey = binding->contextKey, .primary = {}});
    binding->currentId.store(newId.v);
}

Same verb, same missing policy check, same lock discipline. It differs from the two named sites in its trigger — it is a first acquisition, for a result-keyed action that must run somewhere before its key is known, rather than a re-acquisition — but not in its consequence: on a kCallerMustNotBlock backend it parks the calling thread in sendSync's nested QEventLoop exactly as the other two would.

This belongs in this ticket, not a new one. AGENTS.md's rule is to merge only on a shared fix site, and this is the same file, the same verb, the same substitution and the same test. Folding it in here is consolidation on a fix site; filing it separately would produce a second ticket nobody could land independently of this one.

It does not change the ticket's difficulty: ensureBound has no rollback to preserve, so it is the easiest of the three, and switchBackend's throw-keyed atomicity remains the substance.

Why valid despite "not reproduced"

The unverified half is the runtime deadlock, and triage: unverified is for a premise blocked on an experiment. This one is not:

• The structural gap is a code fact, now independently confirmed above.
• The mechanism is corroborated in-tree, by the repository's own spec, not by the filer's reading. docs/spec/concurrency_and_lifetimes.md already documents the reconnect half as an open hazard, naming the same nested QEventLoop and tracking it as residual scope of bridge: installReconnectHandler's liveness-check-then-touch-this window (morph#486's shape), with no safe mechanical fix #489.

So the experiment would raise confidence in a consequence the spec already asserts. It is worth doing — as the closing test, which is where this issue already puts it — but nothing is blocked on it.

The close condition is well-formed and I would not change it, including its AGENTS.md check: the test must hang if the call is put back on the blocking verb. That is the right shape, and #585 has already demonstrated the equivalent proof for the first-registration path.

Sequencing

Blocked on PR #585 landing — this ticket edits bridge.hpp around code that only exists on that branch. Do not dispatch it until #585 is merged.

The bookkeeping question it raises is real and cheap: docs/spec/core/backend.md's migration table assigns the reconnect half to #570, while #570's body scopes itself to examples/ and never mentions bridge.hpp. Resolve it in favour of this ticket — #570 is a consumer-migration ticket for the ladder, switchBackend and ensureBound are named by neither, and splitting three sites in one file across two tickets would leave whichever lands second rebasing on the other. Update the migration row when this lands.

What I did not verify

• No WASM client, no forced reconnect, no observed deadlock — same gap as the filer's.
• I did not check whether any shipped example sets asyncRegistrationEnabled and relies on reconnect or switchBackend, so latent-vs-active is still open and still a priority question rather than a validity one.
• I enumerated call sites in bridge.hpp only. If another header registers a model directly, this scan would not have seen it.

Labels: triage: valid, plus the bug / area: core / area: qt already applied.

[Yaraslaut]

Dependency recorded: #615 depends on #588

Runner note, from deciding #588's ownership.

This ticket moves switchBackend, installReconnectHandler and ensureBound off the blocking registration verbs onto bindModel/promoteModel. The moment it does, each of those three sites must name an executor to deliver its Completion on — and Bridge currently has no executor bound to its own thread to name. Its four existing structural dispatch sites all pass ::morph::exec::detail::inlineExecutor(), which is "deliver wherever you settled" expressed as a value.

So doing this ticket before #588 would add three more inlineExecutor() sites to the four that already exist, making #588 strictly larger and this ticket's own threading story no better than the one it replaces.

Order: PR #585 lands → #588 → this.

Nothing about this ticket's scope changes, including the third call site (ensureBound) recorded in the triage comment above.

[Yaraslaut]

Implemented in PR #639 (laneCORE-batch-615-619-620), together with #619 and #620, one commit each.

Both premises re-measured and held. Both sites now go through bindModel and consult bindWaitPolicy(); the rollback keys on a rejected Completion; and the ownership disagreement this ticket reports as its second finding is settled in docs/spec/core/backend.md — the migration table now carries a morph#615 row and morph#570 keeps only the examples/ scope its own body claims.

One decision worth naming here rather than only in the PR, because it contradicts what the spec used to promise: switchBackend is no longer unconditionally atomic. It is atomic exactly when the new backend answers kCallerMayBlock. For kCallerMustNotBlock it cannot be — "did every re-registration succeed" is not knowable without waiting, and waiting on such a backend is the deadlock the policy exists to prevent. Those binds are deferred (swap happens, currentId cleared, registrationInFlight set so whenBound() gates the window, reply binds it), a post-swap failure rejects that binding's waiters rather than rolling back, and an instance a deferred bind creates on a backend whose switch later threw is not deregistered. All three are written into the header and into bridge.md rather than left to be discovered.

One thing this lane could not do. The branch's insertions shift scripts/mutation_survivors.json's citation of include/morph/core/backend.hpp:1322 to 1412, and scripts/check_mutation_survivors.py fails on it:

scripts/mutation_survivors.json: 1 citation(s) no longer match the code they name.

  - include/morph/core/backend.hpp:1322 has moved to line 1412. The text still matches, so nothing is wrong with the disposition -- update the `line` hint.

That file is held by PR #635, so PR #639 does not touch it and its "Mutation gates" leg will be red until whichever of the two merges second applies the one-line hint change. The equivalent hints in scripts/branch_partial_allowlist.json, which nobody holds, are repointed in their own commit on the branch.