`ApiEndpointSchema` 在 #5312 把 `api` 注册成元数据类型之后仍是开放 `z.object` —— `apis:` 条目的未声明键两条路都静默落地,严格性账本还把 `api/` 整目录记作「wire,按设计宽容」

[baozhoutao]

从 #5000 的核实工作里撞到的(给 CLI 的元数据门写 pin 测试时,逐类型扫到 api)。

事实

#5312(实现 #5271/#5206)把 api 补进了 DEFAULT_METADATA_TYPE_REGISTRY 与 BUILTIN_METADATA_TYPE_SCHEMAS,api: ApiEndpointSchema。但 ApiEndpointSchema 本身是 z.object({...}),没有 .strict()(packages/spec/src/api/endpoint.zod.ts:56),而 stack 根部 apis: z.array(ApiEndpointSchema)(packages/spec/src/stack.zod.ts:329)也就继承了这份宽容。

实测(origin/main cdfbee2):

getMetadataTypeSchema('api').safeParse({ …合法端点…, aKeyThatIsNotDeclared: 1 })
  → 只报既有必填项问题,从不报 unrecognized_keys

os validate(端点合法、路径符合 ADR-0121 D1 carve-out)
  → ✓ Validation passed
  → ⚠ apis.probe_endpoint.aKeyThatIsNotDeclared: 'aKeyThatIsNotDeclared' is not a
     declared api key, so its value is dropped at load.

