docs(adr-0048): N.3 amended — the post-hydration check judges a package's claim against the environment catalog (ruling letter A on #22307)

[objectstack-fleet]

Refs #22307

Records the maintainer's ruling letter A on #22307 (ruling record 6063176077) in ADR-0048: addendum N.3 gains one dated note. The hydration write stays unjudged as a write, and the post-hydration check judges the package's claim against it.

This is the Tier H half of #22307, split from the code PR (#22365) so the code can land on its own record. #22307 stays open after this PR; the code PR carries the card.

What changed — docs/adr/0048-cross-package-metadata-collision.md only

Additive: 7 lines, no existing line edited.

• A dated note directly under N.3's list: "Amended (2026-10-08) — the cold boot". After sys_metadata hydration and before kernel:ready, every package-held permission set and position name is checked against the environment catalog, and a name the environment already holds fails the boot with the N.2 envelope, naming both holders. It cites the ruling record.
• N.3's existing bullet ("A write with no package provenance … stays under ADR-0005 overlay precedence") is left as it is: the hydration write is still not judged as a write, which is what the note says first.
• N.4 ("Where it is implemented") is not edited. The code PR leaves the ADR id in the code (ObjectQLPlugin.refuseEnvironmentHeldSecurityCatalogNames) and extends the module's ADR anchor (scripts/adr-anchors/packages__objectql__src__security-catalog-namespace.ts.json).

Gates (at f86b451)

node scripts/pm/dispatch-gates.mjs --commands derived 19 commands at f86b451. All 19 ran with exit codes recorded, and --ran reconciles 19/19 with 0 NOT-MEASURED (a derived zero). All 19 exit 0. check:doc-formula-expressions first answered PREREQUISITE NOT MET (exit 3); it exited 0 after @objectstack/formula and @objectstack/lint were built. origin/main has moved since the branch point, and git merge-tree against it is clean.

维护者速读(草稿)

改了什么

只改 ADR-0048 的文字，没动代码。在附录 N.3 下面加了一段带日期的说明（7 行），原文一个字都没改。说明的内容就是您在 #22307 上选的 A：重启时，环境里已经存着的权限集或职位名，如果某个包也声明了同名的，启动直接失败，报错点名双方。

为什么改

N.3 原来写的是"环境自己保存的数据不受这条规则管"。重启时，包先注册，环境数据后加载，所以按原来的写法，重启这条路正好漏过去：同一个包热安装会被拒，重启加进来却能装上，还被环境里的同名定义悄悄盖住。您裁定重启也要拒。这段说明把两件事分开写清楚：环境数据的加载本身照旧不判；加载完以后，拿包的声明去对环境目录，重名就拒。不写进 ADR，ADR 和代码就对不上。

风险与代价（含回滚）

• 这份 PR 本身只是文档，没有运行时风险。
• 真正的行为变化在配套的代码 PR（feat(objectql)!: a cold boot refuses a package-held position or permission-set name the environment catalog already holds, as a hot install does (ADR-0048 N.3) #22365）：已经处在"环境里存着同名权限集或职位、配置里又有声明同名的包"这种状态的部署，升级后会起不来，要运维改名或删掉其中一个才行。包括锁上线前保存的旧覆盖行，也包括平台安全插件自带的权限集（例如 member_default）上的旧覆盖行。仓库里的示例应用实测没有这种状态，真实部署的数量测不到。
• 回滚：撤销这份 PR，ADR 回到原文；代码 PR 可以分开回滚。

席位意见

你要做的

请看这段说明的措辞是否准确反映您的裁决，同意就批准（Approve）。这份 PR 属于 Tier H，只能由您批准后落地。

---

Generated by Claude Code

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: f86b451373c080f5736ff2f4deba1e769fa8b1eb
Local-runs: none

Read at 2026-10-08T23:17Z. Inputs, and nothing else: card #22307 (body; the ruling 6063176077, triage 6063800858, the claim 6066505265, the os-dev-report 6070693740); ADR-0048 addendum N as it stands on origin/main 43fc50051c; PR #22366 (body, the 1-file diff from merge base 3599fef123 to the head) read against PR #22365's diff at 3c160a23e3 and this seat's record on it; the check-runs on the head. Read-only: fetched refs and gh api reads; nothing built, run or re-run. This PR touches docs/adr/**: Tier H. This record informs the maintainer's word; it lifts nothing by itself.

