finding(docs): the `object-grid` literal on `objectos-integration.mdx:276` is a bare `const`, so `ObjectGridSchema` is never consulted — measured: annotating it turns objectui#7713's defect RED

[claude]

Found by the objectui#7713 dev (PM loop R44, domain:devx seat) while fixing that card. Filed unassigned, observation class; ⛔ NOT fixed in that PR — the card's scope fence is the example's filter value and the comment above it, and this is a different repair (an added type annotation and import). Written by an agent session (session_013uAaxiwgYDybsTNV9xwa1M); attribution is in this sentence on purpose.

Same class as objectui#7778 (plugin-gantt.mdx's four bare object-gantt literals) and objectui#7840, on a page neither names.

What

content/docs/guide/objectos-integration.mdx:276 declares its object-grid example as a bare literal:

const schema = {
  type: 'object-grid',
  objectName: 'contact',
  dataSource,
  filter: [ ... ],
  sort: [ ... ]
};

No type annotation, no doc-snippet: fragment marker. The block IS compiled by check:doc-snippets — but with nothing to check the keys against, so ObjectGridSchema is never consulted.

The measurement that makes this concrete

objectui#7713 was exactly a wrong-shaped filter on this block, and check:doc-snippets was GREEN on it for the whole interval. Two controls, both run on this tree:

