core: give Bridge an executor bound to its own thread, so the threading guarantee is structural for Bridge-mediated calls too

[Yaraslaut]

Surfaced while implementing #568 (PR #585), filed per that PR's "Gaps in #567's surface" section rather than folded in, since it needs a decision and change that belongs with #571, not with #568.

The finding

Completion delivers to whatever executor the caller passes it. For registration, that caller is Bridge, which owns no event loop and no strand of its own — so the only executor Bridge's four dispatch sites (registerHandlerImpl, ensureBoundAsync, attachHandlerAsync, assignHandlerPrimary) can honestly name is exec::detail::inlineExecutor(): "deliver wherever you settled." That is exactly the prose contract #567/#568/#569 exist to replace with something structural — but naming inlineExecutor() doesn't structurally guarantee anything; it just restates "wherever you settled" as a value instead of as a sentence in a doc comment.

bindModel/promoteModel (#567's structural surface) made backends honest about which thread they settle on. They did not give Bridge, the framework's own caller of those verbs, a thread to name. So:

• qt: move QtWebSocketBackend onto the structural registration surface and delete the WASM special case #568 does not close morph#486, and PR qt: move QtWebSocketBackend onto the structural registration surface #585 says so explicitly rather than implying otherwise.
• If core: remove IBackend's four async twins and retire the prose threading contract #571 intends to "retire the prose threading contract" per its acceptance criteria ("the guarantee is carried by the type rather than by the reader"), that claim is not yet true for any call that goes through Bridge — which is all of them from application code's perspective.

What's missing

Bridge would need to hold an executor bound to the thread that runs ~Bridge, and no ticket in the #522 set (#568/#569/#570/#571) currently owns adding one. This is the difference between "the guarantee is structural" (true of backends now) and "the decision is structural" (not yet true of Bridge) — see PR #585's "Decisions still open" section for the fuller writeup.

Status

Verified by reading: Bridge's four dispatch sites in include/morph/core/bridge.hpp all pass inlineExecutor(); exec::detail::inlineExecutor()'s definition confirms it runs the continuation inline on whichever thread settles the Completion. Not a reproduced defect — a scope gap in the #522 ticket set. Relevant to #571 before it claims its acceptance criteria are met.

🤖 Generated with Claude Code

[Yaraslaut]

Triage: rescope — the gap is real, the proposed remedy contradicts the spec

Assessed against master 70792bee.

First, a revision the issue does not name

"Verified by reading: Bridge's four dispatch sites in include/morph/core/bridge.hpp all pass inlineExecutor()"

That is not true of master. The symbol does not exist there at all:

$ grep -rn "inlineExecutor" include/ src/ tests/     # on 70792bee
(no matches)

$ gh pr diff 585 | grep -c "^+.*inlineExecutor"
9        # every occurrence is an ADDED line

exec::detail::inlineExecutor() is introduced by PR #585, which is
unmerged. The issue is accurate about the branch it was written from and says
so in its opening line, but its Status section reads as a claim about the
repository. Worth pinning, because PR #585 is being rebased onto post-#586
master right now and its reconciliation touches these very call sites — so
the four-dispatch-site count is live, not settled.

This does not weaken the issue. The underlying gap does not depend on #585.

The gap is real — keep it

Bridge owns no executor. docs/spec/concurrency_and_lifetimes.md:54 records
where completion callbacks go:

| Completion::then / onError callbacks | The cbExec executor supplied at dispatch (the GUI executor for BridgeHandler) |

BridgeHandler supplies one. Bridge, calling the registration verbs on its
own behalf, supplies nothing. So #571's acceptance criterion — "the guarantee
is carried by the type rather than by the reader" — would indeed overclaim if
asserted for Bridge-mediated registration. That part of the issue stands and
should survive the rescope.

Why the proposed remedy cannot be built as written

"Bridge would need to hold an executor bound to the thread that runs ~Bridge"

docs/spec/concurrency_and_lifetimes.md:205 is titled, and says, the opposite:

Bridge vs. BridgeHandler — teardown is order-independent, on any thread

But teardown order does not matter, and neither does which thread each
side runs on.

Bridge is deliberately not thread-affine. "The thread that runs ~Bridge"
is not a property the object has — it is whichever thread happens to destroy it,
which the spec explicitly permits to be any thread, and which is unknown at
construction, when such an executor member would have to be initialised. The
remedy as phrased asks for an affinity the design spent §205 and §240–262
arguing against (~Bridge blocks on a shared_mutex gate precisely so that
it does not need one).

Building it as written would either re-impose thread affinity on Bridge — a
public contract change well beyond #571's scope, invalidating the
"order-independent, on any thread" guarantee consumers are told they have — or
produce an executor bound to a thread nobody promised would be the destroying
one, which is the prose contract again with extra steps.

The coherent version — the executor already exists, one frame up

The registration path is:

BridgeHandler ctor  →  makeBinding(bridge)  →  bridge.registerHandler<Model>()  →  registerHandlerImpl(binding)
       ^ holds _guiExec (bridge.hpp:2093)                                              ^ has no executor

BridgeHandler is constructed with guiExec (bridge.hpp:2092, :2105)
and stores it in _guiExec, initialised before _binding{makeBinding(bridge)}
in the same init-list. The executor that spec line 54 says should receive these
callbacks is therefore live and in scope at the moment registration is
dispatched — it is simply not threaded through, because makeBinding
(bridge.hpp:2352) is static and takes only Bridge&.

So the rescoped ticket is: carry the registering handler's guiExec into the
registration dispatch, rather than give Bridge a thread of its own. That
makes Bridge-mediated registration obey the same documented rule as every
other completion in the framework, instead of inventing a second one, and it
needs no change to Bridge's lifetime contract.

The part that genuinely has no answer

Bridge::registerHandler also has two direct overloads (bridge.hpp:438,
:452) reachable without any BridgeHandler — the dependency-injection path.
Those have no executor in scope and no handler to borrow one from. For them the
choice is real and should be made explicitly in the rescoped ticket:

1. require the caller to pass a cbExec, or
2. keep inline delivery and document it as the contract for that overload
   specifically — which is honest prose about a narrow path, not the blanket
   prose contract core: remove IBackend's four async twins and retire the prose threading contract #571 is retiring.

Verdict

triage: rescope. Rewrite around threading the existing guiExec through
registration, plus an explicit decision for the two handler-less overloads.
Keep the issue's core observation — and keep its statement that #568 does not
close morph#486, which is correct.

Dependency, recorded rather than merged: this must not be folded into #571.
#571 retires the prose contract; this decides what replaces it for one caller.
Per AGENTS.md, never merge a live scope-gap into the rewrite of the thing it
lives in — the dependency is noted here and should be noted on #571.

What would change the verdict

• If Bridge is deliberately given thread affinity by some other ticket, the
  original framing becomes buildable and this rescope is moot — but that is a
  public-contract decision that belongs on its own issue, not inside core: remove IBackend's four async twins and retire the prose threading contract #571.
• If PR qt: move QtWebSocketBackend onto the structural registration surface #585's rebase changes the four dispatch sites materially, re-read this
  against the landed version before acting.

Not verified

• I did not build or run anything for this triage: it is a design/contract
  reading of bridge.hpp and concurrency_and_lifetimes.md against the issue's
  claim, plus a grep/gh pr diff check of where inlineExecutor actually
  lives. No behavioural defect is asserted, and none was measured.
• I did not enumerate call sites of the two handler-less registerHandler
  overloads, so how much code path 2 would actually affect is unmeasured.

[Yaraslaut]

Decision: this ticket owns the Bridge executor. #571 does not absorb it, and is not blocked by it — #571's acceptance criteria get narrowed instead.

Asked for and taken by the runner. Reasoning below so it can be argued with rather than just followed.

First, the premise — verified, and narrower than it looks

inlineExecutor exists only on PR #585's branch. It is absent from master entirely:

$ grep -rn "inlineExecutor" include/morph/        # on master a020e69c
(no output)

$ 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());

