[spec] 为 action body 的 `ctx.session` 立契约 schema(按现状声明)—— #5613 契约先行裁定的第一阶段

[os-zhuang]

维护者 2026-08-06 对 #5613 裁定「契约先行(C 骨架 + A 语义)」的第一阶段,由 spec 车道 PM 拆立(session_018fxLGQdatPbBUvCgiVxg6D)。

任务

为 action body 的 ctx.session 声明契约 schema——按现状声明,不在本单改运行时行为:

• 现状形状(packages/runtime/src/action-execution.ts buildActionSession(),行号需重定位):{ userId?: string, organizationId?: string, roles?: string[] },三键均条件展开(可缺)。
• roles 照现状声明,但 .describe() 必须标注:deprecated,值实为 positions(ADR-0090 D3 词汇),更名由 [runtime] action body 的 ctx.session 仍在生产 roles(值是 ec.positions)—— 自称「mirroring hook ctx.session」,而 hook 侧该键已按 ADR-0049 退役 #5613 第二阶段执行——声明现状不等于背书拼法。
• schema 落点由 dev premise-first 判定(spec 侧 kernel/contracts 面;ScriptContext.session?: unknown 在 runtime/sandbox/script-runner.ts:71 是消费锚点)。runtime 侧把裸 any 接到该类型属第二阶段还是本单,以「本单零行为变更」为界:类型标注可做,行为不动。
• pin:schema 与 buildActionSession() 实际产出的一致性事实测试(参照 docs(spec): HookContext.input 契约表改成引擎真正构造的形状 (#5273) #5668 的 hook-input-shape-contract 做法,pin 落在能执行该路径的包)。

背景

#5613 三问题:ADR-0090 D3 禁的 roles 拼法在边界被翻译回来;「mirroring hook ctx.session」注释在 #5050 后已失真;action ctx 完全无 schema(declared-nowhere/produced-anyway)。裸 any 面是漂移根因,故契约先行。

第二阶段(#5613,cli 车道,Blocked-by: 本单):roles → positions 更名 + 弃用窗口 + ADR-0087 语义迁移 + 注释修正。

[os-zhuang]

PM 认领(spec 车道 PM,session_018fxLGQdatPbBUvCgiVxg6D,2026-08-06)

• 分支:claude/issue-5697-action-ctx-session-schema;工作树:../objectstack-5697-action-ctx(基于最新 origin/main);域:domain:spec
• 文件面:spec 侧 action ctx.session 契约 schema(落点 premise-first 判定,kernel/contracts 面)+ 一致性 pin(落在能执行 buildActionSession 路径的包,参照 docs(spec): HookContext.input 契约表改成引擎真正构造的形状 (#5273) #5668 做法)+ runtime 侧仅类型标注(零行为变更为硬界)
• 裁定依据:[runtime] action body 的 ctx.session 仍在生产 roles(值是 ec.positions)—— 自称「mirroring hook ctx.session」,而 hook 侧该键已按 ADR-0049 退役 #5613 契约先行第一阶段(正文即派发规格);roles 按现状声明 + deprecated 标注,更名属第二阶段
• 同批不相交:ADR-0087 别名转换会把「被遮蔽的旧拼法」留在存量元数据里 —— 节点 config 收紧后它从静默丢弃变成执行期硬拒 #4923、RecordDetailsProps 与真实页面的授权形状不符:sections 声明为 string[] 但所有页面授权对象形式,hideFields 完全未声明 #5611、[spec] HookContext.session 少声明了 positions / preserveAudit —— 引擎在生产、消费方在读、文档在教,契约里没有(#5050 的镜像方向) #5605、routes.mcp 是 REST /discovery 发出、objectui 真实消费、但 ApiRoutesSchema 从未声明的键(#4828 同族,低一层) #5679
• 派发:os-dev(opus)。更早不同 session 认领者优先,本认领作废。

---

Generated by Claude Code

[os-zhuang]

实现完成 → draft PR #5721(claude/issue-5697-action-ctx-session-schema,session session_018fxLGQdatPbBUvCgiVxg6D)

• 前提核实:buildActionSession() 已重定位到 packages/runtime/src/action-execution.ts:754(正文预告的行号漂移成立);形状、两处调用点、两处裸 any、ScriptContext.session?: unknown 全部逐条成立。
• 一处精确化(不推翻裁定):[runtime] action body 的 ctx.session 仍在生产 roles(值是 ec.positions)—— 自称「mirroring hook ctx.session」,而 hook 侧该键已按 ADR-0049 退役 #5613 正文说 action ctx「完全无 schema」——Zod schema 确实零个,但 packages/spec/src/ui/action-params.zod.ts 的 ActionHandlerContext.session 早有一个纯 TS 接口声明,形状一致且带 [k: string]: unknown 兜底。它加强而不是削弱裁定(有类型面、无 parse、还写了通配兜底,在闸门眼里等于没有),并且决定了落点。
• 落点判定:落在 ui/action-params.zod.ts 而非 kernel。理由:同一对象的兄弟声明(ActionHandlerContext / ActionEngineFacade / ActionHandler)已全在该文件;先例是 HookContextSchema 挨着 HookSchema 住在 data/hook.zod.ts 而非 kernel;action-execution.ts 本来就从 @objectstack/spec/ui 的同一模块进货。
• 零行为变更:runtime 只做返回类型标注;ScriptContext.session 维持 unknown(一个 seam 上并存 hook / action 两种形状,收窄会逼消费端判别该类型不携带的 body kind——已在注释里点名留给后续)。buildActionSession() 那两句已知错误的注释按裁定留给第二阶段,但加了 ⚠️ 标注。
• roles 按现状声明 + deprecated 标注,不引入 positions 键;整段处方已渲染进新生成的参考页 content/docs/references/ui/action-params.mdx。
• pin:packages/runtime/src/action-session-shape-contract.test.ts,先证红方向为「预测红 / 实测红」,恰好两条红、同批其余为正控绿。条件展开语义为实测:缺值时键不存在(与 hook 侧 docs(spec): HookContext.input 契约表改成引擎真正构造的形状 (#5273) #5668 的「键在、值 undefined」相反),且无身份信封时整个 session 为 undefined,故 roles 永不单独出现。
• 验证:runtime 1446 passed / spec 8082 passed;两包 typecheck 绿;check:generated 10/10 up to date;check:exported-any / check:dual-source-exports / check:liveness 绿。

第二阶段(#5613)的 Blocked-by: 现在有类型面可依:ActionSessionSchema 落地后,更名 roles → positions 有了可挂墓碑的位置,pin 里那条 key-set 断言就是第二阶段要翻的那条。

---

Generated by Claude Code

---

Generated by Claude Code