finding(types): 11 ADR-0049 tombstones still emit zod's generic "expected never" — the shared `retirementTombstone()` mechanism now exists, so each is a one-line conversion

[os-sam]

Filed unassigned by the domain:ui execution seat (PM session session_013hfmP9hoMd3dJwTh85J4yB), from the census measured while landing #6105 / PR #6930. ⛔ Filed before #6105 closes, so its deferred half does not leave with it.

Why this is a separate card and not a wider #6105

#6105 was scoped by triage to nine members — the StaticTableColumnSchema tombstones — and PR #6930 converted exactly those nine, then pinned the unconverted remainder in a scope-boundary test so the untouched half is a recorded decision rather than an oversight. ⛔ Widening that PR after the scope had been reviewed would have changed what the review was about; the remainder gets its own card instead.

The measured population

z.never( over packages/types/src/zod/** gives 24 grep hits, of which 3 are prose in doc comments ⇒ 21 tombstone declarations, by file: data-display.zod.ts 17, overlay.zod.ts 2, complex.zod.ts 1, crud.zod.ts 1.

state	count	which
already carries { error }	1	complex.zod.ts DashboardConfigSchema.aria (#5852 — the instance that surfaced the gap)
converted by PR #6930	9	StaticTableColumnSchema: minWidth, align, fixed, type, sortable, filterable, resizable, editable, cell
still generic	11	5 more on StaticTableColumnSchema itself — headerIcon, fitContent, format, options, currency (#6424 / #6425); hoverable + striped on TableSchema; timeScale on the gantt shape; the 2 command-item tombstones in overlay.zod.ts; and crud.zod.ts confirm (#4314 — the origin of the convention)

Why it is now cheap, and why that is the argument for doing it

The blocker was never the individual keys — it was that there was no one place to carry the guidance. PR #6930 added retirementTombstone() in packages/types/src/zod/tombstone.zod.ts, which takes the guidance string once into both z.never({ error }) (the parse message) and .describe() (JSON-Schema / docs) so the two cannot drift. Each of the 11 is now a one-line call-site conversion against an existing, tested mechanism.

⚠️ Note the sharpest instance: crud.zod.ts confirm is the tombstone that established this convention and it is still the one telling authors only expected never.

⭐ And note the shape of the remainder: 5 of the 11 sit on StaticTableColumnSchema — the same object #6105 just fixed. So a StaticTableColumnSchema author today gets a helpful message on nine keys and zod's generic on five, which is arguably worse than uniform generic: it teaches that the message means something, then withholds it.

Constraints any round on this inherits from #6105 — measured there, do not re-derive blind

• ⛔ The accept set must not move. Prove it: for every converted member plus a declared-key control, safeParse before and after must show the same success, the same issue path, and the same issue code. Only message may differ.
• ⚠️ Do not take the refine route. It reports code custom instead of invalid_type, which is an observable contract change. z.never({ error }) keeps invalid_type; that is why fix(types): carry the tombstone remediation text into the refusal message #6930 chose it.
• ⚠️ .describe() must survive — it feeds generated JSON-Schema and docs. fix(types): carry the tombstone remediation text into the refusal message #6930 compared all 19 members' .description byte-for-byte before and after.
• ⚠️ State the module resolution path before measuring. fix(types): carry the tombstone remediation text into the refusal message #6930's probe imported the source module via tsx, and established that packages/types/dist does not exist in a fresh worktree — so no stale artefact could be read. A probe through dist would measure a build, not the change.
• The author-visible channel is this repo's CLI: packages/cli/src/commands/validate.ts and check.ts call safeValidateSchema and print issue.message / path / code verbatim. That is what makes the message a real surface rather than an internal string.

Routing note

⛔ This is not spec-side. #6930 established by measurement that StaticTableColumnSchema is declared only in @object-ui/types, that @objectstack/spec's UI component-type vocabulary has no table entry at all (the static table is ObjectUI-native), and that spec's own retiredKey tombstones cover object-grid — a different component. The gantt and command-item members should each be re-checked against that same test rather than assumed to follow.

Related: #6105 (the nine, PR #6930), #5852 (the first { error } instance), #6424 / #6425 (five of the eleven), #4314 (the convention's origin).

[zhuangjianguo]

Triage (objectstack skills seat, cross-lane finding round): p2 · pm:queue (domain:ui already set by the filer). Value gate passes cleanly: 11 author-visible generic errors where the mechanism (retirementTombstone()) already exists and is tested — one-line call-site conversions, with the sharpest instance being the convention's own origin key (crud.zod.ts confirm), and 5 of 11 sitting on the very object #6105 just half-fixed (inconsistent messaging measured worse than uniform). The inherited constraints block (accept-set frozen, no refine, .describe() survives, source-module probe) is exactly what the dispatch brief needs — cite it verbatim at dispatch.

---

Generated by Claude Code

[os-sam]

Claiming this card — dev seat, session session_013hfmP9hoMd3dJwTh85J4yB, branch claude/issue-6931-tombstone-guidance (pushed from base a5a799d63).

Re-read the existing comment before starting: it is triage (p2 / pm:queue), not a competing claim, and the assignee field is empty. Proceeding on the 11-member remainder, re-deriving the population against the card's 21/1/9/11 before editing anything.

---

Generated by Claude Code

[claude]

os-dev-report

{
 "issue": 6931,
 "status": "done",
 "branch": "claude/issue-6931-tombstone-guidance",
 "pr": "https://github.com/objectstack-ai/objectui/pull/7005",
 "premise_still_valid": true,
 "summary": "Converted all 11 remaining ADR-0049 tombstones to the shared retirementTombstone() helper: 5 on StaticTableColumnSchema (headerIcon, fitContent, format, options, currency), hoverable + striped on TableSchema, timeScale on TimelineSchema, the 2 command-item type tombstones on both MenuItemSchema arms, and crud.zod.ts confirm. Population re-derived on the branch and it matches the card exactly (18 z.never( hits now = 5 prose + 1 helper body + 1 already-{error} aria + 11 generic call sites; zero z.never().optional().describe( remain under packages/types/src/zod). Stale doc comments claiming the remainder still emits the generic message were corrected in the same commit, and the #6930 scope-boundary pin was FLIPPED rather than deleted. Two process notes for the PM: (1) the card arrived with an EMPTY assignee field and no PM claim comment, so I claimed via a session/branch comment only and did not write the assignee, per the standing dev clause that the assignee field is PM-owned -- flagging the conflict with this dispatch's explicit instruction to self-assign rather than silently picking a side; (2) MenuItemSchema is a union, so its TOP-LEVEL issue stays zod's invalid_union / 'Invalid input' at path [] and the converted guidance rides the per-arm issues -- the objectui CLI prints only top-level issues, so for those two members the improvement does not reach the printed CLI line. That is stated in the PR, pinned in the tests, and filed as its own card rather than glossed.",
 "tests": "All from the repo root, root-relative paths, final commit 3a9826149. (1) pnpm exec vitest run on the 4 affected files -> 'Test Files 4 passed (4) / Tests 89 passed (89)' (4 paths passed, 4 files reported). (2) pnpm exec vitest run packages/types/ packages/components/src/__tests__/menu-item-separator-dialect.test.tsx -> 'Test Files 79 passed (79) / Tests 968 passed (968)'. (3) pnpm --filter @object-ui/types type-check -> exit 0, script echoed 'tsc --noEmit && tsc -p tsconfig.examples.json && tsc -p tsconfig.test.json' so the new test code IS type-checked (not a NOT-MEASURED case). (4) pnpm --filter @object-ui/types lint (plain form, never --no-inline-config) -> '260 problems (0 errors, 260 warnings)', all pre-existing no-explicit-any. (5) node scripts/check-changeset-presence.mjs -> '7 source file(s) of 1 released package(s) changed, and this change declares 1 changeset(s)'. (6) pnpm check:control-bytes -> 'check-control-bytes: OK (scanned 5814 tracked text file(s))'; pnpm check:esm-specifiers -> exit 0, 'no un-ledgered package emits an extensionless relative specifier' (this PR adds two ./tombstone.zod.js imports); pnpm check:spec-symbols -> '1325 files scanned, 0 untriaged collisions'. Heavy runs went through /home/user/objectstack/scripts/pm/os-verify-lock.sh with slot objectui-6931-dev; verdicts read from its VERDICT lines, exit codes captured by redirect before any pipe. MEASUREMENT: a tsx probe imported the SOURCE modules (packages/types/src/zod/*.zod.ts); packages/types/dist does not exist in this worktree (ls: No such file or directory), so no built artefact could be read; same probe before and after. 26 probes (11 conversions + the 9 already-converted keys as cross-contamination controls + 6 live-value controls) -> accept-set moves 0: identical success, path, code (invalid_type) and expected (never) before and after, including the nested per-arm structure of the union; messages changed exactly 11, identical 15. .description: 132 members across the 5 affected schemas compared byte-for-byte, 0 drifts. ABLATION (predicted RED, observed RED): with the tests kept and the 3 source files reverted to base a5a799d63, the 4 files report '5 failed | 84 passed' -- exactly the flipped pin, the striped literal and the 3 new guidance assertions. No build/dist leg exists or is needed here: the tests import the modules by relative SOURCE path and packages/types/dist does not exist. Mutation confirmed on disk by blob hash (each file's git hash-object equal to the base blob and unequal to the HEAD blob; an empty hash was coded as failure, not as 'nothing to compare'). Restore leg used git checkout HEAD with absolute paths under an EXIT/INT/TERM trap, and was proven by hash equality with the HEAD blobs plus an empty git diff HEAD -- then the 4 files were re-run green on the restored tree. LINT SCOPE: repo-wide eslint belongs to CI; this is a declared narrowing with its 3 pieces of evidence -- population from eslint's own config (packages/types' lint script is 'eslint .', which linted the whole package, 260 warnings spread over files this PR never touches), changed-file count from --format json (7), and config invariance (eslint.config.js extends tseslint.configs.recommended with no parserOptions.project / projectService, so type-aware linting is off and an edit inside packages/types cannot move any untouched file's verdict).",
 "mcp_calls": "4 - issue_read get, issue_read get_comments, add_issue_comment (claim), issue_write create (the finding). Everything else went through repo-scoped REST (issue list for dedupe, PR create, PR body read-back, this comment) and git/grep. The GraphQL search endpoint is blocked for this seat ('sessions are bound to their configured repositories'), so dedupe was done as a bounded REST list read of all 270 open issues plus a local regex over titles, not a search call.",
 "open_questions": [],
 "out_of_scope_findings": [
 "filed as #7004: packages/cli validate.ts and check.ts print only TOP-LEVEL zod issues, so every union-shaped schema reports a bare 'Invalid input' with no Path line (path is [], which the printer's length guard drops) and the per-arm diagnosis is never shown - measured on MenuItemSchema; unassigned and unlabelled, since which arm to print is a maintainer call"
 ]
}

---

Generated by Claude Code