core: honour bindWaitPolicy at switchBackend and reconnect, cancel the adapter's own completions, and document TimeoutScheduler::cancel (fixes #615, fixes #619, fixes #620)

[Yaraslaut]

Three tickets on the core threading/cancellation tree, one commit each, plus one clearly-labelled bookkeeping commit. Nothing was rejected.

Commit	Ticket	What it is
481c3c1	fixes #620	TimeoutScheduler::cancel() documentation + contract clarification
38370fe	fixes #619	SynchronousBackendAdapter::cancelPending cancels its own completions
f944e26	fixes #615	switchBackend and the reconnect handler onto bindModel/bindWaitPolicy
1ca161d	—	repoints three branch_partial_allowlist.json line hints this branch moved

#620 — TimeoutScheduler::cancel() and an already-firing callback

Conclusion asked for by the ticket: prose, plus one contract clarification — not a behaviour change. run() erases the entry before invoking the callback and drops _mtx across the invocation, so a cancel() for a callback that has started takes the not-found branch and returns while that callback is still running. The header's "already fired" silently covered both "finished" and "currently running".

Making cancel() wait would be the wrong fix, not a missing feature: a callback that posts back to the cancelling thread would deadlock it — the family docs/spec/concurrency_and_lifetimes.md names and the reason CallbackScope has no block-until-drained either. What was missing is the obligation that not-waiting puts on a caller, so cancel() now states it: every scheduled callback must stay safe to run after its own cancel(). Both shipped callers now say why they are (first-result-wins in Bridge::executeVia, reply-exactly-once in RemoteServer), and the @file comment gains the third build difference — only the single-threaded browser build actually gives "no callback starts after cancel() returns".

Two Catch2 cases. The finding one is mutation-checked: running the callback under _mtx in run(), so cancel() blocks behind it, fails it at REQUIRE_FALSE(finished.load()) with !true.

#619 — the adapter's own pending completions

cancelPending was _inner->cancelPending(exc);. The two verbs the adapter reshapes settle from a task on its own _control strand, holding a promise the wrapped backend has never seen — so the forward reached none of them and a cancelled bind went on to resolve successfully. The adapter now tracks each dispatched promise weakly and rejects the live ones before forwarding, on the snapshot-then-deliver shape and amortised compaction LocalBackend already uses.

Reproduced and fixed, with bindModel and promoteModel covered — #619 measured only the bind and inferred the promote. Mutation: restoring the plain forward fails both sections at REQUIRE(waitUntil([&] { callerExec.runOnce(); return errRan.load() == 1; })) with false.

One thing this deliberately does not fix, and it is filed rather than folded: a task already queued on _control still runs its blocking control call against the wrapped backend after the cancellation, so the caller is told the bind was cancelled while the registration may still go through. That needs the task to check before calling op(), not the promise to be settled after it — #636.

#615 — the two sites that never asked bindWaitPolicy()

switchBackend's phase 1 and installReconnectHandler's callback still called the blocking registerModelShared/registerModelWithContext directly. Both now go through bindModel with the shape every other site already has — dispatch, park an inline reply in an AsyncDispatchHandoff, then awaitHandoff or claimHandoff by policy.

For every kCallerMayBlock backend this is behaviour-for-behaviour what it was: the default bindModel runs exactly the legacy verb the request shape names and settles inside the call. What is new is kCallerMustNotBlock:

• switchBackend defers those binds — the swap happens, currentId is cleared, registrationInFlight is set so whenBound() can gate the window, and the reply binds it. Atomicity is now exactly as strong as the wait is, and the header and bridge.md both say so rather than continuing to promise all-or-nothing. A deferred bind that fails after the swap is logged and rejects that binding's waiters; it cannot roll the switch back, and an instance it created on a backend whose switch later threw is not deregistered. Both are consequences of not waiting, stated rather than hidden.
• The rollback keys on a rejected Completion rather than a thrown exception, which is what the ticket asks for.
• The reconnect handler clears currentId for a deferred binding (the id belonged to the connection that dropped), and a failing re-registration no longer throws out of the handler onto the transport thread taking every later binding with it.
• Waiters are resolved, and the staging exception rethrown, only after _mtx/_attachMtx are released — resolving one runs consumer code free to re-enter the Bridge.

It also settles the ticket's second finding: docs/spec/core/backend.md's migration table assigned the reconnect half to #570, whose own body scopes itself to examples/ and never mentions bridge.hpp, and assigned switchBackend to nobody. The table now has a #615 row and #570 keeps only what its body claims.

Review reasoning, inline (no /code-review, no /simplify)

Reading the change back, four things wanted deciding rather than assuming:

