docs(audit): spec enum ↔ renderer coverage audit (#2901)

[os-zhuang]

Closes the first pass of #2901. Deliverable is the table, not the fixes — as the issue asked.

Audits every named enum export in @objectstack/spec@16.0.0-rc.0 ui/ against its renderer counterpart in both directions, plus field types and filter operators. Five parallel auditors; every row read off the dispatch code, with the highest-stakes claims independently re-verified in source.

What it found

Direction A gaps with a user-visible defect	24
…plus inert ones (validate, change nothing)	11
Surfaces carrying renderer-local dialect	10
objectui forks shadowing a spec symbol name	5
Enum-value parity guards in the repo	1

The issue's premise was inverted

#2901 read ChartTypeSchema as a 7-value spec enum outgrown by a 13-value renderer. The spec has 19 values; the 7-value list is an objectui fork (types/src/zod/data-display.zod.ts:209) re-exported under the spec's own symbol name.

That generalises, and it is the audit's most useful result: the recurring failure is rarely "renderer forgot a name" — it is "a second definition of the vocabulary exists, and the renderer is faithful to the wrong one". Five such forks; the PageType trio holds three disagreeing definitions inside one package, drifting in both directions at once.

Triaged by runtime symptom, not by direction

That axis orders the work by how long a defect survives undetected:

• Tier 1 (6) — silently wrong output. Worse than the bug that prompted this issue. PivotTable.tsx:114 returns a sum for count_distinct; DatasetReportRenderer.tsx:370 silently draws a bar chart for 10 of 19 types. A blank cell is detectable; a plausible wrong number is not.
• Tier 2 (15) — silently absent. The feat(grid): compute all eleven spec column summary aggregations (#2890) #2897 shape, including element: 'toggle' deleting the whole filter bar, and 6 of 9 animation presets doing nothing because useAnimation.ts:64 keys its lookup in hyphens where the spec enum uses underscores.
• Tier 3 (3) — loud red box. Cheapest to triage precisely because it cannot hide.
• Tier 4 (11) — inert. Live the moment anyone wires the surface up.

Structural finding

19 of 30 spec UI vocabularies have nothing mechanically tying them to the spec. The repo has a mature drift-guard doctrine for schema shape (#2231, three tests) and exactly one guard for enum-value renderer coverage (#2897). Two tests that look like coverage guards aren't: field-type-coverage.test.ts hard-codes its expected list instead of importing FieldType — which is why the autonumber display gap survived — and block-config.test.ts asserts palette exclusions by hand, locking drift in rather than detecting it.

Prerequisite for the guard work: 6 of the 13 packages that need one cannot import the spec today.

Follow-ups

Two items in the table are plain bugs with no design question and are handled separately: $ncontains (a token appearing zero times in the spec, which objectui's own converter throws on) and secret missing from INLINE_EXCLUDED_FIELD_TYPES two lines from password. Per-tier issues to follow.

Docs-only. No code touched.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Jul 28, 2026 5:16pm