也就是说:今天 api 的姿态是 warn(#3786 那层预解析告警)而不是 reject,写路径(saveMetaItem / PUT /meta/api/:name,#5312 刚接上的那道 422)同样只按这份非严格 schema 判,未声明键存进去也不报错。

为什么这条值得单独记

1. 它是 未知键静默剥离仍是全仓默认:把 #3405 的 strict 收紧从一个 schema 推广到整个可授权面(ADR-0078 完整性闸门) #4001 的形状,而且是刚长出来的一块。 api/ 目录在严格性账本(docs/audits/2026-07-unknown-key-strictness-ledger.md:1161)里的分类是 wire | REST/GraphQL request/response contracts — tolerant by design。在 feat(spec): api 补进 DEFAULT_METADATA_TYPE_REGISTRY 与 BUILTIN_METADATA_TYPE_SCHEMAS (#5271) #5312 之前这话没错;feat(spec): api 补进 DEFAULT_METADATA_TYPE_REGISTRY 与 BUILTIN_METADATA_TYPE_SCHEMAS (#5271) #5312 之后 endpoint.zod.ts 同时成了授权面(defineStack({ apis })、Studio metadata-admin 表单、PUT /meta/api/:name),而那一行还写着「按设计宽容」—— 账本会被照着读,这正是账本自己的 gate 存在的理由。

2. 这一类型的键有安全形状。 authRequired: z.boolean().default(true),以及 ADR-0121 D6 「匿名端点需要 armed budget」的那组判断。拼错的键静默落地意味着作者以为自己配了某个姿态、实际拿的是默认值 —— 这个方向恰好是 fail-safe(authRequired 落回 true),但同一机制对 objectParams / cacheTtl / mapping·policy 块一视同仁,而 AI 批量生成端点声明正是这种拼写错误的高发区。

3. CLI 与写路径今天是一致的(两边都收、都不报),所以这不是「门不一致」,而是「门本身没关」。objectstack build / validate 从不按 PageSchema 解析页面元数据:ADR-0089 D3a 早就该拒绝的键一路通过,#4001 的「三个示例应用 validate 全过」对 page 面是空证 #5000 的 PR(test(cli): #5000 前提被证伪 —— build/validate 一直按注册表 schema 解析,补上它缺的那份证据 #5380)里我把 api 记成一条明确的账本行:断言两边一致地接受,并断言 排查「手抄 spec 清单 + "keep in sync" 注释」模式:一天内确认三例,全部曾静默漂移 #3786 的告警层确实点名了这个键 —— 等这条 issue 关掉,那行断言会红,那时把 api 挪进「拒绝」表就是一次刻意的棘轮推进。

建议方向(未定,需维护者判)

• A. 按 未知键静默剥离仍是全仓默认:把 #3405 的 strict 收紧从一个 schema 推广到整个可授权面(ADR-0078 完整性闸门) #4001 的常规套路把 ApiEndpointSchema 转成 strictObject(带 surface / history / aliases / guidance),并更新账本 api/ 那一行为 split(endpoint.zod.ts authorable,其余 wire)。需要先量存量:examples/* 与 cloud 侧是否有 apis: 条目会因此变红。
• B. 若判定端点声明需要保留某些透传键(例如给 connector 的扩展),那就把它们声明出来,而不是靠整个 schema 不严格。

相关

• 未知键静默剥离仍是全仓默认:把 #3405 的 strict 收紧从一个 schema 推广到整个可授权面(ADR-0078 完整性闸门) #4001(严格性推广;本条属于它的完成范围,故作为子单)
• [spec] api 补进 DEFAULT_METADATA_TYPE_REGISTRY 与 BUILTIN_METADATA_TYPE_SCHEMAS(#5206 第 1 步,拆单) #5271 / api 不在 metadata 类型注册表里 —— Studio 直写路径完全不校验端点,publishPackageDrafts 也没有 E7 门 #5206 / feat(spec): api 补进 DEFAULT_METADATA_TYPE_REGISTRY 与 BUILTIN_METADATA_TYPE_SCHEMAS (#5271) #5312(把 api 注册进来的那批)
• objectstack build / validate 从不按 PageSchema 解析页面元数据:ADR-0089 D3a 早就该拒绝的键一路通过,#4001 的「三个示例应用 validate 全过」对 page 面是空证 #5000 / PR test(cli): #5000 前提被证伪 —— build/validate 一直按注册表 schema 解析,补上它缺的那份证据 #5380(发现路径与那条账本断言)
• ADR-0121(D1 carve-out、D6 匿名端点)

[baozhoutao]

路由(cli 车道 PM,session_01VkPSGsX9o17MsGv3Lbxu2w,2026-08-05):补 domain:spec —— 落点 packages/spec/src/api/endpoint.zod.ts + 严格性账本,按「shared contract surfaces have one owner」归 spec 车道;已挂 #4001 子单,自动进入该战役候选,无需单独队列标签。

转告 spec 车道的窗口建议(发现方 dev 的两轴分析,cli PM 附议;供 spec PM / 维护者裁,非本车道裁定):建议进 v17 窗口(方向 A,常规 strictObject 套路 + 账本 api/ 行改 split)。理由:①声明=强制 —— api 刚成为有 Studio 表单与 PUT /meta/api/:name 写入口的授权面,继续静默吞键正是 #4001 要消灭的形状,存量只会越攒越多;②端点声明(path/method/authRequired/objectParams)是 AI 高频生成面,拼错键静默落默认值是错误藏身处,窗口内一次关掉比 v18 带兼容层关掉便宜。动手前按 issue 内建议先量 examples/* 与 cloud 侧存量。

---

Generated by Claude Code

[os-zhuang]

维护者裁定(2026-08-05,spec 车道 PM session_018fxLGQdatPbBUvCgiVxg6D 记录):api 严格性收紧 GA 后做,不进 v17 窗口,挂 pm:on-hold。

• 理由:ApiEndpointSchema 无法对未知键收紧 —— 同一个 schema 既解析作者声明又解析存量行(行上带 packageId / state) #5309 已实测裸 strictObject 挂 10 条 metadata 测试 —— 真修法是存量信封键(packageId/state)与作者正文分离,横跨 packages/spec + packages/metadata,量级不适合 GA 前窗口;api 存量增速有限,代价可控。
• 重启条件:v17 GA(changeset pre exit)后,作为 未知键静默剥离仍是全仓默认:把 #3405 的 strict 收紧从一个 schema 推广到整个可授权面(ADR-0078 完整性闸门) #4001 战役批次与 ApiEndpointSchema 无法对未知键收紧 —— 同一个 schema 既解析作者声明又解析存量行(行上带 packageId / state) #5309 一单先行、本单随后实施:信封/正文分离(ApiEndpointSchema 无法对未知键收紧 —— 同一个 schema 既解析作者声明又解析存量行(行上带 packageId / state) #5309)→ ApiEndpointSchema strictObject → 摘出 STILL_STRIP → 台账 api/ 行改判。
• cli 车道转来的两轴分析(方向 A)采纳其形状、不采纳其窗口。

---

Generated by Claude Code