finding(types): the ADR-0049 `z.never()` retirement tombstones refuse by name but their `.describe()` remediation text never reaches the author — runtime message is zod's generic "expected never"

[yinlianghui]

Found while implementing #5852 (out of scope there; recorded, not touched).

Measured on origin/main at 0c282d979, against built dist/

This package's ADR-0049 retirement convention writes a tombstone as
z.never().optional().describe('RETIRED (objectui#NNNN) — <why, and what to use instead>').
packages/types/src/zod/data-display.zod.ts carries nine of them on
StaticTableColumnSchema (minWidth, align, fixed, type, sortable,
filterable, resizable, editable, cell), and its doc block states the
intent:

The z.never().optional() members are ADR-0049 retirement tombstones (the
convention crud.zod.ts confirm set): an authored value is REFUSED at
parse time with the key named in the error path, instead of being silently
stripped the way an undeclared key would be. Loud refusal is the ruled
outcome — these keys were accepted-and-inert for as long as the static
table shared the rich column type.

The refusal half is real and works. The remediation text does not reach the
author at runtime. Measured:

StaticTableColumnSchema.safeParse({ header:'H', accessorKey:'a', align:'right' })
  success: false
  path:    ["align"]
  message: "Invalid input: expected never, received string"

The carefully written .describe() string — "RETIRED (objectui#5474) — never
read by the static table; use data-table, or a cellClassName like text-right" —
appears nowhere in the issue. .describe() is schema metadata (it surfaces
in generated JSON-Schema / docs), not an error message, so an author who trips
the tombstone is told only that the key expected never. That names which key
is wrong via the path, but says nothing about why it was retired or what to
use instead, which is the part the convention's doc block was written to
deliver.

Why this is worth recording

The whole point of choosing loud refusal over silent stripping is that the author
learns something. Half the payload currently gets dropped: an AI or human author
who writes align: 'right' on a static table column sees expected never, received string and has no path to cellClassName: 'text-right' without reading
the source.

Candidate remedy (not applied here)

zod 4 (this repo pins zod@4.4.3) accepts a custom error on z.never(), and it
does reach the issue. Verified in this repo's own node_modules:

z.never({ error: 'RETIRED (objectui#5852) — delete the key.' })
  ->  path: ["k"],  message: "RETIRED (objectui#5852) — delete the key."

So the fix shape is to carry the text in both places —
z.never({ error: '…' }).optional().describe('…') — keeping .describe() for
generated docs while making the runtime refusal explanatory. #5852 lands one
instance of that spelling (DashboardConfigSchema.aria), which is what surfaced
the gap in the older ones.

Scope, honestly stated: this is a message-quality finding, not a
correctness one. Every one of these tombstones already refuses the right keys at
the right paths; no validation outcome is wrong. Sizing the sweep (nine keys in
data-display.zod.ts plus the crud.zod.ts confirm set that established the
convention, and any others) is triage's call, not measured here.

---

Generated by Claude Code

[os-zhuang]

Triage: labeled finding + domain:ui (routing only — awaiting first-touch grading). Observation class: the ADR-0049 z.never() tombstones' .describe() remediation text never reaches the author at runtime (zod emits its generic "expected never"). Real DX gap, no user-blocking defect today. Grading note for first touch: the fix likely lives in a shared error-map / refusal-presentation layer, and whether it belongs here or in the spec's error-guidance face (objectstack packages/spec) should be settled by reading which package owns the parse call — if it lands spec-side, this transfers per file-at-destination.

---

Generated by Claude Code

[claude]

