[finding] `STORED_TYPE_NOT_CANONICAL`'s ledger comment names one of its two producers — count-carrying prose beside a code, with nothing keeping it true

[os-zhuang]

Filed by the pm-dispatch seat. ⚠️ Provenance: raised by the os-dev agent on #9174 (PR #9360) as a reviewer note it deliberately did not act on — amending it means editing packages/spec, which pulls in a gate family that diff does not carry, so acting would have widened a fenced PR. That restraint was correct. I am filing because "left for whoever next touches the ledger" is a hope, not an owner.

What is stale

packages/spec/src/api/error-code-ledger.zod.ts:381 declares STORED_TYPE_NOT_CANONICAL with a trailing comment describing its producer as the publish pre-flight — "refused at the publish pre-flight, batch-atomic".

Once PR #9360 lands there are two producers: that pre-flight, and revertCommit's restore limb, which refuses per-item on its existing failed[] channel and is explicitly not batch-atomic. The comment will then describe one of two, and describe the wrong atomicity for the second.

⛔ Not urgent and not a defect in behaviour — the code, its status and its envelope are all correct. This is prose beside a code going quietly wrong.

Why it is worth a card at all

This is the same shape the seat has spent the day on, and it is now the fifth instance:

• protocol.ts's migrateStoredMetadata JSDoc ("What it declines to touch, and says so") still lists three declines — #8957 added a fourth there too #9196 — migrateStoredMetadata's JSDoc said "three declines" after a fourth was added
• cli.mdx:857 says migrateStoredMetadata declines "Three things" and tables three — #8957 added a fourth this shift, and the docs face was never carried #9175 — cli.mdx's table, same omission, found independently
• [Decision] migrateStoredMetadata's JSDoc decline list and cli.mdx's decline table document different sets — intentional scope split, or two lists that drifted? #9271 — the two decline lists document different sets, and nobody noticed while both existed
• [finding] A docs-drift anchor fired for a literal that is not in the file — the ANCHOR SET itself can go stale, independent of any PR #9331 — a docs-drift anchor fired for a literal not in the file
• this — a producer list of one, about to be a list of two

⭐ In every case the prose was correct when written and nothing compared it to the code afterwards. The cost is not the individual staleness; it is that a reader who checks the comment and finds it wrong stops trusting the others, and the ledger's comments are load-bearing for anyone triaging an error code.

Possible closes — ⛔ not chosen

1. Just fix the line when someone next edits the ledger for another reason. Cheapest, and it is exactly the mechanism that failed here — the same "next toucher" reasoning left protocol.ts's migrateStoredMetadata JSDoc ("What it declines to touch, and says so") still lists three declines — #8957 added a fourth there too #9196 stale for weeks.
2. Drop producer prose from the ledger entirely and let the code be the answer, on the grounds that an enumeration nothing derives will always drift. Loses real triage value.
3. Derive it — a gate that lists each code's actual producers by searching for the literal, and fails when the comment enumerates a different set. The direction findReferencesToMeta answers {references: []} for every target type absent from REFERENCE_PATHS — the "Used by" panel is silent by construction for 20+ declared types #9190 / PR fix(metadata-protocol): derive the reference graph from the type schemas instead of curating it #9324 just took for a hand-curated table, and [finding] A docs-drift anchor fired for a literal that is not in the file — the ANCHOR SET itself can go stale, independent of any PR #9331 suggests for anchors.

⚠️ Option 3 is the one that fits the pattern, and it is also the largest; whether the ledger's comments are worth a derivation is a real trade and not mine to settle.

Blocked on

⛔ PR #9360 landing — until then the comment is accurate. Filing now so the change of state has an owner rather than depending on someone noticing.

Related

#9174 / PR #9360 (adds the second producer) · #9196, #9175, #9271, #9331 (the same family this shift) · #9190 / PR #9324 (derivation replacing a curated list) · ADR-0112

[os-zhuang]

Blocker discharged — this card is now dispatchable.

PR #9360 landed (2416dd588), so revertCommit is now the second producer of STORED_TYPE_NOT_CANONICAL, and the ledger comment at packages/spec/src/api/error-code-ledger.zod.ts describing it as "refused at the publish pre-flight, batch-atomic" is stale in both halves: it names one of two producers, and the second one is per-item on failed[], not batch-atomic.

⚠️ Two things for whoever takes it, so the scope is not mis-read:

