docs(kernel): runtime-services 的 hook 示例改教真实通道 —— 去掉不存在的 ctx.services (#5720)

[os-zhuang]

Closes #5720

按维护者 2026-08-06 批复裁「改教 ctx.api」执行:docs-only,⛔ 不新增「hook ctx 注入 services」公共契约 —— packages/spec/**、packages/objectql/** 零改动。

为什么是缺陷

hook 上下文由引擎逐键构造(object / event / input / session / provenance / user / api / transaction / ql,engine.ts 五处构造点同构),沙箱 buildHookSandboxContext 同样不产 —— 从来没有 services 键。照抄旧示例写 beforeUpdate 授权检查,ctx.services?.sharing?.canEdit(…) 因可选链短路成 undefined,if (!ok) throw new Error('PERMISSION_DENIED') 于是无条件抛出:该对象上所有更新一律 403,而失败方向伪装成"正常拒绝",极难归因到文档。

services.* 本身不是幻觉,是这几页记录的契约签名面(索引页 binding note 已写明:开放框架不往 hook ctx 注入 services,托管运行时才提供该绑定)。缺陷在于把它当成 hook 能拿到的东西来教。

改了什么

content/docs/kernel/runtime-services/examples.mdx

• 页首新增一张「各运行面真实拿到的数据通道」表(hook → ctx.api;flow script 函数 → 无;plugin → 插件上下文),并点名 ctx.services 的短路后果。
• 第 1 节(旧:flow custom node 用 ctx.services.data)改写为真实通道:声明式 get_record 节点读行 → script 节点把变量映射进注册函数的 inputs → 函数返回值由后续声明式节点落库。
• 第 2 节(旧:hook 手查 ctx.services?.sharing?.canEdit)改为 hook 的真实数据通道 ctx.api.object(…);示例语义(写前校验 + 拒绝路径)保留,但换成引擎无法代劳的业务规则(合同金额 vs 客户信用额度)。共享强制由 plugin-sharing 的引擎中间件按动词自动执行(update 走 canEdit、delete 走 canDelete,拒绝抛 FORBIDDEN),hook 手查是冗余教学,故删。
• 两块入参 ctx: any → (ctx: HookContext)([spec] HookContext.session 少声明了 positions / preserveAudit —— 引擎在生产、消费方在读、文档在教,契约里没有(#5050 的镜像方向) #5605 落地后 session.positions 已可正常标类型)。

content/docs/kernel/runtime-services/sharing-service.mdx

• 新增「Enforcement is automatic — do not re-check it in a hook」一节:中间件按动词自动执行 + hook 无 services 键 + hook 自己的通道是 ctx.api。
• Example 改为「由持有该服务的代码调用」(契约类型 ISharingService,来自 @objectstack/spec/contracts),并首次给该块补 os:check 标记 —— 本页自称 canonical source 是那个契约文件,现在真的被钉住了。

与 issue / 裁定子断言不符的两处(按实测办)

1. examples.mdx 第 1 节不是「同病同修 ctx.api」。实测它是 flow script 节点调用的注册函数:按契约是纯函数(handlerContract: 'pure',A script node's function is contractually pure, but nothing enforces it — a function that writes makes its run under-report #4396),运行时只交 input / variables / automation / logger,没有任何数据句柄 —— 既没有 services,也没有 ctx.api(skills/objectstack-automation/SKILL.md 原话:hooks get ctx.api; flow functions don't)。所以第 1 节不能改成 ctx.api,只能改成"读在声明式节点、算在纯函数"。旧示例是双重失真:键不存在,且它教的行为本身违反纯函数契约。
2. sharing-service.mdx 的 Example 不是 action 面。实测它教的是 hook:注释自称 "The hook exposes the caller's org as organizationId",读的是 ctx.input.id / ctx.session(action ctx 是 params / record / recordId)。故按 hook 处置,不是"仅标注语境"。

验证

反向验证(方向先定后跑:预期红) —— 把两处旧函数体的 any 换成如实的 HookContext 后编译,两处都报同一条:

old1.ts(5,24): error TS2339: Property 'services' does not exist on type '{ object: string; event: …; input: Record< string, unknown >; … 8 more …; }'
old2.ts(5,39): error TS2339: Property 'services' does not exist on type '{ … }'

即:键确实不存在,而 check:skill-examples 此前是绿的 —— ctx: any 让块内每一次属性访问都不被检查,os:check 标记成了空门(issue 正文第 2 点)。

新示例不止过类型,还真解析/真跑:

• defineFlow 实际 parse 通过(flow parsed ok: sales_order_roll_up_totals 5 nodes);
• defineHook 实际 parse 通过,并用手搭 ctx 跑了两条路径:超限 → rejected as expected: VALIDATION_FAILED: contract amount exceeds the account credit limit;未超限 → within limit: passed (expected)。旧示例是"恒抛",新示例只在业务规则被违反时抛。

门禁(全绿)

门	结果
check:skill-examples	✅ 207 prose examples type-check —— 206 → 207(sharing-service 新增 1 块);runtime-services 三块从"标记了但零覆盖"变为真检查
check:doc-authoring	✓ 362 files clean
check:nul-bytes	OK (scanned 5723 tracked text file(s))
check:docs-audit-scope	✓ scope in sync (178 hand-written docs),releases 只读未动
fumadocs MDX 生成	通过(新增的 Callout 内嵌表格可解析)

docs-only,不发布任何包 ⇒ 无 changeset,已加 skip-changeset 标签。

分开交付(不在本 PR)

• check:skill-examples 加「os:check 块内禁止把入参标 any」约束 —— 落 packages/spec/scripts/,属 spec 座位面,已拆子单。
• packages/spec/src/data/hook.zod.ts:416 的 JSDoc 同病 —— 已在 HookEvent 的枚举注释仍在说批量写把行级谓词「carried in input」—— 与 #5273 同一句假话,在同文件 40 行之外 #5899 留证据评论归拢(该文件属 spec 座位面,不自改)。

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01GX3sL71LFq8m2usg6VqTSE

---

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 12:38pm

[os-zhuang]

分开交付的三件已落地(均未认领、按 PD #10 不夹带进本 PR):

• [spec] check:skill-examples 应拒绝 os:check 块内把入参标 any —— 标记了却零覆盖的空门 #5943 —— 从 [docs] runtime-services 的 hook 示例在教 ctx.services —— hook 上下文从来没有这个键,照抄的 hook 会拒掉每一次写入 #5720 拆的子单:check:skill-examples 禁止 os:check 块内把入参标 any(维护者 2026-08-06 已预批立项,落 packages/spec/scripts/,spec 座位面)。已挂为 [docs] runtime-services 的 hook 示例在教 ctx.services —— hook 上下文从来没有这个键,照抄的 hook 会拒掉每一次写入 #5720 的 sub-issue。
• HookEvent 的枚举注释仍在说批量写把行级谓词「carried in input」—— 与 #5273 同一句假话,在同文件 40 行之外 #5899 评论 —— packages/spec/src/data/hook.zod.ts:416-417 的 JSDoc 同病(services.sharing.canEdit(..., { positions }) + 「the shape both content/docs/kernel/runtime-services/ pages teach」,后半句在本 PR 合入后即成过时引用),已留证据评论请一并记入该单修复面;该文件属 spec 座位面且 HookEvent 的枚举注释仍在说批量写把行级谓词「carried in input」—— 与 #5273 同一句假话,在同文件 40 行之外 #5899 已在跟同文件另一处,故不自改。
• [docs] services.data 页的 Example 也是 hook 语境混搭 —— ctx.input.contact_id 配上 hook 拿不到的 services.data #5944 / [spec] HookContext.api 声明为 z.unknown() —— 按 (ctx: HookContext) 标类型的 hook 无法调用 ctx.api.object(…),而文档/技能全在这么教 #5945 —— 本次实测顺带发现、超出派发面的两项:
  • [docs] services.data 页的 Example 也是 hook 语境混搭 —— ctx.input.contact_id 配上 hook 拿不到的 services.data #5944:data-service.mdx 的 Example 同族混搭(ctx.input.contact_id 配 hook 拿不到的 services.data),该页未在本单裁定/派发面内;
  • [spec] HookContext.api 声明为 z.unknown() —— 按 (ctx: HookContext) 标类型的 hook 无法调用 ctx.api.object(…),而文档/技能全在这么教 #5945:HookContext.api 声明为 z.unknown(),导致按 (ctx: HookContext) 标类型的 hook 调 ctx.api.object(…) 直接 TS18046 —— 这也是本 PR 示例里那个 as CrossObjectApi 局部窄化的由来(contract-first 意义上,真修法在生产者侧,故单独立单请维护者拍板)。

标签回读(bots 落定后):documentation、size/m、skip-changeset —— 并集写入,bots 的两个标签未被覆盖。

---

Generated by Claude Code