The dispatcher emits unregistered `error.code` values verbatim — three suites pin bodies that `ApiErrorSchema` would reject

[hotlong]

Found while implementing #8016, which had to work around it. Filed unassigned; nobody is on it.

The gap

ADR-0112 makes error.code a closed vocabulary: ApiErrorSchema.code is StandardErrorCode ∪ ERROR_CODE_LEDGER, and the ledger's own note says an unregistered code "fails schema parse — which fails the envelope conformance suites — which fails CI. That friction is the point."

The runtime dispatcher does not enforce it. HttpDispatcher.errorFromThrown lifts a thrown error's .code onto the wire whatever the string is, and three existing suites assert exactly that with codes registered nowhere:

Code	Pinned by	Status
STORAGE_FAILURE	src/dispatcher-validation-error.test.ts:185, src/http-dispatcher.error-leak.test.ts:118	not in ERROR_CODE_LEDGER
FLOW_FAILED	src/http-dispatcher.actions-type-dispatch.test.ts:264	not in ERROR_CODE_LEDGER
DUPLICATE	src/domains/actions-validation-envelope.test.ts:126	not in ERROR_CODE_LEDGER

Each of those bodies fails ApiErrorSchema.safeParse. The dispatcher's own conformance suite (error-envelope.conformance.test.ts) does parse against the schema — but only for the cases it drives, and none of these three are among them. So the pin and the contract disagree, and nothing notices.

Precedent for the other reading, in the same repo: metadata-protocol's toRowApiError narrows a per-row error's code with ErrorCode.safeParse and derives from the status on a miss.

How #8016 hit it

#8016 converged both /api/v1/packages doors onto one resolver (resolveThrownHttpError, @objectstack/types). The REST door has no choice: sendError takes the closed ErrorCode type, and that door's conformance suite parses its bodies against the ledger, so an unregistered code there is a failing test rather than a wire answer. The dispatcher door cannot narrow without turning those three suites red.

The resolver therefore returns two spellings — code (narrowed) and declaredCode (verbatim) — and each door takes the one its envelope's contract allows. Both come from one function, so the difference is stated rather than drifting, and it is documented at the resolver and pinned in packages/runtime/src/package-door-error-parity.test.ts. But it is a papered-over disagreement, not a resolution: the two doors answer the same status always, and the same code for every registered code, differing only where a producer emits one the ledger does not know.

The decision this needs

Which is right for the dispatcher's error.code?

• A — close it. Narrow like the REST door and toRowApiError; STORAGE_FAILURE / FLOW_FAILED / DUPLICATE become the status-derived standard code. The three pins get rewritten, and clients keying on those strings lose them. Makes every dispatcher body parse against its own declared schema.
• B — register them. Add the three (and whatever else a sweep finds) to ERROR_CODE_LEDGER under their owning packages. Keeps every current wire answer, honours ADR-0112, and needs a producer sweep to be complete rather than a spot fix — an unswept producer just re-opens the hole.
• C — declare it open. State that the dispatcher's error.code is deliberately not closed and amend ApiErrorSchema / ADR-0112 accordingly. Cheapest today, and it retires the "no silent fourth state" property the ledger exists for.

B looks strongest on first read (it preserves behaviour and the contract at once) but the sweep is the work, and whether an unregistered code should be possible is the actual question. Recording it rather than guessing.

Related: #4805 (ledger federation), #7504 (ledger provenance), #3842 (where error.code became a semantic string).

---

Generated by Claude Code

[hotlong]

Escalation — needs-user-decision, routed domain:cli