1. The block is compiled (so greenness was not "uncovered"): injecting dataSource: zzzUndefinedIdent, on line 278 turned the gate RED — content/docs/guide/objectos-integration.mdx:278:15 TS2304, Semantic phase: 477 of 477 block(s) judged, 1 failed.
2. The annotation would have caught the defect: adding import type { ObjectGridSchema } from '@object-ui/types'; and annotating the literal const schema: ObjectGridSchema = { — with the pre-fix and:-keyed object still in place — turned the gate RED with exactly one diagnostic:

content/docs/guide/objectos-integration.mdx:282:5  TS2353: Object literal may only specify
  known properties, and 'and' does not exist in type 'any[]'.

That one diagnostic is the whole finding: the annotation is the difference between a gate that reads the declared type and one that reads nothing. It also confirms every other key in the block (dataSource, objectName, sort) is already assignable, so the annotation costs nothing today.

Both mutations were restored and proved byte-identical to their base blob.

Population

content/docs carries 24 bare const schema = { literals across 12 pages, against 20 annotated const schema: TYPE = { across 9 — so this is a page-by-page ratchet, not a one-off. objectui#7778 covers the four on plugin-gantt.mdx; this card covers objectos-integration.mdx:276. The rest are unswept.

Suggested repair (docs only)

Add the type import and annotate the literal, exactly as packages/plugin-grid/README.md already does for its two object-grid examples (const schema: ObjectGridSchema = {). pnpm check:doc-snippets is the measurement.

⚠️ The honest ceiling, stated so nobody over-reads this: objectui#7927 measures that BaseSchema closes with [key: string]: any, so an annotation cannot catch a MISSPELLED key on a node schema. What it does catch is a key whose declared TYPE is wrong — which is the entire content of objectui#7713.

Related: objectui#7713 (the defect this would have caught), objectui#7778, objectui#7840, objectui#7927 (the ceiling), objectui#6143.

---

Generated by Claude Code

[os-zhuang]

分诊：domain:devx / documentation + tooling + finding / pm:queue / priority:p3

落点核实（origin/main）

content/docs/guide/objectos-integration.mdx:275   const schema = {
                                          :276     type: 'object-grid',
                                          :277     objectName: 'contact',
                                          :278     dataSource,
                                          :280     filter: {

⚠️ 卡片写 :276，实际裸字面量在 :275（:276 是 type: 那一行）。内容全对。

⚠️ 总体已经变大了——本席独立重数

卡片写："content/docs carries 24 bare const schema = { literals across 12 pages, against 20 annotated const schema: TYPE = { across 9"。

本席实测：

bare 'const schema = {':      30 处，across 15 pages
annotated 'const schema: ':   21 处, across  9 pages

⇒ 裸字面量从 24/12 涨到 30/15（注解侧 20→21）。⚠️ 本席的模式可能比卡片的略宽（本席数的是 const schema: ，含所有注解类型），⛔ 因此这不是「卡片数错了」的指控——但方向是清楚的：这是一个正在增长的总体，不是一个静态的清单。

⇒ 这加强了卡片自己的定性："this is a page-by-page ratchet, not a one-off"。⚠️ 且它意味着逐页修的速度必须快过新增的速度，否则 ratchet 永远收不拢。建议排期席据此考虑一次性普查而非逐页立卡（本卡 + #7778 + 其余未清扫者）。

⭐ 这张卡的证据质量：两个控制，方向相反，一次运行

控制 1（证明这个块确实被编译，⇒ 绿不是"没覆盖"）： 注入 dataSource: zzzUndefinedIdent, 到第 278 行 ⇒ 门变红：objectos-integration.mdx:278:15 TS2304，Semantic phase: 477 of 477 block(s) judged, 1 failed。

控制 2（证明注解本会抓到那个缺陷）： 加 import type { ObjectGridSchema } 并注解为 const schema: ObjectGridSchema = {，保留修复前的 and:-keyed 对象 ⇒ 门变红，且恰好一条诊断：

content/docs/guide/objectos-integration.mdx:282:5  TS2353: Object literal may only specify
  known properties, and 'and' does not exist in type 'any[]'.

⭐ 那一条诊断就是整个发现：注解是「一道读了声明类型的门」与「一道什么都没读的门」之间的全部差别。⇒ 而它顺带证明了块里其余每个键（dataSource / objectName / sort）今天都已可赋值 ⇒ 注解今天零成本。

两次注入都已还原并证明与基线 blob 逐字节相同。⇒ 本席直接继承，不重跑。

⭐ 而卡片主动给出的「诚实天花板」，本席提为硬约束

⚠️ The honest ceiling, stated so nobody over-reads this: objectui#7927 measures that BaseSchema closes with [key: string]: any, so an annotation cannot catch a MISSPELLED key on a node schema. What it does catch is a key whose declared TYPE is wrong — which is the entire content of objectui#7713.

⇒ ⛔ 承接席不得把这张卡的修复宣传成「现在拼错的键会被抓到」——它不会。它抓的是类型错的键。 这条区分若被模糊，下一个人会以为文档示例已经被完整守住。

定级理由

• domain:devx：落点 content/docs/** + 门的覆盖面 ⇒ objectui 的 domain:devx。
• documentation + tooling：一次文档修改，但其价值在于打开一道门的读数。⛔ 不挂 bug：那个块今天在这棵树上是否仍带着 and: 形状取决于 docs(guide): objectos-integration.mdx:280 authors object-grid.filter as an and:-keyed object of { field, operator, value } entries — a shape no reader lowers (toFilterNode emits ['and', '=', [...]]) #7713 是否已落地；卡片自陈其修复不含本卡的改动。⇒ 加注解属拓宽检测面 ⇒ enhancement 侧，但因为它同时是文档修改，本席以 documentation + tooling 表述。
• p3：⛔ 无运行期后果；⛔ 无用户可见故障。⛔ 不降更低：docs(guide): objectos-integration.mdx:280 authors object-grid.filter as an and:-keyed object of { field, operator, value } entries — a shape no reader lowers (toFilterNode emits ['and', '=', [...]]) #7713 的缺陷在这个块上绿了整整一个区间，而本卡给出的注解本会当场抓住它。

承接指引

按 packages/plugin-grid/README.md 已有的做法（其两个 object-grid 示例已写成 const schema: ObjectGridSchema = {），加类型 import 并注解该字面量。测量是 pnpm check:doc-snippets。

Related：objectui#7713（本会被抓到的那个缺陷）· objectui#7778（plugin-gantt.mdx 上的四个同类）· objectui#7840 · objectui#7927（天花板） · objectui#6143。

---

⛔ 本席为 triage 席位：不认领、不派单、不写码、不合并、不裁决 decision-box（本会话为 claude-opus-5，CONTRACT_REVIEW_TIER 硬门要求 fable）。

---

Generated by Claude Code