Skip to content

docs: LADDER.md's framework prerequisites have all shipped - #273

Open
Yaraslaut wants to merge 2 commits into
masterfrom
docs/271-ladder-stale-prereqs
Open

docs: LADDER.md's framework prerequisites have all shipped#273
Yaraslaut wants to merge 2 commits into
masterfrom
docs/271-ladder-stale-prereqs

Conversation

@Yaraslaut

Copy link
Copy Markdown
Member

Closes #271.

Wider than reported

#271 reports that item 1 of LADDER.md's "Framework prerequisites" is stale.
Checking the other three found the same thing — all four have shipped:

# prerequisite shipped as
1 async shared/keyed attach for WASM IBackend::registerModelSharedAsync (backend.hpp:187), attachModelAsync (:286), consumed by Bridge::ensureBoundAsync/attachHandlerAsync, implemented by QtWebSocketBackend
2 client-side execute deadline Bridge::setExecuteDeadline (bridge.hpp:1099)
3 injectable time source setNowOverride / ScopedNowOverride (util/datetime.hpp) — precisely the "process-global now-provider convention" the item asks for
4 fault-injection wire proxy examples/common/testkit/fault_proxy.hpp, with strand_interleaver.hpp alongside it exactly as the item promised, both tested

The section opens with "Adversarial review found four items that invalidate
rung definitions-of-done as written
"
— so as it stood, it told a reader that
four things block the ladder when none of them do.

Kept, not deleted

The section explains why the rungs were sequenced as they were, which is still
worth knowing. What changes is its status: each item now says where it
landed, so a reader can check rather than take the document's word for it.

The "Also queued deliberately" paragraph

Same problem, but the three claims aged differently, so I didn't sweep them
together:

  • offline queue depth bound — shipped (IOfflineQueue::maxDepth() +
    OfflineQueueFullError, reject-newest)
  • SyncWorker's 5-attempt capstill hard-coded at 5, so that half
    stands. What changed is that the surfacing hook rung 4 needs now exists
    (SyncWorker's DeadLetterSink parameter), making "surface dead-letters in
    the UI, not logs" buildable rather than blocked
  • SQLITE_BUSY waits occupying pool threadsleft untouched. It's a
    claim about runtime pool starvation, not about whether a symbol exists, and
    reading headers cannot settle it

Verification

Every path and symbol I wrote into the document was checked to exist first — 8
paths and 10 symbols. That felt worth doing explicitly here: writing an
unverified claim into a ladder document is the exact failure this PR is fixing.

Documentation only; scripts/check_spec_citations.sh passes.

Related

This is the fourth instance of the same defect class. #269 (TESTING.md +
polls/README.md: execute deadline and pendingCalls()) and #270
(polls/README.md: async attach) cover the other two files; both collide with
open PR #261 and are best done as one pass once it lands. LADDER.md is
collision-free, which is why this one goes first — and it is the document the
other two cite.

The "Framework prerequisites (schedule as issues now, not rung discoveries)"
section opens with "Adversarial review found four items that invalidate rung
definitions-of-done as written". All four have since shipped. morph#271 reports
item 1; checking the other three found the same thing:

  1. async shared/keyed attach -> IBackend::registerModelSharedAsync (backend.hpp:187)
     and attachModelAsync (:286), consumed by Bridge::ensureBoundAsync /
     attachHandlerAsync, implemented by QtWebSocketBackend
  2. client-side execute deadline -> Bridge::setExecuteDeadline (bridge.hpp:1099)
  3. injectable time source -> setNowOverride / ScopedNowOverride
     (util/datetime.hpp) -- precisely the "process-global now-provider
     convention" the item asks for
  4. fault-injection wire proxy -> examples/common/testkit/fault_proxy.hpp, with
     strand_interleaver.hpp alongside it as the item promised, both tested

The section is kept rather than deleted: it explains why the rungs were
sequenced as they were, which is still worth knowing. What changes is its
status -- each item now says where it landed, so a reader can check instead of
taking the document's word.

The "Also queued deliberately" paragraph had the same problem and is corrected
with more care, because the three claims did not age the same way:

  - offline queue depth bound: shipped (IOfflineQueue::maxDepth() +
    OfflineQueueFullError, reject-newest)
  - SyncWorker's 5-attempt cap: *still* hard-coded at 5, so that half stands.
    What changed is that the surfacing hook rung 4 needs now exists
    (SyncWorker's DeadLetterSink parameter), which makes "surface dead-letters
    in the UI, not logs" buildable rather than blocked
  - SQLITE_BUSY waits occupying pool threads: left untouched. It is a claim
    about runtime pool starvation, not about a symbol's existence, and reading
    headers cannot settle it

Every path and symbol cited above was checked to exist before being written
down -- the failure mode this section is an instance of.

Closes #271
@Yaraslaut
Yaraslaut force-pushed the docs/271-ladder-stale-prereqs branch from c42d2e4 to 7a6ded0 Compare August 24, 2026 21:15
@codecov

codecov Bot commented Aug 24, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

…deadline

The 'event sequences / polling' entry told a reader the polling helper must wrap
its own timeout because 'a rate-limited server drops frames silently and morph
has no client-side execute deadline'. Both halves have since changed:
Bridge::setExecuteDeadline bounds the wait, and the transport answers a
rate-limited frame rather than dropping it (morph#225).

Found while combining #269 and #270 -- grepping for the stale phrasing across
examples/ turned this up in the file this PR already owns, so it belongs here
rather than in a second PR touching LADDER.md.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

examples/LADDER.md's async shared/keyed attach 'framework prerequisite' also shipped

1 participant