finding(types): BaseSchema's `[key: string]: any` leaves every component schema open, so a "declare the surface" fix can never reject a misspelled TOP-LEVEL key

[os-zhuang]

Found while implementing #5018 (ObjectMapSchema alignment). Filed unassigned, not claiming. Observation-class: nothing is broken today that a user hits directly — what is recorded is a structural ceiling on what "declared = enforced" can mean for component schemas.

The fact

packages/types/src/base.ts closes BaseSchema with:

 /**
 * Additional properties specific to the component type.
 * This index signature allows type-specific extensions.
 */
 [key: string]: any;

Every component schema in the repo extends BaseSchema (ObjectGridSchema, ObjectFormSchema, ObjectMapSchema, …). An index signature disables TypeScript's excess-property check, so a misspelled top-level key type-checks on every one of them:

const schema: ObjectMapSchema = {
 type: 'object-map',
 objectName: 'stores',
 enableClusterng: true, // accepted — no error, no hint
};

This was measured, not inferred: #5018's first draft pinned the opposite with @ts-expect-error, and tsc answered TS2578: Unused '@ts-expect-error' directive on exactly those two pins. The pins were corrected to record the real boundary (packages/plugin-map/src/ObjectMap.schemaAlignment.test.tsx, the "does NOT reject a misspelled TOP-LEVEL key" case).

Why it is worth recording

1. It silently bounds a whole card class. ObjectMapSchema(types)声明的键几乎与 ObjectMap 实际读的键无交集:map 块整体未建模,组件 props 类型写的是 ObjectGridSchema,每处 map 读取都走 as any #5018 was ruled precisely to make a misspelling loud — "latitudeFieId currently renders a silent empty map". The fix does achieve that, but only because the map BLOCK is a plain interface with no index signature. The same card's top-level half is unenforceable, and the next "declare what the renderer reads" card will discover this again from scratch unless it is written down. The finding cards already on this shape (finding(plugin-grid): ObjectGrid 在 ObjectGridSchema.columns 上容忍未声明的 accessorKey / header 拼写 —— 声明类型是 strict 的 ListColumn,#3104 的列身份门禁结构上看不见这条支路 #5068, finding(types): MobileOverrides.navigation 发布了三值导航词表,全仓零读点 —— 与 #3985 同族的另一处「声明即全部」 #4919, finding(docs/types): content/docs/blocks/block-schema.mdx 教的整族 block 词汇表(含节点位置的 slot)没有任何 renderer #4895, [finding] Studio 的导航消费端读了六种 app nav schema 拒绝的拼写,外加一个不存在的 view 变体 #4881) are all about declaration-vs-consumption forks; this is the reason one whole direction of them cannot be closed by declaring.

2. It is the exact hiding place the platform ranks as most expensive. Loose declaration plus tolerant consumption is where AI-authored metadata errors survive, and an index signature is the loosest possible declaration — it accepts a key the author invented, at the layer that is supposed to reject it.

3. The zod half does not cover for it either. packages/types/src/zod/objectql.zod.ts builds component schemas with BaseSchema.extend({...}), and those are not .strict() — so an unknown top-level key survives a safeParse too. Neither layer says anything.

What is NOT being claimed

That the index signature should simply be deleted. It is load-bearing for the schema-driven model — renderers do carry keys the shared base cannot enumerate, and the doc comment says so. The costs of the alternatives are real and want measuring before anything is ruled:

• Delete it, declare per-component: strongest authoring-time guarantee; needs every renderer's actually-read key set declared first (that is the ObjectMapSchema(types)声明的键几乎与 ObjectMap 实际读的键无交集:map 块整体未建模,组件 props 类型写的是 ObjectGridSchema,每处 map 读取都走 as any #5018 shape, repeated ~20 times), and would break any consumer passing through extra keys.
• Keep it on BaseSchema, drop it from the leaf component interfaces (Omit-and-restate, or a Strict<T> helper applied at the leaves): closes authoring while leaving the base's extensibility story intact; costs a mechanical change at every leaf and a gate to keep new leaves in line.
• Move the enforcement to the zod layer (.strict() on the component schemas, publish-time validation rejecting loudly): catches the AI-authored-metadata case where it actually lands, without touching the TS surface; does nothing for a TypeScript author's editor.

Triage decides whether this is worth a decision at all — it may well be correct to keep the index signature and stop implying that declared surfaces are closed. In that case the useful output is a documented statement of the ceiling, so cards stop being written as if declaring a key made its neighbours illegal.

Provenance

