feat(plugin-security): delete the curated capability seeder — the boot writes no sys_capability row for the platform's capabilities (ADR-0131 D3, #15204 stage 6b-1b)

.changeset/15204-s6b1b-system-capability-seeder.md

@@ -0,0 +1,15 @@
+---
+'@objectstack/plugin-security': minor
+'@objectstack/spec': patch
+'@objectstack/lint': patch
+---
+
+feat(plugin-security): the boot no longer writes `sys_capability` rows for the platform's curated capabilities
+
+Clause-②: no
+
+The curated and derived-default capability seeder (`bootstrapSystemCapabilities`) is deleted. On a fresh database the boot writes no `sys_capability` row for the nine curated platform capabilities (`manage_users`, `manage_org_users`, `manage_metadata`, `manage_platform_settings`, `setup.access`, `setup.write`, `studio.access`, `manage_sharing`, `view_all_audit_log`), and none for a name a permission set grants in `systemPermissions` without declaring it. The curated capabilities are served by the registry: `GET /api/v1/meta/capability` lists them and `GET /api/v1/meta/capability/:name` answers each one's definition, as before. Declare a capability your package grants with `defineCapability` (`stack.capabilities`); a declared capability is still seeded as a package row.
+
+No authorization decision changes: a grant is still resolved by the capability name in `systemPermissions`, and no runtime check reads a `sys_capability` row. On a database that was already seeded, the existing rows stay as they are; they are no longer refreshed at boot.
+
+In `@objectstack/spec` (`PLATFORM_CAPABILITIES`) and `@objectstack/lint` (`validateCapabilityReferences`), the doc comments now name the registry instead of the retired seeder; no behaviour changes there.

content/docs/permissions/authorization.mdx

@@ -204,10 +204,10 @@ to write into another package's capability.
 
 This **replaces the implicit back-door** where a capability existed only as an
 untitled placeholder derived from whatever a permission set happened to reference
-in `systemPermissions[]`. That derivation still runs for back-compat (a
-reference with no declaration keeps resolving as a `managed_by:'platform'`
-placeholder), but an explicit `defineCapability` takes precedence and — for a
-pre-existing derived placeholder — **claims** it, upgrading the row to package
+in `systemPermissions[]`. That derivation is retired: a reference with no
+declaration still matches by name at runtime but gets no `sys_capability` row.
+An explicit `defineCapability` takes precedence and — for a derived placeholder
+an older database still holds — **claims** it, upgrading the row to package
 provenance with the authored label/description/scope. This is the ADR-0066 D1
 direction: retire the implicit `managed_by`-guessing back-doors in favour of
 explicit, attributable declarations.
@@ -543,15 +543,17 @@ The complete, prioritized gap map lives in issue **#2561** (the production
 
 - **Deny/muting layer** (ADR-0066 ⑦⑧) — union-only grants can't take access
   away; needed for large-org governance and packaged-set adjustment.
-- **Capability registry** (ADR-0066 D1) — **landed**: capabilities are seeded
-  as first-class `sys_capability` records from the canonical list in
+- **Capability registry** (ADR-0066 D1, ADR-0131 D3) — **landed**: the
+  platform's curated capabilities, from the canonical list in
   `@objectstack/spec` (`security/capabilities.ts` → `PLATFORM_CAPABILITIES`),
