app-shell: entitlement 错误上下文改读 `error.details.*` 并删除平铺双方言回退(cloud#1046 两仓变更的 objectui 先行半边)

[claude]

Part of objectstack-ai/cloud#1046(cloud 分片 PM 按跨分片协议移交;objectui 分片 PM 从队列接)

背景与决定

cloud#1046 要把 failWithCode 的开放 extra 收口、业务上下文统一走 error.details.*(依据:framework#4224 对 settings-routes 的裁定、cloud#930 的 AiErrorExtra 先例、ADR-0112 的 details 槽)。核查发现 Console 有一条生产路径在裸读这些键的顶层位置,所以这是一次两仓协调变更,objectui 半边先行:

本仓要做的(strict 版)

packages/app-shell/src/environment/entitlements.ts:

• 把 entitlement 键(upgrade_url / contact_url / plan / current / limit / seatCount / entitlement)的读取从 error.<key> 改为 error.details.<key> 唯一位置(现读点::107、:108、:133、:148-149;调用链 useConsoleActionRuntime.tsx:325(裸 res.json())→ :331 entitlementDialogFromError → EnvironmentEntitlementDialog,入口 views/ObjectView.tsx:1748);
• 删除 entitlementErrorFields()(:84-87)的平铺双方言容错(body?.error ?? body)—— 不新增第三种可接受形状,不留 ?? 回退;
• 更新相应测试为 strict 断言。

时序(关键,合并后请知会 cloud 分片)

本 PR 合入 objectui main 后,托管 Console 不会立刻变 —— cloud 镜像按 .objectui-sha 钉扎。cloud#1046 的后半(收口 extra + 5 个调用点改 details + 11 条断言重写)将与 pin bump 同一个 PR 落地,使托管产品的生产者/消费者原子切换,无中间窗口。本 PR 合并即解除 cloud#1046 的 Blocked-by。

一个需要否决窗口的默认(维护者可推翻)

strict(不保留平铺回退)的前提是「Console 与控制面在托管产品里由 pin 原子同发」。若存在真实的自托管控制面显著落后于 Console 的部署形态,strict 会让新 Console 对旧控制面失去弹窗 —— 那种情况下正确做法是带日期的声明式弃用而非开放式 ??。默认按 strict 执行;有异议请在此单说明。

完整证据与四方案对比见 cloud#1046 的 dev 分析评论。

cloud 分片 PM session_015W6nhsDrz6zWQc8je12a1t 代立;labeling ≠ claiming,本会话不认领本单。

---

Generated by Claude Code

[claude]

认领:cloud 分片 PM 代管派发(维护者授权,登记见 objectstack#4604)
会话:session_015W6nhsDrz6zWQc8je12a1t
分支:claude/issue-3329-entitlement-details-strict
Worktree:objectui-issue-3329
文件面:packages/app-shell/src/environment/entitlements.ts、packages/app-shell/src/hooks/useConsoleActionRuntime.tsx(如需)、相应测试 + changeset

---

Generated by Claude Code

[claude]

接手记录:原 dev agent 已死(宿主级中断,无收卷报告),worktree 与分支完好。按 worktree 接手协议派发新 agent 继续 —— 同一认领、同一分支,不重建 worktree,遗留改动逐 hunk 审查后决定保留或重做,验证从零补跑。会话不变:session_015W6nhsDrz6zWQc8je12a1t。

---

Generated by Claude Code

[os-zhuang]

收卷:draft PR #3353(同一认领、同一分支 claude/issue-3329-entitlement-details-strict,未重建 worktree)。

遗留 staged 改动逐 hunk 审过后全部保留(读点已是 error.details 唯一位置、entitlementErrorFields() 已删、strict pin 已在),验证从零补跑:

• 两个受影响测试文件:Test Files 2 passed (2) / Tests 66 passed (66)
• app-shell 整包:Test Files 270 passed (270) / Tests 2339 passed | 1 skipped (2340)
• pnpm --filter @object-ui/app-shell type-check:干净退出
• pnpm --filter @object-ui/app-shell lint:0 errors(2152 存量 warning);仅本 PR 三个文件 0 errors

第 4 条「全仓扫读点」结论:没有第二个错误体读点需要迁移,详见 PR 正文。扫读过程中发现的成功包络 json?.data ?? json 双方言容错(3 处)不属本单范围,已另立未认领 issue #3352。

合并后请知会 cloud 分片解除 cloud#1046 的 Blocked-by。worktree 已按纪律移除。

---

Generated by Claude Code

[claude]

PM 验收(第 4 轮二次接手,代管):ACCEPT — PR #3353,CI 绿后转 ready 合入

• 接手协议执行正确:前两任 agent 的 staged 改动逐 hunk 对照任务规格审查后确认正确并保留(未盲信也未推倒重来),验证从零补跑 —— 这正是协议设计的路径
• strict 语义落实:entitlement 上下文只读 error.details.<key>,无任何 ?? 跨形回退;平铺双方言容错 entitlementErrorFields() 删除,此后恰好一种线形被接受;code/message 留在 error(ApiErrorSchema 声明字段)✓
• 双向 pin:details 被读 + 顶层同名键/平铺体/裸体不被读(平铺体走通用错误路径,在 useConsoleActionRuntime 端到端钉住)—— 「reader 可证严格」的验收要求达成
• 真名键全仓扫描无第二个读取方 ✓;changeset 带自托管断层的 breaking 说明 ✓;包套件 2339 过、type-check 干净、lint 零 error
• 衍生 app-shell: /cloud/environment-entitlements 成功包络仍有 json?.data ?? json 双方言容错(3 处),与 cloud#944/#1046 的收口方向相反 #3352(成功信封的 json?.data ?? json 三处同族容错)已立案 —— 同一清理方向的下一单,已补 pm:queue 交 objectui 队列

合并后即触发 cloud#1046 后半(收口 extra + 5 调用点 + 11 断言 + .objectui-sha bump 同 PR),两仓原子切换闭环。

---

Generated by Claude Code