[Decision] When a curated capability name is already held in the platform bucket, should the seeder keep declining — or adopt, backfill, or refuse the collision at authoring time?

[os-zhuang]

Surfaced while reviewing #8470 / PR #8537. Not blocking that PR — it lands with the conservative behaviour and reports the collision loudly. This card is the policy question the PR deliberately declined to answer, and it is filed because the dev was right to decline it, not because anything is wrong with the fix.

The state the question is about

After #8537, the curated seeder looks up { name, managed_by: 'platform', organization_id: null } — the row the platform owns. If that matches nothing and the insert is then refused by the unique key, the platform's curated definition is missing from sys_capability installation-wide, and the seeder counts it (blockedCurated) and warns on every boot.

It declines to resolve the collision, for two stated reasons: adopting a differently-stamped row into the platform's identity would reverse #5876's ruling that "not provably ours" resolves to leave-it-alone, and backfilling a stamp is a data migration. Both are calls above the implementer's pay grade, so neither was made.

What was measured, not assumed

Two of the three non-platform provenances in that bucket are reachable, and one is ordinary rather than exotic:

• managed_by: 'admin' — reachable and ordinary. organization_id auto-stamping lives in the enterprise @objectstack/organizations runtime, which is also what activates every walled posture. A deployment without it is single posture with no stamper, so every Setup-authored capability row lands in the NULL-organization bucket. That is the default community shape.
• managed_by: 'package' — reachable via name promotion, with real instances. bootstrapDeclaredCapabilities refuses a name in PLATFORM_CAPABILITY_NAMES, but a package that declared a name before the platform curated it left a managed_by: 'package' row there. setup.write and manage_sharing were both added to the curated set after the fact.
• no managed_by at all — NOT engine-reachable. The field is required: true with defaultValue: 'admin', and applyFieldDefaults resolves defaults on insert before the beforeInsert hooks, so an insert omitting it stores 'admin'. (The diagnostic still handles it, because a message must not assert what it cannot observe.)

Why this is a decision and not a follow-up bug

For the package case specifically, #8537 changes the outcome on already-upgraded installations rather than only fixing a defect:

	before #8537	after #8537
installation where a package declared setup.write before it was curated	the seeder found that row by { name }, took the update branch, and overwrote it with the platform copy — so the platform definition effectively existed	the scoped lookup matches nothing, the insert is refused, and the platform definition is absent installation-wide, with a warning every boot

Neither state is good. The new one is the one ADR-0066 D1 implies (do not clobber another author) and it is honest about itself, which is why it is the right thing to ship now. But whether it is the right long-term answer on the two deployment shapes above is a product call.

The options, stated without a recommendation

1. Keep declining — the shipped behaviour. The platform definition stays absent on colliding installations; the operator sees a warning naming the blocking row's provenance and has to resolve it by hand.
2. Adopt a platform-bucket row into the platform's identity when nothing else claims it. Reverses The back-compat capability derivation refreshes label/description on ANY existing sys_capability row, including admin-authored ones — the comment above it says the opposite #5876's "not provably ours → leave alone" for this specific bucket.
3. Backfill the managed_by stamp for known-curated names in the NULL bucket. A data migration, and it decides on the operator's behalf that those rows were the platform's.
4. Refuse the collision at authoring time — stop Setup from creating a sys_capability row whose name is in PLATFORM_CAPABILITY_NAMES, so the state cannot arise going forward. Does nothing for installations already carrying one, so it likely pairs with 1 or 3.

⛔ I am not answering this on the maintainer's behalf, and I have deliberately not ranked the options. I will note only that option 4 is the one that matches the standing principle recorded 2026-08-12 — "if the platform cannot honour a declaration, refuse it at the latest checkpoint that can see the whole picture, name the offending key path, and never answer 200" — because authoring a curated name in Setup is precisely a declaration the platform later cannot honour. Whether that principle should govern here is the question, not the answer.

Related

• bootstrapSystemCapabilities reconciles an arbitrary row when a curated capability name exists in more than one organization — find(..., limit: 1) has no ORDER BY, so the platform's own row can be left unseeded #8470 / PR fix(security): the curated capability seeder reconciles the row the platform owns, not whichever row shares the name (#8470) #8537 — the fix that makes this state observable and names it.
• The DERIVED half of bootstrapSystemCapabilities also leaves the platform bucket unseeded when an organization holds the name — the #5876 guard skips instead of inserting #8536 — the DERIVED half has the same unseeded-bucket shape, on the half bootstrapSystemCapabilities reconciles an arbitrary row when a curated capability name exists in more than one organization — find(..., limit: 1) has no ORDER BY, so the platform's own row can be left unseeded #8470's ruling excluded.
• The back-compat capability derivation refreshes label/description on ANY existing sys_capability row, including admin-authored ones — the comment above it says the opposite #5876 — the "not provably ours resolves to leave-it-alone" ruling that option 2 would reverse.
• ADR-0066 D1 — the platform DEFINES, admins EXTEND.