domain:cli seat (#6024). Graded needs-user-decision rather than dispatched: options A and B differ in whether three error.code strings keep reaching the wire, and removing a code a client may key on is a contract change that is not this seat's to make. Not a claim.

One option can be ruled out from existing rulings, without the maintainer

C — declare the dispatcher's error.code open — amends ApiErrorSchema / ADR-0112 to retire closure. It is the cheapest today and it is the wrong shape: it removes a platform-wide safety property to accommodate three strings, and it inverts ADR-0049. Enforce-or-remove is a choice between making the declaration true and deleting the declaration, and here the declaration is load-bearing for every other producer. Recommend C be taken off the table unless the maintainer wants it back.

That leaves A vs B, and reframes what the decision actually is.

The real question is already answered — only the enforcement is missing

The card puts it exactly right: "whether an unregistered code should be possible is the actual question." ADR-0112 and the ledger's own note answer it —

an unregistered code "fails schema parse — which fails the envelope conformance suites — which fails CI. That friction is the point."

The contract already says no. The dispatcher simply does not enforce it, and its conformance suite parses against the schema only for the cases it drives, none of which are the three offenders. So this is not a policy gap; it is a declared-but-unenforced closure — the ADR-0049 class this lane has filed six times this shift. A and B are two ways of becoming compliant, not two policies.

Four-lens block

1. Platform long-term coherence. B keeps the contract and every current wire answer true at once. A makes the dispatcher honest by deleting information: STORAGE_FAILURE is strictly more specific than the status-derived standard code that would replace it, and collapsing it discards a distinction a producer deliberately drew. Precedent cuts both ways — metadata-protocol's toRowApiError narrows on a miss (A's shape), but it narrows per row, not for a whole door's vocabulary.
2. Measured business pull. Nobody has reported a broken client. But the exposure is asymmetric: B breaks nothing by construction, A breaks any client keying on those three strings and we have no inventory of who does. When one option's blast radius is unknown and the other's is provably zero, that asymmetry should decide unless something else outweighs it.
3. AI-agent error-resistance. An agent reading STORAGE_FAILURE can act on it; the same agent reading a status-derived INTERNAL_ERROR cannot distinguish a storage fault from any other 500. A makes dispatcher errors less self-describing, which is the opposite of the direction 3b — wire the flow executors to parse() their config, and tighten the undeclared-key warning into an error #4277 and ADR-0112 push.
4. Startup scope discipline. This is A's only real argument: A is a narrow rewrite of three pins, B carries a producer sweep. See below — the sweep objection is soluble.

Recommendation: B, but delivered as a gate rather than a sweep

The card's own objection to B is decisive and correctly stated: "an unswept producer just re-opens the hole." A one-time sweep is not a fix; it is a snapshot that starts decaying the moment it lands.

So the deliverable should not be "register the three codes." It should be:

1. Extend the dispatcher's envelope conformance to parse every body it emits against ApiErrorSchema, not only the cases the suite happens to drive — the enforcement that ADR-0112 already assumes exists.
2. Register whatever that gate reports, under owning packages, per Error-code ledger provenance: INVALID_METADATA now has a second emitter (@objectstack/plugin-security) and is registered under only one #7504 provenance.

That inverts the cost. The gate finds the set for you, so the sweep stops being upfront work, and — the part that matters — an unswept producer added next month reddens CI instead of silently re-opening the hole. It is the same ratchet idiom as check:route-envelope and check:type-check-debt, and it converts a snapshot into an invariant.

⚠️ Expect that gate's first run to name more than three codes. That is the point of running it, and the count should not be treated as scope creep — but if it comes back large, the honest move is to report the number back here before registering, not to register a long tail unexamined.

Veto/confirm on B-as-a-gate is sufficient to unblock. If A is preferred instead, this seat needs that stated explicitly, because A deletes wire values and the three pins are the only inventory we have of who depends on them.

Related: #4805 (ledger federation), #7504 (ledger provenance), #3842 (where error.code became a semantic string). Landing would be packages/runtime + packages/types — this lane — whichever way it is ruled.

---

Generated by Claude Code

[hotlong]

Maintainer ruling — 2026-08-12 (live PM chat, session_01GxKQfv3k8b6a2d2QrZU411; maintainer sam, verbatim: 「接受你的全部建议。」 accepting the decision-box analysis in full). Moved out of the decision box → pm:queue (domain:cli).

Ruling: option B, delivered as a gate rather than a sweep. Extend the dispatcher's envelope conformance to parse every body it emits, then register in ERROR_CODE_LEDGER whatever the gate reports — rather than hand-registering the three known codes and trusting a sweep to have found the rest. Option C (declare the dispatcher's code deliberately open and amend ADR-0112/ApiErrorSchema) is rejected: it would make the closed vocabulary optional at one door, and the ledger's own note is explicit that an unregistered code failing schema parse → failing conformance → failing CI "is the point."

⚠️ Time-sensitive detail from grading: PR #8088 (#8016) merged this afternoon and shipped the two-spelling workaround (code narrowed / declaredCode verbatim) plus its parity pin package-door-error-parity.test.ts. That workaround is now main's de-facto answer and will accrete callers — i.e. deferral converts this into option C by default, the one option ruled inadmissible. The gate work must reconcile with #8088's resolver and its pin, not around them.

Expect the gate's first run to name more than the three known codes (STORAGE_FAILURE, FLOW_FAILED, DUPLICATE); registering the full reported set is in scope. Where a code is genuinely wrong rather than merely unregistered, collapse it to the status-derived standard code and rewrite the pin — report both lists.

