fix(rest): narrow the flat door's thrown code to the declared ADR-0112 vocabulary (#9232)

[os-zhuang]

Fixes#9232

⚠️ READ FIRST — this PR touches docs/adr/**, so it is maintainer-merge-only

The dispatch asked me to establish, by reading, whether docs/adr/0112-*.md genuinely needs an edit, because the answer decides the landing path. It does. The ADR edit is isolated in its own commit (ad0beb32) so it can be reviewed — or dropped — on its own.

But not for the reason anyone expected, and the PM's measurement was right.docs/adr/0112-error-code-vocabulary-and-ledger.md contains ZERO7035 citations (control: 13 ADR hits in the same file, so the search works and the zero is real). The ruling's third bullet asks for the stale #7035 citations to be repointed — naming #9098's prose and the ADR-0112 amendment. Taken literally, that finds nothing to do in the ADR.

What the ADR actually needed is a different sentence. The #9106 amendment's Scope paragraph carves this exact door OUT of the closure:

packages/rest's flat sendThrownError dialect … is a different envelope position and is out of scope here; it is measured and filed as #9232 … Read that card before quoting "every door" at the flat dialect … #9232 is where the remaining question about the flat top-level code is recorded.

Once this lands there is no remaining question, and the flat door is no longer exempt. Leaving that paragraph would move the declared-≠-actual contradiction rather than remove it: the ADR would tell a reader the flat door is carved out while the code narrows. That is the same defect class the ruling required fixing for the parity sentence, pointing the other way.

---

What changed

packages/rest's flat responder passed a caught error's code to the wire verbatim, at four arms — resolveErrorResponse's 4xx and 5xx passthroughs and mapDataError's two declared-status arms. All four now resolve the code through the shared resolveThrownHttpError / demotedDeclaredCode pair, which is the ONE definition the three dispatcher exits already read:

• registered code → unchanged, verbatim, in code, nothing beside it.
• unregistered code → code carries the member the status derives; the producer's spelling moves to a top-level declaredCode sibling. Presence means demotion.
• no code → still no code. Narrowing the vocabulary must not start inventing codes for bodies that carried none.

Delegating rather than open-coding a fourth ErrorCode.safeParse is deliberate: a second definition of one rule is the shape that let two doors answer differently in the first place.

One bounded fix taken in place, named here because it was not in the dispatch

The two resolveErrorResponse arms gated on bare truthiness, so a non-string code — a numeric driver errno — could reach the flat body as code: 1062. The other two arms already asked "non-empty string". Unifying them on the shared resolver's question closes that limb. Evidence that this is the settled shape, not my invention: resolveThrownHttpError already classes a non-string code as context, with the reasoning in its own source — "promoting it would put a number in the field callers branch on, which is the drift #3842 removed". Same defect class as the card, same file, same gate family, mechanical. Pinned in §4 of the new suite.

The pin

packages/rest/src/rest-thrown-code-vocabulary.test.ts — 24 cases over all four arms, in both directions. §2 (a registered code still arrives verbatim) is the half a regression does not redden, which is exactly why it is written down: a door answering INTERNAL_ERROR for everything would satisfy §1 on every case and destroy the vocabulary silently.

Reverse verification, direction predicted before running. Restoring the resolveErrorResponse 5xx passthrough: 3 RED, 21 green — §1's 5xx demote case, §4's numeric errno, §5's status-derivation — and every §2 registered case stayed green, the predicted asymmetry.

That ablation also earned its keep by finding a weak case of my own: §1's "presence means demotion" stayed green under it, because every assertion it made is vacuously true of undefined. Fixed in 896cac00 with a toBeTypeOf('string') guard. A pin that cannot fail for the defect it names is worse than no pin.

Fixture triage — three dispositions, not one batch rename

Nine existing cases moved. Each was judged separately and the reason is recorded at the site:

Vehicle	Verdict	Disposition
UPSTREAM_UNAVAILABLE (3 files)	invented; no producer anywhere, the real ledger code is CONNECTOR_UPSTREAM_UNAVAILABLE	vehicle swapped to that registered code — these cases' subject is the status/message rule, not the vocabulary
HOOK_REFUSED	invented; no producer	swapped to the registered ERR_HOOK_TARGET_REBIND
X_FAULT	placeholder	swapped to a registered member
owd_widening_forbidden	REAL producer	assertions updated to the demote — see below

Every replacement is deliberately not the status-derived code for any status in its loop, so "the producer's own code survives" can still fail.

The observable case, and a real finding underneath it

plugin-security's objectPostureGate throws a lowercaseowd_widening_forbidden. It violates ADR-0112 on two counts at once — D1 rules the value space ^[A-Z][A-Z0-9_]*$, and the ledger carries it in no casing — so that body could never satisfy the schema it claimed to. It now answers PERMISSION_DENIED with its own spelling preserved in declaredCode.

It is invisible to check:dispatcher-error-vocabulary, whose scan matches SCREAMING_SNAKE shapes only. Filed unassigned rather than fixed here: registering a code is the packages/spec lane's call, and that gate's own scope note says nothing there edits the ledger.

Consumer sweep — re-run, not inherited

The card assumed zero measured pull. Corrected, in the direction that matters: there IS a live read of the flat top-level code — packages/client's asSemanticCode(errorBody?.code), which ADR-0112's D5 amendment already records as one of the two live envelopes' declared spots. It is a generic pass-through normalisation, not a branch.

What matters is whether anything branches on an unregistered spelling. Nothing does. Every code any consumer compares against was classified against the live union:

• DESTRUCTIVE_CHANGE, INVALID_METADATA, ITEM_LOCKED, CONCURRENT_UPDATE, BATCH_UNRESOLVED_REF, BATCH_NOT_ATOMIC, UPLOAD_SESSION_EXPIRED, FLOW_FAILED, VALIDATION_FAILED, PERMISSION_DENIED, RECORD_LOCKED, FORBIDDEN, NOT_IMPLEMENTED — all REGISTERED, so all unaffected.
• objectui's one unregistered branch, INVALID_PAYLOAD, has zero producers in this repo, and both of its call sites are ||-guarded by err?.status === 422 anyway.

The sweep covered packages/client, client-react, examples, packages/qa and the objectui checkout, including the helper-mediated errorCodeIs / errorCodeIsAnyOf shapes a comparison-shape scan cannot see.

Stale citations repointed

#7035 reached state completed on 2026-08-10 via PR #7293, having converged three /meta 501 handlers and nothing else, and was still being cited as an open finding owning the envelope-position line. Repointed where it was stale, in error-response.ts, rest-server.ts and rest-field-visibility-fault-envelope.test.ts. A stale #8111 citation beside one of them got the same treatment — it reached state completed on 2026-08-12 via PR #8212, having converged the family it named.

Citations that describe #7035 accurately in the past tense were left alone; they are history, not drift.

⚠️The live owner is the check:route-envelope ratchet, not a card — because there is no live card. #7035, #8111 and #3843 have all reached state completed, and no open issue owns the envelope-position line (verified against the 27 open domain:cli issues). Rather than point live prose at a card that closes with this very PR, the prose now names the ratchet, which is a mechanism CI actually enforces. The gate script's own ratchet: '#7035 …' fields still name the closed card; that file is outside this PR's declared surface and is filed separately.

The envelope position is untouched and still open. It was explicitly not a precondition.

Merged origin/main for the renamed required check

The repository's required-check set changed after the first push: ruleset 12119582 now requires Lint & Repo Gates instead of ESLint, and the workflow PR that produces that context (#9421) merged afterwards. The old head could not emit it, so origin/main was merged (never rebased) — head is now 047457ca3.

Re-verified rather than assumed, because main moved 18 commits:

• My diff is unchanged by the merge — still 12 files, +596/-55, and the four narrowed arms are intact. No conflicts.
• The new ledger codes do not touch this PR. Main registered FLOW_DISABLED and FLOW_NO_START_NODE; the STORED_TYPE_NOT_CANONICAL change is comment-only. Every vehicle this PR's suites depend on was re-checked against the rebuilt union: PACKAGE_IS_HAUNTED, owd_widening_forbidden, UPSTREAM_UNAVAILABLE, HOOK_REFUSED and X_FAULT are still unregistered (so no §1 case went vacuous), and RECORD_LOCKED, CONNECTOR_UPSTREAM_UNAVAILABLE, ERR_HOOK_TARGET_REBIND and FIELD_VISIBILITY_UNRESOLVED are still registered.
• check-route-envelope.mjs's 420-line rewrite left this PR green, and — worth noting for the finding filed alongside this PR — it left both#7035ratchet: fields (lines 245 and 309) untouched. The rewrite added a new plugin-route audit with #9364 owners and did not repoint the two stale ones.

Nothing was adjusted to accommodate main.

Verification

All at 047457ca3, the current head — a merge of origin/main (e374b4d74). Every figure below was re-measured on that merged head, not carried over: pnpm install --frozen-lockfile, a full closure rebuild (70/70 tasks, 68 of them not cached), then the suites and the gate union. main had moved 18 commits / 64 files, including a 420-line rewrite of check-route-envelope.mjs and two new ledger codes.

What	Result
@objectstack/rest suite	125 files / 2058 tests passed
@objectstack/runtime suite	167 files / 2503 tests passed (4 more than before the merge — main added them)
@objectstack/http-conformance	4 files / 72 tests passed
@objectstack/dogfood (on rebuilt dist/)	110 passed, 1 skipped
@objectstack/resttsc --noEmit	clean
downstream consumers typecheck	14 green — of the 16 dependents of @objectstack/rest (--filter '...^@objectstack/rest', the direction a contract tightening lands in), 14 declare a typecheck script and all 14 ran and passed. Counted rather than inferred from the exit code, because a filter matching no script exits 0
eslint --no-inline-config on the changed files	clean
gate union (12 families)	all green at 047457ca3
check:type-check-debt --re-measure	OK at 047457ca3 — 33 ledger entries re-measured in 221.6s, none above its recorded number

The workspace closure was built before the ratchet and dogfood runs (turbo run build, 70 tasks) — a throw on an unbuilt tree is not measured.

⚠️check:type-check-debt initially went red (@objectstack/rest TEST_DEBT 155 → 156, TS2835). Fixed at the source in eb70f7f4a by giving the new file's import an explicit .js extension. The ratchet was not touched, and it is still green on the merged head.

ℹ️ The only card this PR closes is #9232. Every other number above — #7035, #8111, #3843, #9098, #9106 — is cited as history or as a live neighbour and is not addressed here.

Required checks

TypeScript Type Check · Lint & Repo Gates · Test Core · Dogfood Regression Gate · Build Core · Temporal Conformance (live PG + MySQL)

(Lint & Repo Gates replaced ESLint in ruleset 12119582; the merge above is what lets this head emit it.)

⛔ Auto-merge is deliberately not armed. ADR maintainer approval is not one of the six required contexts, so arming it would carry this ADR change into the merge queue past the approval that check exists to demand.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/rest, touching 6 documentable anchor(s).

12 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/ai/agents.mdx(via /:object/query (route))
• content/docs/api/client-sdk.mdx(via data.query (sdk))
• content/docs/api/data-api.mdx(via /:object/query (route))
• content/docs/api/wire-format.mdx(via /:object/query (route))
• content/docs/data-modeling/analytics.mdx(via /:object/query (route))
• content/docs/data-modeling/queries.mdx(via /:object/query (route))
• content/docs/getting-started/quick-reference.mdx(via /:object/query (route))
• content/docs/kernel/runtime-services/data-service.mdx(via data.query (sdk), /:object/query (route))
• content/docs/kernel/services-checklist.mdx(via /:object/query (route))
• content/docs/protocol/objectql/query-syntax.mdx(via /:object/query (route))
• content/docs/ui/forms.mdx(via mapDataError (symbol), /forms/:slug/submit (route))
• content/docs/ui/public-data-collection.mdx(via /forms/:slug/submit (route))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17.mdx(via /:object/query (route))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/rest/src/rest-server.ts) — pages documenting those are invisible to this run

Coarse fallback — 13 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json origin/main → packageMentionDocs.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.

[claude]

Status for the maintainer: this PR is ACCEPTED by the domain:cli seat and is waiting on you — but it is still a DRAFT, and that is a tooling limitation on my side, not a signal about the work.

PM domain:cli seat (#6024), session session_012WKSnqAaoqtW3QX7SSf1Vk.

• ⛔ Auto-merge is deliberately NOT armed and will not be. This PR edits docs/adr/0112-error-code-vocabulary-and-ledger.md, so it is maintainer-merge-only under this seat's standing rule.
• ⚠️ Worth knowing, because it is a trap: ADR maintainer approval is not one of the six required checks. Arming auto-merge here would have carried an ADR change into the merge queue as soon as the six went green, past the approval that check exists to demand. The rule is what prevents that, not the mechanism.
• I could not flip it out of draft: that conversion needs the GraphQL mutation, and this session's GraphQL budget is currently exhausted (API rate limit already exceeded). REST's PATCH /pulls/{n} silently ignores draft: false. I will flip it on the next patrol once the budget resets; if you want to merge before then, marking it ready yourself is the only step missing.

Full review is on the card: #9232, comment 5322936316. Summary of the decision you are being asked to merge — the ADR edit is isolated in ad0beb326 (one file, +12/−2) precisely so it could be dropped, and I ruled against dropping it: the #9106 amendment's Scope paragraph currently tells readers this door is carved out of the closure and that #9232 is where the open question lives. Landing the code without it would move this card's own declared-≠-actual contradiction rather than remove it.

---

Generated by Claude Code

[os-zhuang]

⚠️ Recording a fact, not objecting to a decision: this PR is in the merge queue with the ADR approval gate RED and zero reviews.

Measured at 11:5xZ, on head 047457ca3:

reading	value
ADR maintainer approval	completed / failure (since 06:00:08Z)
reviews on this PR	0 (get_reviews → empty)
enqueued	11:56:28Z, actor os-steve

This merges regardless, because ADR maintainer approval is not one of the six required contexts in ruleset 12119582. That asymmetry is recorded in this seat's post as: "arming auto-merge bypasses it; the rule stops it, not the mechanism." The mechanism is now doing what the mechanism does.

⛔ I have not dequeued it and will not. Two reasons, and I want both on the record rather than just the conclusion:

1. It may be authorized.os-steve is a collaborator seat that could be acting on a maintainer instruction I cannot see — the same way this seat acted on a one-time model-tier downgrade earlier today that would look unauthorized to anyone reading only the labels. ⛔ I do not reverse another seat's action on an inference about its authority.
2. The rule I have been enforcing is scoped to me."ADR/skills-path PRs are never merged or enqueued by this seat" — it governs my hands, not the repo's mechanism. I held this PR for ~9 hours on exactly that rule and declined to arm auto-merge on it three separate times; that stands as the right call for me, and it is not authority to override someone else.

What I am doing instead: stating it plainly, now, while it is still actionable — the queue takes minutes, and a merge is revertible but noisier than a dequeue. Escalated to the maintainer in this round's report in the same breath.

⚠️If this was NOT authorized, the thing to notice is that the gate cannot stop it: ADR maintainer approval being advisory means every ADR change in this repo is one enable_pr_auto_merge away from landing unreviewed, by any seat, at any time. That is a mechanism-level observation and it is the maintainer's to rule on — ⛔ I am not proposing a ruleset change, and repo settings are the manual floor. (It would also be the second Settings-vs-workflow ordering hazard this repo has hit today; the first was the Lint & Repo Gates rename that deadlocked every open PR for an hour.)

📌 For completeness, since it decides nothing but is worth having beside the above: the six required checks are all green on this head, and mergeable_state was unstable rather than dirty, so there is no conflict and no merge-main was needed. The only red thing on this PR is the approval gate.

---

Generated by Claude Code

[os-zhuang]

✅ Withdrawn — the approval landed 28 seconds after my reading. My comment above was accurate when taken and wrong by the time it posted.

hotlong approved this PR at 11:56:56Z. The enqueue was 11:56:28Z. So the ordering was enqueue-then-approve within half a minute — a coordinated action, ⛔ not the gate bypass my previous comment raised as a possibility. The concern is withdrawn in full, and nothing in it should be read as an objection to how this landed.

⭐ Worth keeping, because it is a method failure and not just bad luck: I took three readings (ADR maintainer approval = failure, reviews = 0, enqueued-by = os-steve), every one of them correct, and reached a conclusion that was false within the same minute. This seat's own standing note says "a reading with a timestamp is still a reading — re-take it when a landing decision depends on it." I had been applying that to readings that go stale over hours (the required-check list that changed in five hours, the lane inventory that changed in one). This is the same rule at a much shorter timescale: on a PR that is actively being acted on by someone else, the state can move faster than the time between measuring and writing.

⇒ The concrete fix, which I will apply rather than merely note: when a reading is the basis for raising an alarm about someone else's in-progress action, re-take it immediately before posting, not just before deciding. The cost of the extra read is one API call; the cost of skipping it was a public accusation-shaped comment about a colleague's action that was already resolved.

📌 What stands from that comment, because it is independent of the false alarm: ADR maintainer approval is not one of the six required contexts, so it does not mechanically block a merge — the approval that just landed is what makes this correct, not the ruleset. That remains a maintainer-floor observation about the mechanism, ⛔ not a proposal, and it is now attached to a case where the humans did the right thing anyway.

Also unchanged and still true: six required checks green, mergeable_stateunstable not dirty, no conflict, no merge-main needed.

Landing this unblocks #9426, #9488 and #9487 — all three land in packages/rest/src/rest-server.ts and have been serialised behind it. I will confirm the landing with the usual two readings plus the probe (declaredCode in packages/rest/src/error-response.ts, 0 pre-merge, control resolveThrownHttpError = 3 files) and then take them into selection.

---

Generated by Claude Code