① Derived judgments

Check-runs on the head: 35, all completed; 24 success, 11 skipped, none failure, none in_progress. The required contexts: TypeScript Type Check, Test Core (and 1–6/6), Dogfood Regression Gate, Lint & Repo Gates, Governed Surface Queue Guard — success; Build Core, Temporal Conformance (live PG + MySQL) and the Dogfood shards — skipped by the path filter on a docs-only diff. Check Changeset — success (the skip-changeset label is on the PR). Governed surface: docs/adr/0048-cross-package-metadata-collision.md — Tier H, lifts only on an authorized APPROVED review; the PR is a draft and awaits it. packages/spec: untouched. Merge base 3599fef123; git merge-tree against 43fc50051c clean on my read.

1. The amendment states the ruling's line exactly — RIGHT. The ruling 6063176077: "ADR-0048 addendum N.3 gains one line: the hydration write stays unjudged as a write, and the post-hydration check judges the package's claim against it." The note's first sentence: "The hydration write stays unjudged as a write, and the post-hydration check judges the package's claim against it:" — verbatim, then the elaboration ("after sys_metadata hydration and before kernel:ready, every package-held permission set and position name is checked against the environment catalog, and a name the environment already holds fails the boot with the N.2 envelope, naming both holders") — each clause true against feat(objectql)!: a cold boot refuses a package-held position or permission-set name the environment catalog already holds, as a hot install does (ADR-0048 N.3) #22365's diff: the check sits in ObjectQLPlugin.start() right after the hydration if/else, before kernel:ready; it reads position and permission; the refusal is SecurityCatalogNameConflictError (N.2's envelope: 422, the namespace gate's code, conflicts[] naming both holders). The citation ("ruling record 6063176077 on [decision] cold boot admits a package whose permission set or position name the environment catalog already holds (package registration runs before sys_metadata hydration), while a hot install of the same package is refused #22307, letter A") follows the form the addendum already uses for 6050490870.
2. No other ADR text changes — RIGHT. The diff is +7/−0: one dated blockquote under N.3's list, before "### N.4 Where it is implemented". N.3's bullets, N.4 and everything else are byte-identical to the merge base. skip-changeset is right: no released package changes.
3. Placement — RIGHT. The note sits under N.3 ("What stays as §3.4 has it"), beside the bullet it qualifies ("A write with no package provenance … stays under ADR-0005 overlay precedence"), which is where a reader of that bullet meets the cold-boot consequence. N.4 (where it is implemented) is left as it is; feat(objectql)!: a cold boot refuses a package-held position or permission-set name the environment catalog already holds, as a hot install does (ADR-0048 N.3) #22365 leaves the ADR id in ObjectQLPlugin.refuseEnvironmentHeldSecurityCatalogNames and extends the module's ADR anchor, so the anchor gate covers the new seam without an N.4 edit.
4. Public surface — none; a document.

② Semver level

skip-changeset — RIGHT: the diff publishes nothing from any released package. Clause-②: the PR body carries no line and needs none for a docs-only diff; the behaviour the note records is #22365's, declared there as Clause-②: no and reviewed on that PR.

③ Boundary flags

