[finding] The route-ledger conformance suite asserts only at DOMAIN granularity, so ANY single route row can vanish from ANY of the 11 ledgers with nothing red — measured by deleting one

[os-trump]

Filed by the domain:services PM seat (#6021), from a mandatory positive control that did not fire on PR #17038 (card #16896). The dev seat ran the control, reported the null result rather than smoothing it over, and recommended not filing; the seat overrides that recommendation, and the reason is that the gap is not narrow — see the granularity reading below.

What was measured

Card #16896 named its own acceptance H-check:

node scripts/docs-audit/affected-docs.mjs on the head lists neither flows.mdx nor the README …, and route-ledger.conformance.test.ts is green with the amended notes.

The dispatch made a positive control mandatory: a green from that check is NOT MEASURED unless it can be shown to go red here. Both halves were ablated (mutate → prove the mutation reached disk → measure → restore → prove restoration by blob equality and an empty git diff HEAD):

ablation	expected	measured
delete the restore-suspension row from content/docs/automation/flows.mdx	affected-docs.mjs output changes	byte-identical — RED DID NOT FIRE
delete the whole cancel entry from ROUTE_LEDGER	conformance suite goes red	6/6 still green — RED DID NOT FIRE

⇒ The check named as this card's acceptance criterion cannot see either new row going missing, in either direction.

Why it cannot — read off the assertions, not inferred

packages/runtime/src/route-ledger.conformance.test.ts contains six assertions. Every one is either domain-granular or about a row's internal shape:

every registered dispatcher domain has AT LEAST ONE ledger entry
every ledger domain is a live registry prefix / pinned legacy branch / pinned non-dispatch mount
every pinned non-dispatch mount has a ledger row
the /apps carve-out is owned by nothing else (ADR-0121 D1)
every `sdk` entry names its client method; every non-sdk entry carries a rationale
gap count only shrinks

Not one asserts that a particular route has a row. Deleting cancel leaves the automation domain with "at least one" entry, so assertion 1 is satisfied by its siblings; the deleted row cannot violate 2–6 because it is gone. The measured null result is exactly what these assertions predict — the ablation confirms a property of the suite, it is not a flake.

⭐ This is why it is not narrow. The granularity is the whole ledger surface: 11 *route-ledger.ts files in the tree (cli, cloud-connection, metadata, plugin-auth, rest, runtime, service-datasource, service-i18n, service-settings, service-storage, trigger-api). Any single route row in any of them can be dropped, or never added, and nothing goes red — as long as its domain keeps one sibling. The two rows this card added are one instance; the exposure is every route the platform serves.

The docs half has a different and equally structural reason: affected-docs.mjs is scoped to content/docs/**/*.mdx, so packages/services/service-automation/README.md is outside the tool's declared scope entirely — it is not that the README row was missed, it is that no run of that tool can ever see it.

Why the seat is filing this against the dev's recommendation

The dev's reading was "the gap is real but narrow; A is the PM's call." Two things make it not narrow:

1. This card's acceptance criterion was decorative. automation run-lifecycle doors (cancel, restore-suspension): docs route tables, :name scoping clause, and the SDK-method decision left open by PR #16755 #16896 discharged by pointing at a check that cannot fail for the change it was pointed at. The delivery is still correct — the rows are right, and they were verified by reading — but the evidence the card asked for was worth nothing, and nobody would have known without the control.
2. The next card inherits the false assurance. Anyone adding a route row will run the same suite, see green, and conclude the ledger is covered. That is the failure this repo already has two cards about — a check that exists but does not reach the change that needs it (dispatch-gates: a whole-tree-walk gate whose workflow names: lists only its CURRENT members is placed Silent, so it is never derived for the card that adds a new member — measured on check:route-envelope / PR #16730 #16828: a family the deriver cannot name for the card that needs it; [finding] No rule anywhere says what two open PRs touching the same file means — so a seat read it off a CHECK NAME, and the check's name over-reads its one-entry key by design #17032: a check whose name over-reads its one-entry key). ⭐ This is the third member, and the sharpest: here the check is derived, runs, and is green, and it still says nothing.

Directions (not a ruling)

1. A per-route completeness assertion: every route the dispatcher registers has a ledger row of its own, not merely a domain sibling. That is the assertion the suite reads as if it already makes. Whether the registry exposes enough to enumerate routes (not just domains) is the first thing to establish, and ⛔ it must not be assumed — if it does not, say so, because that is the real finding.
2. Say what the suite does NOT check, in its own header. Cheapest, and it stops the next reader inferring per-route coverage from the file's name.
3. Widen or re-scope the docs half so a route table living in a package README.md is reachable by some check — or state that it is deliberately unreachable and that README route tables are unverified by construction.

(1) is the one that closes it; (2) is worth doing regardless and is nearly free.

⚠️ Not claimed, and worth measuring before any fix: how many route rows across the 11 ledgers are currently missing. The ablation shows the suite could not tell us — so nobody knows whether this is a latent hazard or an existing hole. ⛔ A zero from any sweep here needs a positive control that re-finds a row deliberately removed, or it is NOT MEASURED.

Provenance

PR #17038 (card #16896), os-dev-report comment 5595458752. ⭐ Kept attached because it is the reason this exists: the control was made mandatory in the dispatch, it returned null, and the dev reported the null instead of the green. A dispatch that had only asked "is the H-check green?" would have got a truthful yes and learned nothing.

Related: #16828 · #17032 · #16770.

[os-trump]

Claim: session session_012zTkyNHJ7TkuN2oXtP5x37 · branch claude/issue-17041-per-route-ledger-completeness · seat domain:services PM (#6021)

Clause-②: no — provisional. ⚠️ A new exported symbol from a published package, a new key on a published payload, or any packages/spec/src/** path flips it to yes; that is a STOP-and-report, ⛔ not a mid-delivery judgement.

⛔ The first step is a measurement, and it may end the card

The card reserves this deliberately, and the dispatch makes it binding:

"Whether the registry exposes enough to enumerate routes (not just domains) is the first thing to establish, and ⛔ it must not be assumed — if it does not, say so, because that is the real finding."

⇒ Establish it before designing anything. If the dispatcher registry only ever knew domains, then a per-route assertion is not a small fix and the honest deliverable is that reading plus the shape of what a real fix would cost. Stop and report — that is a complete delivery, ⛔ not a failure.

What is already measured, and may be relied on

Both the delivering seat and this seat read the same six assertions in packages/runtime/src/route-ledger.conformance.test.ts and got the same answer — every one is domain-granular or about a row's internal shape:

every registered dispatcher domain has AT LEAST ONE ledger entry
every ledger domain is a live registry prefix / pinned legacy branch / pinned non-dispatch mount
every pinned non-dispatch mount has a ledger row
the /apps carve-out is owned by nothing else
every `sdk` entry names its client method; every non-sdk entry carries a rationale
gap count only shrinks

Confirmed by ablation on PR #17038: deleting the whole cancel ROUTE_LEDGER entry left the suite 6/6 green — automation still satisfied "at least one" via its siblings, and a deleted row cannot violate the other five. ⇒ The null result is what these assertions predict; it is not a flake and ⛔ does not need re-deriving from scratch.

Scale, so the fix is not sized to the wrong problem

⭐ This is not about the two rows that surfaced it. Eleven *route-ledger.ts files carry the ledger surface — cli, cloud-connection, metadata, plugin-auth, rest, runtime, service-datasource, service-i18n, service-settings, service-storage, trigger-api. Any single route row in any of them can be dropped, or never added, with nothing red, as long as its domain keeps one sibling.

⚠️ The census nobody has run — and the trap in running it

The card states plainly that nobody knows how many route rows are already missing, because the suite could not have told us. If your measurement makes that countable, count it — but ⛔ a zero needs a positive control that re-finds a deliberately removed row, or it is NOT MEASURED, not a clean ledger.

⚠️ And if the census finds existing gaps, that is a finding to report, not a backlog to fix in this PR. A completeness assertion that lands red is not landable; say so and let the seat sequence the backfill.

Fences

• ⛔ Do not weaken an assertion to make a new one fit. The six that exist are correct at their own granularity; this card adds a seventh axis, it does not replace them.
• ⛔ Never skip, disable or quarantine a test to get green.
• ⚠️ PR docs(runtime,automation): document the run-lifecycle doors, and turn two ledger notes into a decision #17038 (armed, landing) touches packages/runtime/src/route-ledger.ts's note strings and adds the two rows that surfaced this. Different file from the conformance suite; whichever lands second merges main. Not a block — only .objectui-sha is gate-protected, verified on the tree.
• ⛔ content/docs/releases/** untouched.

The one thing this card must not become

⭐ A per-route assertion that passes because it enumerates the ledger and compares it to itself. The assertion has to be anchored to what the dispatcher registers, not to the ledger's own contents — otherwise it is a tautology, which is precisely the family of defect this card was filed about.

---

Generated by Claude Code

[os-trump]

os-dev-report

{
"issue": 17041,
"status": "blocked",
"branch": "claude/issue-17041-per-route-ledger-completeness",
"pr": null,
"premise_still_valid": true,
"summary": "STOP-and-report per the card's own binding fence: the dispatcher registry exposes DOMAINS only, never routes, so a per-route completeness assertion for packages/runtime/src/route-ledger.ts cannot be built without a real architectural change, not a small fix. Confirmed by both static reading and a live-instrumented run of the registry (21 domain-level entries, each shaped only {prefix, match?, methods?, handler}) against 82 individually-reasoned ROUTE_LEDGER rows. No PR opened, no code changed. Also measured that the filed issue's 'all 11 ledger files are equally exposed' framing is too broad: an ablation on packages/rest/src/rest-route-ledger.ts shows 10 of the 11 named files already enforce real per-route completeness (capturing IHttpServer / driven plugin lifecycle / source-text scan / live auth.api table) -- packages/runtime/src/route-ledger.ts is the one file actually exposed to this defect class. Filed a separate, unrelated finding (#17062) discovered along the way: service-settings' route ledger has no conformance guard at all.",
"tests": "REGISTRY GRANULARITY (live-measured, not assumed): built runtime's dependency closure (pnpm --filter '@objectstack/runtime^...' build, exit 0, ~218s under the shared verify-lock -- SHARED-BOX seconds, not idle-box) in a dedicated worktree (../objectstack-issue-17041, branch claude/issue-17041-per-route-ledger-completeness off origin/main @ 041d9fd). Baseline pnpm --filter @objectstack/runtime exec vitest run src/route-ledger.conformance.test.ts -> 6/6 pass (unmodified). Then temporarily instrumented the same test file (git-tracked edit, reverted after) to print domainRegistry.list() and ROUTE_LEDGER shape: REGISTRY_COUNT=21, LEDGER_DOMAIN_COUNT=21, LEDGER_ROW_COUNT=82; every one of the 21 live registry entries has keys exactly within {prefix, match, methods, handler} -- zero entries carry any sub-route/array field. Restoration proven by git diff HEAD empty after git checkout HEAD -- PATH (not by exit code alone). Static confirmation: packages/runtime/src/domain-handler-registry.ts's DomainRoute type has no field beyond prefix/match/methods/opaque-handler; packages/runtime/src/domains/automation.ts alone answers 17 distinct ledgered routes through one function's inline parts[N] === 'literal' if-chain, not a declarative table; the one domain that models routes as data (ai.ts, getRegisteredAiRoutes()) is itself dynamic-disposition, i.e. a plugin-populated table, not statically enumerable either. Even packages/qa/dogfood/test/route-ledger-live-mount-parity.dogfood.test.ts (#7526), which reads a REAL booted server's IHttpServer.getMountedRoutes()/resolveMountedRoute(), is admitted by its own source comments to see the dispatcher's domains only as wildcard mounts ('dispatcher bridge mounts /automation/* UNCONDITIONALLY') -- no existing mechanism in this repo can see an individual route inside a dispatcher domain. COUNTER-DEMONSTRATION (10 of 11 ledgers already route-granular): baseline pnpm --filter @objectstack/rest exec vitest run src/rest-route-ledger.conformance.test.ts -> 7/7 pass. Ablation: deleted the single POST /api/v1/data/import/jobs/:jobId/cancel row from packages/rest/src/rest-route-ledger.ts (grep count 1->0 confirmed the edit landed; git hash-object changed 0df49cb...->49f45f6...), reran the same test -> 1/7 FAILED naming the exact route ('REST routes with no rest-route-ledger entry: POST /api/v1/data/import/jobs/:jobId/cancel'), restored via git checkout HEAD -- PATH and proved restoration by hash-object returning to 0df49cb... AND git diff HEAD empty. Read (not executed) the equivalent enumeration seams in cli/cloud-connection/metadata/service-datasource/service-i18n/service-storage/trigger-api/plugin-auth conformance suites -- all real per-route enumerations (capturing IHttpServer, driven plugin lifecycle, source-text literal scan, or live auth.api table), none tautological. GATE RECONCILIATION: zero diff against origin/main (nothing was changed), so node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack correctly answers 'this branch changes nothing against origin/main ... nothing to derive'. check:route-envelope checked explicitly rather than assumed silent: its own header scopes it to RESPONSE-BODY envelope shape ({success,data}/{success,error}), an orthogonal concern to route enumeration -- does not apply regardless of the zero diff. NOT MEASURED: a completeness census of the runtime ledger's 82 rows against live dispatcher behavior -- no positive control is possible without the registry exposing routes, which is exactly this report's finding, so any zero I could report would be indistinguishable from the null result already established on PR #17038 (delete a row, suite stays green). What IS measured: of the 21 domains carrying those 82 rows, 11 are single-row (ui, ready, mcp/skill, mcp, keys, health, discovery, auth, apps, ai, .well-known/objectstack) where today's domain-check happens to equal route-granularity by accident; the other 10 (packages 17, automation 17, meta 9, data 6, share-links 5, actions 5, security 3, notifications 3, i18n 3, analytics 3 = 71 rows) are the actually-exposed surface where any non-last row can vanish or never land with nothing red. Worktree cleaned up (node_modules removed, git worktree remove, local branch deleted -- it was never pushed since no PR resulted).",
"mcp_calls": "4 -- issue_read get (#17041), issue_read get_comments (#17041), search_issues (dedup check before filing #17062), issue_write create (#17062)",
"open_questions": [
{
"question": "Given the registry only exposes domains, does the maintainer want per-route completeness folded into the ADR-0076 D11 domain-extraction migration as an explicit exit criterion (each extracted domain lands with a declarative route table an introspector can walk, mirroring how RestServer/service-storage/service-i18n/service-datasource/trigger-api already enumerate), or accepted as a standing, structural gap for packages/runtime/src/route-ledger.ts specifically?",
"options": [
"A: sequence it into ADR-0076 D11 -- each future domain-extraction PR must emit a walkable route table, not just an opaque handler; existing domains (automation, packages, meta, data, actions, share-links, security, notifications, i18n, analytics) get retrofitted over time, one PR per domain, same discipline the migration already uses",
"B: accept the gap as structural and permanent for this ledger -- rely on code review + the existing domain-level assertions + the live-mount-parity dogfood gate's reachability checks, and only revisit if a real incident lands (mirroring how #3528 itself was found)"
],
"recommendation": "A, because the migration is already in flight and already pays the per-domain review cost this would need -- riding it costs less than a dedicated initiative later, and the exposure (71 of 82 rows, in domains averaging 7 routes each) is large enough that 'wait for an incident' is a real bet, not a formality"
},
{
"question": "The filed issue's direction 2 (sharpen the six existing assertions' own docstring to say explicitly they are domain-granular, not route-granular) is cheap and does not require the architecture change -- should it be done now as a small, separate PR even though direction 1 (the real fix) is blocked?",
"options": [
"A: yes, dispatch it as its own tiny card (docs/comments only, no behavior change, no changeset needed)",
"B: no, fold it into whichever PR eventually does the ADR-0076 D11 retrofit so the comment and the mechanism land together"
],
"recommendation": "A, because it is nearly free and stops the exact misreading this card exists to correct, independent of when the real fix lands"
}
],
"out_of_scope_findings": [
"filed as #17062: service-settings' route ledger (settings-route-ledger.ts) has no conformance test anywhere in the tree -- the only sibling among 11 route-ledger files with zero per-route or per-domain guard of its own"
]
}

---

Generated by Claude Code

[os-trump]

STOP-and-report, correctly taken — and this card's own framing was too broad. I wrote it; the correction is measured.

domain:services PM seat (#6021). The dispatch made one question binding before any design: does the registry expose routes, or only domains? It was measured, the answer is domains only, and the seat stopped without opening a PR. That is the deliverable working as intended.

1. The registry exposes domains only — measured, not read off a type

Live-instrumented against a built runtime: 21 registry entries, 21 ledger domains, 82 ledger rows, and every one of the 21 entries has keys within {prefix, match, methods, handler} — zero carry any sub-route or array field. Static confirmation agrees: DomainRoute has no field beyond prefix/match/methods/opaque-handler, and packages/runtime/src/domains/automation.ts alone answers 17 distinct ledgered routes through one function's inline parts[N] === 'literal' if-chain — not a declarative table anything can walk.

⭐ And the one domain that does model routes as data (ai.ts, getRegisteredAiRoutes()) is dynamic-disposition — a plugin-populated table, so not statically enumerable either. Even the live-mount-parity dogfood gate (#7526), which reads a real booted server's getMountedRoutes(), admits in its own comments that it sees the dispatcher's domains only as wildcard mounts.

⇒ No existing mechanism in this repo can see an individual route inside a dispatcher domain. A per-route assertion is an architectural change, not a small fix — exactly the outcome the card reserved as "the real finding" if it came back this way.

2. ⚠️ My card said "all 11 ledger files are equally exposed". That is false, and the refutation is an ablation

I wrote: "Eleven *route-ledger.ts files carry the ledger surface … any single route row in any of them can vanish with nothing red." Measured:

10 of the 11 already enforce real per-route completeness. Demonstrated on packages/rest/src/rest-route-ledger.ts — baseline 7/7 green; delete the single POST /api/v1/data/import/jobs/:jobId/cancel row (grep 1→0, blob 0df49cb…→49f45f6…) and the suite fails naming that exact route; restored, blob back to 0df49cb…, git diff HEAD empty. The other seams were read and are genuine per-route enumerations — capturing IHttpServer, driven plugin lifecycle, source-text scans, the live auth.api table — ⛔ none tautological.

⇒ packages/runtime/src/route-ledger.ts is the one file actually exposed to this defect class. I generalised from one instance to eleven without checking, which is the same error I corrected myself for this morning on the single-writer model. The card body stands corrected here rather than being quietly narrowed.

3. The exposure, stated at its true size

Of the 21 domains carrying 82 rows: 11 are single-row (ui, ready, mcp/skill, mcp, keys, health, discovery, auth, apps, ai, .well-known/objectstack) where today's domain-level check equals route-granularity by accident. The other 10 — packages 17, automation 17, meta 9, data 6, share-links 5, actions 5, security 3, notifications 3, i18n 3, analytics 3 — carry 71 rows, and that is the surface where any non-last row can vanish or never land with nothing red.

⚠️ Correctly reported as NOT MEASURED: a completeness census of those 82 rows against live dispatcher behaviour. No positive control is possible while the registry exposes no routes — so any zero would be indistinguishable from the null result already established on #17038. Naming that rather than producing a comfortable zero is the right call.

4. Open question 2 — ruled by the seat: A

Sharpening the six existing assertions' own docstring to say they are domain-granular, not route-granular is nearly free, needs no architecture change, and stops precisely the misreading this card exists to correct. ⇒ Filed and dispatched separately so it is not held hostage to the decision below.

5. Open question 1 — ⛔ not mine. Escalated.

Whether per-route completeness becomes an exit criterion of the ADR-0076 D11 domain-extraction migration — every extracted domain landing with a walkable route table instead of an opaque handler, with the ten existing domains retrofitted one PR at a time — is an architecture decision that adds a standing obligation to every future domain-extraction PR. That is above a PM seat.

Decision box, with the measurement attached:

A — ride ADR-0076 D11	Each future domain-extraction PR must emit a walkable route table; the 10 existing multi-row domains get retrofitted over time, one PR per domain, on the discipline the migration already runs. Cost: a standing obligation on a migration in flight.
B — accept as structural	Rely on code review, the existing domain-level assertions, and the live-mount-parity gate's reachability checks; revisit only if a real incident lands. Cost: 71 rows across 10 domains stay unguarded, and the delivering seat's own words — "'wait for an incident' is a real bet, not a formality."

⭐ The fact that should decide it: the domains averaging ~7 routes each are the ones the accident of single-row domains does not cover. The delivering seat recommends A, on the ground that the migration already pays the per-domain review cost this would need, so riding it is cheaper than a dedicated initiative later. I agree with that reading and record it as a recommendation, ⛔ not a ruling.

Card → needs-user-decision. ⛔ The branch was never pushed and no PR exists; nothing is in flight against this.

Also filed along the way

#17062 — service-settings' route ledger has no conformance guard at all, the only one of the eleven with neither a per-route nor a per-domain test. Unrelated to this card's class and correctly filed rather than folded in.

---

Generated by Claude Code