core: remove IBackend's four async twins and retire the prose threading contract

[Yaraslaut]

Re-scoped out of #522, step 5 of 5 — the one that actually closes the finding. Blocked by #568, #569 and #570: every production backend and every consumer must be off the old verbs first.

What to remove

• The four twins on IBackend: registerModelAsync (backend.hpp:180), registerModelSharedAsync (:222), attachModelAsync (:322), assignPrimaryAsync.
• The prose threading contract at backend.hpp:131-135 and the explanatory block at :106-115 — not by deleting the reasoning, but by relocating what remains true. The morph#486 use-after-free those paragraphs describe is real; after this set the guarantee is carried by the type rather than by the reader, and the documentation should say that, in docs/spec/core/backend.md.

Also in scope

Migrate LocalBackend and SimulatedRemoteBackend (core/remote.hpp:1826) and the 11 test doubles across tests/test_async_registration.cpp, tests/test_switch_backend.cpp, tests/test_bridge_lifetime.cpp and tests/test_client_execute_deadline.cpp. None of these overrides the async verbs, so all are candidates for SynchronousBackendAdapter rather than hand-editing — if any needs more than the adapter, that is worth saying in the PR, because it means the adapter's shape is wrong.

Acceptance

• The four verbs do not exist anywhere in the tree. grep -rn 'registerModelAsync\|registerModelSharedAsync\|attachModelAsync\|assignPrimaryAsync' include src tests examples returns nothing.
• IBackend's virtual count is recorded before and after in the PR body. core: IBackend has grown a parallel async shadow of four of its own methods #522 observes 18 virtuals with 14 defaulted and predicts the interface "roughly halves" — report what it actually did, including if the prediction was wrong.
• The full suite passes, and the Bridge lifetime tests in tests/test_bridge_lifetime.cpp still cover the morph#486 teardown race. A test that only compiled because a defaulted virtual existed must not be quietly dropped — if any coverage is lost, name it.
• docs/spec/core/backend.md describes the single surface, and no doc names a removed verb.

Notes

R core-async lane. Closing this closes #522. Nothing on this board should be marked done for F4 until this merges — the intermediate steps improve the shape but leave the duplication in place, which is the thing #522 is actually about.

[Yaraslaut]

Triaged as part of the #567–#571 set. Verified against origin/master.

"11 test doubles" — re-measured, holds exactly. Enumerated every IBackend/LocalBackend-derived class across the four named test files: 8 in tests/test_async_registration.cpp, 3 in tests/test_switch_backend.cpp, 5 in tests/test_bridge_lifetime.cpp, 2 in tests/test_client_execute_deadline.cpp — 18 total. Of those, exactly 11 override none of the four *Async verbs (all 3 in test_switch_backend.cpp, all 5 in test_bridge_lifetime.cpp, both in test_client_execute_deadline.cpp, plus ThrowingSyncRegisterSharedBackend in test_async_registration.cpp — read its body directly, it only overrides the synchronous registerModelShared). The other 7 (AsyncRegisterBackend and its three derivatives, AsyncBackendShim, AsyncAssignPrimaryBackend, SelfFiringAssignPrimaryBackend) exist specifically to simulate async backend behavior and are not simple adapter candidates — consistent with this ticket's own framing that the 11 are the ones a hand-edit-free adapter swap should cover, and that anything needing more is worth flagging. SimulatedRemoteBackend is confirmed at core/remote.hpp:1826 and, like the production backends, overrides none of the four.

Same stale-baseline note as #567. The acceptance criterion here says "#522 observes 18 virtuals with 14 defaulted." Direct count in backend.hpp: 18 total confirmed, but 5 pure / 13 defaulted, not 4/14 (registerModel, deregisterModel, execute, notifyBackendChanged, cancelPending are the five = 0 virtuals). Use the corrected baseline when reporting the before/after count and checking whether "roughly halves" held.

This ticket is the one that actually deletes the twins and the prose contract, and it's correctly gated on #568/#569/#570 all landing first, with an explicit guard against silently dropping Bridge lifetime coverage (tests/test_bridge_lifetime.cpp's morph#486 teardown race) just because a defaulted virtual disappears. No invariant is violated by the removal itself — it retires duplication whose sole justification (the WASM special case) will already be structural by the time this runs.