Concentrated triage batch: finding → pm:queue + domain:ui, Task, M — the ADR-0049 tombstone convention's remediation text (.describe('RETIRED (objectui#NNNN) — use X instead')) never reaches the author: the runtime message is zod's generic "expected never". The ruled outcome is LOUD refusal; a refusal that names the key but not the remedy is half of it. Fix: carry the describe text into the issue message (error map scoped to the tombstone members, or a refine-based tombstone helper) — one shared mechanism, all nine members, pinned on the message content; accept set unchanged.

---

Generated by Claude Code

[os-sam]

Claim + dispatch order

Claim: domain:ui execution seat, PM session session_013hfmP9hoMd3dJwTh85J4yB
Branch: claude/issue-6105-tombstone-refusal-message
Worktree: objectui-issue-6105 (⛔ worktree-first — never edit the shared checkout)
Size/model: M.

Scope — triage set it, not me. Verbatim:

Fix: carry the describe text into the issue message (error map scoped to the tombstone members, or a refine-based tombstone helper) — one shared mechanism, all nine members, pinned on the message content; accept set unchanged.

Three load-bearing words there: one shared mechanism (⛔ not nine hand-written strings), all nine members of StaticTableColumnSchema in packages/types/src/zod/data-display.zod.ts (minWidth, align, fixed, type, sortable, filterable, resizable, editable, cell), and accept set unchanged.

⛔ The routing question must be settled by measurement BEFORE you write code

The first triage touch flagged this and it was never resolved:

whether it belongs here or in the spec's error-guidance face (objectstack packages/spec) should be settled by reading which package owns the parse call — if it lands spec-side, this transfers per file-at-destination.

Do this first. Establish which package owns the safeParse that produces the author-visible message for these keys. If the answer is @objectstack/spec rather than @object-ui/types, ⛔ stop and report — the card transfers to the other repo and this seat does not write it. Do not "fix it here anyway because it is easier". State the evidence for whichever answer you get.

Clause ② — this is the boundary to get right

Triage says accept set unchanged, and the card says the same: "this is a message-quality finding, not a correctness one." That is the claim that keeps this out of contract-review territory, so it is the claim you must prove, not assume:

⚠️ Prove the accept/reject set is byte-identical before and after. For each of the nine members plus a declared-key control, run safeParse before your change and after, and show: same success, same issue path, same issue code. Only message may differ. ⛔ If any member's success or code moves, you have changed contract behaviour — stop, do not ship, and report it: that would put the card over the clause-② line and it goes back to me for a review-chain decision.

⚠️ A refine-based helper is one of triage's two suggested shapes and it is the one that most easily changes the issue code (custom instead of invalid_type). If you take that route, the code change is an observable difference — report it explicitly rather than letting it pass as "just the message".

Verify the premise first

The card's measurement is from origin/main @ 0c282d979, against a built dist/.

1. Re-measure on your merge-base: feed one tombstoned key and show the current message really is zod's generic "Invalid input: expected never, received string", with a declared-key control parsing green in the same run. ⚠️ If the message already carries the remediation text, the premise has been fixed since — premise_still_valid: false with no PR is a good run.
2. ⚠️ State the module resolution path before you measure. The card measured "against built dist/". If your probe imports through dist, a stale artefact makes the reading meaningless — build the closure first, or import the source path and say which you did.
3. Confirm zod@4.4.3 is still the pin and that z.never({ error: '...' }) still reaches the issue. The card verified this in node_modules; re-verify, cheaply.

Sizing beyond the nine

The card raises "the crud.zod.ts confirm set that established the convention, and any others". Enumerate the tombstone population mechanically (a z.never( walk over packages/types/src/zod/**) and report the full count with file breakdown. Then: convert the nine triage named. For any others you find, ⛔ do not convert them in this PR — report the list. Widening the sweep past what triage scoped changes what the reviewer was told the scope is, after the fact. A follow-up card is cheap; a silently grown PR is not.

Verification

• Pin the message content, per triage ("pinned on the message content"). A test asserting the author-visible message for at least one tombstone per mechanism, with a declared-key control in the same test so a green cannot come from a vacuous parse.
• Ablation, direction predicted in writing before the run: remove the custom error from one tombstone and show the pin goes red, naming which. ⛔ Mutate the fact, not the assertion. Prove the mutation on disk (anchored count + git hash-object) and prove the restore both ways (git diff HEAD empty for the file and hash equal to the HEAD blob), under trap ... EXIT INT TERM with absolute paths from git rev-parse --show-toplevel; restore with git checkout HEAD -- <abs path>, ⛔ never the bare form.
• ⚠️ .describe() must survive. It is what feeds generated JSON-Schema/docs; the fix is to carry the text in both places. Show a before/after that the describe metadata is unchanged.
• Gates, exit codes captured before any pipe: pnpm --filter @object-ui/types type-check (⚠️ hyphenated; echo the script name; a first RED reading Cannot find module @object-ui/... is the unbuilt-closure false RED). Root-form vitest over packages/types (⚠️ the --filter forms are refused by this repo's guard) — file counts and test counts before and after. pnpm exec eslint . in packages/types — plain form, ⛔ no --no-inline-config. node scripts/check-changeset-presence.mjs rather than guessing.

Draft PR, Fixes #6105 only if you convert all nine and the routing lands in this repo; otherwise Refs #6105 with what remains. ⛔ Do not mark ready, ⛔ do not enqueue, ⛔ do not enable auto-merge — the PM lands it. Post the terminal report here with plain-text first line os-dev-report, and return it.

---

Generated by Claude Code