fix(client): meta.getItem / meta.saveItem 在两个表面标上 spec 已声明的响应类型 (#5545)

[baozhoutao]

Fixes #5545

前提复核(先证后改)

基线 origin/main @ a6b3ee7a1。issue 的事实在最新 main 上仍然成立,行号已随 main 漂移:

位置	方法	改前注解	改前实际类型
:538	ObjectStackClient.meta.getItems	Promise< GetMetaItemsResponse >	✅ 已有
:554	ObjectStackClient.meta.getItem	无	unwrapResponse(res) 无泛型实参 → unknown
:570	ObjectStackClient.meta.saveItem	无	同上 → unknown
:4685	ScopedProjectClient.meta.getItems	Promise< GetMetaItemsResponse >	✅ 已有
:4692	ScopedProjectClient.meta.getItem	无	parent._unwrap(res) 无泛型实参 → unknown
:4699	ScopedProjectClient.meta.saveItem	无	同上 → unknown

同时复核了两个解锁前提,都已落地:

• 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(PR fix(rest,runtime,client-react)!: GET /meta/:type/:name 收敛到 spec 已声明的 {type,name,item} 信封,删掉 isMetaEnvelope 嗅探 (#5563) #5895,d9cac6019):GET /meta/:type/:name 的缓存 / 非缓存两条分支现在都经
  RestServer.translateMetaEnvelope 重建同一个信封(rest-server.ts:2714 的注释把这点写死了:
  "This is the ONE place the single-item read paths rebuild their response body")。因此
  GetMetaItemResponse 现在是唯一诚实注解 —— 在 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 之前默认(缓存)分支发裸文档,
  任何一种注解都会在某种服务端配置下撒谎,这正是前任 dev 停手的理由。
• [#5563 附带裁决] SaveMetaItemResponseSchema 补齐实现实际返回的字段(version / seq / state / projectionApplied) #5745(PR feat(spec): SaveMetaItemResponseSchema 声明保存响应的全集字段 version / seq / state / projectionApplied (#5745) #5861):SaveMetaItemResponseSchema 已含 version / seq / state /
  projectionApplied(protocol.zod.ts:273)。实测确认后才标注 —— 对着旧的
  { success, message } 声明标注会把 ADR-0008 OCC 令牌 version 从公开签名里抹掉,
  那才是前任 dev 拒标 saveItem 的原因。

改动

四处方法(两个表面 × getItem/saveItem)标上 spec 已声明的响应类型,类型从
@objectstack/spec/api import 而非新增,与并排的 getItems 同源;两个类型同时加进
packages/client 既有的 spec 类型再导出块,调用方才有办法给收到的东西命名。

packages/spec 一字未动。

测试

client.test.ts 的 getItem 断言从 toMatchObject 权宜写法升级为类型化字段读取,
as any 一并摘掉(该 cast 存在的唯一理由就是这个表面没类型):

const result = await client.meta.getItem('object', 'customer');
expect(result.type).toBe('object');
expect(result.name).toBe('customer');
expect(result.item).toMatchObject({ name: 'customer', label: 'Customer' });

result.item 保持结构断言,不是遗漏:GetMetaItemResponseSchema 里 item 就是
z.unknown()(信封有类型,它装的文档没有),这是 schema 的形状本身。

新增一条 saveItem 测试,钉住 save 响应的 OCC 载体(version / seq / state);
替身按真实路由构造 —— rest-server.ts:4491 是 res.json(result),原样发协议层的返回对象。

该测试的 getItem 替身在 #5563 里已翻成信封形状,本 PR 无需再翻。#5787 记录的替身问题
(endpoints 已退役、capabilities 形状错)不在本 PR 范围,未顺手修。

命令与结果:

$ pnpm --filter @objectstack/client typecheck
> tsc --noEmit && pnpm check:test-typecheck
✓ check:test-typecheck --self-test — 8 semantic case(s) + the parser hold.
check:test-typecheck: OK — @objectstack/client's test layer compiles under
packages/client/tsconfig.test.json; 3 file(s) / 6 error(s) held in
test-typecheck-debt.json (shrink-only, #5286).

$ pnpm --filter @objectstack/client test -- --maxWorkers=2
Test Files  19 passed (19)
     Tests  237 passed (237)

debt 账本未动(仍是 3 文件 / 6 错误,全部是 #5543 的 objectql registerObject
INPUT/OUTPUT 类型问题),client.test.ts 不在账本里 —— 按该 gate 的口径,未列入的文件
必须零错误。

反向验证(方向事先预测,结果一致)

预测:摘掉四处注解 → 载荷回落 unknown → 类型化读取处报 TS18046。实测:

$ npx tsc --noEmit -p tsconfig.test.json      # 四处注解已临时摘除
src/client.test.ts(124,16): error TS18046: 'result' is of type 'unknown'.
src/client.test.ts(125,16): error TS18046: 'result' is of type 'unknown'.
src/client.test.ts(131,16): error TS18046: 'result' is of type 'unknown'.
src/client.test.ts(147,16): error TS18046: 'saved' is of type 'unknown'.
src/client.test.ts(148,16): error TS18046: 'saved' is of type 'unknown'.
src/client.test.ts(149,16): error TS18046: 'saved' is of type 'unknown'.
src/client.test.ts(150,16): error TS18046: 'saved' is of type 'unknown'.

注解恢复后归零。这条正是 #5449 在 client.test.ts(106,16) 报的同一个错 —— 那次是
测试层刚接进 tsc 时暴露的,这次是我们主动把它请回来确认新断言真的挂在注解上。

语义:为什么是 patch

公开签名从 unknown 收窄。unknown 不允许任何属性读取、也不能赋给有类型的绑定,
所以改前能编译的表达式改后一样能编译;没有删除任何东西,没有新方法/新选项。非破坏,patch。

未做(明确留白)

• meta.getHistory ×2:spec 里没有任何 history 响应 schema,不凭空发明形状,保持现状。
  (另注:非作用域表面的那个已带手写内联形状,作用域表面的仍是 unknown —— 两者不对等,
  已在报告里留给 PM 转分诊。)
• 11 个 unwrapResponse< any > 的 meta.* 方法(getPublished / listDrafts /
  migrateStored / getLegalNextStates / getDiagnostics / getReferences /
  getBookTree / getAudit / publishItem / rollbackItem / diffItem):产出 any
  不是 unknown,且逐条补注解等于逐条定契约,前任 PM 已裁为另案。
• meta.getView:确实产出 unknown,但不能标 GetViewResponse —— 生产端
  getUiView 发的是 { list: … } / { form: … },spec 声明的是 { object, view },
  两者形状不同。这是 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 同族的声明/实际背离,已另行立单,不在本 PR 修。
• data.* 两个表面注解齐全(复核确认,无缺口)。

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 6, 2026 12:44pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/client.

14 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/ai/skills-reference.mdx (via packages/client)
• content/docs/api/client-sdk.mdx (via @objectstack/client)
• content/docs/api/data-flow.mdx (via @objectstack/client)
• content/docs/api/environment-routing.mdx (via @objectstack/client)
• content/docs/api/error-catalog.mdx (via @objectstack/client)
• content/docs/getting-started/your-first-project.mdx (via @objectstack/client)
• content/docs/kernel/runtime-services/data-service.mdx (via packages/client)
• content/docs/kernel/runtime-services/index.mdx (via packages/client)
• content/docs/permissions/authentication.mdx (via @objectstack/client)
• content/docs/plugins/packages.mdx (via @objectstack/client)
• content/docs/protocol/kernel/realtime-protocol.mdx (via @objectstack/client)
• content/docs/releases/implementation-status.mdx (via @objectstack/client)
• content/docs/releases/v16.mdx (via @objectstack/client)
• content/docs/releases/v17.mdx (via @objectstack/client)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.