Verdict: triage: valid.

[Yaraslaut]

Carried forward from PR #585 (#568)'s "Gaps in #567's surface" section — not a defect, a heads-up for whoever edits core/backend.hpp / docs/spec/core/backend.md here:

BindRequest cannot express registerModelShared with an empty primary, and the mapping from request-shape to wire verb is not injective. Bridge::ensureBoundAsync asks for an anonymous shared instance — registerModelShared(typeId, factory, {contextKey, primary = {}}) — which in BindRequest terms is primary empty + current zero, the same shape bindModelBlocking routes to registerModelWithContext. Different verb, same request shape.

Verified harmless today: IBackend::registerModelShared documents an empty primary as degrading to registerModelWithContext, and every backend in the tree (LocalBackend, SimulatedRemoteBackend, SocketBackend, QtWebSocketBackend) implements that degrade as its first statement. Server-side, register+shared and attach with modelId == 0 both reach acquireSharedInstance(..., ModelId{0}) through the same authorizeRegister gate. But it did cost PR #585 one failing test when a test double's throw-on-registerModelShared stopped firing because the call was silently routed to registerModelWithContext instead.

Also related: the twin case, attachModel(..., current = 0), is not expressible in BindRequest either — it maps to registerModelShared.

Please don't assume the request-shape → verb mapping is injective when closing this out.

🤖 Generated with Claude Code

[Yaraslaut]

Dependency recorded from #588 (triaged rescope), not folded in.

#588 finds that this ticket's acceptance criterion — "the guarantee is carried by the type rather than by the reader" — would overclaim if asserted for Bridge-mediated registration. Bridge supplies no executor for its own registration dispatch, so retiring the prose threading contract does not, by itself, make those calls structurally guaranteed.

#588's original remedy (give Bridge an executor bound to its own thread) was rescoped: it contradicts docs/spec/concurrency_and_lifetimes.md:205, "teardown is order-independent, on any thread... neither does which thread each side runs on." The rescoped direction is to thread the registering BridgeHandler's existing _guiExec through registration instead.

Per AGENTS.md this is not merged into #571 — a live scope gap must not be folded into the rewrite of the thing it lives in. The dependency runs one way: #571 should not claim its acceptance criteria are met for Bridge-mediated calls until #588 is resolved, or should state explicitly that those calls are out of its scope.

Analysis and evidence: #588.

[Yaraslaut]

Second dependency recorded: #593 (triaged valid), filed out of #585's CI failure. Not folded in.

#593 is the same seam as the #588 note above, hit from a different direction: #567's surface is structural for backends, but leaves Bridge — its own caller — unable to act on it.

Concretely, Bridge::registerHandlerImpl has one call site for acquiring a model, and after #586 and #585 two shipped backends need opposite behaviour there: net::SocketBackend must block until bindModel settles (its callers use the handler on the next line), while QtWebSocketBackend with asyncRegistrationEnabled must not (blocking is the nested-QEventLoop deadlock that aborts the WASM page). From Bridge's side the two are indistinguishable, and backend.hpp:487-493 removed the discriminator deliberately.

I verified the regression independently rather than relying on the report: the same test passes in 0.03 s on master's green run and times out at 2.02 s on #585, same leg, same runner.

Why it lands here: one of #593's two candidate resolutions is to drop executeVia's raw == 0U fail-fast at bridge.hpp:1463 in favour of queue-until-bound. Once registration is universally asynchronous there is no moment at which "bound" is synchronously guaranteed, so that check fails on the normal case rather than an error — which makes it this ticket's scope. The other resolution restores the bool #567 removed on purpose.

I am not choosing between them; that is a public-surface decision for whoever owns #567/#571.

#588 and #593 should be decided together, not one at a time — different mechanisms, same seam. And #585/#568 is blocked until this has an answer.

[Yaraslaut]

Chain status, recorded so the blocker is findable from here.

This is step 5 of 5 and is blocked by #568, #569 and #570. The current actual blocker of the whole chain is #593, one level deeper than this issue's header records:

• net: move SocketBackend onto the structural registration surface, or justify the adapter #569 — landed (70792bee, PR net: put SocketBackend on the structural registration surface natively #586).
• qt: move QtWebSocketBackend onto the structural registration surface and delete the WASM special case #568 — PR qt: move QtWebSocketBackend onto the structural registration surface #585 is open and red. Its CI on a08db4f9 fails six jobs on one test (SocketBackend: action result delivered via then, -1 == 99).
• That red is 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 #593: after qt: move QtWebSocketBackend onto the structural registration surface and delete the WASM special case #568 deletes the registerModelAsync overrides, Bridge::registerHandlerImpl has one call site from which morph::net::SocketBackend needs blocking behaviour and QtWebSocketBackend needs non-blocking, and core: give IBackend a registration surface whose threading contract is structural, not prose #567's surface removed the discriminator that could tell them apart.
• ladder: move the example GUIs and the WASM spike onto the structural registration surface #570 — not started; blocked on qt: move QtWebSocketBackend onto the structural registration surface and delete the WASM special case #568.

So the order is #593 → #585/#568 → #570 → this → closes #522. A lane is on #593 now.

Nothing here needs re-scoping. Noting it because this issue's "Blocked by" line does not mention #593, which did not exist when this was written, and a reader arriving at the chain head would otherwise go looking at #568 and find a PR that looks merely broken rather than blocked on a design question.

[Yaraslaut]

Acceptance criteria amended — see #588

Recording a runner decision so #571 does not claim, on merge, something that will not be true.

This issue's acceptance includes:

The prose threading contract at backend.hpp:131-135 […] after this set the guarantee is carried by the type rather than by the reader

That is true of backends and not of Bridge. #567/#568/#569 made backends honest about which thread they settle on via bindModel/promoteModel. They did not give Bridge — the framework's own caller of those verbs, and the only one application code sees — a thread to name. Bridge's four dispatch sites on PR #585's branch all pass ::morph::exec::detail::inlineExecutor(), verified:

$ git show origin/fix-568-qt-structural-registration:include/morph/core/bridge.hpp | grep -n inlineExecutor
 747:  ::morph::exec::detail::inlineExecutor());
 894:  ::morph::exec::detail::inlineExecutor());
1034:  ::morph::exec::detail::inlineExecutor());
1975:  ::morph::exec::detail::inlineExecutor());

Naming inlineExecutor() is "deliver wherever you settled" written as a value instead of as a sentence in a doc comment. It is not a structural guarantee.