1. The 维护者速读 draft, against feat(objectql)!: a cold boot refuses a package-held position or permission-set name the environment catalog already holds, as a hot install does (ADR-0048 N.3) #22365's diff and this seat's remedy judgment — truthful; two sentences for the seat to add before the maintainer reads it. True as written: "原文一个字都没改" (+7/−0); the content is letter A; the cost paragraph names the pre-lock overlay rows and the platform's own sets (member_default) as refused after the upgrade, the in-repo census zero, deployed environments unmeasured; the rollback sentence (revert the ADR, the code PR rolls back separately) is right. What it does not yet say, and the maintainer should see: (i) for a platform-held set the remedy is NOT "remove the package" — it is the Discard Overlay action on the release the deployment runs now, before upgrading, or a direct delete of the env-wide sys_metadata row afterwards (the only offline path; no CLI command exists) — feat(objectql)!: a cold boot refuses a package-held position or permission-set name the environment catalog already holds, as a hot install does (ADR-0048 N.3) #22365's changeset names the database path; (ii) a consequence of A the ruling did not spell out: the 2026-08-24 remedies (the boot overlay reading, the drift pass's overlay_shadow, Discard Overlay) have no boot-time population for code-package-declared sets after this change, because such a boot is refused before kernel:ready — they stay reachable pre-upgrade only; whether to keep or retire them is a decision for the maintainer, filed as its own card by the seat. "席位意见" is empty — the seat fills it.
2. Wording the maintainer should see. N.3's existing bullet still ends "that path is unchanged by this addendum" (the author's save path). Under the amendment the save path is indeed unchanged, but its consequence at the next restart is not: a save that lands over a package-held name now fails that restart. The note says so; the bullet does not. Acceptable as a dated note under an unedited bullet, since the ADR's convention is additive dated notes — flagged so the maintainer chooses knowingly between the note alone and one clause on the bullet.
3. "the N.2 envelope" — right: N.2 names the 422 with the §3.2 namespace gate's code and "both holders"; feat(objectql)!: a cold boot refuses a package-held position or permission-set name the environment catalog already holds, as a hot install does (ADR-0048 N.3) #22365 reuses the class, and only the message gains a cold-boot variant.
4. Local runs — none.

Implemented-by: claude/issue-22307-adr-0048-n3-amendment
Reviewed-by: session_01EUBvqtauTDmHi2ZgY759p2

VERDICT: PASS

Tier H: the maintainer's approval is what lands this; the two 速读 sentences in ③ item 1 are the seat's to add before requesting it.

---

Generated by Claude Code

[objectstack-fleet]

维护者速读(终稿)

domain:engine#1 · session_01EUBvqtauTDmHi2ZgY759p2 (os-litant) · 2026-10-08T23:21Z。席位已对照本 PR 的 diff（+7/−0，只有一处插入）和配套代码 PR #22365 校正草稿。达档契约复审 PASS：本 PR 6070955792，代码 PR 6070947709。

改了什么

只改 ADR-0048 的文字，不动代码。在附录 N.3 下面加了一段带日期的说明，写的是你在 #22307 上裁的 A：环境数据加载这一步照旧不做判断，加载完之后，再拿包声明的权限集和职位名去和环境目录对照，重名就拒绝启动。原文一字未改。

为什么改

N.3 原来写"加载写入不受判断"。代码 PR #22365 落地后，重启时会在加载之后做这道检查。ADR 不跟着改，文档写的和代码做的就对不上了。

风险与代价（含回滚）

• 这个 PR 本身只是文档，没有运行时风险。回滚就是撤销这个 PR。
• 真正的行为变化在 feat(objectql)!: a cold boot refuses a package-held position or permission-set name the environment catalog already holds, as a hot install does (ADR-0048 N.3) #22365：环境里存着与包同名的权限集或职位时，重启会被拒（你裁定时已接受这个代价）。复审查实了改法，发布说明会写明：
  • 升级前，在 17.x 上用 Setup 里的"丢弃覆盖"(Discard Overlay) 删掉这类行；
  • 升级后如果起不来，在数据库里删掉那条环境级 sys_metadata 行。要连旧的复数类型名（permissions / positions）一起删。没有 CLI 命令能做这件事。
• 仓库内的示例应用没有这类行，重启都正常。已部署环境里有多少，测不到。

席位意见

建议批准。说明文字与你的裁定逐字一致。复审提醒两点，供你过目：

1. N.3 原有的一条仍写着保存路径"不受本附录影响"。保存路径本身确实没变，但它在下次重启时会有后果。新加的说明写清了这一点，原句没改；按"只追加、不改原文"的惯例保留。
2. 2026-08-24 那套补救工具（启动时列出被遮住的权限集、漂移检查的 overlay_shadow、丢弃覆盖按钮）在 v18 上对代码包权限集永远找不到对象。要不要撤掉，已单独立卡 [decision] after #22307 a cold boot refuses any environment row over a package-held permission set or position, so the 2026-08-24 legacy-overlay remedies (boot overlay reading, drift overlay_shadow, Discard Overlay) find nothing on v18: keep or retire? #22371 请你定，不挡这个 PR。

你要做的

在 PR #22366 上批准（Approve）。批准后由席位落地。代码 PR #22365 不等这个 PR。

---

Generated by Claude Code