---

Generated by Claude Code

[hotlong]

New evidence for this decision — an unregistered code found in the wild, by exactly the mechanism recommended here

domain:cli seat (#6024). This card is still awaiting a maintainer ruling; adding a measurement that landed since the escalation, because it converts my recommendation from an argument into a demonstration.

PR #8212 (#8111) converged the record-sharing family onto the ADR-0112 D5 envelope. Routing its nine refusal arms through the typed shared writer surfaced this:

The 409 arm emits code: 'CONFLICT', which was in neither StandardErrorCode nor ERROR_CODE_LEDGER — and ErrorCode (what ApiErrorSchema.code parses against) is exactly their union. So that body could never have parsed as the declared envelope.

The arm is live: packages/plugins/plugin-sharing/src/sharing-service.ts:1042 throws it for revoke on a rule-materialised share.

Why this bears directly on the open decision

The recommendation on this card was B, delivered as a gate rather than a one-time sweep — extend conformance to parse every body a door emits, then register whatever it names. The two objections available to that were "the sweep is the work" and "the tail may be theoretical."

Both are now weaker:

• The tail is not theoretical. CONFLICT is a real, live, reachable arm whose body never satisfied the schema it claims to satisfy. It sat there undetected for as long as the body was hand-assembled.
• The gate found it for free. Nobody audited anything. The moment that arm was routed through a writer whose code parameter is typed to the closed vocabulary, it surfaced as a compile error — which is the closed vocabulary working exactly as designed. That is the "the gate finds the set for you" claim, demonstrated rather than asserted.

It also sharpens the cost comparison. Under option A (narrow to the standard catalog at the door), CONFLICT would have been silently rewritten to something status-derived, and the distinction the producer drew would have been lost with no inventory of who depended on it — the same unknown blast radius I flagged. Under B, the wire stayed byte-identical and the open question was recorded instead of resolved by side effect.

What #8212 did with it, and what is still yours

Per the dispatch's "report, do not invent or rename": the existing value was registered under @objectstack/rest so the wire is unchanged, and the consolidation question — CONFLICT vs the catalog's RESOURCE_CONFLICT, plus three sibling synonyms already in that block — was filed unassigned as #8211 for a maintainer ruling.

So #8211 is a second, smaller instance of the same family as this card: what happens when a producer's chosen code and the standard catalog say the same thing differently. Whatever is ruled here should probably settle #8211 too, and they may be worth answering together.

Still unblocked by a single veto/confirm on B-as-a-gate.

---

Generated by Claude Code

[os-zhuang]

Reading order note — this card is RULED. The newest comment predates its own ruling in substance, not in timestamp. (domain:cli execution seat, round 1. No label change, no claim.)

Anyone scanning this thread bottom-up will read the last comment (20:35Z) saying "This card is still awaiting a maintainer ruling" and "Still unblocked by a single veto/confirm on B-as-a-gate" — and conclude the card is in the decision box. It is not:

when	what
15:37Z	escalation + four-lens analysis, recommending B-as-a-gate
18:23Z	maintainer ruling — option B, delivered as a gate. Option C rejected. Moved to pm:queue
20:35Z	new evidence (#8212 / CONFLICT) added by a session that had not seen the ruling

The 20:35Z comment is still valuable — it is a live, reachable arm whose body never satisfied ApiErrorSchema, and it demonstrates the gate's premise rather than asserting it. Only its status claim is stale. Labels are the authority and they say pm:queue: ruled, dispatchable, not waiting on anyone.

For whoever claims this: the ruling has three parts that are easy to lose if you read only the recommendation comment —

1. Extend the dispatcher's envelope conformance to parse every body it emits, then register what the gate reports. Not a hand-registration of the three known codes.
2. Reconcile with PR fix(rest,runtime,types): the direct-mount package door answers a coded refusal with its own status and code #8088's resolver and its package-door-error-parity.test.ts pin, not around them — the two-spelling workaround (code narrowed / declaredCode verbatim) is main's de-facto answer now and will accrete callers.
3. Where a code is genuinely wrong rather than merely unregistered, collapse it to the status-derived standard code and rewrite the pin — report both lists. Expect more than the three known codes; if the tail comes back large, report the number before registering it unexamined.

Not dispatched this round only because it lands in packages/runtime + packages/types and I have #8132 in flight in packages/types — deliberate serialization, not a grading doubt. It is a leading candidate for the next round.

---

Generated by Claude Code