core: #567's registration surface gives Bridge no way to tell a natively non-blocking backend from a blocking one, and two shipped backends now need opposite behaviour at that one call site

[Yaraslaut]

Bridge::registerHandlerImpl has exactly one call site for acquiring a model, and after morph#569 (#586) and morph#568 (#585) two shipped backends need opposite behaviour from it. #567's surface deliberately removed the only signal that could tell them apart, so the call site cannot satisfy both.

This was predicted as "Gap 1" in #585's PR body while the wall was still hypothetical. It is no longer hypothetical: it is now reproducible against a production backend, and it blocks #585.

The two requirements

Backend	What bindModel does	What registerHandlerImpl must do	Why
morph::net::SocketBackend (native since #586)	returns an unsettled Completion; the I/O thread settles it later	must block until it settles	its callers construct a BridgeHandler and use it on the next line; executeVia fails fast on currentId == 0
QtWebSocketBackend, asyncRegistrationEnabled = true	returns an unsettled Completion	must not block	blocking here is the nested-QEventLoop deadlock that aborts the WASM page — the whole point of #568

From Bridge's side the two are indistinguishable: both are an override of bindModel that returns unsettled. include/morph/core/backend.hpp:487-493 rules out the discriminator by design:

1. The continuation is not opt-in. There is no bool saying "I have no async path, call the other one" — so no call site carries a second path, and a backend cannot be half migrated.

That bool was registerModelAsync's return value, and it was exactly this signal. #568 deletes the overrides that produced it.

Verification status

Reproduced, locally and in CI, on a08db4f9 (#585's head, rebased onto master 70792bee). GCC 16.2.1, Debug, -DMORPH_BUILD_QT=ON -DMORPH_BUILD_NET=ON. The mutation experiment below was run locally; I did not run it under a sanitizer, and I did not retrieve the CI logs for the clang-tsan and Valgrind memcheck legs (the run was still in progress), so my attribution of those two to this same cause is inferred from the leg configuration, not measured.

Reproduction, as shipped

tests/net/test_socket_backend.cpp — 5 consecutive local runs, all failing identically:

2/2 Test #1631: SocketBackend: action result delivered via then ...***Failed    2.03 sec
  REQUIRE( result.load() == 99 )
with expansion:
  -1 == 99

Six tests fail, all SocketBackend, none of which this branch's diff touches:

96% tests passed, 6 tests failed out of 142

	1631 - SocketBackend: action result delivered via then (Failed)
	1647 - SocketBackend: executeTimeout surfaces as backend::TimeoutError, not a generic runtime_error (Failed)
	1652 - SocketBackend: many concurrent in-flight executes all resolve, matched by callId (Failed)
	1660 - SocketBackend: server dropping mid-call resolves the pending completion with DisconnectedError (Failed)
	1663 - SocketBackend: two backends share one server with isolated model state (Failed)
	1804 - SocketBackend interop: connects to a QtWebSocketServer and completes an action (Failed)

On master the same leg is green and the same test takes 0.03 s, versus a 2.02 s spin here — it is not timing jitter, the completion never arrives at all.

Mechanism

registerHandlerImpl probes registerModelAsync first; with #568's overrides deleted it returns false, so control reaches the bindModel fallback. SocketBackend::bindModel is non-blocking, so registerHandlerImpl returns with binding->currentId == 0. The next line's execute then hits bridge.hpp:1463:

if (raw == 0U) {
    typedState->setException(std::make_exception_ptr(std::runtime_error("handler not bound")));
    return typed;
}

The test's .onError([](const std::exception_ptr&) {}) swallows that, result stays at its -1 initialiser, and spinUntil burns its full 200 × 10 ms budget. Nothing hangs; the registration simply had not completed.

Mutation experiment — both horns measured

Forcing the default blocking bindModel at that one call site, bypassing the virtual:

auto completion = backend->::morph::backend::detail::IBackend::bindModel(...);

flips which suite breaks, and breaks the one #568 exists to fix:

	1566 - morph::qt::QtWebSocketBackend: (serverUrl, tls, cfg) constructor overload omits the dispatcher/registry pair (issue #55) (Failed)
	1567 - morph::qt::QtWebSocketBackend: Config-only constructor overload omits the dispatcher/registry pair (issue #55) (Failed)
	1571 - morph::qt::QtWebSocketBackend: bindModel (non-blocking via Config::asyncRegistrationEnabled) registers without blocking (Failed)
	1572 - morph::qt::QtWebSocketBackend: bindModel called before the socket connects queues and retries once connected fires (Failed)
	1577 - morph::qt::QtWebSocketBackend: bindModel's pending registration is cancelled when the connection drops before a reply arrives (Failed)

All six SocketBackend failures clear under that mutation, and five QtWebSocketBackend ones appear. Neither setting of the one call site is correct, which is the finding: this is not a bug in either backend, it is a missing distinction in the surface between them.

Why it is not fixable inside #568

• Reintroduce a capability signal on IBackend — contradicts backend.hpp:487-493, quoted above. That is a core: give IBackend a registration surface whose threading contract is structural, not prose #567-level spec decision, not a step-2 one.
• Make executeVia queue until bound instead of failing fast — changes a documented, separately-tested contract (currentId == 0 → "handler not bound"), and is core: remove IBackend's four async twins and retire the prose threading contract #571's scope.
• Drop qt: move QtWebSocketBackend onto the structural registration surface #585's registerHandlerImpl change — reinstates the nested-QEventLoop block for the WASM path, which examples/common/testkit/test_wasm_registration_path_native.cpp proves hangs rather than fails.

Blast radius beyond the tests

This is not test-only. Any SocketBackend consumer that constructs a BridgeHandler and uses it without gating on whenBound() silently starts getting "handler not bound". The GUI presenters already gate (trackBound(_handler.whenBound())); tests/net/ and any downstream code written against the synchronous contract do not. #585's own body argues this exact property is why Config::asyncRegistrationEnabled must be kept for Qt — "a BridgeHandler would stop being usable on the line after its constructor". SocketBackend has no equivalent flag, so #586 gave it no way to opt out.

What would change the verdict

• A decision on core: give IBackend a registration surface whose threading contract is structural, not prose #567/core: remove IBackend's four async twins and retire the prose threading contract #571 that either restores a caller-visible "registers asynchronously" signal, or migrates executeVia to queue-until-bound and accepts async registration everywhere. Either closes this.
• Evidence that SocketBackend's synchronous registration contract was never load-bearing outside tests/net/ would reduce this to "update six tests", and would reopen the option of simply accepting the behaviour change in qt: move QtWebSocketBackend onto the structural registration surface #585. I did not audit downstream consumers, so I cannot rule that in or out.

[Yaraslaut]

Triage: valid — premise verified independently, and the escape hatch the surface names does not apply

Assessed against master 70792bee and a08db4f9 (#585's head).

What I re-checked rather than took on trust

The backend.hpp quote is exact. Lines 487–493 read as quoted, and the surrounding text matters: the "no bool" rule is stated as one of two differences that "carry the whole change", so removing the discriminator was deliberate, not an oversight. This issue is therefore not reporting a missing feature — it is reporting that a deliberate removal has met a case it did not anticipate.

The regression is not timing jitter. I pulled the same leg from master's own run (35463707574, head 70792bee, finished 26/26 green) and compared against #585's:

master,  Linux / clang-ubsan:  Test #1669 ... Passed  0.03 sec   (100% of 1751 passed)
#585,    Linux / clang-ubsan:  Test #1669 ... Failed  2.02 sec   (full 200 x 10ms spinUntil budget)

Same test, same leg, same runner image. 0.03 s against a 2 s timeout is not a slow machine.

CI counts, counted rather than relayed: 30 pass, 5 fail, 4 pending, the five being clang-asan, clang-coverage, clang-tsan, clang-ubsan, Valgrind memcheck — every instrumented leg, and only those.

The escape hatch named two lines below the quote does not solve this

backend.hpp:493 says a blocking backend can satisfy the surface "without blocking the caller at all through SynchronousBackendAdapter", which reads like the intended answer. It is not, and the issue is right not to reach for it. SynchronousBackendAdapter (backend.hpp:827) wraps a blocking backend and runs its blocking control calls on a separate executor — blocking → non-blocking. What registerHandlerImpl needs for SocketBackend is the reverse: a natively non-blocking bindModel made to look settled to a caller that uses the handler on the next line. No adapter in the surface does that.

Worth recording because it is the first thing a reader will propose.

Blast radius — the question #585's lane could not rule in or out

It explicitly said it had not audited downstream consumers. I did:

$ grep -rnE '(^|[^A-Za-z])SocketBackend' examples src include tests \
    | grep -v QtWebSocketBackend | grep -v '^tests/net/' | grep -v '^include/morph/net/socket_backend.hpp'

Every remaining hit is a doc comment, except one real consumer: tests/net_qt_interop/test_net_qt_interop.cpp. So morph::net::SocketBackend has no non-test consumer anywhere in this repository — no example, no src/, no rung.

That is already reflected in the failure list (test 1804 is the interop one), so the six failures span two test trees, not one.

But that does not make it "just update six tests"

Two reasons to be careful with the cheap option:

1. The tests encode the contract, they are not merely testing it. "Construct a BridgeHandler, use it on the next line" is the documented usage of a blocking backend. No in-repo consumer is not the same as no consumer — morph::net is public API, and this would be a silent behaviour change for anyone outside this tree.
2. net_qt_interop is evidence for the opposite conclusion. Its makeHandlerPumpingQt helper (:68–:92) exists solely because BridgeHandler's constructor registers synchronously and would deadlock against a Qt peer, so it spawns a worker thread and pumps Qt events until construction returns. That is a consumer already paying to work around synchronous registration. It argues the non-blocking direction is right, and that restoring a discriminator so the old blocking path survives is the step backwards.

On the two resolutions the issue offers

It names them without choosing, correctly — this is a public-surface decision. Recording the asymmetry I see, as input rather than as verdict:

• Restore a caller-visible signal re-introduces exactly the bool that backend.hpp:487 removed on purpose, and re-creates the "a backend can be half migrated" state the surface exists to forbid.
• Queue-until-bound in executeVia removes the raw == 0U fail-fast at bridge.hpp:1463. That check is arguably a leftover from the synchronous world: once registration is universally asynchronous, there is no moment at which "bound" is synchronously guaranteed, so failing fast on "not bound yet" is failing on the normal case rather than an error.

The second looks like the direction the rest of #567 is already committed to, which would put it in #571's scope. That is a judgement about design intent, not something I measured.

Dependencies

• Blocks qt: move QtWebSocketBackend onto the structural registration surface #585 / qt: move QtWebSocketBackend onto the structural registration surface and delete the WASM special case #568. qt: move QtWebSocketBackend onto the structural registration surface #585 is correctly marked BLOCKED and must not merge; I verified its failing legs myself.
• Related to core: give Bridge an executor bound to its own thread, so the threading guarantee is structural for Bridge-mediated calls too #588 (also rescoped): both are cases where core: give IBackend a registration surface whose threading contract is structural, not prose #567's surface is structural for backends but leaves Bridge, its own caller, without the thing it needs. Different mechanisms, same seam — worth deciding together at the core: give IBackend a registration surface whose threading contract is structural, not prose #567/core: remove IBackend's four async twins and retire the prose threading contract #571 level rather than one at a time.

What would change the verdict

Close this if SocketBackend's synchronous registration is deliberately abandoned and the six tests are updated to await binding — but that decision needs writing down in docs/spec/core/backend.md, because the current text tells a caller the handler is usable on return.

Not verified

• I did not re-run the mutation experiment; I am relying on the lane's report for "forcing the blocking bind breaks five QtWebSocketBackend tests instead". Its other checkable claims all held, which is why I weight it, but that specific one is inferred from its report, not measured by me.
• I did not audit consumers outside this repository, which is the whole population that matters for the public-contract question above.

[Yaraslaut]

Dispatched to a lane, batched with #594 onto PR #585's branch (fix-568-qt-structural-registration).

Recording the runner-side re-measurement, since the issue's figures were taken on a08db4f9 before master moved:

CI run 35467846733 on a08db4f9 fails six jobs — all optional features (clang), all optional features (gcc), clang-asan, clang-tsan, clang-ubsan, clang-coverage — plus Valgrind memcheck. In CI each of the six fails on exactly one test, not six:

tests/net/test_socket_backend.cpp:242: FAILED:
  REQUIRE( result.load() == 99 )
with expansion:
  -1 == 99

The following tests FAILED:
	1663 - SocketBackend: action result delivered via then (Failed)
Errors while running CTest
##[error]Process completed with exit code 8.

That is the same test and the same expansion (-1 == 99) this issue reports, so the mechanism is corroborated by CI and not only locally. The count is not — this issue reports six SocketBackend tests failing locally; CI shows one. I have not resolved which is right and the lane has been told to establish it on a rebased tree rather than assume. I also did not read the Valgrind memcheck log, so this issue's "inferred from the leg configuration, not measured" caveat about clang-tsan and Valgrind still stands for Valgrind; clang-tsan is now measured and fails on the same single test.

The branch's base is materially stale, which is why the lane rebases before measuring anything. Merge-base is 70792bee; origin/master is a020e69c. Since that base, master has changed:

• gates — .github/workflows/ci.yml, cmake/CompileCache.cmake;
• files the branch touches — include/morph/core/backend.hpp, scripts/branch_partial_allowlist.json, docs/spec/core/backend.md;
• the failing test's own file — tests/net/test_socket_backend.cpp, and include/morph/net/socket_backend.hpp.

So both the line number (242) and the ctest index (1663) above may have moved, and the failure may present differently after the rebase. Treat the figures here as evidence that the defect is real, not as coordinates.

This issue is the head of the blocked chain: closing it unblocks #585 → #570 → #571 → #522.

[Yaraslaut]

Fixed in #585 (commit 48195d0e), on the rebased branch. The framing here held up under measurement and is not altered; one number in it is explained rather than corrected, and one of its two proposed resolutions was taken in a narrower form than either option as written.

The framing held

Reproduced on the rebased tree (branch on a020e69c, GCC 16.2.1, Debug, -DMORPH_BUILD_QT=ON -DMORPH_BUILD_NET=ON) — the same six, none of which this branch's diff touches:

99% tests passed, 6 tests failed out of 1833

	1660 - SocketBackend: action result delivered via then (Failed)
	1676 - SocketBackend: executeTimeout surfaces as backend::TimeoutError, not a generic runtime_error (Failed)
	1681 - SocketBackend: many concurrent in-flight executes all resolve, matched by callId (Failed)
	1689 - SocketBackend: server dropping mid-call resolves the pending completion with DisconnectedError (Failed)
	1692 - SocketBackend: two backends share one server with isolated model state (Failed)
	1833 - SocketBackend interop: connects to a QtWebSocketServer and completes an action (Failed)

The "six locally, one in CI" discrepancy is not a difference in behaviour

Every test preset in CMakePresets.json sets stopOnFailure, and ci.yml runs every leg through ctest --preset …, so a leg with six failures stops at the first. The one failing leg on run 35467846733 that does not use a preset, Valgrind memcheck, reported five — and its log ends ERROR SUMMARY: 0 errors from 0 contexts, so it was this same functional regression and not a memcheck finding. Filed the preset behaviour separately as #616.

What was done, and why not either option as stated

This issue's "what would change the verdict" offered two exits: restore a caller-visible "registers asynchronously" signal, or migrate executeVia to queue-until-bound. The fix takes a narrower cut than the first.

IBackend::bindWaitPolicy() does not say "I register asynchronously" — SocketBackend does, and it answers kCallerMayBlock. It says only whether the thread that called bindModel may stop and wait for the continuation it just registered:

• kCallerMayBlock (default): the completion settles without the calling thread's participation, inside the call or on a thread the caller does not own.
• kCallerMustNotBlock: QtWebSocketBackend under asyncRegistrationEnabled (the reply arrives on the calling thread's own Qt event loop) and SynchronousBackendAdapter (it exists to move the blocking off the caller, and would deadlock against its own strand).

registerHandlerImpl then holds its existing inline window open until the completion settles and publishes the outcome through the code that already handled a backend settling inline — rethrow included. That matters against this issue's own objection to backend.hpp:487-493: the removed bool chose which verb to call, so a call site carried two paths and a backend could be half-migrated. This one chooses nothing. One verb, called unconditionally, one continuation.

On the alternative this issue left open

Evidence that SocketBackend's synchronous registration contract was never load-bearing outside tests/net/ would reduce this to "update six tests" […] I did not audit downstream consumers, so I cannot rule that in or out.

Still not audited — and the fix makes the audit unnecessary rather than answering it. registerHandler goes on returning a bound handler for every backend that can honour it, so no consumer has to be found before the branch is safe. That is deliberate: "nobody appears to depend on it" is a weaker warrant for a silent runtime behaviour change in a framework than "we kept the contract".

Both horns, re-measured against the fix

Mutation at the one call site	Result
none	100% tests passed out of 1835
false && … (never wait — the discriminator ripped out)	7 failed: the six above, plus the new kCallerMayBlock case
true ‖ … (always wait)	6 failed: the new kCallerMustNotBlock case, plus five tests/qt/ cases that time out at 120 s

	1596 - morph::qt::QtWebSocketBackend: (serverUrl, tls, cfg) constructor overload ... (Timeout)
	1597 - morph::qt::QtWebSocketBackend: Config-only constructor overload ... (Timeout)
	1601 - morph::qt::QtWebSocketBackend: bindModel (non-blocking via Config::asyncRegistrationEnabled) registers without blocking (Timeout)
	1602 - morph::qt::QtWebSocketBackend: bindModel called before the socket connects queues and retries once connected fires (Timeout)
	1607 - morph::qt::QtWebSocketBackend: bindModel's pending registration is cancelled when the connection drops before a reply arrives (Timeout)

Worth noting against this issue's own mutation experiment, which recorded those five as Failed: forcing the blocking verb makes them fail, forcing the wait makes them hang. Same conclusion, one degree worse.

Two new cases in tests/test_backend_registration_surface.cpp pin both answers at the call site, and each fails under the opposite policy, as the table shows.

Not verified

• No sanitizer, Valgrind or coverage run locally. The 1835/1836-case figures are a GCC Debug build.
• The unbounded wait in awaitHandoff is bounded by contract, not by a timeout: a backend answering kCallerMayBlock that fails to settle its own Completion hangs there. That is deliberate (a timeout would make "is this handler bound on return" depend on network speed) and documented, but it is a contract, not a mechanism, and I did not test a contract-violating backend.
• Bridge::switchBackend and installReconnectHandler still call the blocking verbs directly and do not consult the new policy — 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