docs(kernel): services.data 页的 Example 去掉 hook 语境混搭,并说清 Canonical source 为何是 SDK (#5944)

[hotlong]

Fixes #5944

docs-only,单文件:content/docs/kernel/runtime-services/data-service.mdx。

前提复核(对 origin/main)

前提成立,且比 issue 描述的更硬。原 Example 不是「在 hook 里会 TypeError」而是在任何语境下都不成立——按 check:skill-examples 同款 tsconfig 编译原块:

old.ts(1,23): error TS2304: Cannot find name 'services'.
old.ts(1,52): error TS2304: Cannot find name 'ctx'.
old.ts(2,22): error TS2304: Cannot find name 'services'.

ctx 与 services 这两个名字在本运行时里没有任何一处同时在作用域内:hook 有 ctx 没 services,持有绑定的代码有 services 没 ctx。这正是该块把两个语境拼在一起的机器化证据。

复核 #5720 的结论在 origin/main 未变(628b028):

• packages/objectql/src/engine.ts 四处 hookContext 构造点(4796 / 4929 / 5505 / 6059)逐键构造 object / event / input / session / provenance / user / api / transaction / ql;
• packages/runtime/src/sandbox/body-runner.ts 的 buildSandboxContext 只产 input / previous / user / session / event / object / result / api / log / crypto;
• 两条路径都没有 services 键。packages/objectql/src/hook-input-shape-contract.test.ts 是这批构造点的现存 pin 测试(HookContext.input 的契约注释声明批量写携带 input.ast,引擎从不设置它(AST 只在 opCtx 上);同一张表也未描述 #5038 后 after 事件的按行形状 #5273),未改动。

改法(取 PR #5938 的第二支)

1. Example 改写为「持有该绑定的代码在调用」,形状对齐 #5938 给 sharing-service.mdx 定的 mayEditContract(sharing: ISharingService, …):记录 id 作为普通入参传入,全块无 ctx。顺带修掉原块两处误读——get 返回的是信封 { object, id, record } 而不是行本身(原文 contact.id 是撞对的:信封的 id 恰好等于记录 id),find 返回 { records, … } 而原块拿到 orders 后就没再用。

2. 新增 binding note Callout:hook 没有 services 键,其跨对象通道是 ctx.api,并指向 examples.mdx 第 2 节(#5938 已进 os:check 真编译的那块)。本页不重复那段 hook 代码——重复一份未被门看住的副本正是这一族缺陷的来源。

3. 新增 ## Canonical source 一节,答分诊点名的措辞问题。本页是全章唯一不指向 contracts/*-service.ts 的页,而这个差异是真的、不是疏漏:spec 根本没有 IDataService;最近邻 IDataEngine(packages/spec/src/contracts/data-engine.ts)是形状不同的更低一层面——find(objectName, query, options): Promise< any[] > 直打引擎,而不是本页记录的「对象名 + options」协议调用。故签名取 ObjectStackClient.data,其返回体对应 spec 的 GetDataResponseSchema / CreateDataResponseSchema / UpdateDataResponseSchema / DeleteDataResponseSchema(packages/spec/src/api/protocol.zod.ts),SDK 的 *DataResult 接口逐键镜像之;托管运行时按同一形状绑定 services.data。

os:check 标记:不补 —— 且与 #5945 无关

PM 交代此项取决于 #5945(HookContext.api 为 z.unknown())的裁决。实测结果是另一条独立的硬约束,和 #5945 不沾边:本块从头到尾不触碰 ctx.api。

反向验证(先定方向再跑:预测「红,且诊断是模块解析而非类型错误」):给该块加上标记后,

content/docs/kernel/runtime-services/data-service.mdx:88:40
  error TS2307: Cannot find module '@objectstack/client' or its corresponding
  type declarations.

仅此一条诊断,方向与预测一致。check:skill-examples 的 paths 由 @objectstack/spec 自己的 exports 派生,而 spec 不依赖 client,所以标记后只能把 DataService 改成手写局部类型——那样这块就只钉住它自己,是标准的 phantom check。此约束已如实写进正文,并说明「待本面有 spec 侧契约可 import 时再补标记」。⛔ 未改动任何类型声明文件。

自验

检查	结果
check:doc-authoring	✅ 362 files clean
check:nul-bytes	✅ 5745 tracked text files,无原始控制字节
check:docs-audit-scope	✅ 178 hand-written docs 同步
check:skill-examples	✅ 207 blocks(与 #5938 后基线一致:本页不贡献标记块,也不产生 orphan)
Example 块真编译	✅ 对已构建的 @objectstack/client 声明 tsc --noEmit 退出 0
MDX 编译	✅ @mdx-js/mdx + remark-gfm 通过(examples.mdx / sharing-service.mdx 作阳性对照)

Example 块虽然进不了 check:skill-examples(上节的模块解析约束),但它本身是真编译过的——只是那次编译得手工把 @objectstack/client 的 dist 声明喂进 paths,门做不到这件事。

Changeset

不带。docs-only,零 user-visible 运行时变更,按派发约定由验收时打 skip-changeset 标签。

---

关联:#5720 / PR #5938(同族,已定模式);#5945(HookContext.api 决策,本 PR 不受其约束也不抢跑);#5943(check:skill-examples 禁块内 any 入参)。

---

Generated by Claude Code

[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 2:03pm