Studio save of a package-declared permission set forks it into a silent, undiscoverable overlay

[os-sam]

Split out from #9952's maintainer ruling (2026-08-20), which named it explicitly:

⚠️ Follow-up worth its own card, filed by whoever lands this if not absorbed: the overlay-shadow mechanism itself (a Studio save of a package-declared set silently forking it from the package, customized flag untouched) — arguably the real product defect the field report uncovered.

#9952 built the surfacing half (a drift_status/drift_detail diagnostic + a "Needs Attention" Setup view + a sanctioned "Discard Overlay" action) — an independent detector that catches an overlay-shadowed set even when the row's own customized flag reads wrong. It does not fix the underlying mechanism this card is about:

The mechanism

A sys_metadata overlay of a package-declared (artifact-backed) permission set can exist today — either a legacy row created while permission still had allowOrgOverride: true (pre-#6483/PR #6608, i.e. before ADR-0094 D5-R, 2026-08-09), or a fresh one created through the documented OS_METADATA_WRITABLE=permission operator hatch. Once it exists:

• reconcilePermissionSetProjection's env door (ADR-0094 D4 step 1) re-projects that overlay's content onto the record on every boot, unconditionally, keyed only on overlay presence — so the overlay wins forever regardless of what the package ships next, with no expiry.
• upsertEnvPermissionSet's customized flag is only trustworthy when the row's managed_by is already correct ('package'); on a row whose managed_by predates provenance tracking (the provenance_skip mechanism [field report] rc→GA upgraded envs: package-declared permission sets frozen at first-boot snapshot — provenance skip is silent and has no adoption/migration path #9952 also documents), the flag is forced false even though an overlay genuinely shadows the row — measured on the field-reported environment: customized stayed 0 for two weeks while the overlay froze the set.
• There is no diff, no "the package has moved on since this overlay was taken" signal, and (pre-[field report] rc→GA upgraded envs: package-declared permission sets frozen at first-boot snapshot — provenance skip is silent and has no adoption/migration path #9952) no link from the generic "1 unpublished change" console badge to which set, which surface, or the fact that a shipped declaration is being shadowed.

Why it is a product defect, not just a missing diagnostic

#9952's drift_status field tells an admin that a set has drifted and why, and gives them a button to fix it — but nothing stops the fork from happening again the same way, and nothing makes customized itself correct independent of managed_by. An admin who has never opened the new "Needs Attention" view has no reason to know a Studio save on a package-declared set (via the operator hatch) silently committed them to a permanently-shadowed set.

Candidates worth considering (not scoped/decided — for whoever picks this up)

• Make customized's computation independent of managed_by correctness (compute it the same way [field report] rc→GA upgraded envs: package-declared permission sets frozen at first-boot snapshot — provenance skip is silent and has no adoption/migration path #9952's drift_status overlay-shadow branch does — an active overlay for the name, checked directly against sys_metadata — rather than gating on existing.managed_by === 'package').
• An expiry/diff signal: when the shipped artifact has changed since the overlay was captured, say so (not just "an overlay exists").
• Reconsider whether the OS_METADATA_WRITABLE=permission hatch should be able to mint a new overlay on an artifact-backed set at all, now that ADR-0094 D5-R's stated intent is "no new overlay of a packaged set can be minted."

Related: #9952 (parent field report — surfacing + discard action), #8672 (open — org-less materialization, same file).

[os-zhuang]

Maintainer ruling recorded — step 1, Salesforce-style: lock the base, clone to customize

Provenance: maintainer, 2026-08-24, live PM chat, verbatim: 「同意 第一步(创业阶段,Salesforce 式)」, ruling on the mainstream-platform comparison presented in the batch review (fork may exist, but never silently; startup stage takes the lock-and-clone shape first).

Ruled scope:

1. The silent fork path closes at the server. A Studio/API save targeting a package-declared permission set (a row carrying package provenance) is refused loudly, with a message that names the sanctioned path: clone it. No silent overlay row is ever created again.
2. Clone-to-customize is the sanctioned path. The clone is an ordinary new org-owned permission set (this org's row, no upgrade linkage), optionally recording "cloned from @" as informational provenance. Upgrades keep flowing to the package-declared base untouched.
3. Existing silent overlays (already-forked rows in live deployments): implementation includes a detection reading (count + names, reported loudly — e.g. a boot warning or diagnostic listing), but ⛔ no automatic reap/merge — disposition of existing forks is a follow-up reading for the maintainer, not a silent migration.
4. End state recorded, not chartered: the ServiceNow-style explicit overlay layer (badge / customization list / diff-vs-base / revert / upgrade skip-report) is the mature direction if customer pull for in-place customization of packaged sets ever appears. No card until then.

Clause-②: yes — this narrows the accept set on a write door (edits previously accepted are now refused); contract-review tier at dispatch. UI half (lock rendering + Clone button in Studio) is filed separately in objectui, blocked on this server half landing.

State: finding → pm:queue (services lane), type Feature.

---

Generated by Claude Code

[os-sam]

Claim + dispatch — ruled step 1 (Salesforce-style: lock the base, clone to customize)

• Session: session_01APWX2AwT3a4xDcjPCe8bk4 (os-sam, domain:services execution seat)
• Branch: claude/issue-11513-lock-packaged-permission-set
• Worktree: ../objectstack-11513 (per-repo; ⛔ never the shared checkout; ⛔ never git stash)
• pm:queue → pm:dispatched, needs:contract-review added

Authority: maintainer ruling 5394202746, 2026-08-24, verbatim 「同意 第一步(创业阶段,Salesforce 式)」. Scope is the three ruled items — refuse the fork at the server with a message naming clone; make clone-to-customize the sanctioned path; ship a detection reading for existing overlays. ⛔ Item 4 (the ServiceNow-style explicit overlay layer) is recorded, not chartered — no work.

Clause-② — yes, and this seat is below the tier

The ruling grades it: this narrows the accept set on a write door — saves previously accepted are now refused. CONTRACT_REVIEW_TIER re-read live this round at scripts/pm/dispatch-gates.mjs:3070 = claude-fable-5; this seat is below it. So needs:contract-review stays on the card and I will not clear it, will not flip the PR ready, and will not arm auto-merge.

⭐ The fence that matters most on this card

The natural implementation asks "is this set package-declared?" before refusing. The obvious helper for that question is known-broken.

#11518 (open, unclaimed finding): buildExistingByName's unscoped page cap limit: names.length truncates once a name can carry more than one row — and a truncated page reads as "absent". Live on main in permission-set-projection.ts:1176 and bootstrap-declared-capabilities.ts:416.

⇒ On this card that defect inverts into a fail-open: a truncated "absent" would mean "not package-declared", which means the save this ruling exists to refuse gets accepted. A silent fork, produced by the code written to stop silent forks.

⛔ Do not fix #11518 here — it is an open unclaimed finding and belongs to whoever takes it. Do make sure your provenance check does not inherit it: decide package-declared-ness from a read that cannot truncate into a false negative, and say in your report which read you used and why it cannot. ⚠️ I own this warning personally — #11518 shipped in PR #11470, which I reviewed and merged, and I missed it because an adjacent fix on the scoped arm made the line look already-repaired. An adjacent fix is not coverage.

Two scope edges

customized is not chartered. The card lists "make customized's computation independent of managed_by" among its candidates; the ruling did not charter it. Your detection reading (item 3) must therefore not depend on customized — the card measures it staying 0 for two weeks while an overlay froze the set. Check sys_metadata directly, the way #9952's drift_status overlay-shadow branch does. ⛔ Do not expand into re-computing customized platform-wide; if you conclude the ruling cannot be implemented without it, report that rather than doing it.

⛔ No reap, no merge, no migration of existing forks. Ruled explicitly: detection is a reading — count + names, reported loudly. Disposition of existing forks is a follow-up reading for the maintainer.

⚠️ A citation on this card that cannot be read

The card's Related line says "#8672 (open — org-less materialization, same file)". #8672 404s as both an issue and a PR in this repo, checked with both instruments demonstrably working on other numbers. Recorded as unmeasured, not "does not exist" — most likely a cross-repo citation that lost its prefix. ⛔ Do not treat it as a live constraint you failed to read, and ⛔ do not guess at its contents; if your work needs it, report the gap.

---

Generated by Claude Code