Four call sites, exactly the four this issue names. So this ticket is blocked on #585 landing — it describes code that does not yet exist on master. Recording that because nothing on the issue said it.

Why not fold it into #571

#571 already carries: remove four virtuals, migrate LocalBackend and SimulatedRemoteBackend, and convert 11 test doubles across four test files. Adding "give Bridge an executor bound to the thread that runs ~Bridge" puts a design change to Bridge's lifetime contract into that batch.

That is precisely the failure #522 was re-scoped to escape, in #522's own words:

The suggested fix spans core + qt + net + the ladder + 11 test doubles. No single lane could land it.

Undoing that by re-merging a design question into the largest ticket of the set would reproduce the problem the five-way split solved.

Why #571 is not blocked by it either

Blocking #571 would stall closing #522 on a question that is genuinely open — where does Bridge's executor come from? Does the embedder supply it, is it the Qt main thread, is it a strand Bridge owns? — and #522 is not about that.

#522 is about duplication: four async twins alongside four synchronous ones, an interface that "roughly halves." #571 can deliver that completely and honestly. What it cannot honestly claim is the other half of its acceptance text, and this issue is right that the two have been conflated.

So: #571's acceptance is amended

• The prose threading contract at backend.hpp:131-135 […] not by deleting the reasoning, but by relocating what remains true […] after this set the guarantee is carried by the type rather than by the reader