Filed unassigned by the domain:metadata PM seat.

[hotlong]

Triage: labels verified correct (needs-user-decision + domain:metadata), type set Task. Human floor confirmed, not auto-adjudicable: options 2/3 are ruling-reversal / data-migration shapes, option 4 changes the authoring acceptance surface, and the object is the RBAC capability registry (security surface). — triage seat Routine.

Four-prism block (supplied by triage per the decision-card protocol; the filer deliberately declined to rank — this is analysis, not an answer):

• Platform long-term coherence: option 4 makes the collision unrepresentable going forward (shrinks the special-case space); options 2/3 each carve a one-time exception into The back-compat capability derivation refreshes label/description on ANY existing sys_capability row, including admin-authored ones — the comment above it says the opposite #5876's "not provably ours → leave alone"; option 1 preserves every standing ruling but accepts a permanent warning state as the steady state on colliding installations.
• Measured business pull: real, not speculative — the card measures that the NULL-bucket admin shape is the default community deployment (no enterprise stamper), and two curated names (setup.write, manage_sharing) are known to have pre-curation package rows.
• AI-agent error-resistance: option 4 is the refuse-loudly-at-the-checkpoint shape and matches the 2026-08-12 principle quoted on the card; options 2/3 are silent-adoption shapes an agent cannot distinguish from clobbering another author's row.
• Startup scope discipline: option 1 is zero new code (already shipped); 4 is one guard at one checkpoint; 3 is a migration with permanent obligations; 2 rewrites an existing ruling.

Prism reading: leans 4 (+ 1 for already-colliding installations) — but choosing the residual-state half (1 vs 3) is exactly the migration call that puts this on the human floor, so no recommendation is recorded beyond the lean.

Related-card note: #8536 records the same unseeded-bucket shape on the DERIVED half; a ruling here likely carries to it.

---

Generated by Claude Code

[hotlong]

Maintainer ruling recorded — option 4 + option 1: refuse the collision at authoring time going forward; existing installations keep the shipped decline-and-warn. Provenance: maintainer live session, 2026-08-13 ~23:50Z, verbatim 「接受你的全部建议」, accepting this seat's four-prism briefing of the full decision box (this card's briefed recommendation was 4+1).

The ruling, spelled out for dispatch:

1. Option 4: Setup can no longer create (or rename) a sys_capability row whose name is in PLATFORM_CAPABILITY_NAMES — refused at the write door with a located error naming the colliding curated name. This is the standing 2026-08-12 principle applied: a declaration the platform cannot honour is refused at the latest checkpoint that can see the whole picture, never answered 200.
2. Option 1 for existing installations: the seeder's shipped behaviour stands — scoped lookup, decline on collision, loud per-boot warning naming the blocking row's provenance (blockedCurated). The warning should carry one operator-facing remediation line (how to resolve by hand), since the ruling deliberately leaves stock rows to the operator.
3. Options 2 and 3 are explicitly rejected: adoption would reverse The back-compat capability derivation refreshes label/description on ANY existing sys_capability row, including admin-authored ones — the comment above it says the opposite #5876's "not provably ours resolves to leave-it-alone", and backfill is a data migration deciding provenance on the operator's behalf.

Label transition: needs-user-decision → pm:queue.

Dispatch notes: the authoring refusal is an accept/reject change on the data write door for sys_capability ⇒ treat as the fable-clause tier at dispatch. Both reachable non-platform provenances (admin no-stamper community shape; pre-curation package rows for setup.write/manage_sharing) are measured on the card — the refusal must not break the legitimate halves of those flows (creating non-curated names stays open).

Recorded by the triage seat on the maintainer's direct channel.

---

Generated by Claude Code

[os-zhuang]

Claim — dev seat dispatched for the recorded ruling (option 4 + option 1).

• Session: session_012WMpuAfA2KSdDjGF6tm1bH
• Branch: claude/issue-8552-refuse-curated-name
• File surface (full):
  • packages/plugins/plugin-security/src/security-plugin.ts — new curated-name refusal at the sys_capability admin-door write gate (create + rename), sited with the existing ADR-0066 asset gates
  • packages/plugins/plugin-security/src/security-plugin.test.ts — gate tests incl. positive controls in both deployment shapes
  • packages/plugins/plugin-security/src/bootstrap-system-capabilities.ts — one operator-facing remediation line on the blockedCurated warning
  • packages/plugins/plugin-security/src/bootstrap-system-capabilities.test.ts — warning-content pin update
  • .changeset/*.md — accept/reject change record

Not touching sys-permission-set.object.ts or any translations/*.objects.generated.ts (held by PR #8599); the refusal message and the boot warning are runtime/log text, not field metadata, so no translation bundle is implicated. Also staying clear of the live worktrees on packages/objectql/src/registry.ts (#8459) and the /meta read-exit materialization (#8376).

---

Generated by Claude Code

---

Generated by Claude Code