Skip to content

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

Merged
qq9340100 merged 2 commits into
mainfrom
claude/issue-6011-adr0087-ledger-entry
Aug 7, 2026
Merged

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

Conversation

@qq9340100

@qq9340100 qq9340100 commented Aug 7, 2026

Copy link
Copy Markdown
Collaborator

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 也不新造一个(那是另一个设计决定,不在本单范围)。

⛔ 范围外(已刻意不动)

🤖 Generated with Claude Code

https://claude.ai/code/session_01Wbxm29qPKnLf44AbSxizqW

Generated by Claude Code

claude added 2 commits August 7, 2026 03:00
@claude
feat(spec): ADR-0087 台账登记 ctx.user.roles 的立即退役 (#6011)
6ea2533 
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
@claude
chore(spec): 重生 ADR-0087 生成物并补 changeset (#6011)
ed4fe57 
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

vercel Bot commented Aug 7, 2026

Copy link
Copy Markdown

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

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

Request Review

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

github-actions Bot commented Aug 7, 2026

Copy link
Copy Markdown
Contributor

📓 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.

@github-actions github-actions Bot added documentation Improvements or additions to documentation tooling labels Aug 7, 2026
This was referenced Aug 7, 2026
Closed
Closed
@qq9340100
qq9340100 marked this pull request as ready for review August 7, 2026 03:33
@qq9340100
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
qq9340100 deleted the claude/issue-6011-adr0087-ledger-entry branch August 7, 2026 03:45
@qq9340100 qq9340100 mentioned this pull request Aug 7, 2026
Open
@hotlong hotlong mentioned this pull request Aug 7, 2026
Closed
@claude claude Bot mentioned this pull request Aug 7, 2026
Open
This was referenced Aug 7, 2026
Merged
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

documentation Improvements or additions to documentation size/m tooling

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@qq9340100 @claude