HookEvent 的枚举注释仍在说批量写把行级谓词「carried in input」—— 与 #5273 同一句假话,在同文件 40 行之外 #5899

Activity

1. claude

   added

   domain:spec

   pm:queue

   on Aug 6, 2026
2. claude commented on Aug 6, 2026

   

   claudebot

   on Aug 6, 2026 – with Claude

   Contributor

   More actions

   分诊:入队 pm:queue,域 domain:spec。

   落点锚定:packages/spec/src/data/hook.zod.ts:135-140,origin/main @ 7adc841 逐字核实 —— 「row-scoping predicate carried in input」原句仍在枚举注释里,而同文件 200 行外的契约表已写着「NOT reachable from input at all」。文件在 packages/spec/** ⇒ domain:spec(同 #5920 的读法:域跟落点文件走,不跟「这是注释改动」的性质走)。

   分类理由:具体缺陷 + 落点精确到行 + 真值来源已在 main 上(hook-input-shape-contract.test.ts 的三条钉子,含阳性对照「读路径确实带 ast」)⇒ 无需新测,直接可派。正文对 #5668 为何没覆盖到它的考据(git log -L 135,144 显示该段最后一次变动是 b49ccfdfe/#5306)分诊侧复核认可。

   同文件协调:hook.zod.ts 无在飞 PR(最近一次触碰是 290d944/#5780);#5900 是同一条假话在 skills/** 那一面,本轮同批入队但文件面不相交,可并行。

   查重:三仓搜 HookEvent / carried in \input`/hook.zod.ts,命中 #5273(已修的那一半)/ #5670 / #5906(hook context alias 无生产者,另一轴,finding`);无重复入口。

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

   ---

   Generated by Claude Code
3. os-zhuang commented on Aug 6, 2026

   

   os-zhuang

   on Aug 6, 2026 – with Claude

   ContributorAuthor

   More actions

   归拢证据:同文件 :416-417 的 JSDoc 也在指一个不存在的 hook 通道,建议一并记入本单修复面

   来自 #5720 的实现(PR #5938,docs-only)。本评论只留证据,不改代码 —— #5720 的派发面明确 packages/spec/** 零改动,而本单已经在改 packages/spec/src/data/hook.zod.ts 的注释、且是同一类「注释里的假句」,分两个 PR 碰同一个文件不如折进来。

   事实(对 origin/main 核实)

   packages/spec/src/data/hook.zod.ts:409-427,session.positions 的 JSDoc:

        * ⚠️ **Descriptive, NOT an authorization input.** A hook may READ this to
        * describe the caller — forwarding it as the sharing service's evaluation
   :416 * context (`services.sharing.canEdit(..., { positions })`, the shape both
   :417 * `content/docs/kernel/runtime-services/` pages teach), tailoring a
        * message, logging — and nothing more.
   

   两处不成立:

   1. services.sharing.… 在 hook 里拿不到。 这是 [docs] runtime-services 的 hook 示例在教 ctx.services —— hook 上下文从来没有这个键,照抄的 hook 会拒掉每一次写入 #5720 的实测结论:HookContext 由引擎逐键构造(object / event / input / session / provenance / user / api / transaction / ql,engine.ts 五处构造点同构),沙箱 buildHookSandboxContext 同样不产 —— 没有 services 键。把旧文档示例的 ctx: any 换成如实的 HookContext 后编译,直接 TS2339: Property 'services' does not exist on type …。所以一段 HookContext.session 的 JSDoc 用 services.sharing.canEdit(...) 举例「hook 可以怎么读 positions」,举的是 hook 做不到的动作 —— 与本单 :135-140 的 carried in input 同族(注释是这段的唯一规格,读到哪段随机)。

   2. 它引的文档形状已经不存在了。 PR docs(kernel): runtime-services 的 hook 示例改教真实通道 —— 去掉不存在的 ctx.services (#5720) #5938 按维护者 2026-08-06 裁定(改教 ctx.api,docs-only)改掉了这两页:

      • content/docs/kernel/runtime-services/examples.mdx 不再教 hook 调 canEdit(共享强制由 plugin-sharing 的引擎中间件按动词自动执行:update 走 canEdit、delete 走 canDelete,拒绝抛 FORBIDDEN,hook 手查是冗余);hook 示例改用 ctx.api.object(…) 做业务校验。
      • content/docs/kernel/runtime-services/sharing-service.mdx 的 Example 改为由持有该服务的代码调用(契约类型 ISharingService),并新增一节写明「Enforcement is automatic — do not re-check it in a hook」。

      即 :417 的「both pages teach」现在两页都不再那样教;这句在 docs(kernel): runtime-services 的 hook 示例改教真实通道 —— 去掉不存在的 ctx.services (#5720) #5938 合入后立刻变成过时引用。

   建议改法(仍是纯注释,主张不变)

   positions 的边界主张(描述性、非授权输入、不得用它自行判权)完全保留,只把举例从「hook 调 service」换成 hook 真实能做的读法,或改成通道中立的措辞;顺带别再把这两页当作该形状的出处。若要保留「转发给 sharing service 作为评估上下文」这个用途,应注明那是持有该服务的代码(插件 / 托管运行时绑定)的调用,不是 hook 的。

   预计同样不动 .describe() 与生成物,但按本单已有结论跑 check:generated 确认即可。

   关联

   • [docs] runtime-services 的 hook 示例在教 ctx.services —— hook 上下文从来没有这个键,照抄的 hook 会拒掉每一次写入 #5720 / PR docs(kernel): runtime-services 的 hook 示例改教真实通道 —— 去掉不存在的 ctx.services (#5720) #5938(hook 侧 ctx.services 的文档面,已 docs-only 修完;packages/spec/** 按派发面未动)
   • [spec] check:skill-examples 应拒绝 os:check 块内把入参标 any —— 标记了却零覆盖的空门 #5943(从 [docs] runtime-services 的 hook 示例在教 ctx.services —— hook 上下文从来没有这个键,照抄的 hook 会拒掉每一次写入 #5720 拆出:check:skill-examples 禁 os:check 块内入参标 any —— 就是让上面那句 TS2339 一开始就该红的门)

   ---

   Generated by Claude Code