读侧的 ADR-0008 OCC 载体没有契约:GET /meta/:type/:name 非缓存分支发 lock/lockReason/lockSource,GetMetaItemResponseSchema 只声明 {type,name,item}

在 #5545(给 client.meta.getItem 补返回类型注解)里测绘到。写侧的同一问题已由 #5745 修掉(SaveMetaItemResponseSchema 曾是真实 body 的真子集,version/seq/state 被抹);读侧还留着一个没人收的同形缺口。

事实(基线 `origin/main` @ `a6b3ee7a1`)

spec 声明(packages/spec/src/api/protocol.zod.ts:234)只有三个键:

export const GetMetaItemResponseSchema = lazySchema(() => z.object({
  type: z.string(), name: z.string(), item: z.unknown(),
}));

生产端(packages/metadata-protocol/src/protocol.ts getMetaItem,主 return 在 :3733 附近)发的是超集:

return {
    type: request.type,
    name: request.name,
    item: decorated,
    lock: lockState.lock,
    ...(lockState.lockReason !== undefined ? { lockReason: lockState.lockReason } : {}),
    ...(lockState.lockSource !== undefined ? { lockSource: lockState.lockSource } : {}),

REST 侧 translateMetaEnvelope(packages/rest/src/rest-server.ts:2714)...envelope 原样铺开,所以这三个键会到线上。而 #5563 收敛后的缓存分支(默认 enableCache: true)重建的信封只有 { type, name } + item,代码注释里写明是有意的:

rest-server.ts:4278 — "The cached read carries no lock — it is the fast published-value path and never consulted the lock resolver; a caller that needs the ADR-0008 OCC carriers reads the uncached path."

为什么这是个缺口

#5563 把文档的形状在两条分支上收敛了,但 OCC 载体没有:lock 是否出现仍由服务端 enableCache 决定,且这件事在 spec 里一个字也没有。于是

SDK 调用方(client SDK 的 meta.getItem 没有声明返回类型(载荷为 unknown),而并排的 meta.getItems 有 —— 同一表面上相邻两个方法的类型化不对等 #5545 之后 meta.getItem 标 Promise< GetMetaItemResponse >)在类型上看不到 lock,要读只能 cast —— 正是本仓一贯反对的消费端宽容;
「读回 lock → 写时带 If-Match」这条 ADR-0008 链路,写侧有契约([#5563 附带裁决] SaveMetaItemResponseSchema 补齐实现实际返回的字段(version / seq / state / projectionApplied) #5745 补的 version),读侧没有;
一个只在某种服务端配置下出现的键,是 GET /meta/:type/:name answers two different body shapes on the same request — the cached branch (the DEFAULT) returns the bare document, the non-cached branch returns the spec-declared { type, name, item } envelope #5563 那类「配置决定契约」的残留。

处置(建议,待分诊)

在 GetMetaItemResponseSchema 上把三个键声明为 optional,并在 describe 里写清「仅非缓存读路径提供;缓存读路径不解析锁」——这与 #5745 的做法一致(先实测哪些必选、哪些条件出现,再照实声明),且不改任何运行时行为。若认为「配置决定字段有无」本身才是要修的,那是更大的一步,应单独定案。

关联:#5545(测绘出处)、#5563(读路由形状收敛)、#5745(写侧同形缺口,已修)、ADR-0008。

分诊:pm:queue + domain:spec。

落点锚定:packages/spec/src/api/protocol.zod.ts:234 的 GetMetaItemResponseSchema。修法是把 lock / lockReason / lockSource 按实测补成 optional + 在 describe 里写明「仅非缓存读路径提供,缓存读路径不解析锁」,零运行时行为改动 —— 与写侧同形缺口 [#5563 附带裁决] SaveMetaItemResponseSchema 补齐实现实际返回的字段(version / seq / state / projectionApplied) #5745(PR feat(spec): SaveMetaItemResponseSchema 声明保存响应的全集字段 version / seq / state / projectionApplied (#5745) #5861 已落地 version/seq/state/projectionApplied)完全同一姿态。packages/spec 恒归 spec 座位(SKILL「shared contract surfaces have one owner」)。
为什么不进决策箱:主处置「声明补齐到真实 body」有先例、无方向分歧。正文自陈的另一问(「配置决定字段有无」本身是否要修)是更大的一步,已声明应单独定案 —— 承接方若判定必须先答那一问才能动手,STOP 上报,⛔ 不在本单顺手翻 enableCache 的语义。
查重:三仓 open issue/PR 搜 GetMetaItemResponseSchema / GetViewResponseSchema / 关键词「读侧 lock 契约」,仅命中本单与 GET /ui/view/:object/:type 发的是 {list} / {form},spec 的 GetViewResponseSchema 声明的是 {object, view} —— 同一路由声明与实际两种形状(#5563 同族) #5948(同族另一条路由,本轮已分诊为决策卡),无重复派发入口。
过时前提:git log --oneline origin/main -- packages/spec/src/api/protocol.zod.ts 最近一条即 [#5563 附带裁决] SaveMetaItemResponseSchema 补齐实现实际返回的字段(version / seq / state / projectionApplied) #5745→feat(spec): SaveMetaItemResponseSchema 声明保存响应的全集字段 version / seq / state / projectionApplied (#5745) #5861,读侧三键仍未声明;packages/metadata-protocol/src/protocol.ts 最近两条(保存成功的回执一律自称 "customization overlay",包括注册表声明 supportsOverlay:false 的类型(object / flow / action / seed / hook) #5265→fix(metadata-protocol): 保存回执按 isArtifactBacked 分句,不再一律自称 customization overlay (#5265) #5926、loadMetaFromDb 用 /no such table/i 正则判「良性首启」,其余 sys_metadata 读失败吞成 console.warn + loaded:0 —— isMissingTableError 的手抄第二份 #5841→fix(metadata-protocol): loadMetaFromDb 判「表未建」改问 isMissingTableError,退休手抄的 /no such table/i (#5841) #5889)不触 getMetaItem 的返回形状。前提成立。

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

Generated by Claude Code

Release-board audit (maintainer-directed re-audit of non-board domain:spec items, 2026-08-07): adding target:v17 — criterion ②: the uncached GET /meta/:type/:name branch sends lock/lockReason/lockSource on the wire while GetMetaItemResponseSchema declares only {type,name,item} — undeclared wire shape; the write-side twin was already fixed (#5745). Triage seat may veto.

Generated by Claude Code

Bundled into sweep card #6487 (undeclared response shapes on GET /meta/:type/:name, 2 members). Keeps pm:queue but is excluded from batch selection while #6487 is open — claim the sweep card, not this one; it closes via Fixes when that PR merges. Bundled with #5882 because both land on the same handler and would have to serialize regardless.

Generated by Claude Code

test(spec): the first api/ file group's test titles state each cited …

Navigation Menu

Repository navigation

读侧的 ADR-0008 OCC 载体没有契约:`GET /meta/:type/:name` 非缓存分支发 `lock`/`lockReason`/`lockSource`,`GetMetaItemResponseSchema` 只声明 `{type,name,item}` #5950

事实(基线 `origin/main` @ `a6b3ee7a1`)

为什么这是个缺口

处置(建议,待分诊)

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

读侧的 ADR-0008 OCC 载体没有契约:GET /meta/:type/:name 非缓存分支发 lock/lockReason/lockSource,GetMetaItemResponseSchema 只声明 {type,name,item} #5950

Description

事实(基线 origin/main @ a6b3ee7a1)

为什么这是个缺口

处置(建议,待分诊)

Activity

claude commented on Aug 6, 2026

hotlong commented on Aug 7, 2026

os-project-manager commented on Aug 8, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

读侧的 ADR-0008 OCC 载体没有契约:`GET /meta/:type/:name` 非缓存分支发 `lock`/`lockReason`/`lockSource`,`GetMetaItemResponseSchema` 只声明 `{type,name,item}` #5950

事实(基线 `origin/main` @ `a6b3ee7a1`)