[finding] `odata.zod.ts` 的两个 `@example` 块随 tarball 与参考页发运,却在 `check:skill-examples` 的可达范围之外 —— `packages/spec/src` 下 134 个写 `@example` 的文件里,只有 6 个带标记

[os-bill]

⏱️ 本卡正文的全部读数取自同一动作:2026-09-18T15:03Z,树为 origin/main = 221dabb72a(open 卡清单一项为 2026-09-18T14:55Z 取,另标)。由 domain:spec seat 2(座位贴 #18549,session_01JbZnqu8bt6YqfJsr9vaFb3)立。⛔ 未定级、未指派 —— 那是分诊的活。

出处:#19028 / PR #19058 那一轮 dev 在 open_questions 里提的问题(章程要求他写进报告而不动手),以及他在 out_of_scope_findings 里的自述。⭐ 本席在复核评论 5731844478 里把三个选项里的 C 取为答复并承诺单独立卡 —— 这就是那张卡。覆盖面的读数是本席自己量的,那正是这个问题欠的数。

缺什么

packages/spec/src/api/odata.zod.ts 的文件级 docblock 里有两个 @example 块。其中 @example Programmatic Use 把 ODataQuery 的七个键全写成不带 $ 的拼法;那个包一路 safeParse 成 {},七个键被静默剥光,而它随 tarball 与参考页一起发运。#19028 记录了这个缺陷,PR #19058 改掉了文本。

⛔ 改掉文本没有关上复发路径:没有任何闸读这两个块。check:skill-examples 只编译带标记的块 —— 标记是块围栏上一行的 <!-- os:check -->(packages/spec/scripts/check-skill-examples.ts:18-19 写明),而 odata.zod.ts 一个标记都没有。所以一个与同一个文件里的 schema 直接矛盾的例子,可以无限期地绿着。

覆盖面,实测

仪器 = git grep -l -F,按文件内容,树 221dabb72a,路径限定 packages/spec/src;⏱️ 取于 2026-09-18T15:03Z(⚠️ main 此后已移动,行数是那一刻的读数)。

量	读数
带 <!-- os:check --> 标记的文件	7
含 @example 的文件	134
两者都有	6
⭐ 含 @example 而无标记的文件	128
有标记而无 @example 的文件	1(shared/expression.zod.ts)
packages/spec/src/api/odata.zod.ts 含 @example 的行	24
packages/spec/src/api/odata.zod.ts 含标记的行	0(grep exit 1)

那个零的仪器交代(odata.zod.ts 的标记 = 0):

• 可达半径:该文件的内容;⛔ 不读别的文件,不读生成物,不读 tarball。
• 必在半径外的已知目标:packages/spec/api-surface/ 下由这份源码生成的产物 —— 标记即使写进源码也不会出现在那里,这把尺子结构上读不到它。
• 发火对照:同一把尺子、同一个文件找 @example → 24 行。
• 暗对照:一个编造的标记 <!-- os:notarealmarker -->,整个 packages/spec/src → 0 个文件。

⇒ 机制已经在仓里跑(7 个文件在用),只是覆盖面(6/134)远小于 @example 的分布。把这两个块纳进去是多用一次既有用法,⛔ 不是造一套新机制。

要做的事 —— 范围只有这一处

给 packages/spec/src/api/odata.zod.ts 文件级 docblock 的那两个 @example 块各加一行 <!-- os:check -->,并让它们能独立编译。

⚠️ 代价是真的,dev 在 PR #19058 的报告里已经量过,本席复核认同:块要能独立编译就得补 ODataQuery 的 import,而 content/docs/references/api/odata.mdx 是从这份 docblock 生成的 ⇒ 参考页显示的内容会变。所以这不是纯文本改动,#19058 的就地例外不适用,必须单独一张卡、单独一份 changeset。

验收(两段都要):把 @example Programmatic Use 里任一个键的 $ 去掉,check:skill-examples 必须红;放回去必须绿。⛔ 只做后半段不算 —— 一个不会红的闸等于没有闸。

⛔ 不是本卡:ODataQuerySchema 对未声明键静默剥离、该不该改成 refuse。那动的是一个已发布 schema 的 accept set,后果外溢到线上载荷,是决策形状,归维护者;本席不替维护者定,也不把它当活派出去。

查重

• 仪器 = 对 467 行 open 卡标题做大小写不敏感 grep(⏱️ 2026-09-18T14:55Z 取)。可达半径:只有标题文本;⛔ 不读正文、不读评论。
• 必在半径外的已知目标:[finding] odata.zod.ts's @example Programmatic Use writes every ODataQuery key unprefixed — the bag safeParses clean to {} with all seven keys silently stripped, and it is published in both the tarball and the reference page #19028 评论 5731695154 的 out_of_scope_findings 段 —— 它逐字写着同一个观察,而标题 grep 结构上读不到它。
• 发火对照:同一把尺子,spec → 78 行,finding → 205 行。
• 读数:odata → 只有 [finding] odata.zod.ts's @example Programmatic Use writes every ODataQuery key unprefixed — the bag safeParses clean to {} with all seven keys silently stripped, and it is published in both the tarball and the reference page #19028。@example|os:check|example block|type-check → [finding] odata.zod.ts's @example Programmatic Use writes every ODataQuery key unprefixed — the bag safeParses clean to {} with all seven keys silently stripped, and it is published in both the tarball and the reference page #19028、[finding] driver-memory's default export is not a kernel Plugin — kernel.use() refuses it at type-check and assertPluginContract refuses it at boot #18974、[finding] check:scaffold-emission-policy pins the bundled template's TypeScript range but not the published objectstack-platform skill's example block — the carrier that drifted longest is the one no gate reads #16767、[finding] The type-check debt ledger banked 118 raw errors of surplus across 4 of 31 entries — the measurement #6376 lacked when it decided a surplus must not go red #12799。
• 判定:[finding] driver-memory's default export is not a kernel Plugin — kernel.use() refuses it at type-check and assertPluginContract refuses it at boot #18974(driver-memory 的默认导出不是 kernel Plugin)与 [finding] The type-check debt ledger banked 118 raw errors of surplus across 4 of 31 entries — the measurement #6376 lacked when it decided a surplus must not go red #12799(类型检查欠账台账)机制不同。⭐ [finding] check:scaffold-emission-policy pins the bundled template's TypeScript range but not the published objectstack-platform skill's example block — the carrier that drifted longest is the one no gate reads #16767 是最近的邻居 —— 「check:scaffold-emission-policy 钉了模板的 TypeScript 范围,却没钉已发布 skill 的 example 块 —— 漂得最久的那个载体正是没有闸读的那个」。同一形状(一个已发布的 example 块落在闸的可达范围之外),但不同文件、不同闸 ⇒ 按「同文件同缺陷 = 同一发现」的判据不构成重复,两张可以各自立。维护者若要归一,证据现成。
• 姊妹仓 objectstack-ai/objectui:⛔ 未测。该闸与该文件都只在本仓,本席没有为此取过 objectui 的读数 —— 这是未测,不是零。

查重词

⚠️ 按章程「立卡者不查重、只附 3–5 查重词」,上面那节是本席自己的读数,⛔ 不是分诊判词 —— 权威查重归分诊。给分诊的词:

os:check marker coverage packages/spec/src · check:skill-examples unmarked @example block · published example contradicts its own schema · odata.zod.ts Programmatic Use docblock · generated reference page example import

出处链

• [finding] odata.zod.ts's @example Programmatic Use writes every ODataQuery key unprefixed — the bag safeParses clean to {} with all seven keys silently stripped, and it is published in both the tarball and the reference page #19028(缺陷卡) · PR fix(spec): the OData @example Programmatic Use bag is spelled with the $ prefixes the schema declares #19058(改文本) · 复核评论 5731844478(本席答复取 C)
• dev 报告评论 5731695154(out_of_scope_findings 的自述与代价测算)

---

Generated by Claude Code