-  seeded by `packages/plugins/plugin-security/src/bootstrap-system-capabilities.ts`.
+  are declared `capability` metadata served by the registry
+  (`registerBuiltinCapabilities`, `GET /api/v1/meta/capability`), with no
+  `sys_capability` row.
   A **package** now DEFINES its own capabilities explicitly via
   [`defineCapability` / `stack.capabilities`](#package-capability-declaration-adr-0066-d1),
   seeded with `managed_by:'package'` + `package_id` provenance by
   `bootstrap-declared-capabilities.ts` — replacing the implicit
-  derive-from-`systemPermissions` back-door (which stays for back-compat).
+  derive-from-`systemPermissions` back-door (now retired).
   The authoring lint (ADR-0066 ⑨) is also **landed**: `validateCapabilityReferences`
   (`@objectstack/lint`) warns at author time (`os validate` / `os lint`) when a
   `requiredPermissions` names a capability registered nowhere — no built-in, no

content/docs/permissions/capabilities.mdx

@@ -220,7 +220,7 @@ behind that behaviour are set out in
 the scope and the provenance that make a capability reviewable, attributable and
 uninstallable — but no authorization check reads it. Permission-set grants and
 resource `requiredPermissions` match capability names **as strings**; the only
-production readers of the table are the two boot seeders. The row's `active`
+production reader of the table is the declared-capability boot seeder. The row's `active`
 flag is a catalogue/visibility flag with no authorization effect: clearing it
 revokes nothing. Withdraw a capability by withdrawing the **grant**.
 </Callout>

content/docs/permissions/permission-sets.mdx

@@ -40,7 +40,7 @@ export const SalesUser = definePermissionSet({
   // Tab/app visibility
   tabPermissions: { app_crm: 'default_on', app_admin: 'hidden' },
 
-  // System capabilities (flat strings, resolved against sys_capability)
+  // System capabilities (flat strings, matched by capability name)
   systemPermissions: ['export_reports'],
 });
 ```
@@ -147,8 +147,12 @@ the anchor decides *which* unit `unit*` means.
 
 ## Capabilities & required permissions (ADR-0066)
 
-- **Capabilities** are first-class `sys_capability` records — named privileges
-  such as `manage_users`, `manage_metadata`, `setup.access`, `studio.access`.
+- **Capabilities** are named privileges such as `manage_users`,
+  `manage_metadata`, `setup.access`, `studio.access`. The platform's curated
+  ones are declared `capability` metadata served by the registry
+  (`GET /api/v1/meta/capability`) and have no `sys_capability` row; a
+  capability a package declares with `defineCapability` is also seeded as a
+  `sys_capability` row.
   Grant them via `systemPermissions`; declare them as prerequisites via an
   object/field/app `requiredPermissions` (an **AND**-gate checked before any
   CRUD grant).

content/docs/permissions/tenant-audit-census.mdx

@@ -83,7 +83,7 @@ what moved this page's population from 225 to 227; nothing about the two sites
 changed, only whether this instrument could see them.
 
 **The expensive failure direction is a keyword.** Sites whose receiver the author
-typed `any` have no type to read, and there are 53 of them — just over a fifth
+typed `any` have no type to read, and there are 51 of them — just over a fifth
 of the population, concentrated in exactly the seed and bootstrap paths this
 control exists for. Scoring an unreadable receiver as "not an engine" would have
 dropped every one of them silently, with a clean exit and a smaller number that
@@ -122,7 +122,7 @@ are reported as `undecidable` rather than assumed either way.
 
 The same holds twice over for the context. An options argument spelled as a
 literal can be read; one spelled `options`, `{ ...opts }`, or handed through a
-forwarding shim cannot, and **53 of the 241 sites are spelled that way**. A
+forwarding shim cannot, and **53 of the 239 sites are spelled that way**. A
 context resolved from an inline literal or a local `const` can be tested for
 `isSystem`; one arriving from a helper call cannot.
 
@@ -187,10 +187,10 @@ reproduce them. Where it disagrees, it disagrees on the page:
 
 | carried figure | where it survives | this census |
 | :--- | :--- | ---: |
-| 175 write call sites | quoted in the merged changeset | **241** |
+| 175 write call sites | quoted in the merged changeset | **239** |
 | 24 carrying no tenant context | quoted in the merged changeset | **2** provable and tenancy-enabled; **32** more whose options argument is unreadable |
-| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **160 of 241** decidable, **81** undecidable |
-| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 128 decidably elevated, 0 decidably not, 105 undecidable |
+| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **160 of 239** decidable, **79** undecidable |
+| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 126 decidably elevated, 0 decidably not, 105 undecidable |
 | 141 and 132, two independent re-derivations | the card that filed this work | — |
 
 **The differences are not reconciled, and deliberately so.** The old census's
@@ -200,18 +200,18 @@ be stated is what this instrument counts, which is written above and re-runnable
 at any commit.
 
 Two structural facts do plausibly widen this reading against any hand or regex
-one, and both are counted in the generated tables below: the 53 sites reached
+one, and both are counted in the generated tables below: the 51 sites reached
 through an erased (`any`) receiver, and the 53 that name their object through a
 `const` rather than inline. An instrument that read either the way a person does
 would report a smaller number and would not say so.
 
 The fourth row is the one worth flagging to anyone citing it. **The 135 / 77%
 figure has no surviving corroboration anywhere in the tree.** This census reads
-128 of 241 (53%) as decidably elevated, with 105 more whose elevation is a
+126 of 239 (53%) as decidably elevated, with 105 more whose elevation is a
 run-time fact — so the claim is neither confirmed nor refuted, and the honest
 answer is that a static reading cannot settle it.
 
-⇒ **Cite `2 / 241`, and say what it is**: the sites whose options argument was
+⇒ **Cite `2 / 239`, and say what it is**: the sites whose options argument was
 READ and holds no tenant context, against a decidably tenancy-enabled object.
 That is the control's provable yield surface. ⛔ Do not cite it as "the sites
 without tenant context" — **32 further sites** have an options argument this
@@ -223,30 +223,30 @@ cannot read, and they are neither in nor out.
 
 | what | count |
 | :--- | ---: |
-| write call sites on the application surface | **241** |
+| write call sites on the application surface | **239** |
 | …whose object name is statically decidable | 160 |
-| …whose object name is chosen at run time | 81 |
+| …whose object name is chosen at run time | 79 |
 | …against an object with tenancy ENABLED | 159 |
 | …against an object that declares tenancy off | 1 |
-| threading a tenant context | 180 |
+| threading a tenant context | 178 |
 | PROVABLY carrying none (options read, no context key) | **8** |
 | …of those, against a decidably tenancy-enabled object | **2** |
 | options argument UNREADABLE — may or may not carry one | 53 |
 | …of those, against a decidably tenancy-enabled object | 32 |
-| threading a decidably ELEVATED (`isSystem`) context | 128 |
+| threading a decidably ELEVATED (`isSystem`) context | 126 |
 | threading a context that is decidably NOT elevated | 0 |
 | threading a context whose elevation is a run-time fact | 105 |
 
 | how the instrument reached the site | count |
 | :--- | ---: |
 | receiver carried a readable engine type | 188 |
 | receiver erased, placed by the object NAME | 33 |
-| receiver erased, placed by an `object: string` PARAMETER | 15 |
+| receiver erased, placed by an `object: string` PARAMETER | 13 |
 | receiver erased, placed by an `UNTYPED_RECEIVERS` row | 5 |
 
 | object name spelled inline | 107 |
 | object name spelled through a `const` | 53 |
-| object name is an `object: string` parameter | 19 |
+| object name is an `object: string` parameter | 17 |
 | object name is some other run-time expression | 62 |
 
 ### Subtractions the census could NOT defend — enforced
@@ -297,13 +297,13 @@ holds still. They are required to be HERE and to say WHEN they were true;
 their values are not compared. The reasoning, and the measurement behind it,
 are in `scripts/check-tenant-audit-census.mjs`.
 
-Measured on 2026-10-09 at `5551f8d8d`.
+Measured on 2026-10-10 at `b88b35678`.
 
 | corpus scale (not enforced) | count |
 | :--- | ---: |
-| tracked non-test sources scanned | 625 |
+| tracked non-test sources scanned | 631 |
 | engine-shaped types recognised | 72 |
-| declared objects in the registry | 116 |
+| declared objects in the registry | 117 |
 | same-named calls subtracted as non-engine | 162 |
 
 {/* END GENERATED: tenant-audit-census */}

docs/audits/2026-08-tenant-audit-write-call-sites.counts.md

@@ -33,17 +33,17 @@ silent, and `node scripts/tenant-audit-census.mjs --write` is the resolution.
 
 | Measure | Value |
 |---|---:|
-| Write call sites | 241 |
+| Write call sites | 239 |
 | Object name statically decidable | 160 |
-| Object name chosen at run time | 81 |
+| Object name chosen at run time | 79 |
 | Against a tenancy-enabled object | 159 |
 | Against an object declaring tenancy off | 1 |
-| Threading a tenant context | 180 |
+| Threading a tenant context | 178 |
 | Provably carrying none | 8 |
 | …and decidably tenancy-enabled | 2 |
 | Options argument unreadable | 53 |
 | …and decidably tenancy-enabled | 32 |
-| Threading a decidably elevated context | 128 |
+| Threading a decidably elevated context | 126 |
 | Threading a decidably non-elevated context | 0 |
 | Threading a context of undecidable elevation | 105 |
 
@@ -90,13 +90,13 @@ holds still. They are required to be HERE and to say WHEN they were true;
 their values are not compared. The reasoning, and the measurement behind it,
 are in `scripts/check-tenant-audit-census.mjs`.
 
-Measured on 2026-10-09 at `5551f8d8d`.
+Measured on 2026-10-10 at `b88b35678`.
 
 | corpus scale (not enforced) | count |
 | :--- | ---: |
-| tracked non-test sources scanned | 625 |
+| tracked non-test sources scanned | 631 |
 | engine-shaped types recognised | 72 |
-| declared objects in the registry | 116 |
+| declared objects in the registry | 117 |
 | same-named calls subtracted as non-engine | 162 |
 
 ## Every site
@@ -165,8 +165,6 @@ Measured on 2026-10-09 at `5551f8d8d`.
 | `packages/plugins/plugin-security/src/bootstrap-declared-positions.ts` | `update` | `object` | undecidable | context, elevation undecidable | 1 |
 | `packages/plugins/plugin-security/src/bootstrap-platform-admin.ts` | `insert` | `object` | undecidable | elevated | 1 |
 | `packages/plugins/plugin-security/src/bootstrap-platform-admin.ts` | `update` | `object` | undecidable | elevated | 1 |
-| `packages/plugins/plugin-security/src/bootstrap-system-capabilities.ts` | `insert` | `object` | undecidable | elevated | 1 |
-| `packages/plugins/plugin-security/src/bootstrap-system-capabilities.ts` | `update` | `object` | undecidable | elevated | 1 |
 | `packages/plugins/plugin-security/src/claim-seed-ownership.ts` | `update` | `schema.name` | undecidable | elevated | 1 |
 | `packages/plugins/plugin-security/src/cleanup-package-permissions.ts` | `delete` | `object` | undecidable | elevated | 1 |
 | `packages/plugins/plugin-security/src/grant-permission-set-name-backfill.ts` | `insert` | `DATA_MIGRATION_FLAG_OBJECT` | undecidable | elevated | 1 |

packages/drivers/driver-sql/src/sql-driver-declared-index-organization-respelling.test.ts

@@ -379,7 +379,6 @@ describe('#8323 — declared unique indexes on the platform’s tenant-scoped ob
       // The NULL-safe key part is what makes this hold: a bare
       // `(organization_id, name)` composite would be NULL-distinct under SQL,
       // so every platform-seeded capability could be duplicated at will.
-      // `bootstrapSystemCapabilities` upserts by name and depends on it.
       const d = makeDriver();
       await d.initObjects(FIXED_APP as any);
 

packages/lint/src/validate-capability-references.ts

@@ -19,8 +19,7 @@
  *      (`stack.capabilities`) — the explicit, package-provenanced declaration
  *      (ADR-0066 D1), materialized at boot by `bootstrapDeclaredCapabilities`,
  *   3. every capability a permission set in this stack GRANTS via
- *      `systemPermissions` (granting a capability also declares it — mirrors
- *      the runtime `bootstrapSystemCapabilities` derived-defaults rule), and
+ *      `systemPermissions` (granting a capability also declares it), and
  *   4. any `sys_capability` row shipped as seed data.
  *
  * WARNING, not error: a single package's lint cannot see capabilities declared