feat(spec): SaveMetaItemResponseSchema 声明保存响应的全集字段 version / seq / state / projectionApplied (#5745) - #5861
Merged
Conversation
`PUT /api/v1/meta/:type/:name` 一直比 schema 承认的多发字段。声明停在
`{ success, message? }`,而路由实际返回 `{ success, version, seq, state,
message }`(注册了 projector 时还有 `projectionApplied`)—— 契约描述的是真实
响应体的真子集。
因为这些是普通 `z.object`,这个缺口以最安静的方式失败:`safeParse` 保持绿,
未声明的键被静默 strip。改前在 origin/main 上实测:
raw keys : ["success","version","seq","state","message"]
after parse : ["success","message"]
STRIPPED : ["version","seq","state"]
safeParse ok : true
`version` 是其中最要紧的一个:它正是 ADR-0008 乐观并发链在用的令牌 —— 下次写入
把它作为 `If-Match` 回传,并发编辑就会得到 409 `metadata_conflict` 而不是被静默
覆盖。此前它在线上被携带却没有契约兜底,于是解析响应的消费者恰好丢掉了 OCC
握手所需的那个值。
逐字段按实测定型(证据见 PR 正文):
- `version: string` required —— 不透明内容哈希,ADR-0008 `If-Match` 令牌
- `seq: number` (int) required —— 元数据事件序号,排序用,不是 OCC 令牌
- `state: 'draft' | 'active'` required —— 落库的生命周期
- `projectionApplied?: { success, error? }` optional —— ADR-0094 投影结果,仅在
该类型注册了 projector 时出现;缺席表示"没有 projector 跑过",而不是"投影失败"
三个字段定 required 是因为实测生产者恒发,而非假设:`saveMetaItem` 唯一可达的
成功返回是仓储写路径,REST 路由把该对象原样交给 `res.json()`。它的另一个 return
(legacy raw-engine,三者皆无)不可达 —— 其上游 code-only 闸门拒绝的正是能走到
那里的类型。
运行时行为不变:路由本就返回这些字段,且此前没有任何地方用该 schema 解析响应。
`client.meta.saveItem` 的返回类型注解按裁定留给 cli 车道(#5545),以便对着已落地
的契约标注而不是提前撒谎。
测试:
- `packages/spec/src/api/protocol.test.ts` —— schema 侧钉住四字段的存在性、
可选性与类型;断言落在"解析后没有键被 strip"上,而不是 `safeParse` 的判定
(后者改前改后都是绿的,正是本单要修的静默失败形态)
- `packages/objectql/src/save-meta-response-conformance.test.ts` —— 生产者侧
conformance:驱动真实 protocol + 真实 ObjectQL 引擎,断言真实响应体过 schema
零 strip,并用 `agent` → NOT_CREATABLE 钉住"legacy 返回不可达"这条 required
的前提
反向验证(方向预先写死为红,实测吻合):把 schema 改回 origin/main 后
conformance 3/5 转红,stripped keys 为 `["version","seq","projectionApplied",
"state"]`;仍绿的两例分别是"safeParse 恒绿"与死代码绊线,符合预期。
生成物走 os-regen;`authorable-surface.base.json` 的重锚漂移按 #5358 剔除
(本单是加键,锚点不前移)。
Fixes #5745
Co-Authored-By: Claude <noreply@anthropic.com>
…e-meta-response-fields
合并 origin/main 后带进 PR #5782(#5264):`saveMetaItem` 的 legacy raw-engine 分支已被删除,现在只剩唯一一个成功 return。这与本单改前的独立实测结论一致, 并且让 `version` / `seq` / `state` 定 required 的依据更干净 —— 不再是"另一条 返回不可达",而是"只有一条返回"。相应更新 schema 头注释、conformance 测试注释 与 changeset 的措辞。 同时,新声明的 `state: z.enum(['draft','active'])` 让 `ObjectStackProtocolImplementation` 不再满足 `MetadataProtocol.saveMetaItem` (TS2416):对象字面量属性会把两个字面量的三元表达式**加宽成 `string`**,所以 实现的返回类型说 `state: string`,而契约现在说的是它一直在发的那个闭集。 这正是收紧契约要抓的松动:此前消费者读到的 `state` 是 `string`,把它和拼错的 `'publshed'` 比较不会有任何类型错误。修在生产端(Prime Directive #12 契约优先), 只加一处类型断言,**取值不变、运行时行为不变**。 未采用的替代方案:把 spec 里的 `state` 降级为 `z.string()` 或 `z.string().refine(...)` 就能不动 metadata-protocol,但那是为了绕过文件面边界而 明知故犯地弱化契约(Prime Directive #5「不要 workaround」),且恰好丢掉在编写期 阻止错误的那一半价值。 证据:`tsc --noEmit -p packages/metadata-protocol` 在本改动下为 **63** 个错误, 与 origin/main 基线一致(该包无 typecheck script,是已计量 DEBT 项);若只改 spec 而不加这一行则为 64 —— 多出来的正是上述 TS2416。 Co-Authored-By: Claude <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
Contributor
📓 Docs Drift CheckThis PR changes 2 package(s): 110 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
github-actions
Bot
added
documentation
os-zhuang
marked this pull request as ready for review
August 6, 2026 09:48
Contributor
⛔ merge queue 构建失败 — 先分诊，再决定要不要重排队列构建 31090703275 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集）， 失败的 job（日志抽取，best effort）：
历史信号：
分诊清单：
Generated by Claude Code · merge-queue-triage workflow (#4859) |
github-merge-queue
Bot
removed this pull request from the merge queue due to failed status checks
Aug 6, 2026
…e-meta-response-fields
…ble-surface) #5861 被合并队列踢出,签名是 `strictness-ledger-doc.test.ts > is checked in current`。 归因:#5849 / #5857 在入队前合入 main(#5857 给 `api/` 新增了一个 z.object 站点), 本分支的 counts.md 是在旧树上渲染的,合并树上不再等于现渲染 —— 单体生成物的串行税 (#5837 正在治的病),不是实现回归。 在合并树上重跑 os-regen:`api/` 站点数 395 → 396(main 的 +1 与本单 `projectionApplied` 嵌套对象的 +1),docs 与 authorable-surface 一并重渲。相对 origin/main 的净增量仍只有 本单四个键。`authorable-surface.base.json` 本轮无重锚漂移(已核对与 main 一致)。 Co-Authored-By: Claude <noreply@anthropic.com>
Contributor
Author
|
重新入队就绪(生成物随 main 重渲,非实现改动) 被踢出签名 处置(os-regen 循环,在合并树上跑):
复跑结果:
相对 Generated by Claude Code |
os-zhuang
enabled auto-merge
August 6, 2026 10:20
Contributor
Author
|
队列管家让行（Routine 本 PR 09:49Z 被队列踢出（run 31090703275 + 31090703357）。本座位按完整日志归档独立认签名，结论与车道 10:19Z 那条回报一致：生成物计数基漂移，非实现回归。⇒ 车道已在处置，本座位让行 —— 不重投、不入队、不做任何队列动作。留此一行只为审计闭环，外加补一条车道视野外的队列层读数。 签名（两个 job 同一根因）
连坐清单（车道视野外的读数）：同一签名还踢出过 #5865（run 31091255496 / 31091255193，09:57Z，基
Generated by Claude Code |
baozhoutao
pushed a commit
that referenced
this pull request
Aug 6, 2026
第三次基漂移,签名同前:335 是在推上校准提交那一刻冻结的,而 #5861 (SaveMetaItemResponseSchema,#5745)几乎同分钟落地。合并 c15fcee 后实测 339, +4 全部集中在该 PR 新增的 src/save-meta-response-conformance.test.ts 一个文件: - :115 TS2554 Expected 2-5 arguments, but got 1 - :119 TS6133 'LOG' is declared but its value is never read - :119 TS2304 Cannot find name 'appendFileSync' - :119 TS2304 Cannot find name 'OUT' tests 126 -> 127。其余 33 条纹丝不动(合计 2022 raw errors,无一超出记录值,也没有 一行 can-be-lowered —— 34 条全部与实测严格相等)。 那两条 TS2304 已在 note 里点名:名字都解析不到,那一行根本跑不起来,不是类型讲究 问题 —— 但那是 #5861 自己要修的,不是本台账要修的,所以只记录、不代修。 按非确定性假说已证伪(前一轮双跑逐字节相同),本轮不再双跑。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01559M8FVm6W6vDLABL3jvdW
This was referenced Aug 6, 2026
Closed
This was referenced Aug 6, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #5745
按 #5563 维护者 2026-08-06 附带裁定「先补齐 spec 字段」,把
SaveMetaItemResponseSchema从真子集补成实现真实返回的全集。本单只做 spec 半边;client.meta.saveItem的返回类型注解按裁定留给 cli 车道(#5545 家族),packages/client一行未动。一、先测产出:逐字段实测表
生产者只有一个:
ObjectStackProtocolImplementation.saveMetaItem(packages/metadata-protocol/src/protocol.ts)。REST 路由PUT /meta/:type/:name把它的返回值原样交给res.json()(packages/rest/src/rest-server.ts),所以协议返回即线上响应体,无需另测 REST 层。实测手段:真实
ObjectQL引擎 + 真实 protocol(非 stub),覆盖 publish / draft / 注册 projector 三种情形。successbooleanversionstring,实测形如sha256:+ 64 位十六进制seqnumber(整数)state'draft'/'active'两值z.enummode === 'draft' ? 'draft' : 'active'projectionApplied{ success: boolean; error?: string }messagestring实测原始输出(publish / draft / 带 projector):
与裁定字段集无出入 —— 四个字段都真实存在,没有多也没有少;差异只在
projectionApplied是条件性的,已按「以实测收窄」处理为 optional。二、先证红(方向预先写死)
预定方向:红,且形态是「静默 strip」而非「解析报错」—— 因为这些是普通
z.object,Zod 对未声明键的姿态是丢弃、不是拒收。改前在origin/main上探针实测:safeParse为真而数据消失,是最不容易被发现的失败形态。所以断言必须落在「有没有键被 strip」上,而不是safeParse的判定 —— 后者改前改后都是绿的,拿它当断言就是一个永远不会红的空检查(#4984 家族)。补齐后同一探针转绿,并转正为两处常设测试(见下)。
反向验证
把 schema 改回
origin/main再跑 conformance,方向与预测一致 —— 红:两个仍绿的用例是应该绿的,如实记录:一个断言「没注册 projector 时
safeParse绿」(改前改后都绿,正是上面说的那一点),另一个是死代码绊线。过程中踩到 AGENTS.md §9 陈旧产物陷阱并已修正:第一次回退后测试仍全绿,查出是
packages/spec/dist没有真正重建(objectql 通过 dist 消费 spec);重建后才拿到上面这份真红。三、
state收紧连带的生产端类型修正新声明的
state: z.enum(['draft','active'])使ObjectStackProtocolImplementation不再满足MetadataProtocol.saveMetaItem(TS2416):对象字面量属性会把两个字面量的三元表达式加宽成string,于是实现的返回类型说state: string,而契约说的是它一直在发的那个闭集。这正是收紧契约要抓的松动 —— 此前消费者拿到的
state是string,把它和拼错的'publshed'比较不会有任何类型错误。按 Prime Directive #12 修在生产端,只加一处类型断言,取值不变、运行时行为不变。未采用的替代:把
state降级为z.string()或z.string().refine(...)可以完全不动metadata-protocol,但那是为绕开文件面边界而明知故犯地弱化契约(Prime Directive #5),并且恰好丢掉「在编写期阻止错误」的那一半价值。packages/metadata-protocol在本单派发时被列为在飞不触面(因 #5672)。实际核对后判断碰撞风险为零 —— #5672 的改动面是getDiscovery()的 capabilities 记录,与saveMetaItem的返回相隔约 5000 行、属不同函数不同关注点。若 PM 认为仍应回避,可将这一行拆出另派,但 spec 侧的z.enum会随之被迫降级。证据:
tsc --noEmit -p packages/metadata-protocol在本改动下 63 个错误,与origin/main基线一致(该包无typecheckscript,是已计量 DEBT 项);只改 spec 而不加这一行则为 64,多出来的正是该 TS2416。四、随 main 合入的口径更新
合并
origin/main带进了 PR #5782(#5264):saveMetaItem的 legacy raw-engine 分支已被删除。这与本单改前的独立实测结论一致(我在合并前也测出该分支不可达:agent被NOT_CREATABLE403 挡在更早位置),并让 required 的依据更干净 —— 从「另一条返回不可达」变成「只有一条返回」。schema 头注释、测试注释、changeset 措辞已相应更新。因此本单不再另立死代码 finding —— 该发现已由 #5264 / PR #5782 覆盖,尾巴由 #5783 跟踪。
五、测试
packages/spec/src/api/protocol.test.ts(+76):schema 侧钉住四字段的存在性、可选性与类型。首个用例断言「真实响应体过 parse 后没有任何键被 strip」,即上面那条改前为红的。packages/objectql/src/save-meta-response-conformance.test.ts(新增,+203):生产者侧 conformance,驱动真实 protocol + 真实 ObjectQL 引擎,断言真实响应零 strip;并用agent→NOT_CREATABLE钉住 required 所依赖的前提(不存在第二条无回执的写路径)。pnpm --filter @objectstack/spec testpnpm --filter @objectstack/metadata-protocol testpnpm --filter @objectstack/objectql testtypecheck(spec / objectql / runtime)tsc --noEmit -p packages/metadata-protocolpnpm --filter @objectstack/spec check:generatedcheck:nul-bytes+ 控制字符自查六、生成物
走 os-regen:
authorable-surface.json(+4,恰为本单四键)、content/docs/references/api/protocol.mdx、strictness-ledger counts(api/394 → 395,即projectionApplied的嵌套对象)。authorable-surface.base.json的重锚漂移已照 #5358 剔除:每次gen:schema都会把baseRev前移并吸进mcp/scoping/$icontains/ActionSession:*/hideFields等别人的键 —— 本单是加键,锚点不前移,已逐次还原,最终 diff 中该文件为零改动。七、changeset
@objectstack/specminor(新增声明字段),正文写消费者视角变化:此前 parse 后四字段被静默 strip 且类型面不可见,此后可见且有类型。Generated by Claude Code