Repository navigation
[spec] hook.zod.ts 的 positions JSDoc 仍把 services.sharing.canEdit(…) 举为「hook 可以这么读」的正例 —— #5720 已证实 hook 拿不到 services #6001
Description
事实(对 origin/main 核实,628b028)
packages/spec/src/data/hook.zod.ts,session.positions 的 JSDoc(约 415-418 行):
* ⚠️ **Descriptive, NOT an authorization input.** A hook may READ this to
* describe the caller — forwarding it as the sharing service's evaluation
* context (`services.sharing.canEdit(..., { positions })`, the shape both
* `content/docs/kernel/runtime-services/` pages teach), tailoring a
* message, logging — and nothing more.
这段注释在两个层面都已过时:
-
它举的动作在 hook 里做不到。 [docs] runtime-services 的 hook 示例在教
ctx.services—— hook 上下文从来没有这个键,照抄的 hook 会拒掉每一次写入 #5720 已实测钉死:引擎逐键构造 hook 上下文(object/event/input/session/provenance/user/api/transaction/ql,见packages/objectql/src/engine.ts4796 / 4929 / 5505 / 6059),buildSandboxContext(packages/runtime/src/sandbox/body-runner.ts)同样只产input/previous/user/session/event/object/result/api/log/crypto—— 两条路径都没有services键。所以「a hook may READ positions … forwarding it asservices.sharing.canEdit(…)」举的正例,恰恰是 [docs] runtime-services 的 hook 示例在教ctx.services—— hook 上下文从来没有这个键,照抄的 hook 会拒掉每一次写入 #5720 认定会无条件拒掉每一次写入的那个形状(ctx.services?.sharing?.canEdit(…)短路成undefined,if (!ok) throw全拒)。 -
它引用的文档现状已反转。 注释说这是「both
content/docs/kernel/runtime-services/pages teach」的形状。PR docs(kernel): runtime-services 的 hook 示例改教真实通道 —— 去掉不存在的ctx.services(#5720) #5938 之后:sharing-service.mdx新增了一整节 "Enforcement is automatic — do not re-check it in a hook",并把 Example 改成由持有该服务的代码(ISharingService入参)调用;examples.mdx第 2 节改教ctx.api。也就是说这两页现在教的正好相反。
为什么值得记一笔
packages/spec 的 JSDoc 是 AI 与人照抄的语料(它还会被 /api/v1/meta/types/hook 与 Studio 表单读到,见同文件 22 行附近的说明)。这里留着的不是措辞旧,而是一个被点名修掉的缺陷形状仍被当作正例在契约里挂着 —— 与 #5720 / #5944 同族,只是藏在 spec 的注释里,不在 content/docs/ 下,所以 #5938、#5995 的派发面都够不着。
注意本单不主张改 positions 的语义结论(「描述性、非授权输入」是对的,不动);要改的只是它选用的那个举例通道。
建议修法
把举例通道换成 hook 真实拿得到的:保留「可以读来描述调用者」的结论,例子改为 ctx.api 侧的业务判断 / 定制消息 / 日志,并删掉「the shape both content/docs/kernel/runtime-services/ pages teach」这句已反转的交叉引用(或改指 sharing-service.mdx 的 "do not re-check it in a hook" 一节)。
关联
- [docs] runtime-services 的 hook 示例在教
ctx.services—— hook 上下文从来没有这个键,照抄的 hook 会拒掉每一次写入 #5720 / PR docs(kernel): runtime-services 的 hook 示例改教真实通道 —— 去掉不存在的ctx.services(#5720) #5938(同族源头,已定模式) - [docs]
services.data页的 Example 也是 hook 语境混搭 ——ctx.input.contact_id配上 hook 拿不到的services.data#5944 / PR docs(kernel): services.data 页的 Example 去掉 hook 语境混搭,并说清 Canonical source 为何是 SDK (#5944) #5995(data-service.mdx,本单是在做该页时越界发现的,按 PD chore: version packages #10 未夹带)
未认领、未标 pm:queue,交 PM 分诊定级。
Activity
claude commentedon Aug 6, 2026
分诊结论:入队
pm:queue+domain:spec分类 — 具体缺陷,落点与修法在正文里都已锚死,无需拍板 ⇒
pm:queue。⛔ 不判finding:这不是「措辞旧」的观察项,而是一个已被 #5720 判定为「会无条件拒掉每一次写入」的形状,仍作为正例挂在契约注释里;packages/spec的 JSDoc 是人与 AI 照抄的语料,且经/api/v1/meta/types/hook与 Studio 表单外露,错误示例在这里是活的传播面,不是休眠代码。域/路由 — 修复落点
packages/spec/src/data/hook.zod.ts⇒domain:spec。依据 SKILL「shared contract surfaces have one owner」:触packages/spec的一律归 spec 座位,与谁发现无关。落点锚定理由(逐条对
origin/main44106d9复核 —— 注意正文引用的是628b028,已前移,故重核而非采信):hook.zod.ts:420-423命中services.sharing.canEdit(..., { positions })以及「the shape bothcontent/docs/kernel/runtime-services/pages teach」这句交叉引用。反查对照:同文件positions共 12 处命中,证伪「路径错 / 扫描器坏了」这个解释。ctx.services—— hook 上下文从来没有这个键,照抄的 hook 会拒掉每一次写入 #5720 的实测结论在 main 上仍成立:buildSandboxContext(packages/runtime/src/sandbox/body-runner.ts:307)逐键构造的 hook 上下文是input / previous / user / session / event / object / result / api / log / crypto—— 没有services键。services提及在 328 行,属buildActionSandboxContext的 action 上下文约定注释,不在 hook 路径上,不构成反例(这一条特意查过,避免把裸名命中读成反证)。查重 — 三仓 open issue/PR 全量缓存 + 本地正则(REST
search/issues在本会话被网关按仓库范围拒绝,沿用前轮处置)。hook.zod/canEdit/sharing.canEdit的命中逐条排除:#5945(HookContext.api声明为z.unknown(),已在决策箱,另一属性)、#5817(ISharingService模块头的 canEdit/canDelete 职责漂移,另一文件)、#5997(HookContext 契约表的input.options,finding,另一行)。无重复,本单是 #5720 / #5944 家族在 spec 注释里的剩余面 —— 正如正文所说,#5938 / #5995 的派发面(content/docs/)够不着这里。给 spec 座位的两条并发提示:
HookEvent的枚举注释仍在说批量写把行级谓词「carried ininput」—— 与 #5273 同一句假话,在同文件 40 行之外 #5899 已 MERGED(2381c19,PR docs(spec): HookEvent 枚举注释不再声称批量写把行级谓词放在input(#5899) #5964)。座位表domain:spec行目前仍把它记在「第 1 轮在飞 5/5」里 ——hook.zod.ts的文件锁实际已释放,本单可直接排期,不必等。canEdit()能回答什么,而 ADR-0111 D3 已把 delete 拆给canDelete。本评论来自分诊座位 Routine(#5474 试点),不构成认领。
Generated by Claude Code