That claim is true of backends after #567/#568/#569 — bindModel/promoteModel made backends honest about which thread they settle on. It is not true of Bridge, and naming inlineExecutor() does not make it true; as this issue puts it, that just restates "wherever you settled" as a value instead of as a sentence in a doc comment.

#571 should therefore claim: the duplication is gone and the surface is single, and state explicitly that the threading guarantee is structural for backends and remains carrier-by-prose for Bridge-mediated calls, tracked here. A comment saying so is going on #571.

Dependency this creates, not previously recorded

#615 depends on this ticket. #615 moves switchBackend, installReconnectHandler and ensureBound off the blocking verbs onto bindModel/promoteModel. The moment it does, each of those sites must name an executor to deliver the Completion on — which is exactly the gap here. Doing #615 first would add three more inlineExecutor() sites to the four that already exist, making this ticket strictly larger.

Order: #585 → this → #615.

What this ticket should now contain

The scope is a design decision plus its mechanical consequence, and the design part is the substance:

1. Where Bridge's executor comes from. The constraint is that it must be bound to the thread that runs ~Bridge, because that is the thread morph#486's use-after-free is about. Candidates worth weighing in the ticket rather than assumed: the embedder supplies one at construction (composes, testable, but another required argument); Bridge owns a strand; or the executor is captured from the constructing thread. Invariant 2 applies — a framework requirement on consumers must compose, so if this becomes a constructor argument it should have a sane default rather than being mandatory.
2. Replace the four inlineExecutor() sites with it.
3. A test that fails if the executor is wrong — per AGENTS.md, a test that would pass with inlineExecutor() restored is not evidence. The shape that works here is the one qt: move QtWebSocketBackend onto the structural registration surface #585 used for the equivalent claim: assert the continuation runs on the expected thread, so putting inlineExecutor() back makes it fail rather than merely not-prove.
4. Then docs/spec/concurrency_and_lifetimes.md can say the guarantee is structural without the carve-out.

Retitling the issue to match, and applying triage: valid. It was filed by a lane, so this is an assessment of someone else's description, not a self-assessment.

What I did not verify

• I did not read exec::detail::inlineExecutor()'s definition; I am taking the filer's description of it (runs the continuation inline on whichever thread settled the Completion) as read, and it is consistent with the four call sites' surrounding comments.
• I have not evaluated the three candidate executor sources above — naming them is scoping, not designing. Whoever takes this should weigh them and record why.
• Whether morph#486's teardown race is actually reachable through any of the four sites today was not re-checked.

[Yaraslaut]

Runner, housekeeping: this issue carried both triage: rescope (2026-09-19) and triage: valid (2026-09-20). The open issues are the only state this backlog has, and two contradictory verdicts on one issue make it unbatchable — Step 2 groups by triage: label, so an issue with two cannot be picked up.

Resolved in favour of valid, because the later comment says so in terms: "Retitling the issue to match, and applying triage: valid. It was filed by a lane, so this is an assessment of someone else's description, not a self-assessment." That is a re-assessment superseding the earlier verdict, not a second opinion sitting beside it. Removed triage: rescope; no verdict changed, only the record made consistent with the decision already taken.

Worth noting the failure mode for next time: applying a new triage: label without removing the old one leaves the issue in a state where the most recent verdict is only discoverable by reading the timeline, which nothing does.