1. Where the waiters get settled. resolveRegistrationWaiters invokes consumer callbacks. Both new sites had them inside the {_mtx, _attachMtx} region on the first pass; a waiter that re-enters the Bridge would self-deadlock. They are collected under the locks and settled after, and the staging exception is rethrown after that too, so the throw path settles its waiters rather than stranding them.
2. Whether the late continuation can deadlock against the switch. It takes _mtx, which switchBackend holds for the whole staging + commit + swap. A reply that lands during that window blocks a transport thread until the swap is done, and then sees pinned == loadBackend() — the outcome we want. It cannot be the calling thread, because an inline settle is parked by parkIfInFrame and handled in-frame.
3. What a deferred binding's currentId should be. Leaving the old id would let executeVia dispatch a dangling id at a backend that never issued it. 0 makes it fail fast, which is the documented "handler not bound" path, and whenBound() makes the window waitable.
4. The function-size consequence. With all of this inline, clang-tidy scored switchBackend 45 and installReconnectHandler 46 against a 25 threshold — CI's clang-tidy-diff leg failing, and correctly: four concerns in one body. Split into rebindThroughSurface / stageRebinds / rollbackStaged / commitRebinds / reregisterLive, with the three sites' continuation pair collapsed into one makeBindCallbacks instead of three near-copies.

Verification

Measured, GCC 16.2.1 Debug, Linux: 1547 cases / 22704 assertions, all passing (the one "failed as expected" is test_replay_ledger's deliberate negative-conformance run). Also clean locally: clang-format, check_nolint_directives.sh, check_catch_test_names.sh, check_test_type_names.sh, check_deprecated_markers.sh, check_spec_citations.sh, check_spec_sync.sh (driven with the real origin/master..HEAD path list: "10 sub-domain(s) classified; every touched header sub-domain has a matching spec change"), the Doxygen doc target, and clang-tidy-diff.py over the whole branch diff with clang 22.1.8 (CI's pinned version) — the last one against a tests-only configure, where CI configures every optional feature, so it is partial rather than equivalent.

#615's three new cases were run against this branch's base (git show a8511aa6:include/morph/core/bridge.hpp) and all three fail, including the rollback case at REQUIRE_THROWS_AS(...) with "no exception was thrown where one was expected". Re-introducing just the blocking legacy call at both sites fails the two timing cases at REQUIRE(returnedPromptly) with false.

Worth flagging because it nearly slipped through. The first mutation run of the #615 timing cases passed. The test double's legacy verbs were bounded by kDefaultWaitBudget — the same two seconds the test's own waitUntil polls for — so the blocked thread came back at almost exactly the moment the measurement gave up. The bound is now 60 s, a wedge guard rather than a race partner, and only then did the mutation fail. A budget equal to the thing it measures is not a measurement; the comment in the double says so, with the observation.

Not verified: any of this against a real QtWebSocketBackend with asyncRegistrationEnabled, or in a browser — no WASM toolchain here, and no shipped example sets that flag and relies on reconnect or switchBackend. The WASM consequence stays inferred from the dispatch chain, exactly as #615 states it. What is measured is that neither site blocks a caller on a kCallerMustNotBlock backend and that both bind it when the reply lands. Also not re-measured: branch coverage (no llvm-cov build was made here), so the repointed allowlist entries are "still partial" on the gate's last measurement, not on a new one.

One thing this branch knowingly leaves red

scripts/check_mutation_survivors.py fails on this branch:

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.

scripts/mutation_survivors.json is held by PR #635, so this lane does not touch it. Whichever of the two merges second applies that one-line hint change (1322 → 1412, aware.reserve(_changeAware.size());).

Issues filed

• core: SynchronousBackendAdapter::cancelPending settles the completion but the queued control call still registers on the wrapped backend #636 — SynchronousBackendAdapter::cancelPending settles the completion but the queued control call still registers on the wrapped backend. Reproduced as a side observation of core: SynchronousBackendAdapter::cancelPending does not cancel the completions the adapter itself produced #619's own regression test; the assertion recording it is in this PR and is the one that would change if core: SynchronousBackendAdapter::cancelPending settles the completion but the queued control call still registers on the wrapped backend #636 is fixed.

Closes #615, #619, #620.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VptDWG2fKr2vBnLSJcgzgW

[Yaraslaut]

Runner verification (landing sweep, 2026-09-20)

Checked the one claim the branch's safety rests on, against the repository.

The claim: for every kCallerMayBlock backend — everything in the tree today — switchBackend and the reconnect handler behave exactly as before, because the default IBackend::bindModel runs the same legacy verb the request shape names and settles inside the call.

1. The evidence tests really are unchanged. tests/test_switch_backend.cpp is +275 / −0 — purely additive, so the pre-existing ReconnectableLocalBackend cases that count registerModelShared / registerModelWithContext calls are intact by construction, not by assertion. Same for test_backend_registration_surface.cpp (+130/−0) and test_timeout_scheduler.cpp (+54/−0). No existing case was edited to accommodate the change, which is the failure mode that would have made "the suite still passes" worthless.

