core/ladder: retire IBackend's four async twins and move the examples' prose onto the structural surface (fixes #570, fixes #571)

[Yaraslaut]

The tail of the #522 registration-surface chain: #570 then #571, in that order, because the second cannot land until the first has moved the last consumers. Three commits — one per ticket, plus a separate, clearly-labelled one for the two line-hint gates.

Closes #570. Closes #571. Closes #522 (see the caveat under "What this does not claim").

---

1 — #570: the examples were already on the surface; the prose was not

6cdff61d

The ticket reads as a code migration. It is not one, and that is worth stating plainly rather than quietly delivering a documentation change against a ticket that asked for something else.

Nothing under examples/ has ever called registerModelAsync, registerModelSharedAsync, attachModelAsync or assignPrimaryAsync. Application code reaches a backend only through Bridge, and #568 moved Bridge's four dispatch sites onto bindModel/promoteModel. Checked rather than assumed: all 25 hits under examples/ on c55ea5b7 were comments — //, ///, a CMake #, or Markdown.

So this commit moves prose that named verbs nothing had implemented since #568 and that commit 2 deletes:

• The GUI clients and AppContext now name QtWebSocketBackend::bindModel() as what queues a private bind issued before the socket connects. The described behaviour is unchanged and still true (src/qt/qt_websocket_backend.cpp, the !_connected arms: a request with an empty primary is queued and sent on the next connected; one with a non-empty primary is rejected with "disconnected").
• AppContext's readiness contract gains the half it was missing. With asyncRegistrationEnabled the backend answers kCallerMustNotBlock, so registerHandler hands back an unbound handler and the caller must gate on whenBound()/isBound(). That was already true; the doc comment described only the queue.
• polls/README.md's struck assignPrimaryAsync claim keeps its correction but states it against IBackend::promoteModel, which no backend can decline — a stronger version of the same rebuttal.
• LADDER.md, TESTING.md and polls/README.md keep their "shipped" history: each says what shipped then and that 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 replaced it, rather than deleting the record.

examples/common/testkit/test_wasm_registration_path_native.cpp still pins the single-threaded registration path through Bridge — only its comment moved, and its citation of tests/qt/test_qt_websocket.cpp now names that file's current test name.

2 — #571: the four twins, and the prose contract they carried

085b401b

$ grep -rn 'registerModelAsync\|registerModelSharedAsync\|attachModelAsync\|assignPrimaryAsync' include src tests examples
$ echo $?
1

Removed from IBackend and from SynchronousBackendAdapter's forwarding block; Bridge's four "offer the twin, fall back to bindModel" branches are now one unconditional dispatch each.

Virtual count — and #522's prediction, which was wrong

struct IBackend, excluding the destructor:

	virtuals	pure	defaulted
before (c55ea5b7)	21	5	16
after (085b401b)	17	5	12

#522 says "18 virtuals with 14 defaulted" and predicts the interface "roughly halves". The baseline was already stale (there were 21 once bindModel/promoteModel/bindWaitPolicy landed), and 21 → 17 is a 19% reduction, not a halving. It could never have been one: the four twins were the only things this set removes, and the synchronous verbs they sat beside all remain, because bindModelBlocking dispatches to them by request shape — which is what lets an un-migrated backend keep working. Full before/after name lists are on #522.

What the twins carried that the surface does not

One thing, named rather than left to be found. A bool twin handed Bridge two raw std::functions, so a backend firing twice reached detail::parkIfInFrame's double-claim guard. A Completion cannot be settled twice — CompletionState drops the second settle before any Bridge code sees it — so DoubleFiringBackend now pins the observable contract ("exactly one onDone") while that guard is no longer reachable from a backend. Filed as #648, with the smaller sibling case (the catch (...) around the dispatch, now reachable in-tree only from a test double).

The prose threading contract is relocated, not deleted

The @note shared by the four twins asked every backend author to deliver from a thread on which ~Bridge could not run concurrently — #486's use-after-free. That reasoning now lives in docs/spec/core/backend.md under "What was wrong with the old shape" (what the contract was, and why registerHandlerImpl was the one site that did not depend on it) and "How the threading contract becomes structural" (what replaced it), plus docs/spec/concurrency_and_lifetimes.md's continuation bullet.

Per the runner decision recorded on #571, the claim is stated narrowly in all three places and in bridge.hpp's call-site comments: the guarantee is structural for backends; Bridge's four dispatch sites still name exec::detail::inlineExecutor(), which reproduces the old delivery thread exactly, so #486's window is unchanged, not closed. Closing it is #588 and is not here.

The ticket's "Also in scope" list is stale, and is not acted on

It asks for LocalBackend, SimulatedRemoteBackend and "the 11 test doubles" in test_switch_backend.cpp, test_bridge_lifetime.cpp and test_client_execute_deadline.cpp to be wrapped in SynchronousBackendAdapter. Measured on 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_client_execute_deadline.cpp:0
tests/test_bridge_lifetime.cpp:0
tests/test_switch_backend.cpp:0

None of them — nor LocalBackend, nor SimulatedRemoteBackend — overrides a twin, so none needs migrating: bindModel's default already routes them. Wrapping them would be a regression: the adapter answers kCallerMustNotBlock unconditionally, which would make registerHandler return an unbound handler to every in-process embedder — the exact regression #593 undid for SocketBackend. Full reasoning on #571.

Doubles that were migrated

tests/test_async_registration.cpp. AsyncRegisterBackend overrides bindModel (one verb, all three acquire shapes, deferred into the same completeNext()/failNext() queue) and answers kCallerMustNotBlock, which is what reproduces "dispatch and return without waiting". InlineCompletingBackend, ThrowingDispatchBackend, DoubleFiringBackend and AsyncBackendShim follow; AsyncAssignPrimaryBackend and SelfFiringAssignPrimaryBackend move to promoteModel.

One detail the twins hid, found by a test failing rather than by reading: ThrowingDispatchBackend must tell its two arms apart by request.primary, not request.current — attachHandlerAsync's first attach carries a zero current, so both tests landed on the same arm. tests/test_backend_registration_surface.cpp's RecordingBackend drops the twins and their four forwarding assertions; the adapter's forwarding test still pins every synchronous verb.

Spec section rename

backend.md's "Asynchronous registration — registerModelAsync" becomes "Why registration needs a non-blocking path", keeping the live content (the nested-QEventLoop/WASM rationale, the asyncRegistrationEnabled gate, the pre-connect queue, what an unbound handler means) and handing the history to "What was wrong with the old shape". Every citation is repointed: locality.md, bridge.md, shared_instances.md, three sites in include/morph/core/bridge.hpp, and three examples/ files. scripts/test_check_spec_citations.sh's rename fixture is repointed too, and its self-test still catches all sixteen drifts it claims to.

Two places still name the removed verbs, deliberately: backend.md's one paragraph saying what was removed, and shared_instances.md's one-line pointer to it. A spec that cannot name what it removed cannot explain the removal. The grep acceptance criterion is scoped to include src tests examples, and that is clean.

3 — gates

50a8569d, separate so no ticket's diff carries a number nobody read the code for.

scripts/mutation_survivors.json: three backend.hpp citations, two of them reported as "appears 2 times … not decidable" exactly as those entries' own reason text predicted. Resolved by reading both candidates, not by taking the first — registerCount → 1031 (LocalBackend::registerModel, not 1050's registerModelShared arm, which the reason names as the one it is not); executeInFlight → 1195 (immediately after fetch_add, not 1240's fetch_sub); reserve → 1138, unambiguous.

scripts/branch_partial_allowlist.json: backend.hpp:1414 → 1140, bridge.hpp:1551 → 1540, bridge.hpp:1673 → 1662. The last is ambiguous three ways; 1662 is the catch (...) block in executeVia, which is what that entry's reason describes, and the parenthetical naming the other two (1697, 1786) is updated to 1686, 1775.

One hit not edited: mutation_survivors.json's classification_2026_09_09 sample citing bridge.hpp:584 and started = backend->attachModelAsync(...). That is a dated record of a measurement, not a description of the tree; rewriting it would destroy the record. A note saying so is added beside the verdict.

---

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

• Is the deletion safe? The one claim the branch rests on: since qt: move QtWebSocketBackend onto the structural registration surface and delete the WASM special case #568 no backend in the tree overrode any twin, so every twin call returned false and every dispatch site already took the bindModel branch. Verified by grep on c55ea5b7 — the only overriders left were test doubles. Deleting a branch that never ran therefore changes no production path.
• Did anything only compile because a defaulted virtual existed? SynchronousBackendAdapter's four forwards, removed with them. Nothing else: the full-tree grep is empty and the build is clean with -Werror.
• The try/catch in attachHandlerAsync/ensureBoundAsync is kept, though bindModel's default rejects rather than throws. Removing it would be a behaviour change for an out-of-tree override, outside this ticket. Its comment now says what it actually guards. Recorded in core: parkIfInFrame's double-claim guard is unreachable from a backend now that every dispatch goes through one Completion #648.
• bindWaitPolicy forwarding in AsyncBackendShim is not cosmetic: without it the shim would answer the default kCallerMayBlock while its target defers forever, and switchBackend's phase 1 would park. Called out in the code.

What this does not claim

• A deletion going green proves only that nothing referenced the deleted thing. Beyond compilation: every test that previously drove the twin branch now drives the bindModel branch with the same double and asserts the same outcomes — inline settle, inline failure, synchronously-throwing dispatch, double-settle, the three staleness guards, the two teardown races. So the migration is checked by tests written against the twins' behaviour, not by new ones written against the replacement. The single exception is parkIfInFrame's guard (core: parkIfInFrame's double-claim guard is unreachable from a backend now that every dispatch goes through one Completion #648). No behavioural claim beyond that is made.
• core: IBackend has grown a parallel async shadow of four of its own methods #522 closes with a narrowed claim, per the runner decision on core: remove IBackend's four async twins and retire the prose threading contract #571: the duplication is gone and the surface is single, and the threading guarantee is structural for backends. For Bridge-mediated calls it is still carried by the delivery thread the backend chose — core: give Bridge an executor bound to its own thread, so the threading guarantee is structural for Bridge-mediated calls too #588.
• Nothing WASM was verified. No Emscripten toolchain was available, so morph_ladder_wasm_spike and every *_gui_wasm target were never configured, let alone built. ladder: move the example GUIs and the WASM spike onto the structural registration surface #570's "the WASM ladder clients build, and the WASM demo deploys" is unmet by local measurement and rests entirely on the wasm-ladder and wasm-demo CI legs.
• Not run locally: clang-tidy, any sanitizer build, and scripts/coverage.sh (so the branch-coverage and error-path gates' coverage halves are unverified; their line-hint halves were audited directly — see below).

Verification actually performed

Linux, GCC 16.2.1, Debug, -DMORPH_BUILD_TESTS=ON -DMORPH_BUILD_EXAMPLES=ON -DMORPH_BUILD_QT=ON -DMORPH_BUILD_NET=ON -DMORPH_BUILD_LADDER=ON -DMORPH_LADDER_RUNGS=all, build clean.

tests/morph_tests                          22931 assertions in 1556 cases   (1 failed as expected)
tests/qt/morph_qt_tests                      578 assertions in   79 cases
tests/net/morph_net_tests                   1112 assertions in  191 cases
tests/net_qt_interop/..._interop_tests         9 assertions in    2 cases
examples/common/ladder_common_tests          587 assertions in  153 cases

$ bash scripts/check_spec_citations.sh
Prose lint OK: every pinned fact is still cited; no banned terminology found; every cited path resolves; every cited section exists; every forms key and rule kind is documented.

$ bash scripts/test_check_spec_citations.sh
scripts/check_spec_citations.sh detects every section-citation and forms-vocabulary drift it claims to.

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

$ git diff --name-only origin/master HEAD | bash scripts/check_spec_sync.sh
Spec sync OK: 10 sub-domain(s) classified; every touched header sub-domain has a matching spec change.

$ bash scripts/check_catch_test_names.sh
checked 2986 test-case name(s) in 707 file(s)
Catch2 test-name lint OK: every discovered test name selects itself as a filter.

$ bash scripts/check_ctest_name_collisions.sh build
ok: 2886 ctest test names under build are unique

$ bash scripts/check_nolint_directives.sh
NOLINT directive lint OK: 164 NOLINTNEXTLINE directive(s), all annotating code.

$ bash scripts/check_rung_filters.sh
All 49 rung-filter checks passed.

$ bash scripts/check_tidy_suppression_scope.sh
ok: tests/.clang-tidy records the reach it actually has

Doxygen with WARN_AS_ERROR = FAIL_ON_WARNINGS builds clean (-DMORPH_BUILD_DOCUMENTATION=ON, target doc). clang-format --dry-run -Werror clean over every changed C++ file — with the caveat that the local binary is 22.1.8 and CI pins 20; I checked that v22 reports the unmodified tests/test_async_registration.cpp from origin/master as already clean, so the two agree at least on that file.

The branch-coverage and error-path allowlists' line hints were audited by calling check_branch_coverage.resolve_allowlist_source_line over every entry of both files: 0 failures each. Their coverage halves need build/clang-coverage/coverage.lcov, which was not produced.

Issues filed

• core: parkIfInFrame's double-claim guard is unreachable from a backend now that every dispatch goes through one Completion #648 — parkIfInFrame's double-claim guard is unreachable from a backend now that every dispatch goes through one Completion. Reasoned from the code, not from a coverage run; says so.
• Comment on core: SynchronousBackendAdapter::cancelPending settles the completion but the queued control call still registers on the wrapped backend #636 — core: remove IBackend's four async twins and retire the prose threading contract #571 neither helps nor hinders it; the queued _control task still runs inner->bindModelBlocking(...) and cancelPending is untouched.
• Comment on core: IBackend has grown a parallel async shadow of four of its own methods #522 — its virtual-count arithmetic, with the measurement.
• Comment on core: remove IBackend's four async twins and retire the prose threading contract #571 — its "Also in scope" list, with the greps.

---

4 — rebase onto f7c231df, and the two things that made clang-tidy-diff red

Rebased from c55ea5b7 onto f7c231df before anything else: #647 landed and
changed the very leg this section fixes — the clang-tidy job now builds two
*_autogen targets so the AUTOMOC self-including sources parse, and asserts
every self-included .moc exists. A CI result judged against the old base
would not have meant anything. Rebase was clean; no conflicts.

The failed run (35544723152) stalled with Linux / all optional features (clang) never starting, so its log is unreachable. The clang-tidy-report
artifact is the evidence, and it is reproduced below locally rather than taken
on trust.

4a — bugprone-exception-escape: a real finding, fixed on its merits

a7f8aba9

tests/test_async_registration.cpp:582:5: error: an exception may be thrown in
function '~SelfFiringAssignPrimaryBackend' which should not throw exceptions
[bugprone-exception-escape,-warnings-as-errors]
  note: frame #0: unhandled exception of type 'bad_weak_ptr' may be thrown in
        function '__throw_bad_weak_ptr' here
  note: frame #5: function 'setValue' calls function 'shared_from_this' here
                                      include/morph/core/completion.hpp:108
  note: frame #6: function 'resolve' calls function 'setValue' here
  note: frame #7: function '~SelfFiringAssignPrimaryBackend' calls function
        'resolve' here

This double settles its one still-pending ModelCompletion from inside its
own destructor — the only way to reach assignHandlerPrimary's !pinned arm.
A destructor is implicitly noexcept, so an escape is std::terminate with
no attribution, not a failed assertion.

The named bad_weak_ptr is a static over-approximation: the Promise holds a
shared_ptr to the state, so shared_from_this() cannot fail here. The
obligation is not an over-approximation, because setValue also runs the
continuation Bridge::assignHandlerPrimary attached, inline, on this thread,
and that is ordinary caller code.

So: try/catch (...), and the catch records into an std::exception_ptr
the test owns and CHECKs after the backend is gone. A NOLINT would have
kept the terminate; a bare catch (...) {} would have turned it into
silence. The new CHECK is what stops the arm being a swallow.

Not bundled with 4b's suppression, deliberately — that is how a real defect
gets hidden behind an environmental one.

4b — the five TUs this configure cannot build: the gate is wrong, not the diff

3c6dd24f, .github/workflows/ci.yml only.

The other 21 findings were all clang-diagnostic-error, from five changed
sources this branch edits in comments only. A changed comment line is a
changed line, so clang-tidy-diff analysed five TUs nothing had ever analysed:
four WASM mains needing an Emscripten/Qt-WASM toolchain the job does not
configure, and
tests/compile_checks/client_only_facade_no_model_header.cpp, which is built
by a configure-time try_run() with -DMORPH_CLIENT_ONLY and deliberately
omits model.hpp — the artifact's note chain resolves every bridge.hpp,
registry.hpp and model.hpp error to that one TU.

Reverting the comment edits was checked and is not available. Those four
WASM comments cite a docs/spec/core/backend.md section this branch renames,
so leaving them at their old text turns the spec-citation gate red instead —
measured, by actually reverting them and running the script:

::error file=examples/bookmarks/gui_wasm/main_wasm.cpp,line=88::dangling section citation: docs/spec/core/backend.md has no section "Asynchronous registration"
::error file=examples/pastebin/gui_wasm/main_wasm.cpp,line=78::dangling section citation: ...
::error file=examples/polls/gui_wasm/main_wasm.cpp,line=254::dangling section citation: docs/spec/core/backend.md has no section "Asynchronous registration"
::error file=examples/polls/gui_wasm/main_wasm.cpp,line=254::dangling section citation: docs/spec/core/backend.md has no section "Shared/keyed registration"

This is the third instance of one structural problem (#624 a generated
header, #650 tests/lint/ fixtures, this), so the fix generalises rather than
special-casing five paths. The diff is filtered before clang-tidy-diff.py
sees it:

• a changed source with no entry in compile_commands.json is dropped and
  named in the log with a ::warning::;
• a changed header is never dropped — a header is never a translation
  unit, and discarding headers is exactly -only-check-in-db's behaviour and
  clang-tidy-diff CI gate cannot fail: its exit status is tee's, and -extra-arg=-warnings-as-errors=* errors on every file #479's defect one directory over;
• sections are kept or dropped whole, never hunk by hunk, because
  clang-tidy-diff.py attributes @@ lines to the last +++ it saw.

What keeps the filter from being a control that measures nothing. It
refuses to run unless the database is still the wide one the Configure step
builds: ≥600 in-workspace sources, ≥200 under examples/. Counting only paths
that resolve inside the workspace means a resolution mismatch trips the
floor too, instead of silently skipping everything. Measured here: 703 entries
naming 695 distinct in-workspace sources, 270 under examples/; CI measured
690/276 at #481's revision. The regression the floors exist to catch —
MORPH_BUILD_LADDER back to its OFF default — takes examples/ to 16, not to
199.

No path list is hard-coded anywhere; the exclusion is derived from the tree on
every run.

Verification for section 4 — measured, with the flag set that matters

Everything below ran the gate itself, not a bare clang-tidy file.cpp -- -std=c++23 (which enables none of the warnings CI builds with and reports
clean on broken code). That means: this job's exact configure
(clang-debug + the nine MORPH_BUILD_* flags), the two *_autogen targets
#647 added, clang-tidy-diff.py, clang-tidy 22.1.8 (CI's pinned major),
-p1 -extra-arg=-std=c++23 -extra-arg=-Wno-missing-include-dirs -quiet.
Findings are recognisable by ending [check-name,-warnings-as-errors].

	result
gate on the branch before these two commits	exit 1, 22 findings: 21 clang-diagnostic-error from the 5 unbuilt TUs + 1 bugprone-exception-escape
gate on the branch after	exit 0, no findings; 26 of 31 changed file section(s) analysed, 5 source(s) skipped as unbuilt here
mutation — unguarded destructor re-introduced, filter still on	exit 1, bugprone-exception-escape at the moved line 609
Python embedded in the YAML, extracted back out of the parsed workflow	byte-identical filtered diff to the standalone version tested
bash -n on the edited step	clean
check_workflow_job_banners.py	ok: all 24 section banner(s) introduce the job they describe
check_ci_clang_pin.sh	ok: all 7 CI-clang-pin assertion(s) agree with .github/workflows/ci.yml
check_workflow_option_coverage.py	16 MORPH_BUILD_* option(s) declared, all accounted for
check_spec_citations.sh	Prose lint OK: ...
clang-format --dry-run -Werror on the changed test	clean
tests/morph_tests (clang 22 Debug)	22932 assertions in 1556 cases — the branch's 22931 plus this commit's one CHECK — 1 failed as expected

Not verified, plainly: no Emscripten toolchain here, so nothing was built
for the four WASM mains — the only claim made about them is that this job
cannot analyse them, which is what their absence from compile_commands.json
shows. The workflow step was validated as its parts (bash -n, the extracted
Python, the pipeline) rather than executed as one script. Everything section
3's "What this does not claim" already said still stands.

Issues filed for section 4

• 60 of 470 tracked C/C++ sources are outside clang-tidy-diff's reach, and 11 of them only because one CMake flag is missing #651 — 60 of 470 tracked C/C++ sources are outside the gate's reach;
  11 of them (examples/bank/gui, examples/bank/tests) only because the
  job does not pass -DMORPH_BUILD_BANK_GUI=ON, which linux-all-features
  already does. Split by cause, with what is cheap and what is not.
• Comment on tests/lint/ fixtures are inside clang-tidy-diff's scope, and nothing tells the author that until CI is red #650 — its option list changes: tests/lint/ fixtures are
  now filtered out and named, so no new fixture directory costs a red round.
  The documentation half of that issue is untouched.
• Probed and clean, so nothing filed: bugprone-exception-escape over the
  three compiled production sources reports nothing, so 4a's shape does not
  occur outside the test double.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01VptDWG2fKr2vBnLSJcgzgW

[Yaraslaut]

Runner verification — the conclusion holds, the stated inventory does not

The claim this branch rests on: "Since #568, no backend in the tree overrode any of the four twins … the only overriders left were test doubles in tests/test_async_registration.cpp and tests/test_backend_registration_surface.cpp."

The inventory is incomplete. A shipped type overrides all three twins:

class owning line 1049 -> 913: class SynchronousBackendAdapter : public detail::IBackend {

include/morph/core/backend.hpp:1049:    bool registerModelAsync(…) override {
include/morph/core/backend.hpp:1067:    bool registerModelSharedAsync(…) override {
include/morph/core/backend.hpp:1084:    bool attachModelAsync(…) override {

SynchronousBackendAdapter is production code, not a test double. My first attempt to check this missed it too — I grepped for override on the same line as the name, and these signatures wrap, so the grep returned nothing and proved nothing.

But the conclusion survives, because the override is a pass-through:

bool registerModelAsync(…) override {
    return _inner->registerModelAsync(typeId, std::move(factory), contextKey,
                                      std::move(onRegistered), std::move(onError));
}

It returns whatever the wrapped backend returned, so it cannot make the twin branch run unless something beneath it returns true. Nothing does:

$ # twin declarations anywhere in the tree, any extension, at c55ea5b7
  none outside backend.hpp + tests/test_async_registration.cpp
                           + tests/test_backend_registration_surface.cpp

$ # the two production remote backends
  include/morph/net/socket_backend.hpp            0 occurrences
  include/morph/qt/qt_websocket_backend.hpp       0 occurrences

#586/#587 and #585 had already moved both onto the structural surface. So every twin call in production reached the base default and returned false, every dispatch site took the bindModel branch, and deleting a branch that never ran changes no production path — which is the claim as it matters. Confirmed.

Worth restating precisely, because the difference will matter to the next reader: the correct statement is not "nothing overrides the twins" but "nothing implements them — the one production override forwards, and no forwardee implements them either." A forwarder in the inventory is not a counterexample, but leaving it out makes the claim look falsifiable by a one-line grep that anybody will run.

The examples/ finding checks out, and it is the more interesting half of #570: all occurrences under examples/ are prose. Spot-checked four files — bookmarks/gui/main.cpp:98, common/gui/app_context.hpp:62, common/testkit/test_wasm_registration_path_native.cpp:39,41, polls/gui_wasm/main_wasm.cpp:136,252 — every one is a //, /// or Markdown line describing QtWebSocketBackend::registerModelAsync(), a method that stopped existing in that form at #585. So #570 was indeed a documentation ticket wearing a migration ticket's clothes, and saying so beats quietly shipping a no-op migration.

Accepting both judgement calls. Keeping the removed verbs named in backend.md's "What was wrong with the old shape" is right — a spec that cannot name what it removed cannot explain the removal, and #571's acceptance grep is scoped to include src tests examples, which is clean. The section rename with its 10 repointed citations is the kind of churn that is cheaper now than later.

Not merged: CI incomplete at hand-off. The legs to watch are the two the lane could not run locally — Build the ladder's WASM clients and Build & deploy WASM demo — plus clang-format for the 22-vs-20 skew, and Linux / clang-coverage for the coverage halves of the two allowlists whose line-hint halves were audited directly.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VptDWG2fKr2vBnLSJcgzgW

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Yaraslaut]

Runner, landing sweep 02:41: this PR is red on clang-tidy-diff (51 pass, 1 fail, 1 pending). Its run (35544723152) is still in progress, so the job log is not retrievable yet and I am not guessing at the cause from the diff. Queued for the next sweep, which reads the completed log first. Note that #647 landed in the meantime (master is now f7c231df) and it changed this very leg — it now builds two *_autogen targets so the two AUTOMOC self-including sources parse. That is a gate change under .github/workflows/, so this PR will need a rebase before it can be judged regardless of what the log says.

[Yaraslaut]

Runner: diagnosed — the red is not in this PR's code

The run has been stalled for over an hour (Linux / all optional features (clang) pending at 0 elapsed, run last updated 23:49Z), so the job log is unreachable. I read the clang-tidy-report artifact instead, which the step uploads with if: always().

Every finding is a clang-diagnostic-error from a TU that cannot parse in this job's configure, in a file this PR edits only in comments.

examples/bookmarks/gui_wasm/main_wasm.cpp:58:10: error: 'QGuiApplication' file not found
examples/common/wasm_spike/main_wasm.cpp:47:29:  error: expected ')'
examples/pastebin/gui_wasm/main_wasm.cpp:50:10:  error: 'QGuiApplication' file not found
examples/polls/gui_wasm/main_wasm.cpp:178:10:    error: 'emscripten/emscripten.h' file not found
include/morph/core/bridge.hpp:1610:43:           error: no matching member function for call to 'into'
include/morph/core/bridge.hpp:2667:37:           error: no matching member function for call to 'executeVia'

The two bridge.hpp errors are not bridge.hpp's. The notes chain them to their origin:

bridge.hpp:1610 … note: in instantiation of 'Bridge::executeVia<ClientOnlyFacadeModel, …>'
                 note: requested here → tests/compile_checks/client_only_facade_no_model_header.cpp:53
                 note: candidate template ignored: substitution failure [with Model = ClientOnlyFacadeModel]

That TU deliberately omits model.hpp — it exists to prove the client-only facade compiles without it — so ClientOnlyFacadeModel is incomplete by design and the failure cascades into templates attributed to the header. Not a defect in this branch's changes.

Why it appeared now: this PR edits all six of those files, and every edit is prose. For example:

-// Bridge::registerHandler(binding) (registerModelWithContext has no async
-// path for LocalBackend -- see IBackend::registerModelAsync's doc comment),
+// Bridge::registerHandler(binding) (LocalBackend does not override bindModel,
+// so IBackend's default runs registerModelWithContext inline -- see
+// IBackend::bindModel's doc comment), so the factory must succeed

A changed comment line is a changed line, so clang-tidy-diff analysed six TUs that nothing had ever analysed — four needing an Emscripten/Qt-WASM toolchain this job does not configure, and one designed to be incomplete.

This is the third instance of one structural problem, and it is worth naming as such rather than fixing three times: #624 (the two AUTOMOC self-including sources), #650 (tests/lint/ fixtures green only by accident of content), and now this. The rule nobody has written down is editing a line in a file the clang-tidy configure cannot build turns that file red, and there is no signal until CI says so — and the #570 half of this PR is a pure documentation change, which is the least likely way anyone expects to trip a compiler gate.

Also one real finding, unrelated to the above and not to be lost in it: 1 × bugprone-exception-escape. That one is worth reading properly rather than suppressing with the rest.

Dispatching a lane whose whole batch is this PR, with this artifact. It also needs a rebase independently: #647 landed and changed this leg, which is a gate delta.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VptDWG2fKr2vBnLSJcgzgW

[Yaraslaut]

Runner verification — the gate change, checked by driving it, not by reading it

This PR now changes clang-tidy-diff's scope, and AGENTS.md lists "a filter over an invariant body" among the failure modes this repository has actually hit. So I extracted the filter from the parsed workflow (95 lines, via yaml.safe_load → the step's run → the heredoc) and drove it against synthetic databases.

It keeps what it must keep. A diff touching three files, against a database clearing both floors:

::warning file=examples/unbuilt_wasm.cpp::not analysed by clang-tidy-diff: this configure
    builds no translation unit for it …
ok: compile database names 660 in-workspace source(s) (240 under examples/);
    2 of 3 changed file section(s) analysed, 1 source(s) skipped as unbuilt here
exit=0

sections kept:
    +++ b/src/f1.cpp                        (source, in the database)
    +++ b/include/morph/only_a_header.hpp   (header, NOT in the database — kept)

The header is kept although nothing in the database names it, which is the property that separates this from -only-check-in-db and from #479's defect. A dropped source is named in a ::warning file=, so a skip is visible in the run rather than silent.

The floor trips in both directions, and the second floor is not redundant:

420 src + 16 examples   (the MORPH_BUILD_LADDER=OFF shape)  -> ::error:: … exit=1
660 src + 150 examples  (wide overall, thin in examples/)    -> ::error:: … exit=1

That second case is the one I most wanted to see fail: a configure that still looks big while examples/ has collapsed would otherwise let the filter swallow the ladder without anyone noticing. It does not.

Accepting the forced choice on its evidence. The cheap option — revert the comment edits — was not available, and the lane established that rather than asserting it: the four WASM comments cite a docs/spec/core/backend.md section this branch renames, and reverting them produces four dangling section citation errors from check_spec_citations.sh. So any edit at all puts those files in the diff, and the gate had to change.

The residual, stated plainly because a filter's cost is what it stops seeing: a source that drops out of the database without breaching either floor is skipped with only a warning. #651 quantifies that at 60 of 470 tracked C/C++ sources, and usefully splits it by cause — 11 only because this job does not pass -DMORPH_BUILD_BANK_GUI=ON (which linux-all-features already does, so those are recoverable), 36 not translation units by design, 13 WASM with no lint job anywhere. The 11 are the interesting ones and I would rather see them fixed than filtered, but that is #651's business, not this PR's.

On the real finding: keeping bugprone-exception-escape out of the group-1 fix was right, and the fix is better than a NOLINT — the catch (...) records into an exception_ptr the test CHECKs after destruction, so an escape becomes a named test failure instead of std::terminate. The lane also probed the three compiled production sources for the same destructor shape and found none, and filed nothing — the correct outcome for a clean probe.

Not merged: CI incomplete at hand-off. Next sweep counts the checks — and the check to watch is clang-tidy-diff itself, whose own behaviour this PR changes.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VptDWG2fKr2vBnLSJcgzgW