[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

Ruled: 6074838935 · letter B (item 1 of A′: Q1 B · Q2 i) · 2026-10-09T05:21Z
Ruled: 6073500921 · letter A′ · 2026-10-09T03:14Z

Filing gate: ② a decision only the maintainer can make. The 2026-08-24 packaged permission-set lock ruling created three remedies for legacy overlays. #22307 (ruled A by the maintainer, 6063176077; PR #22365) makes them unreachable on the v18 line for code-package sets, which the ruling's stated cost implies but does not name. Retiring ruled machinery is the maintainer's call. Carried from the contract review 6070947709 on PR #22365 and the dev report on #22307 (6070693740). Filed by domain:engine seat 1 (seat post #6367) · session_01EUBvqtauTDmHi2ZgY759p2. ⛔ Not graded or routed here; ⛔ not a claim.

Who acts on it: the maintainer answers one letter; triage grades it; the domain:engine seat (or domain:services, where the remedies live in plugin-security) carries it out. PR #22365 does not wait for it.

维护者速读

• 2026-08-24 的锁之前，有些部署在环境里存过"覆盖包自带权限集"的行。 当时配了三样补救工具：启动时列出这些被遮住的权限集、漂移检查里的 overlay_shadow、以及 Setup 里的"丢弃覆盖"(Discard Overlay) 按钮。
• [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 落地后（你裁的 A），这种行会让部署在重启时直接拒绝启动。 所以在 v18 上，这三样工具对"代码包的权限集"永远找不到东西：能启动的部署里没有这种行，有这种行的部署起不来。它们只在升级前的 17.x 上还有用，正好是让运维在升级前清理的路径。
• 推荐 A：v18 上撤掉这三样工具里只为代码包权限集服务的那一支（17.x 不动，升级前照常可用），发布说明写明"升级前先在 17.x 上丢弃覆盖"。回一个字母：A / B / C。

一句话问题

升级后永远找不到对象的补救工具，留着还是撤掉？

Background (from #22307's dev report and the contract review)

• The three remedies, on main. All three live in plugin-security. Read them in packaged-permission-set-lock*.ts, the drift pass and the Discard Overlay path; plugin-security: discard-overlay deletes the only stored row of a permission set saved into a writable runtime package — its eligibility reads "has a package id" as "package-declared", the defect #21789 fixes in the lock #21860 is the dogfood pin.
  • The kernel:ready overlay reading lists the shadowed packaged permission sets.
  • The drift pass reports overlay_shadow.
  • The audited Discard Overlay action deletes such a row (documented in permission-sets.mdx).
• After 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. A cold boot refuses any environment-wide row over a package-held permission-set or position name, a row bound to the package itself included. So on v18:
  • the boot-time readings have no population for code-package sets;
  • Discard Overlay has no row to discard for those sets;
  • plugin-security: discard-overlay deletes the only stored row of a permission set saved into a writable runtime package — its eligibility reads "has a package id" as "package-declared", the defect #21789 fixes in the lock #21860's pin had to write its overlay into a running deployment to keep its subject.
• Still reachable (contract review, not measured for a non-built-in name): OS_METADATA_WRITABLE=position can mint a position overlay at runtime. That deployment then refuses its next restart.
• The upgrade remedy (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's changeset after its patch round):
  • before upgrading, use Discard Overlay on 17.x;
  • after upgrading, delete the environment-wide sys_metadata row in the database. No CLI command does this.

Governing text

• The 2026-08-24 lock ruling, the source of the remedies.
• [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's ruling A (6063176077): "The cost is stated knowingly: a deployment already holding an environment-saved name a configured package also declares, including rows saved before the packaged locks, fails to boot after the upgrade until an operator renames or removes."
• ADR-0049 (enforce or remove: unreachable machinery is residue).

选项 × 真实代价

业务含义直译:

• A：搬家前清掉旧家具，新家不再留"清旧家具"的工具间。
• B：新家里留着一间永远空着的工具间。
• C：新家门口再放一台"进不了门也能清旧家具"的机器。

os-decision-facets

• ① 项目长远合理性：两年后已无 17.x 遗留行，A 是终态（无无效机制）；B 留永久死代码；C 为过渡期加永久公开面。
• ② 实际业务拉动：从 17.x 升级、带锁前遗留覆盖行的部署；17.x 上的丢弃覆盖已覆盖它们（升级前）。升级后起不来的只能手写 SQL，C 才服务这部分，数量未测。
• ③ 防 AI 犯错：A 让 v18 上不存在"按钮能点但永远无事可做"的误导；B 留误导面；C 多一个命令可误用。
• ④ 创业阶段不扩散：A 删代码；B 不动；C 加命令（Clause-②: yes，转 spec/cli 车道）。

Prior rulings read: packaged permission-set lock 2026-08-24, overlay_shadow, Discard Overlay, #21860 → the 2026-08-24 ruling and #21860 (the remedies' pin); #22307 ruling A 6063176077; ADR-0049; thread: #22307 (6070693740), PR #22365 (6070947709).

推荐

A：v18 撤掉代码包分支，17.x 保留。

• 终态句： 两年后，所有部署都已越过 v18，锁前遗留行不复存在。平台里不应有永远找不到对象的补救机制（ADR-0049）。主流平台在锁定类迁移里也这样做：在旧版本上提供清理工具和升级前检查，新版本不再携带。
• 自检： 只看①选 A；②③④ 是否翻转：否（②只影响发布说明的措辞：必须写明"升级前清理"）。
• 回退： B（不动）。若实测发现升级后起不来的部署不少，再议 C。
• 置信缺口：
  • 真实部署里还有多少锁前遗留覆盖行，测不到。
  • OS_METADATA_WRITABLE=position 在运行时造出的职位覆盖，是否仍需要一个运行时清理入口，未实测。

裁后执行

• 选 A： 本席（或 domain:services 席，按分诊路由）派一张卡：
  • 删 plugin-security 中三样补救的代码包分支，保留其余；
  • plugin-security: discard-overlay deletes the only stored row of a permission set saved into a writable runtime package — its eligibility reads "has a package id" as "package-declared", the defect #21789 fixes in the lock #21860 的 pin 按删除方向翻转；
  • 发布说明和 permission-sets.mdx 写明"升级前在 17.x 上丢弃覆盖"。
• 选 B： 仅在 permission-sets.mdx 注明"v18 上仅对升级前数据有意义"，本卡关闭。
• 选 C： 本卡转 domain:cli（新命令，扩大公开面），契约复审档复核。

Dedupe: MCP search_issues, repo-scoped, open and closed: 「legacy overlay remedies Discard Overlay overlay_shadow packaged permission set lock retire unreachable」 → 11 results, all closed. The nearest:

• plugin-security: discard-overlay deletes the only stored row of a permission set saved into a writable runtime package — its eligibility reads "has a package id" as "package-declared", the defect #21789 fixes in the lock #21860: Discard Overlay eligibility, the pin 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 reshaped;
• A legacy env overlay on an artifact-backed item of a rolled-back type can no longer be REMOVED through the ordinary delete path (403) — only via OS_METADATA_WRITABLE #6960: removal of a legacy overlay through the delete path;
• Boot reconciliation projects env permission-set overlays one at a time, and re-writes every record unconditionally — the #10946 shape on the ADR-0094 door #11097: boot reconciliation of overlays.

None asks whether the remedies stay after the cold-boot refusal.

Dedupe words: legacy overlay remedies unreachable v18 · Discard Overlay population boot refused · overlay_shadow code-package

Generated by Claude Code