2. The mechanism holds, read at the source. The default bindModel (backend.hpp:599) settles on the calling thread:

auto [completion, promise] = Completion<ModelId>::makeSettleable(&cbExec);
try {
    promise.resolve(bindModelBlocking(std::move(request)));
} catch (...) {
    promise.reject(std::current_exception());
}
return std::move(completion);

and bindModelBlocking dispatches by request shape to exactly the legacy verbs:

682:  if (request.current.v != 0U)    return attachModel(...);
685:  if (!request.primary.empty())   return registerModelShared(...);
688:  return registerModelWithContext(request.typeId, ..., request.contextKey);

So a backend that does not override bindModel reaches the same verb, on the same thread, and the returned Completion is already settled when awaitHandoff inspects it. The claim is confirmed on the mechanism, not only on the suite.

3. The knowingly-red mutation gate is real, and reproduced. Not taken on trust:

mutation_survivors.json entry: include/morph/core/backend.hpp line=1322
                               source='aware.reserve(_changeAware.size());'
branch backend.hpp:1322:  return registerModelWithContext(typeId, std::move(factory), identity.contextKey);
branch backend.hpp:1412:  aware.reserve(_changeAware.size());

The hint must move 1322 → 1412, exactly as reported. The lane was right not to edit that file — PR #635 holds it and restructures it substantially (#613 converts the classes citations to the structured shape).

Merge order for these two

#635 lands first, then this PR rebases onto it and repoints the hint in #635's new structured shape. Doing it the other way means a conflict in mutation_survivors.json plus a repoint that has to be redone against the restructured file. Whoever takes that rebase should re-run python3 scripts/check_mutation_survivors.py and expect to repoint every backend.hpp citation this branch moved, not only the one — this branch adds 97 lines to that header, and two other side_channel_metrics entries in it were already repointed once on #635 for the same reason.

Left for the next sweep

gh pr checks 639 reports 30 pending, 0 completed — nothing to judge yet, and the mutation leg is expected red for the reason above.

Noted, not acted on

The finding in the hand-off that the first mutation run of #615's timing cases passed and should not have — the test double's blocking verbs were bounded by the same kDefaultWaitBudget the test's own waitUntil polls for, so the blocked thread returned just as the measurement gave up. A latch bounded by the same budget as the waitUntil that measures it is not a measurement. That is this repository's headline failure mode (AGENTS.md: "a control that reports success while measuring nothing") appearing one level down, inside a test double. It is recorded in the double's comment here; it is worth a tree-wide look at whether other doubles share the budget with the poller, which is a separate ticket and not this PR's job.

#636 filed by the lane is correctly untriaged; Step 1 of the next sweep picks it up.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VptDWG2fKr2vBnLSJcgzgW

[Yaraslaut]

Runner: rebased onto ab420052, all three citations repointed

#635 landed, so the file this branch needed was released. Rebased cleanly onto the new master and the gate reported three citations moved, not one — as predicted, because this branch adds 97 lines to backend.hpp:

scripts/mutation_survivors.json: 3 citation(s) no longer match the code they name.
  - include/morph/core/backend.hpp:1322 has moved to line 1412. …
  - include/morph/core/backend.hpp:1215 … appears 2 times (lines [1305, 1324]) …
  - include/morph/core/backend.hpp:1379 … appears 2 times (lines [1469, 1514]) …

The first is mechanical. The other two are the pair whose entries record in advance that a drift here is reported as ambiguous rather than auto-corrected, so each was resolved by reading both candidates: 1305 is the registerCount emission inside registerModel (1324 is the registerModelShared arm, and the entry names registerModel); 1469 is the executeInFlight fetch_add increment outside the posted task (1514 is the decrement twin inside it, and the entry names the increment side). No source or reason text altered.

Repointed in its own commit (024d5e74), separate from the three ticket commits. After it:

ok: 15 structured citation(s) in scripts/mutation_survivors.json resolve to the line they name.

Gates run locally on the rebased tree before pushing, all clean: check_mutation_survivors.py, check_nolint_directives.sh + self-test (167 directives), check_workflow_option_coverage.py, check_spec_citations.sh, and the branch-coverage allowlist (22 entries, 0 stale).

Fresh CI is running. Not merged this sweep.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VptDWG2fKr2vBnLSJcgzgW

[codecov]

Codecov Report

❌ Patch coverage is 84.66258% with 25 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
include/morph/core/bridge.hpp	85.71%	14 Missing and 7 partials ⚠️
include/morph/core/backend.hpp	75.00%	2 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!