The decision (full reasoning on #588):

• core: remove IBackend's four async twins and retire the prose threading contract #571 does not absorb the Bridge executor work. This is already the largest ticket in the core: IBackend has grown a parallel async shadow of four of its own methods #522 set — four virtuals, two production backends, 11 test doubles — and adding a design change to Bridge's lifetime contract would rebuild exactly the "no single lane could land it" problem the five-way split was created to solve.
• core: remove IBackend's four async twins and retire the prose threading contract #571 is not blocked by it. core: IBackend has grown a parallel async shadow of four of its own methods #522 is about duplication — "the interface roughly halves" — and core: remove IBackend's four async twins and retire the prose threading contract #571 delivers that in full.
• core: remove IBackend's four async twins and retire the prose threading contract #571's claim narrows. On merge, state that the duplication is gone and the surface is single, and that the threading guarantee is structural for backends, remaining carried by prose for Bridge-mediated calls, tracked in core: give Bridge an executor bound to its own thread, so the threading guarantee is structural for Bridge-mediated calls too #588. Update docs/spec/core/backend.md to say the same, with the carve-out named rather than implied.

This costs #571 nothing it actually does, and it stops #522 being closed against a guarantee that is half-delivered — which is the kind of thing this repository's AGENTS.md has a whole section about.

Chain order is now: #593 → #585/#568 → #570 → #571 → closes #522, with #588 → #615 running after #585 on the Bridge side, independently of #570/#571.

[Yaraslaut]

Blocked by #619 — surfaced by #550's cancellation-policy work

SynchronousBackendAdapter::cancelPending is a bare one-line forward (include/morph/core/backend.hpp:211):

void cancelPending(const std::exception_ptr& exc) override { _inner->cancelPending(exc); }

but the adapter settles its own bindModel/promoteModel promises on a private StrandExecutor (kControlStrand), which _inner has never seen. So those completions are not cancelled — by construction, not as a race. Measured: after cancelPending(BridgeDestroyedError) the bind's .then fired with a success value (okRan=1 errRan=0).

Why this blocks this ticket specifically. #571's own acceptance routes the migration through that adapter:

None of these overrides the async verbs, so all are candidates for SynchronousBackendAdapter rather than hand-editing — if any needs more than the adapter, that is worth saying in the PR, because it means the adapter's shape is wrong.

That is LocalBackend, SimulatedRemoteBackend and 11 test doubles — 13 call sites — onto a verb that silently does not cancel. There is no production call site today, which is exactly why it is cheap now and expensive after the migration: the adapter's forwarding is correct, and only its own promises leak, so it will look fine until it doesn't.

This is the ticket's own "the adapter's shape is wrong" case, found before the migration instead of during it. Fix #619 first; it is a small change to one function.

Chain order on this side is therefore: #593 → PR #585/#568 → #570 → #619 → #571 → closes #522, with #588 → #615 running independently after #585.

Context for whoever takes #619: the full cancellation-entry-point table is on #550 — 27 entry points across 8 families, and the finding that every cancelPending in the tree guarantees only "a terminal onError is now posted", not "no further callback will start". The adapter should end up saying the same thing as its siblings, not something stronger.

[Yaraslaut]

"Also in scope" is stale, and following it would have been a regression

Recorded on the ticket rather than only in the PR, because it contradicts the ticket it is filed under.

This issue says:

Migrate LocalBackend and SimulatedRemoteBackend (core/remote.hpp:1826) and the 11 test doubles across tests/test_async_registration.cpp, tests/test_switch_backend.cpp, tests/test_bridge_lifetime.cpp and tests/test_client_execute_deadline.cpp. None of these overrides the async verbs, so all are candidates for SynchronousBackendAdapter rather than hand-editing — if any needs more than the adapter, that is worth saying in the PR, because it means the adapter's shape is wrong.

Measured on origin/master (c55ea5b7):

$ grep -c 'registerModelAsync\|registerModelSharedAsync\|attachModelAsync\|assignPrimaryAsync' \
    tests/test_switch_backend.cpp tests/test_bridge_lifetime.cpp tests/test_client_execute_deadline.cpp
tests/test_switch_backend.cpp:0
tests/test_bridge_lifetime.cpp:0
tests/test_client_execute_deadline.cpp:0

LocalBackend and SimulatedRemoteBackend are the same: neither names any of the four verbs.

The issue's own sentence already says so ("None of these overrides the async verbs"), and the conclusion it draws from that is the wrong one. Because none of them overrides a twin, none of them needs migrating at all. IBackend's default bindModel calls bindModelBlocking, which dispatches to exactly the synchronous verb each request shape names, so every one of these backends reaches the structural surface unchanged and behaves identically through it.

Wrapping them in SynchronousBackendAdapter would be an active regression, not a migration. The adapter answers BindWait::kCallerMustNotBlock — always, by design, and docs/spec/core/backend.md's API table says "Not forwarded: it describes the two verbs the adapter reshapes". So wrapping LocalBackend would make Bridge::registerHandler return an unbound handler to every in-process embedder, and executeVia would fail fast with "handler not bound" on the next line. That is the exact regression #593 was filed to undo for SocketBackend.

So the "if any needs more than the adapter, that is worth saying in the PR, because it means the adapter's shape is wrong" test does not fire: the adapter's shape is fine, and the mistake is in the instruction to apply it. The only doubles that actually overrode the twins are the ones in tests/test_async_registration.cpp, and those are migrated onto bindModel/promoteModel in the PR.

Verification status: the greps above are real output from c55ea5b7. The claim about what wrapping LocalBackend would do is inferred from reading SynchronousBackendAdapter::bindWaitPolicy and Bridge::registerHandlerImpl, not reproduced — I did not build a tree with LocalBackend wrapped to watch it fail.

What would change the verdict: if SynchronousBackendAdapter ever forwards bindWaitPolicy() instead of answering kCallerMustNotBlock unconditionally, wrapping a blocking backend stops being observable to registerHandler's caller and this objection disappears. Nothing proposes that, and #567's reasoning argues against it.