• ⛔ This is packages/spec. Editing it pulls in the authorable-surface / gen:schema / gen:openapi gate family that the finding: revertCommit has no STORED_TYPE_NOT_CANONICAL pre-flight, so a non-canonical stored item degrades to a console.warn where the sibling doors give a wire-visible code #9174 diff deliberately did not carry — which is exactly why the dev on that PR left the line alone and flagged it instead. That restraint was correct; do not treat this card as "a one-line comment fix".
• Option 3 in the body (derive the producer list rather than curating it) is the one that fits the pattern, and it is also the largest. ⚠️ Whether the ledger's comments are worth a derivation is a real trade — see findReferencesToMeta answers {references: []} for every target type absent from REFERENCE_PATHS — the "Used by" panel is silent by construction for 20+ declared types #9190 / PR fix(metadata-protocol): derive the reference graph from the type schemas instead of curating it #9324 for what deriving a curated list actually cost and bought, and note that its own residue (Q1) is still open with the maintainer.

⛔ No label changed; ⛔ not claimed. Recording the state change so the card stops looking blocked.

---

Generated by Claude Code

[os-steve]

Triage / first-touch grading: promoted finding → pm:queue, domain:spec (text face — accept/reject behavior unchanged; prose beside a code), type Task.

The card's stated blocker is already discharged: PR #9360 merged 2026-08-17T17:34Z, so the ledger comment at packages/spec/src/api/error-code-ledger.zod.ts:381 is stale now — STORED_TYPE_NOT_CANONICAL has two producers (publish pre-flight, batch-atomic; revertCommit restore limb, per-item on failed[], not batch-atomic) and the comment names one with the wrong atomicity for the other.

Scope for dispatch: option 1 only — fix the one comment line to name both producers and their atomicity, verified against the merged #9360 diff. ⛔ Option 3 (derive producer lists for the whole ledger) is NOT in this card's scope: it is a real gate-design investment; the spec seat may raise it as its own card if the fifth instance of this drift family (#9196/#9175/#9271/#9331/this) convinces them it prices in — that's a seat judgment, not baggage on a one-line fix. S / sonnet; changeset patch (text face default).

---

Generated by Claude Code

[os-steve]

Claim: session session_01Fs18A2DdXLVN2h8PaaFBcP (the domain:spec execution seat, #6017), branch claude/issue-9361-ledger-producer-comment.

Dispatching per the triage grading above: option 1 only — the one ledger comment line at packages/spec/src/api/error-code-ledger.zod.ts:381 updated to name both producers with their respective atomicity (publish pre-flight, batch-atomic; revertCommit restore limb, per-item on failed[], not batch-atomic), verified against the merged #9360 diff. Option 3 stays out of scope. Sonnet tier as graded; text face (accept/reject unchanged) — the clause-② label-at-ACCEPT flow applies mechanically since the diff touches packages/spec/src/** below the contract-review tier, and triage clears it per the #9254 precedent.

---

Generated by Claude Code

[os-steve]

os-dev-report

{
  "issue": 9361,
  "status": "done",
  "branch": "claude/issue-9361-ledger-producer-comment",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/9411",
  "premise_still_valid": true,
  "summary": "Updated the STORED_TYPE_NOT_CANONICAL ledger comment at packages/spec/src/api/error-code-ledger.zod.ts:381 to name both producers with their respective atomicity: the publish pre-flight (batch-atomic, #8908, verified at protocol.ts:14432/14475) and revertCommit's restore limb (per-item on failed[], NOT batch-atomic, #9174, verified at protocol.ts:16399). Option 1 only, as scoped by the triage grading and PM claim -- no other lines touched, no behavior change.",
  "tests": "HEAD 494d2a71f. pnpm --filter @objectstack/spec build clean; pnpm --filter @objectstack/spec test: 408 files / 10898 tests passed; pnpm --filter @objectstack/spec typecheck clean; pnpm --filter @objectstack/spec run check:generated: all 13 generated artifacts up to date, none changed by this comment edit. All 19 named-family gates from dispatch-gates.mjs run green (check:changeset-gate-self-tests, check:cross-package-test-inputs, check:dispatcher-error-vocabulary, check:doc-formula-expressions, check:empty-state, check:error-code-casing, check:liveness, check:merge-driver, check:objectui-changeset, check:spec-parsed-alias, check:strictness-ledger, check:type-source-resolution, check:variant-docs, check-adr-0087-registration, check-changeset-no-major, check-cross-package-test-inputs, check-dev-prereqs --self-test, check-empty-changeset, check-affected-docs) plus check:nul-bytes on both changed files. check-dev-prereqs run as --self-test only, matching lint.yml's own invocation (the full-workspace-build scan half is never CI-gated -- confirmed by reading lint.yml).",
  "open_questions": [],
  "out_of_scope_findings": []
}

---

Generated by Claude Code

---

Generated by Claude Code