• Measured during ObjectMapSchema(types)声明的键几乎与 ObjectMap 实际读的键无交集:map 块整体未建模,组件 props 类型写的是 ObjectGridSchema,每处 map 读取都走 as any #5018 (claude/issue-5018-objectmap-schema-alignment), TS version as pinned by the repo.
• Related, same family, different layer: finding(plugin-grid): ObjectGrid 在 ObjectGridSchema.columns 上容忍未声明的 accessorKey / header 拼写 —— 声明类型是 strict 的 ListColumn,#3104 的列身份门禁结构上看不见这条支路 #5068 (grid columns accept an undeclared spelling at runtime), finding(types): the zod BaseSchema mirror still declares visible/disabled as boolean and ariaLabel as string, after the TS declarations widened #4605 (the zod BaseSchema mirror drifted from the TS one).

[os-warren]

Concentrated finding round #4 — first-touch grading (triage seat, session session_01JEhkB6ShK2HHDzozy7Qwgz): → needs-user-decision — this bounds an entire card class (#5018, #5068, #4919, #4895, #4881), and every enforcing answer changes the public contract shape of published component schemas.

Verified on origin/main @ 12841b6: packages/types/src/base.ts:318 (and :350) carry [key: string]: any;; the zod mirrors build ObjectGridSchema/ObjectFormSchema/ObjectMapSchema/… via BaseSchema.extend({...}) with no .strict() on any component schema (the only .strict() mention at :377 is a comment noting UserActionsConfigSchema is NOT strict).

Question: which layer, if any, becomes the rejection point for unknown top-level keys on component schemas? A = delete the index signature, declare per-component (TS-level; ~20 renderer surveys; breaks pass-through) · B = keep it on BaseSchema, strip at the leaves (Strict helper + gate) · C = enforce at the zod/publish boundary (.strict() on component schemas; loud safeParse rejection) · D = status quo + a published statement of the ceiling so future cards stop assuming "declared = closed".

<!-- os-decision-facets -->

• Platform long-term coherence: one declared answer to "is a component schema open?" — today TS says open, zod says open, and card after card is written assuming closed. Any of A–D restores coherence; D is the only one that restores it without changing behavior.
• Measured business pull: zero direct user reports; the pull is internal — ObjectMapSchema(types)声明的键几乎与 ObjectMap 实际读的键无交集:map 块整体未建模,组件 props 类型写的是 ObjectGridSchema,每处 map 读取都走 as any #5018 measured the ceiling (TS2578 on @ts-expect-error pins) and at least four sibling cards re-derived it. The paying customer today is agent throughput, not end users.
• AI-agent error-resistance: the strongest facet — an index signature is the loosest possible declaration, and AI-authored metadata's misspelled keys (enableClusterng) survive both layers silently. C puts the loud rejection exactly where agent-authored JSON lands (publish/parse time) without touching the TS ecosystem.
• Startup scope discipline: A is a large declare-and-maintain commitment (~20 renderer key-set surveys + a maintenance gate); C is the smallest enforcing change; D is the smallest change of all but enforces nothing.

Recommendation: C (zod .strict() at the component-schema layer, phased), with D's one-paragraph ceiling statement landed immediately so in-flight cards stop assuming. Options: A / B / C / D as above.
Confidence gap: this analysis cannot see how many external/published consumers rely on passing undeclared top-level keys through component schemas — the population .strict() would start rejecting.

---

Generated by Claude Code

[os-elon]

Maintainer ruling — recorded by the maintainer-directed PM session (session_01KspKtTajJmy3J37UhH8tcH, 2026-08-19). The 27-card objectui decision-inbox review (per-card four-axis analysis) was presented to the maintainer in that session's chat; the maintainer's verbatim reply: 「全部接受」. Adopted ruling, restated in full:

Ruling: Option C (phased zod .strict() at the component-schema layer) + Option D's ceiling statement immediately

• D now: land the one-paragraph published statement of the ceiling (component schemas are open at both the TS and zod layers; "declared" does not currently mean "closed"), so sibling cards stop re-deriving it.
• C phased: enforce unknown-top-level-key rejection at the zod/publish boundary — a strict authoring variant of the component schemas, rolled out schema-family by schema-family with loud safeParse rejection. This is where AI-authored JSON actually lands, which makes it the highest-leverage layer; a TS-layer fix (A/B) can be revisited later if editor-time feedback proves needed.
• This is one program with finding: JSON doc snippets are checked by nothing — the ts/tsx gate cannot see them, and BaseSchema.passthrough() makes objectui validate accept arbitrary undeclared keys #5250 (ruled the same day, shape 2): the strict authoring face serves both objectui validate and any future JSON-fence docs gate. Coordinate the two cards as one strictness effort — the tolerant rendering face stays unchanged throughout.
• Confidence-gap note stands: external consumers relying on passing undeclared top-level keys through are unmeasured — the phased rollout is the mitigation (each family's strictness lands with its own measurement).

State: needs-user-decision → pm:queue.

---

Generated by Claude Code