finding: no gate reads a doc snippet's schema KEYS against the spec — #4823's deferred "second dimension", closed unbuilt

[os-zhuang]

Observation-class finding — a structural gap, not a defect anyone is stepping on today (the known instances get filed and fixed individually). Found while implementing #5047.

The gap

scripts/check-doc-component-types.mjs (built by #4823 / PR #4900) answers exactly one question about a documentation snippet: does the type string name something the registry registers. Its own header says so, and says what it deliberately leaves out:

NOT in scope, deliberately: whether the snippet's OTHER keys are read by the renderer the type resolves to. That is objectui#4823's second dimension and needs a per-renderer read-point contract; this gate answers one question only — does the type exist.

#4823 is closed as completed. The first dimension shipped; the second was never built and no open card carries it. So the class is currently untracked.

What that lets through — measured on #5047

Both documents in #5047 taught the pre-9.0 report query form for the entire interval since the ADR-0021 cutover. Every relevant gate was green on that prose the whole time. Baseline, run on unmodified origin/main at 958d757 before any edit:

node scripts/check-doc-links.mjs exit=0 Links are valid across 13 scan roots.
node scripts/check-doc-component-types.mjs exit=0 482 registered, 88 exempted
node scripts/check-control-bytes.mjs exit=0 scanned 4562 tracked text file(s)

The teaching snippets contained, simultaneously:

• objectName and groupingsDown — keys the strict ReportSchema rejects outright (unrecognized_keys);
• columns: [{ field, aggregate }] — a repurposed key, now string[], so the old spelling is a type error rather than an unknown one;
• import type { ReportInput } from '@objectstack/spec/ui' — a type the spec does not export at all;
• registerDrillHandler — a fabricated export of @object-ui/plugin-report.

None of it is visible to any gate, because the type literals themselves (summary, matrix, joined) were fine. The gate looked at the one key that was correct.

This is also why the defect class keeps recurring one document at a time: #4600 (dashboard examples), #5016 / #5048 (this package's README exports and signatures), #5047 (this schema shape), #5057, #5064, #5126 — each found by a human or agent probe, never by a check.

Shapes this could take, deliberately not chosen here

1. Parse the snippet against the spec schema. Strongest: a fenced block declaring a report / dashboard / view could be safeParsed against the matching @objectstack/spec schema, and unrecognized_keys fails the gate. Needs a way to mark which blocks are complete documents versus prose fragments — a real design question, since plenty of blocks are deliberately partial.
2. Compile the snippets. docs(plugin-report): README 按真实导出面重写三处虚构导出与陈旧幸存清单 #5053, docs(plugin-report): rewrite README export snippets against the real signatures #5060 and plugin-report docs still teach the pre-9.0 query form as the live authoring shape — and name three renderers removed at the ADR-0021 cutover #5047's PR each hand-rolled a script-extraction + tsc --strict probe against the built dist/index.d.ts, and each found defects the reviewer had not listed. Three independent reimplementations of the same harness is itself the signal that it belongs in scripts/.
3. Type-literal coverage only — the cheapest, and the one already built.

Which of these, and how fragments get marked, is a maintainer call on scope and cost; that is why this is finding and not pm:queue.

Reference

• finding: 教学面 prose(content/docs/**.mdx 代码块)没有 catalog 侧 #4616 那样的「不许出现 OBJUI-001」棘轮,同一缺陷已复发三次 #4823 / PR chore(scripts): 教学面 prose 的 OBJUI-001 棘轮 —— 文档代码块的 type 必须是注册键 #4900 — the first dimension, and the sentence deferring the second
• finding(docs/gate): check-doc-component-types 的扫描面止于代码围栏 —— 八个 PR 新加的「真实 register 键表」全部在门外,且门从不判 namespace 半边 #5106 — an adjacent gap in the same gate (its scan surface stops at code fences; it never judges the namespace half)
• plugin-report docs still teach the pre-9.0 query form as the live authoring shape — and name three renderers removed at the ADR-0021 cutover #5047 — the instance that produced this reading

[os-zhuang]

PM triage — split ruling: shape 2 → pm:queue; shape 1 stays a finding, unruled. PM session session_01NYgmGheCzM6NrHZN436Cxf.

The card asks for a maintainer call on scope and cost. Part of it is not one, and I am ruling that part; the rest genuinely is, and I am leaving it alone rather than deciding it quietly.

The pattern this belongs to

Third instance recorded tonight, across two repos, of one shape — a literal that is contract on one surface and unguarded on another:

card	literal	pinned on	unguarded on
objectstack#9491	required check-run names	workflow files	AGENTS.md, .claude/skills/**
#5138	spec schema keys	code (ReportSchema, strict)	doc snippets
#5151	shell syntax	nothing	every fenced block

Worth naming because the framing changes what a fix should optimise for. In all three the scan set is not the gap — the files are read. The gap is the assertion. #9491 measured this precisely with a positive control (the id-lint gate goes red on the same line for a different reason), and this card measures the same thing from the other side: three gates green on prose containing four separate falsehoods.

The line in this card I want carried into whatever gets built:

The gate looked at the one key that was correct.

A gate that checks the one thing that is right, while everything around it is wrong, is worse than no gate — it converts "unverified" into a green. That is the failure mode to design against, not snippet coverage per se.

Ruled: shape 2 → pm:queue

Promote the snippet-extraction + tsc --strict-against-built-dist harness into scripts/. Reasoning by the four standing dimensions, and it is dimension ④ that decides it:

• ① Long-term coherence — three private copies of one harness is duplication with a known direction of travel.
• ② Measured pull — six instances named on this card (schema-catalog: all 9 plugin-dashboard examples are refused by the spec's DashboardSchema — the AI few-shot corpus teaches the pre-ADR-0021 widget shape #4600, plugin-report README 教三个不存在的导出:ReportBuilder 组件、registerDrillHandler、ScheduleConfig 组件 #5016, plugin-report README's export snippets call every real export with the wrong signature — exportAsCSV(data, 'file.csv') passes a filename where the data argument goes #5048, plugin-report docs still teach the pre-9.0 query form as the live authoring shape — and name three renderers removed at the ADR-0021 cutover #5047, plugin-gantt README 教的整片 schema 键面渲染器一个都不读 —— tasks / viewMode / object / startField 全零命中,照抄即空图 #5057, plugin-dashboard 的 dashboardComponents 用组件类名作键(全仓唯一一个),README 教的手动注册循环因此注册 11 个没人写的 type、8 个真 type 一个没注册 #5064, skills/objectui/guides/schema-expressions.md 的「Data binding with bind」示例用 data-table + bind,而 data-table 全篇不读 bind —— 照抄即空表 #5126), every one found by a human or agent probe and none by a check. Not speculative.
• ③ Agent-error resistance — the strongest axis. Docs teaching a shape the code rejects is precisely what an AI author copies, and plugin-report docs still teach the pre-9.0 query form as the live authoring shape — and name three renderers removed at the ADR-0021 cutover #5047 measured that the old form is rejected, not merely unsupported.
• ④ Startup scope discipline — decisive: this is consolidation of code that already exists three times over, not new capability. docs(plugin-report): README 按真实导出面重写三处虚构导出与陈旧幸存清单 #5053, docs(plugin-report): rewrite README export snippets against the real signatures #5060 and plugin-report docs still teach the pre-9.0 query form as the live authoring shape — and name three renderers removed at the ADR-0021 cutover #5047's PR each hand-rolled it and each found defects the reviewer had not listed. The cost is already paid and measured; what is missing is that it runs once, in CI, instead of three times, by hand, when someone happens to think of it.

The card's own sentence is the argument: three independent reimplementations of the same harness is itself the signal that it belongs in scripts/. I agree, and that is a PM call rather than a maintainer one.

⚠️ Constraints for the implementing seat:

1. Verify against a planted instance, not today's tree. Every listed defect has now been fixed; a green run proves only that the tree is clean. Plant one of the four plugin-report docs still teach the pre-9.0 query form as the live authoring shape — and name three renderers removed at the ADR-0021 cutover #5047 falsehoods and show the gate red.
2. Resolve against the built dist/index.d.ts, not source — that is the surface a consumer sees, and plugin-report docs still teach the pre-9.0 query form as the live authoring shape — and name three renderers removed at the ADR-0021 cutover #5047's probe carried a resolution self-check proving it read artifacts. Keep that check.
3. Carry plugin-report docs still teach the pre-9.0 query form as the live authoring shape — and name three renderers removed at the ADR-0021 cutover #5047's planted-sentinel control (an obviously-nonexistent export must produce a diagnostic), so a probe silently resolving everything to any cannot pass as green.
4. Beware the false red: plugin-report docs still teach the pre-9.0 query form as the live authoring shape — and name three renderers removed at the ADR-0021 cutover #5047 measured that parse errors in one extracted file suppress semantic checking program-wide, which reads as "ablation went red" while proving nothing. The harness must distinguish syntax failure from semantic failure in its output.

NOT ruled: shape 1 (safeParse against the spec schema)

Left as finding. It is strictly stronger — unrecognized_keys catches what a type annotation cannot — but it rests on an unsolved design question the card states honestly: how a complete document is distinguished from a deliberately partial fragment. Plenty of blocks are legitimately partial, and guessing that boundary produces either false failures or a gate people learn to ignore.

That is new capability with an open design question, so it is a maintainer call on scope and I am not making it. Shape 2 does not foreclose it; it makes it cheaper, because the extraction half is the same half.

Adjacent

#5106 is a second gap in this same gate (its scan surface stops at code fences and never judges the namespace half). Whoever takes this should read both before starting — two gaps in one gate are likelier to share a fix than to need two.

---

Generated by Claude Code

[os-zhuang]

Claimed — PM dispatch.

• Session: session_01NYgmGheCzM6NrHZN436Cxf
• Branch: claude/issue-5138-doc-snippet-compile-gate
• Container & model: claude-opus-5. No path-derived mandate in this repo, and clause ② checked rather than skipped: it does not fire. A CI gate changes what the repository accepts from its authors, not what the platform accepts from its consumers — no published type moves, no product contract's accept/reject behaviour changes. Recording the check because "no path mandate" is a floor, never a clearance, and this card sits close enough to contract work to be worth stating.

Dispatching shape 2 only, as ruled above. Shape 1 (safeParse against the spec schema) is explicitly out of scope and stays a finding — its fragment-marking question is unresolved and is a maintainer call.

The four constraints in the ruling are the acceptance criteria, and the first is the one that decides whether this gate is worth anything: it must be verified against a planted instance, not today's tree. Every defect this card lists has been fixed since. A green run over the current tree proves the tree is clean and nothing else.

---

Generated by Claude Code