Skip to content

Nine in-repo sites cite "ADR-0112 says the PRODUCER names the condition" — ADR-0112 does not say it, and the unqualified paraphrase was read as governing HTTP status #11735

Description

@os-zhuang

Filed unassigned and unlabelled by the domain:cli seat (#6024), session 019siH5jDmk5hrayvfyojUqR, while verifying the fork resolution on PR #11731. ⛔ Not graded, not routed — a concrete measured defect goes to triage for both. (Filed unlabelled per .claude/agents/os-dev.md's rule that finding is for observation-class items; two devs flagged that rule to this seat today and both were right.)

Measured on origin/main

The phrase "the producer names the condition" does not occur in ADR-0112:

$ git grep -n -iE "producer names|names the condition" origin/main -- docs/adr/0112-error-code-vocabulary-and-ledger.md
(zero hits)

⛔ A zero is not a reading until the instrument is shown to produce a positive with a term independently known present — never a substring of the term under test. Reverse-check on the same file, terms taken from the ADR's own subject rather than from the phrase:

declaredCode -> 7 vocabulary -> 22 ledger -> 16

The instrument works over that file. The phrase is absent.

It lives in nine places, every one attributing it to ADR-0112:

site
packages/rest/src/error-response.ts:394
packages/rest/src/error-response.ts:871
packages/rest/src/analytics-filter-refusal-envelope.test.ts:405
packages/rest/src/rest-5xx-message-sanitization.test.ts:383
packages/rest/src/rest-5xx-status-passthrough.test.ts:218
packages/rest/src/rest-hook-refusal-code-parity.test.ts:346
packages/rest/src/rest-hook-refusal-status-passthrough.test.ts:384
packages/rest/src/rest-thrown-code-vocabulary.test.ts:253
packages/spec/src/shared/external-errors.ts:47

The substance is absent too, not only the wording

This is the part that matters, and it is why the card is not "fix a quote".

ADR-0112 is error-code-vocabulary-and-ledger, and every decision in it governs the semantic code: D2 renames the closed StandardErrorCode enum; D4 closes error.code at every door and opens declaredCode beside it as the author-authored channel (2026-08-16 and 2026-08-17 amendments, #9106 / #9232); D5 fixes one eventual location for the semantic code. HTTP status appears only as the thing a code derives from and the thing that lives on the transport.

Nothing in ADR-0112 rules on what HTTP status an UNDECLARED throw deserves.

As a paraphrase on the code axis the sentence is fair — D4's demote channel really does honour the producer's own spelling rather than discarding it, and error-response.ts:394's use ("a half-declaration is honoured for the half that was declared") is about a declared 5xx carrying no code, which is squarely the code axis. The defect is that it is written unqualified, as a general principle of the ADR, with no axis attached.

Why it is worth a card rather than a nit

The unqualified form was then read as governing status, and it nearly settled a contract question the wrong way.

#11684 records exactly two candidate rulings for "what status does an undeclared hook refusal deserve on /analytics/dataset/query", and names ADR-0112's "the producer names the condition" as the one arguing for 500. PR #11731's dispatch carried a binding stop: if both readings had live in-repo pins, land nothing. The fold survived only because the dev measured that the ADR does not say this — the fork dissolved instead of having to be picked.

Had the citation been believed, the honest outcome was a blocked card and a decision escalated to the maintainer on a premise that is not in the document.

⇒ Same class as #11032 (a doc comment citing ADR-0120 D4 for something D4's text did not say), which this lane closed today. Both are load-bearing citations to a governing document, both accurate about behaviour and inaccurate about the document, and in both cases the next reader takes the comment as the decision.

Not established here

  • Whether the fix is to qualify the nine comments or to amend ADR-0112. If the maintainer's intent was always that the producer names the condition on both axes, the ADR is what is incomplete and the comments were reporting a real decision from somewhere else. ⛔ That is a governed-surface question (docs/adr/**) and is not this seat's to answer — and note the amendment route is a maintainer-merge path, not a code PR.
  • Whether the packages/spec site (external-errors.ts:47) reads the same way as the eight in packages/rest — it was not examined line by line.
  • Whether any other principle is attributed to ADR-0112 in the same unqualified way. Only this phrase was censused.
  • Severity. ⛔ Not judged.

⚠️ Routing note for triage: eight sites are packages/rest and one is packages/spec, so this may want splitting, and the docs/adr/** half is governed either way.

Re-check

git grep -n -iE "producer names|names the condition" origin/main -- docs/adr/
git grep -n -iE "PRODUCER names the condition" origin/main -- '*.ts'
git grep -c -iE "declaredCode|vocabulary|ledger" origin/main -- docs/adr/0112-error-code-vocabulary-and-ledger.md

Related: #11684, #11683, PR #11731 (where this surfaced), #11032 (same class, closed), #11718, #11719.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions