Skip to content

[finding] error-catalog.mdx publishes some error statuses only in prose or a JSON example, so check:error-status-conformance grades them as nothing — three entries publish no status it can read at all #9266

Description

@os-steve

Filed unassigned by the dev seat implementing #9244 (session session_01Fs18A2DdXLVN2h8PaaFBcP). Duplicate-searched over open and closed issues by gate name and by vocabulary terms (doc-published status, ungraded entry, batch operation errors); the only hit was #9244 itself, which covers the ledger-code half and not this.

What was measured

check:error-status-conformance reads a per-code status statement out of the docs in three graded shapes: a **HTTP Status:** line inside an entry, a quick-reference row, and a ## … Errors (NNN) section heading (the weak, category-grade one). Anything else on the page is not a statement it can read.

Measured on main (the run prints this census on every run as of #9244's PR): three catalog entries publish no status in any of those shapes.

ungraded: 3 doc entr(y|ies) whose heading was read but for which no page publishes a
          status in a graded shape (reported, not failed) —
    BATCH_PARTIAL_FAILURE   content/docs/api/error-catalog.mdx:465
    BATCH_COMPLETE_FAILURE  content/docs/api/error-catalog.mdx:470
    TRANSACTION_FAILED      content/docs/api/error-catalog.mdx:475

All three sit under ## Batch Operation Errors — a section heading that names no status, so it covers nothing — and none has a quick-reference row.

The general shape, which is what makes this worth recording: a status published only in prose or in a fenced JSON example is graded as nothing. That is exactly how INVALID_REQUEST's 400 was published before #9244 — the page said answers 400 with: and showed "httpStatus": 400 in an example, and both are invisible to the reconciler by design. #9244 fixed that one instance by making its status a designated **HTTP Status:** line; it did not sweep the page for others, and these three are what the sweep found.

Why it is worth recording

It is the residue of the same declared-vs-enforced shape #9244 closed, one grade weaker. A published status that no gate reads in either direction can drift silently, which is the precise failure the gate was built for.

Not claimed

  • No defect in the gate. The census above is reported on every run precisely so this is visible rather than hidden. Not reading prose is deliberate and correct — the runtime side refuses to mine prose for the same reason, and mining fenced examples would read illustrative envelopes as contracts.
  • Deliberately not failed in [finding] check:error-status-conformance excludes ledger codes on the premise that no doc page publishes their status — error-catalog.mdx now does, and that status is reconciled by nothing #9244's PR, and the reason bounds this card. All three codes are in scripts/error-status-unpinned-baseline.json: no producer the gate can read declares a status for them. So the gate cannot derive what these entries should publish, and failing on them would demand someone invent a published status to turn a gate green. Whoever picks this up needs to establish the real status from the batch write path first — this is not a mechanical doc edit.
  • Not measured: whether the batch paths emit a status at all, or whether these three are documented-but-unreachable codes. Both are live possibilities and they have different remedies (publish the status vs. retire the entries).

Backlinks: #9244 (the ledger-code half, and the PR that added the census that found this) · #8880 (the unpinned-census precedent — "no in-package declaration" recorded as a finding rather than a pass).

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions