feat(spec): ADR-0087 台账登记 ctx.user.roles 的立即退役 (#6011) by qq9340100 · Pull Request #6138 · objectstack-ai/objectstack

qq9340100 · 2026-08-07T03:15:21Z

Part of #6011

#6011 的台账半边(运行时半边已随 PR #6048 合并落地;该 issue 已关闭,本 PR 不重开它)。按 issue 上分诊座位 15:10Z 评论的**走法 1「不拆,registry 条目按跨域例外路径处理」**执行,认领已在 02:55Z 评论申报。RELEASE-BLOCKING for v17.0.0-rc.4。

为什么要有这一条

PR #6048 删掉了 ActorUser 上的 roles 别名(action body 的 ctx.user / AI 路由的 req.user),positions 成为唯一拼法。但 ADR-0087 语义迁移台账里这一面没有任何条目 —— 而同一次 ADR-0090 改名的另外三张面全都在册:

面	台账条目	状态
`data.hookContext.session.roles`	`hook-context-session-roles-retired`	已有
`ui.actionSession.roles`	`action-session-roles-to-positions`	已有
`CEL/formula: current_user.roles`	`cel-current-user-roles-to-positions`	已有
`ctx.user.roles` / `req.user.roles`	无	← 本 PR 补上

这种不对称正是 #6011 立单的原因:退役已经发生,但对 objectstack migrate meta / spec-changes.json / 升级指南的读者不可见。本 PR 只登记既成事实(FROM→TO 已由 #6048 固定),不重判退役范围、不复核消费方。

条目

actor-user-roles-to-positions,置于 packages/spec/src/migrations/registry.ts 的 step17 semantic 列表中、紧邻其同族兄弟 action-session-roles-to-positions。

surface:action body / AI route: ctx.user.roles (req.user.roles)
replacement:ctx.user.positions(AI 路由读 req.user.positions)—— 同一个数组,值逐字不变

⚠️ 「退役一个 spec 从未声明过的键」怎么写(#6048 正文点名的必答项)

ctx.user 面至今没有 spec schema,只有 packages/runtime 里的 TS interface —— 所以 surface 刻意不带 data. / ui. 这类 spec 域前缀,否则会谎称存在一个 spec 声明。写法照抄台账里已有的非 schema 面先例 CEL/formula: current_user.roles 的「渠道: 标识符」形状。

处置口径则沿用 data-driver-find-stream-retired(#4484)/ storage-service-list-retired(#5540)那一族:TS 契约面,无存量源可改写,刻意不设 tombstone(从没有任何 ActorUser 走过 .parse(),写在那里的处方无人可达),强制渠道是 tsc,报在读取点。条目正文如实标注本面比那两条还外一层 —— 它们至少声明在 packages/spec/src/contracts,本面只在 packages/runtime;因此对未加类型的 / 沙箱 body 而言根本没有强制渠道,这正是本台账条目必须存在的理由。

⚠️ 与 `ctx.session` 的边界(条目里双处写明)

同一个 ctx 上两张面、两套时间表,条目开头即警告不要互读:ctx.user.roles 在 17 里已经不存在(无窗口、无双发);ctx.session.roles 保留 #5613 的一个弃用窗口,期间照常双发。

生成物

按 os-regen 纪律整体重生,零手改:pnpm --filter @objectstack/spec build 后 check:generated 判定恰好 2 个过期,--fix 只重生这 2 个。

新条目已出现在重生后的升级指南(docs/protocol-upgrade-guide.md:347,Protocol 16 → 17 的 Semantic 段):

- **`actor-user-roles-to-positions`** — `action body / AI route: ctx.user.roles (req.user.roles)` → ctx.user.positions …

spec-changes.json 里出现两处(单 major 清单 + 跨 major 合成视图),是同一数据的两个投影。

测试证据

pnpm --filter @objectstack/spec build            → 通过
pnpm --filter @objectstack/spec check:generated  → 10 项中恰好 2 项过期(spec-changes / upgrade-guide),其余全绿
  └ --fix                                        → ✓ gen:spec-changes  ✓ gen:upgrade-guide
pnpm --filter @objectstack/spec test             → Test Files 327 passed (327) / Tests 8371 passed (8371)
pnpm --filter @objectstack/spec typecheck        → tsc --noEmit 干净 + check:test-typecheck OK
pnpm --filter @objectstack/spec check:spec-changes      → spec-changes.json is up to date.
pnpm --filter @objectstack/spec check:upgrade-guide     → protocol-upgrade-guide.md is up to date.
pnpm --filter @objectstack/spec check:authorable-surface → ✅ 1622 schemas(锚点 ℹ️ 落后 1 key,属允许形态,未手改锚点文件)
pnpm --filter @objectstack/spec check:docs              → ✅ 232 generated files in sync
node scripts/check-nul-bytes.mjs                        → OK (5870 files, 无裸控制字节)

反向验证(方向事前判定为「红」,结果一致)

把 registry 条目撤掉、生成物保持重生后的样子:

check:spec-changes   → exit 1  "spec-changes.json is stale — the ADR-0087 registries changed without regenerating"
check:upgrade-guide  → exit 1  "docs/protocol-upgrade-guide.md is stale — …"

恢复条目后两条立刻回绿。

但要如实说明这道门禁到底钉住了什么:它钉的是台账 ↔ 生成物同步,不是「已发生的退役必须有台账条目」。本 PR 之前的 origin/main 上,registry 与生成物是互相一致的(都没有这一条),所有门禁全绿 —— 这正是为什么这条缺失只能靠人工/分诊立单发现,而 CI 抓不到。仓库里不存在「退役 ↔ 台账」完备性门禁,本 PR 也不新造一个(那是另一个设计决定,不在本单范围)。

⛔ 范围外(已刻意不动)

packages/runtime 零字节 —— 已随 PR feat(runtime)!: 退役 ctx.user 的 roles 别名,positions 成为唯一拼法 (#6011) #6048 落地。
content/docs/releases/ 未触碰;台账锚点文件 authorable-surface.base.json 未手改。
未新增 rationale 段落:step17 的 rationale 有专门的钉子测试(protocol-17 的 migration rationale 仍写着「the server does not walk areas」,并投影进生成的升级指南 #5337),且最近的同族兄弟 action-session-roles-to-positions 也是只加 semantic 条目、不动 rationale,本 PR 照此惯例。

🤖 Generated with Claude Code

https://claude.ai/code/session_01Wbxm29qPKnLf44AbSxizqW

Generated by Claude Code

Part of #6011 —— 运行时半边已随 PR #6048 落地,本条补上 ADR-0087 语义迁移台账里缺失的 ctx.user 面,与 session 侧三条同族条目对称。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Wbxm29qPKnLf44AbSxizqW

spec-changes.json / docs/protocol-upgrade-guide.md 由 check:generated --fix 整体重生 (仅重生被判过期的 2 个),未手改。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Wbxm29qPKnLf44AbSxizqW

vercel · 2026-08-07T03:15:28Z

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 7, 2026 3:15am

github-actions · 2026-08-07T03:15:42Z

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec.

112 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

content/docs/ai/agents.mdx (via @objectstack/spec)
content/docs/ai/skills-reference.mdx (via @objectstack/spec)
content/docs/ai/skills.mdx (via @objectstack/spec)
content/docs/api/client-sdk.mdx (via @objectstack/spec)
content/docs/api/environment-routing.mdx (via @objectstack/spec)
content/docs/api/error-catalog.mdx (via @objectstack/spec)
content/docs/api/error-handling-client.mdx (via @objectstack/spec)
content/docs/api/error-handling-server.mdx (via @objectstack/spec)
content/docs/api/index.mdx (via @objectstack/spec)
content/docs/automation/approvals.mdx (via @objectstack/spec)
content/docs/automation/connectors.mdx (via @objectstack/spec)
content/docs/automation/flows.mdx (via @objectstack/spec)
content/docs/automation/hook-bodies.mdx (via packages/spec)
content/docs/automation/hooks.mdx (via @objectstack/spec)
content/docs/automation/index.mdx (via @objectstack/spec)
content/docs/automation/webhooks.mdx (via @objectstack/spec)
content/docs/automation/workflows.mdx (via @objectstack/spec)
content/docs/concepts/architecture.mdx (via @objectstack/spec)
content/docs/concepts/design-principles.mdx (via packages/spec)
content/docs/concepts/index.mdx (via @objectstack/spec)
content/docs/concepts/metadata-driven.mdx (via @objectstack/spec)
content/docs/concepts/metadata-lifecycle.mdx (via packages/spec)
content/docs/concepts/north-star.mdx (via @objectstack/spec)
content/docs/data-modeling/analytics.mdx (via @objectstack/spec)
content/docs/data-modeling/drivers.mdx (via @objectstack/spec)
content/docs/data-modeling/external-datasources.mdx (via @objectstack/spec)
content/docs/data-modeling/field-types.mdx (via @objectstack/spec)
content/docs/data-modeling/fields.mdx (via @objectstack/spec)
content/docs/data-modeling/formulas.mdx (via @objectstack/spec)
content/docs/data-modeling/index.mdx (via @objectstack/spec)
content/docs/data-modeling/objects.mdx (via @objectstack/spec)
content/docs/data-modeling/queries.mdx (via @objectstack/spec)
content/docs/data-modeling/schema-design.mdx (via @objectstack/spec)
content/docs/data-modeling/seed-data.mdx (via @objectstack/spec)
content/docs/data-modeling/validation-rules.mdx (via @objectstack/spec)
content/docs/data-modeling/validation.mdx (via @objectstack/spec)
content/docs/deployment/cli.mdx (via @objectstack/spec)
content/docs/deployment/tenancy-modes.mdx (via @objectstack/spec)
content/docs/deployment/troubleshooting.mdx (via @objectstack/spec)
content/docs/deployment/validating-metadata.mdx (via @objectstack/spec)
content/docs/getting-started/build-with-claude-code.mdx (via @objectstack/spec)
content/docs/getting-started/common-patterns.mdx (via @objectstack/spec)
content/docs/getting-started/examples.mdx (via @objectstack/spec)
content/docs/getting-started/quick-reference.mdx (via @objectstack/spec)
content/docs/getting-started/quick-start.mdx (via @objectstack/spec)
content/docs/getting-started/your-first-project.mdx (via @objectstack/spec)
content/docs/kernel/cluster.mdx (via @objectstack/spec)
content/docs/kernel/contracts/auth-service.mdx (via packages/spec)
content/docs/kernel/contracts/cache-service.mdx (via packages/spec)
content/docs/kernel/contracts/data-engine.mdx (via @objectstack/spec)
content/docs/kernel/contracts/index.mdx (via @objectstack/spec)
content/docs/kernel/contracts/metadata-service.mdx (via packages/spec)
content/docs/kernel/contracts/storage-service.mdx (via @objectstack/spec)
content/docs/kernel/index.mdx (via packages/spec)
content/docs/kernel/runtime-services/data-service.mdx (via @objectstack/spec)
content/docs/kernel/runtime-services/email-service.mdx (via packages/spec)
content/docs/kernel/runtime-services/examples.mdx (via @objectstack/spec)
content/docs/kernel/runtime-services/index.mdx (via packages/spec)
content/docs/kernel/runtime-services/queue-service.mdx (via packages/spec)
content/docs/kernel/runtime-services/sharing-service.mdx (via @objectstack/spec)
content/docs/kernel/runtime-services/sms-service.mdx (via packages/spec)
content/docs/kernel/runtime-services/storage-service.mdx (via @objectstack/spec)
content/docs/kernel/services-checklist.mdx (via @objectstack/spec)
content/docs/kernel/services.mdx (via @objectstack/spec)
content/docs/permissions/authorization.mdx (via @objectstack/spec)
content/docs/permissions/permission-sets.mdx (via @objectstack/spec)
content/docs/permissions/permissions-matrix.mdx (via @objectstack/spec)
content/docs/permissions/positions.mdx (via @objectstack/spec)
content/docs/permissions/rls.mdx (via @objectstack/spec)
content/docs/permissions/sharing-rules.mdx (via @objectstack/spec)
content/docs/plugins/adding-a-metadata-type.mdx (via @objectstack/spec)
content/docs/plugins/development.mdx (via @objectstack/spec)
content/docs/plugins/index.mdx (via @objectstack/spec)
content/docs/plugins/packages.mdx (via @objectstack/spec)
content/docs/protocol/backward-compatibility.mdx (via @objectstack/spec)
content/docs/protocol/diagram.mdx (via packages/spec)
content/docs/protocol/kernel/config-resolution.mdx (via @objectstack/spec)
content/docs/protocol/kernel/http-protocol.mdx (via @objectstack/spec)
content/docs/protocol/kernel/i18n-standard.mdx (via @objectstack/spec)
content/docs/protocol/kernel/index.mdx (via @objectstack/spec)
content/docs/protocol/kernel/lifecycle.mdx (via @objectstack/spec)
content/docs/protocol/kernel/plugin-spec.mdx (via @objectstack/spec)
content/docs/protocol/knowledge.mdx (via @objectstack/spec)
content/docs/protocol/objectql/index.mdx (via @objectstack/spec)
content/docs/protocol/objectql/query-syntax.mdx (via @objectstack/spec)
content/docs/protocol/objectql/schema.mdx (via @objectstack/spec)
content/docs/protocol/objectql/security.mdx (via packages/spec)
content/docs/protocol/objectql/state-machine.mdx (via @objectstack/spec)
content/docs/protocol/objectui/actions.mdx (via @objectstack/spec)
content/docs/protocol/objectui/concept.mdx (via @objectstack/spec)
content/docs/protocol/objectui/index.mdx (via @objectstack/spec)
content/docs/protocol/objectui/layout-dsl.mdx (via @objectstack/spec)
content/docs/protocol/objectui/record-alert.mdx (via @objectstack/spec)
content/docs/protocol/objectui/widget-contract.mdx (via @objectstack/spec)
content/docs/releases/implementation-status.mdx (via @objectstack/spec)
content/docs/releases/index.mdx (via @objectstack/spec)
content/docs/releases/v12.mdx (via @objectstack/spec)
content/docs/releases/v13.mdx (via @objectstack/spec)
content/docs/releases/v16.mdx (via @objectstack/spec)
content/docs/releases/v17.mdx (via @objectstack/spec)
content/docs/releases/v9.mdx (via @objectstack/spec)
content/docs/ui/actions.mdx (via @objectstack/spec)
content/docs/ui/apps.mdx (via @objectstack/spec)
content/docs/ui/create-vs-edit-form.mdx (via @objectstack/spec)
content/docs/ui/dashboards.mdx (via @objectstack/spec)
content/docs/ui/field-grouping-and-order.mdx (via @objectstack/spec)
content/docs/ui/forms.mdx (via @objectstack/spec)
content/docs/ui/index.mdx (via @objectstack/spec)
content/docs/ui/public-data-collection.mdx (via @objectstack/spec)
content/docs/ui/setup-app.mdx (via @objectstack/spec)
content/docs/ui/translations.mdx (via @objectstack/spec)
content/docs/ui/views.mdx (via @objectstack/spec)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.

claude added 2 commits August 7, 2026 03:00

github-actions Bot added the size/m label Aug 7, 2026

github-actions Bot added documentation Improvements or additions to documentation tooling labels Aug 7, 2026

qq9340100 marked this pull request as ready for review August 7, 2026 03:33

qq9340100 added this pull request to the merge queue Aug 7, 2026

Merged via the queue into main with commit 7f62706 Aug 7, 2026
25 checks passed

qq9340100 deleted the claude/issue-6011-adr0087-ledger-entry branch August 7, 2026 03:45

qq9340100 mentioned this pull request Aug 7, 2026

[PM seat] domain:cli — 🟢 active #6024

Open

hotlong mentioned this pull request Aug 7, 2026

v17 GA 交付物:AI 一键升级客户元数据项目(升级 skill,骑在 D2 conversions 之上) #6111

Closed

claude Bot mentioned this pull request Aug 7, 2026

[PM seat] triage (objectstack-wide) — 🟢 Routine #6015

Open

Navigation Menu

Uh oh!

feat(spec): ADR-0087 台账登记 ctx.user.roles 的立即退役 (#6011) - #6138

feat(spec): ADR-0087 台账登记 ctx.user.roles 的立即退役 (#6011)#6138
qq9340100 merged 2 commits into
mainfrom
claude/issue-6011-adr0087-ledger-entry

qq9340100 commented Aug 7, 2026

Uh oh!

vercel Bot commented Aug 7, 2026

Uh oh!

github-actions Bot commented Aug 7, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

qq9340100 commented Aug 7, 2026

为什么要有这一条

条目

⚠️ 「退役一个 spec 从未声明过的键」怎么写(#6048 正文点名的必答项)

⚠️ 与 ctx.session 的边界(条目里双处写明)

生成物

测试证据

反向验证(方向事前判定为「红」,结果一致)

⛔ 范围外(已刻意不动)

Uh oh!

vercel Bot commented Aug 7, 2026

Uh oh!

github-actions Bot commented Aug 7, 2026

📓 Docs Drift Check

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

⚠️ 与 `ctx.session` 的边界(条目里双处写明)