fix(runtime): demote non-enum author-thrown codes to declaredCode — error.code closed at every door (#9106)

[os-project-manager]

Part of #9106

⚠️Part of, not Fixes, by PM ruling (superseding the dispatch prompt, which had specified Fixes #9106). The ruling on #9106 names the ADR-0112 prose as the deliverable that matters most, and that prose is in #9233, behind a human-approval gate. If this PR carried the closing keyword, the card would auto-close the moment the code landed while half its ruling sat unmerged — the exact silent half-delivered state #9106 exists to prevent. #9233 carries the closing keyword instead, so #9106 closes only when both halves are in.

Implements the maintainer ruling of 2026-08-16: error.code is a closed vocabulary at every door. An author-thrown code that is not an ErrorCode member is demoted to the wire's declaredCode at the dispatcher exits, mirroring what resolveThrownHttpError already computed for the REST package door — and #7867's capability is preserved: the author's code still crosses the sandbox and still reaches the wire, in the open channel instead of the closed one.

The two binding items from the ruling

1. The binding precondition — measured, empty, search proven. No existing consumer of the actions door branches on author-authored strings in error.code. Method and full classification are on the issue; the load-bearing parts, re-run independently at this head:

• The closed union was extracted from the built spec (288 members — the same count check:dispatcher-error-vocabulary reports), not from a hand list.
• Widened literal scan, not a comparison-shape scan: every SCREAMING_SNAKE string literal across packages/client, client-react, examples, packages/qa, the objectui checkout and the hand-written docs — 480 distinct literals, 409 outside the union. The widening is the point: objectui branches through a helper (errorCodeIs), which an x.code === 'LIT' scan cannot see.
• Proof-of-search before believing the empty result: the scan finds the known-present out-of-vocabulary literals (ANALYTICS_NOT_INSTALLED, DEV_ENV_PLAN_LOCKED) and it sees the helper-mediated ATTACHMENT_DOWNLOAD_DENIED branch that a comparison-shape scan misses.
• Every helper-mediated branch code enumerated: 12 distinct codes reach errorCodeIs / errorCodeIsAnyOf; 11 are closed-union members. The twelfth, INVALID_PAYLOAD, has zero producers anywhere in this repo and rides an OR with the registered INVALID_METADATA plus a status === 422 test — nothing demotes, and the affordance cannot be lost.
• The actions door specifically:objectui/packages/core/src/actions/actionResponse.ts is, by its own docblock, "the ONE place a POST /api/v1/actions/... response is interpreted", and it resolves failures through actionErrorDetail, which reads error / error.message / message and nevercode.
• Zero branches on DUPLICATE anywhere.
• Named residual:objectstack-ai/cloud is not reachable from this session (I attempted to attach it; access denied). Evidence it is unaffected is unchanged: cloud's consumer-branched entitlement codes ride its own control-plane sender, not this repo's dispatcher exits.

2. ADR-0112 text — drafted, in its own PR, awaiting maintainer merge. Prime Directive #14 keeps docs/adr/** off this PR: the amendment is #9233 on claude/issue-9106-adr-0112-closed-everywhere. It states the closure holds everywhere, names declaredCode as the open author-authored channel, pins "presence means demotion" as its semantics, records that #7867 is preserved rather than retired, names where the rule is pinned, and fences DUPLICATE off from the ledger. ⛔ This PR can land without it — but the card stays open until it lands, which is what the Part of above buys.

Review notes on the inherited commit

The implementation commit was written by a previous session that died mid-verification, so nothing in it had passing evidence behind it. Reviewed as a stranger's PR; it held up, with these corrections:

• Merge conflict with The REST door's own sendError overload does not narrow, so an unregistered error.code reaches the wire there too #9098 resolved semantically, both intents stacked.The REST door's own sendError overload does not narrow, so an unregistered error.code reaches the wire there too #9098 landed a correction saying packages/rest has a second, error: any responder and that thrown errors there are "NOT narrowed, deliberately and symmetrically with this door". The branch's rewrite had dropped that paragraph and re-asserted the claim The REST door's own sendError overload does not narrow, so an unregistered error.code reaches the wire there too #9098 had just falsified. The merged text keeps The REST door's own sendError overload does not narrow, so an unregistered error.code reaches the wire there too #9098's correction, scopes "either door" to the two this resolver actually serves, and states the flat-dialect path per path.
• finding: rest-server.ts 里三个相邻 /meta handler 的错误信封是三种不同形状,其中两种不符合 ADR-0112 #7035 is no longer open (landed via PR fix(rest): put the /meta 501 refusals inside the ADR-0112 error envelope (#7035) #7293, three /meta 501 handlers) — The REST door's own sendError overload does not narrow, so an unregistered error.code reaches the wire there too #9098's prose cites it as the live envelope card. Corrected here and in the ADR; the real remaining question is filed as finding: packages/rest's flat sendThrownError still puts a thrown error's code on the wire un-narrowed — ADR-0112's closure does not reach that door #9232.
• ADR anchor added (PD#13) for packages/types/src/thrown-http-error.ts, the definition site of both spellings.
• Vacuity noted, not papered over: the rewritten assertions inside the for (const code of PENDING_AT_DISPATCHER_DOOR) loop in error-envelope.conformance.test.ts currently generate zero tests — that list is empty post-spec: register the dispatcher conformance gate's reported error codes in ERROR_CODE_LEDGER (spec half of the #8087 ruling) #8846. The demote's real coverage is the three cases named below, each independently falsified.

Verification

Everything below at c6255040e, after git merge origin/main (which had moved substantially) plus the deferred regeneration.

What	Result
pnpm --filter @objectstack/runtime test	165 files, 2463 passed
pnpm --filter @objectstack/types test	12 files, 348 passed
pnpm --filter @objectstack/spec test	407 files, 10834 passed
pnpm --filter @objectstack/rest test	122 files, 2011 passed
typecheck (types, runtime)	clean
pnpm --filter @objectstack/spec check:generated	13 of 13 artifacts up to date
check:dispatcher-error-vocabulary	OK — 7 sites, all classified, 0 awaiting a ledger entry
check:type-check-debt --re-measure	OK — 33 entries, none above its recorded number

Reverse verification — direction predicted before running, and observed: red. With the demote ablated in errorFromThrown (the pre-ruling thrown.declaredCode straight into error.code), exactly three cases fail: the actions-door DUPLICATE witness, the sandbox-limb conformance case, and the package-door demote pin. Restored from the committed branch state, tree verified clean, and the gate union re-run afterwards.

Gate union derived from the real changed paths (node scripts/pm/dispatch-gates.mjs), not from memory — the derivation added check:query-options-erasure, check:where-matcher, check:engine-double-contract, check:type-check-debt (convention-triggered by the touched test files) and the changeset family. All run, all green. check:type-check-debt is the gate that refuses on an unbuilt closure — the workspace was built exactly as lint.yml does (turbo run build --filter=./packages/* --filter=./packages/*/*) before it.

What honours the ruling's fences

• DUPLICATE is re-homed, NOT registered. It stays absent from ERROR_CODE_LEDGER and from the PENDING_LEDGER_REGISTRATION hand-off (asserted), fenced off from spec: register the dispatcher conformance gate's reported error codes in ERROR_CODE_LEDGER (spec half of the #8087 ruling) #8846. Registering one tenant spelling closes nothing — the next app picks a different string.
• Action-body writes have no not-found gate: ctx.api.object().update() against a nonexistent id answers 400 (or worse) instead of 404, while the protocol and callData paths both gate correctly #7867's capability is preserved. The author's code crosses the sandbox and reaches the wire; only its slot changed. The actions-door test pins exactly that end to end.
• Presence means demotion.declaredCode is emitted only when the demote actually happened — never as a second copy of a registered code. demotedDeclaredCode() is the single definition, and the conformance suite asserts the property for every body the door emits.

Model-tier substitution — recorded, not silent

The card and its triage comment mandate model: claude-fable-5 for this work under the standing tiering clause (wire-contract behaviour change). That tier's quota is exhausted, and the maintainer explicitly approved finishing on opus instead. The tiering rule was waived by an explicit maintainer decision for this card — it was not overlooked, and this note exists so a future reader can see which of the two it was.

Out of scope, filed not fixed

• finding: packages/rest's flat sendThrownError still puts a thrown error's code on the wire un-narrowed — ADR-0112's closure does not reach that door #9232 — packages/rest's flat sendThrownError still passes a thrown code through un-narrowed. Left alone deliberately: that file is The REST door's own sendError overload does not narrow, so an unregistered error.code reaches the wire there too #9098's surface, the field is the body's top-level code rather than error.code, and The REST door's own sendError overload does not narrow, so an unregistered error.code reaches the wire there too #9098's own note calls narrowing it a separate public-contract decision. Going to the maintainer, not carved into the invariant here.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/runtime, @objectstack/spec, @objectstack/types.

110 hand-written doc(s) reference the affected code — list omitted above 15 rows. Re-derive: node scripts/docs-audit/affected-docs.mjs --json origin/main.

⛔ 7 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

Advisory only. 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.