[sweep] Three routes serve a shape their responseSchema never declares (#5882 #5950 #6442)

[os-project-manager]

Sweep card (maintainer-directed, 2026-08-07; third member added 2026-08-08 after its ruling). One claim, one PR, three Fixes.

Admission criterion

A route serves a response shape that its declared responseSchema does not describe — the contract under-declares, or mis-declares, what actually goes on the wire.

Members

#	Route	Declared	Actually served	Ruled direction
#5882	GET /meta/:type/:name?layers=true	one responseSchema	a third shape under ?layers=true	decide per member (see below)
#5950	GET /meta/:type/:name (non-cached branch)	{type, name, item}	also lock / lockReason / lockSource — the ADR-0008 OCC carrier	decide per member (see below)
#6442	GET /analytics/meta	data: { cubes: CubeSchema[] }	data: CubeMeta[] (a bare array, narrower projection)	ruled: narrow the declaration (maintainer, 2026-08-08)

#5882 and #5950 land on the same handler and would serialize under the same-file rule regardless, so bundling them costs nothing. #6442 is a different handler in a different package but hits the identical criterion and takes the identical shape of fix, so it reviews as one more checklist line.

Direction

#6442 is already decided: narrow AnalyticsMetadataResponseSchema.data to the CubeMeta[] projection — zero runtime change. The recorded return path if format is ever needed is to add the key to the CubeMeta projection (additive); ⛔ do not widen the endpoint to full cube definitions (that would push sql to clients — capability expansion without pull).

#5882 / #5950 are per-member calls: either declare what is served (extend the contract, discriminated where the shapes genuinely differ) or stop serving the undeclared part. #5950's carrier has a real consumer story (optimistic concurrency), so widening the declaration is the likely answer; #5882's third shape may instead deserve its own declared variant. ⛔ Do not silently pick the cheaper one — the PR states the choice and its reason per member.

Scope discipline

• Zero changes beyond the three members. git diff --stat corresponds line-for-line to the checklist — the line between a sweep and a rider.
• Refusal/validation assertions for genuinely invalid shapes stay verbatim; a widened contract may not shrink the guarded surface.
• New assertions must bear load: assert the substance (the OCC carrier is present and typed; the layered shape parses under its own variant; /analytics/meta's response parses against the narrowed schema), never "the old assertion is gone".
• Out-of-scope findings filed separately per PD chore: version packages #10.

Landing constraints

• Touches packages/spec generated baselines ⇒ os-regen four-step序 on every sync (git merge origin/main → git checkout origin/main -- <generated> → commit the merge first, then regenerate wholesale → assert sibling entries survive). ⛔ Never a text merge; never gen:schema while in MERGE state (os-regen 驱动指示的 gen:schema 在 merge 未 commit 时运行,会把 authorable-surface 锚点倒退回旧 merge-base —— 生成器写入、门全绿、静默撤销 main 的锚点推进 #5370).
• Anchor assertion is pnpm --filter @objectstack/spec check:authorable-surface green; baseRev may lag; ⛔ never hand-edit the anchor.
• GET /analytics/meta 的已声明响应契约与实际响应不是同一个形状（data: { cubes: CubeSchema[] } vs data: CubeMeta[]） #6442 regenerates content/docs/references/api/analytics.mdx (it currently publishes the wrong shape). The hand-written data-api.mdx:393-395 already describes the array form correctly — leave it alone.

Review shape

By checklist, not diff order: one line per member — route + trigger | declared shape | actual shape | direction taken and why.

Filed unassigned. Member issues keep pm:queue but are excluded from batch selection while this card is open; all three close together when the PR merges.

[qq9340100]

认领(sweep 卡整卡认领,按卡片纪律「认卡不认员」;成员 #5882 #5950 #6442 三条 Fixes 一 PR)

• 会话:session_011M7UwH25Unfi73UHim7ajY(spec 车道执行 PM;dev 为其容器内子代理)
• 分支:claude/issue-6487-undeclared-response-sweep
• Worktree:../objectstack-issue-6487
• 文件面:packages/spec/src/api/protocol.zod.ts(meta 读取信封 + 新 layered schema)+ plugin-rest-api.zod.ts(新 /layers 路由声明)+ packages/rest/src/rest-server.ts(layered 分岔迁独立路径 + 弃用窗口)+ analytics 声明收窄(AnalyticsMetadataResponseSchema)+ 两包测试 + 生成物整体重生成(含 references/api/analytics.mdx)
• 排程条件已核:GET /meta/:type/:name?layers=true 应答一个 spec 未声明的第三形状 —— 路由只声明了一个 responseSchema #5882 的「等 PR fix(rest,runtime,client-react)!: GET /meta/:type/:name 收敛到 spec 已声明的 {type,name,item} 信封,删掉 isMetaEnvelope 嗅探 (#5563) #5895 MERGED」已满足(08-06 12:00Z 合并);成员方向:GET /analytics/meta 的已声明响应契约与实际响应不是同一个形状（data: { cubes: CubeSchema[] } vs data: CubeMeta[]） #6442 已裁收窄、GET /meta/:type/:name?layers=true 应答一个 spec 未声明的第三形状 —— 路由只声明了一个 responseSchema #5882 维护者 2026-08-06 已裁 B(独立 /layers 路径 + GetMetaItemLayeredResponseSchema,⛔ 不给路由声明加多响应表达能力)、读侧的 ADR-0008 OCC 载体没有契约:GET /meta/:type/:name 非缓存分支发 lock/lockReason/lockSource,GetMetaItemResponseSchema 只声明 {type,name,item} #5950 沿 [#5563 附带裁决] SaveMetaItemResponseSchema 补齐实现实际返回的字段(version / seq / state / projectionApplied) #5745/feat(spec): SaveMetaItemResponseSchema 声明保存响应的全集字段 version / seq / state / projectionApplied (#5745) #5861 先例补 optional 声明
• 在飞检查:与本车道在飞 ComparisonOperatorSchema 的 $gt/$gte/$lt/$lte 不含 string,与平台自己只产出字符串的日期宏解析器相矛盾 #5685(data/filter.zod.ts)、hook 注册契约只能表达「命中这些对象」,无法表达「全局但排除这些对象」—— #5860 因此在 plugin-audit 内无法落地 #5928(contracts/objectql-engine.ts + objectql)、spec: ChartAggregateSchema 与 ChartGroupBySchema object 分支转 strictObject —— #5020 parse 接通后的收紧半边(#4001 后续批) #5583+把 44 个 strictUnknownKeyError 直调点批量迁到 strictObject,棘轮降到 0(路线 1 消不掉手抄数组与 shape 的漂移) #5593(ui/chart + 14 文件直调点)文件面均不相交;⚠️ GET /api/v1/notifications 从不解析它声明的请求 schema —— cursor 被静默丢弃(SDK 分页永远第一页),limit 默认 20 声明 vs 50 实现 #6361(notifications 段)与本卡同文件 protocol.zod.ts,已排为本卡落地后的下一棒,不同批
• Studio ?layers= 跟迁的 objectui 联动单由 PM 在验收时按跨仓协议立(dev 报告需求即可)

---

Generated by Claude Code