feat(plugin-security,cli,spec)!: retire sys_user_permission_set.permission_set_id; the grant key is unique per organization; the boot grant-name backfill is deleted (C7b S3)

.changeset/23430-grant-permission-set-id-retired.md

@@ -0,0 +1,36 @@
+---
+'@objectstack/plugin-security': minor
+'@objectstack/cli': minor
+'@objectstack/spec': minor
+---
+
+feat(plugin-security,cli)!: `sys_user_permission_set.permission_set_id` is retired, the boot-time grant-name backfill is deleted, and a grant is unique per user, set and organization (ADR-0131 D4/D10)
+
+Clause-②: yes (narrowing)
+
+<!-- adr-0087: registered ups-permission-set-id-column-retired -->
+
+**BREAKING**, shipped as `minor` under the repo's launch-window convention for breaking changes.
+
+A permission-set grant names its set by `permission_set`, its one reference (ADR-0131 D4). The legacy id column is no longer declared, and the grant's uniqueness now keys the name.
+
+FROM → TO:
+
+- `sys_user_permission_set.permission_set_id` → `permission_set`, the machine name of the set the grant holds. A seed row or data-door write that still carries `permission_set_id` is refused with `400 INVALID_FIELD`. Fix: delete the key and name the set, `{ user_id, permission_set: '<set name>', organization_id }`.
+- The unique index (`user_id`, `permission_set_id`, `organization_id`) and the (`permission_set_id`) index → one unique index on (`user_id`, `permission_set`, `organization_id`), declared `unique: 'organization'`: its organization key part is NULL-safe (ADR-0120 D3), so it refuses a second grant of one set to one user in one organization AND a second platform-wide grant (organization NULL), for every writer and every write path — batches, multi-row updates, concurrent writes and raw SQL included. The data doors answer `409 UNIQUE_VIOLATION` (the engine throws `DuplicateRecordError`, `DUPLICATE_RECORD`). Fix: keep the grant that exists; to change it, update that row.
+- The boot-time grant-name backfill (`runOneTimeGrantPermissionSetNameBackfill`, the `sys_migration` entry it recorded at `kernel:bootstrapped`) → `os migrate organization-ownership --apply`. Its verified rewrite names every grant from the physical `permission_set_id` column by raw SQL, verifies each name against the security catalog, and its `column-drops` step then drops the column through the schema-drift ceremony (schema sync is additive, so an undeclared column stays until it is dropped). Fix: run the ceremony on every database upgraded from a release before the `permission_set` column existed, then restart the server: the boot's organization-administrator sweep revokes, by name, a newly named grant whose pair no longer qualifies, and a server left running across `--apply` serves it until then.
+
+On a 17.x database every grant names nothing until `--apply` names it, so between the first v18 boot and `--apply` no grant confers anything, the platform administrator's included.
+
+What else changes:
+
+- `os migrate organization-ownership --plan` reports a `grants` block on `sys_user_permission_set`, keyed like the new index (a NULL organization keyed with NULL):
+  - `duplicates`: groups of named grants holding one set for one user in one organization. `--apply`'s `column-drops` step does not drop `permission_set_id` while one group remains.
+  - `rewriteCollisions`: legacy grants whose derived name their user already holds in the same organization. `--apply`'s rewrite names none of them and blocks, naming both ids.
+  - On a database without the `permission_set` column it counts zero and names the remedy (boot this release once), instead of refusing the plan.
+
+  The ceremony deletes no grant: remove the one you do not keep, then re-run.
+- The organization-administrator reconcile and its boot sweep write no grant for a pair holding an unnamed grant in that organization: the ceremony's rewrite names that grant, and a named grant beside it would hold the key the rename needs.
+- `--apply` drops the two retired indexes before the column, in a separate earlier schema-drift apply: MySQL refuses to drop a column a key still uses.
+- The organization-administrator reconcile and its boot sweep, the platform-admin bootstrap's unnamed-grant leg (Leg C) and the catalog reference report read grants by name only. A legacy grant that names nothing confers nothing, still withholds the platform-admin promotion while it is unscoped, and is reached by no revocation until the ceremony's rewrite names it; once named, the boot sweep revokes it where its pair no longer qualifies. The report's `UnnamedGrant` entries lose `permissionSetId`.
+- `GET /meta/object/sys_user_permission_set` no longer serves the hidden `permission_set_id` field.

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

@@ -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 227 sites are spelled that way**. A
+forwarding shim cannot, and **53 of the 225 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 | **227** |
+| 175 write call sites | quoted in the merged changeset | **225** |
 | 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 | **154 of 227** decidable, **73** undecidable |
-| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 122 decidably elevated, 0 decidably not, 97 undecidable |
+| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **154 of 225** decidable, **71** undecidable |
+| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 121 decidably elevated, 0 decidably not, 96 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
@@ -207,11 +207,11 @@ 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
-122 of 227 (54%) as decidably elevated, with 97 more whose elevation is a
+121 of 225 (54%) as decidably elevated, with 96 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 / 227`, and say what it is**: the sites whose options argument was
+⇒ **Cite `2 / 225`, 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,31 +223,31 @@ cannot read, and they are neither in nor out.
 
 | what | count |
 | :--- | ---: |
-| write call sites on the application surface | **227** |
+| write call sites on the application surface | **225** |
 | …whose object name is statically decidable | 154 |
-| …whose object name is chosen at run time | 73 |
+| …whose object name is chosen at run time | 71 |
 | …against an object with tenancy ENABLED | 153 |
 | …against an object that declares tenancy off | 1 |
-| threading a tenant context | 166 |
+| threading a tenant context | 164 |
 | 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 | 122 |
+| threading a decidably ELEVATED (`isSystem`) context | 121 |
 | threading a context that is decidably NOT elevated | 0 |
-| threading a context whose elevation is a run-time fact | 97 |
+| threading a context whose elevation is a run-time fact | 96 |
 
 | how the instrument reached the site | count |
 | :--- | ---: |
-| receiver carried a readable engine type | 189 |
+| receiver carried a readable engine type | 187 |
 | receiver erased, placed by the object NAME | 28 |
 | receiver erased, placed by an `object: string` PARAMETER | 5 |
 | receiver erased, placed by an `UNTYPED_RECEIVERS` row | 5 |
 
 | object name spelled inline | 104 |
 | object name spelled through a `const` | 50 |
 | object name is an `object: string` parameter | 7 |
-| object name is some other run-time expression | 66 |
+| object name is some other run-time expression | 64 |
 
 ### Subtractions the census could NOT defend — enforced
 
@@ -297,12 +297,12 @@ 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-14 at `f98ac45c5`.
+Measured on 2026-10-14 at `95898bba1`.
 
 | corpus scale (not enforced) | count |
 | :--- | ---: |
-| tracked non-test sources scanned | 650 |
-| engine-shaped types recognised | 76 |
+| tracked non-test sources scanned | 649 |
+| engine-shaped types recognised | 75 |
 | declared objects in the registry | 116 |
 | same-named calls subtracted as non-engine | 164 |
 

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

@@ -33,19 +33,19 @@ silent, and `node scripts/tenant-audit-census.mjs --write` is the resolution.
 
 | Measure | Value |
 |---|---:|
-| Write call sites | 227 |
+| Write call sites | 225 |
 | Object name statically decidable | 154 |
-| Object name chosen at run time | 73 |
+| Object name chosen at run time | 71 |
 | Against a tenancy-enabled object | 153 |
 | Against an object declaring tenancy off | 1 |
-| Threading a tenant context | 166 |
+| Threading a tenant context | 164 |
 | Provably carrying none | 8 |
 | …and decidably tenancy-enabled | 2 |
 | Options argument unreadable | 53 |
 | …and decidably tenancy-enabled | 32 |
-| Threading a decidably elevated context | 122 |
+| Threading a decidably elevated context | 121 |
 | Threading a decidably non-elevated context | 0 |
-| Threading a context of undecidable elevation | 97 |
+| Threading a context of undecidable elevation | 96 |
 
 ## Subtractions the census could NOT defend — enforced
 
@@ -90,12 +90,12 @@ 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-14 at `f98ac45c5`.
+Measured on 2026-10-14 at `95898bba1`.
 
 | corpus scale (not enforced) | count |
 | :--- | ---: |
-| tracked non-test sources scanned | 650 |
-| engine-shaped types recognised | 76 |
+| tracked non-test sources scanned | 649 |
+| engine-shaped types recognised | 75 |
 | declared objects in the registry | 116 |
 | same-named calls subtracted as non-engine | 164 |
 
@@ -160,8 +160,6 @@ Measured on 2026-10-14 at `f98ac45c5`.
 | `packages/plugins/plugin-security/src/bootstrap-platform-admin.ts` | `insert` | `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/plugins/plugin-security/src/grant-permission-set-name-backfill.ts` | `update` | `GRANT_OBJECT` | undecidable | context, elevation undecidable | 1 |
 | `packages/plugins/plugin-security/src/invitation-placement.ts` | `insert` | `sys_user_position` | enabled | elevated | 1 |
 | `packages/plugins/plugin-security/src/suggested-audience-bindings.ts` | `delete` | `sys_audience_binding_suggestion` | enabled | context, elevation undecidable | 1 |
 | `packages/plugins/plugin-security/src/suggested-audience-bindings.ts` | `insert` | `sys_audience_binding_suggestion` | enabled | context, elevation undecidable | 1 |

packages/cli/src/commands/migrate/organization-ownership.ts

@@ -37,7 +37,6 @@ import {
   TemplateChoiceRefusal,
   type ApplyExecutor,
   type CeremonyLedgerPort,
-  type ColumnDropOutcome,
   type OrganizationOwnershipApplyReport,
 } from '../../utils/organization-ownership-apply.js';
 
@@ -482,43 +481,29 @@ export default class MigrateOrganizationOwnership extends Command {
           },
         },
         columnDrops: {
-          drop: async (tables) => {
-            const drift = await liveStack.detectManagedDrift();
-            const wanted = new Set(tables);
-            const entries = drift.filter((d) => {
-              const op = (d as { op?: { type?: string; column?: string } }).op;
-              return op?.type === 'drop_column' && op.column === 'organization_id' && wanted.has(String(d.table));
-            });
-            const outcomes: ColumnDropOutcome[] = [];
-            const proposed = new Set(entries.map((d) => String(d.table)));
+          drop: async (columns) => {
             // The tables this booted composition declares, keyed as the driver
             // keys its managed set. A table outside it can never be proposed,
             // whatever a release declares: `not-declared`, and `not-proposed`
             // only for a declared one. A rotation shard is judged by its base.
             const { StorageNameMapping } = await import('@objectstack/spec/system');
             const { rotationBaseOf } = await import('../../utils/unmanaged-tables.js');
+            const { buildIndexName } = await import('@objectstack/driver-sql');
+            const { dropColumnsThroughDrift } = await import('../../utils/organization-ownership-column-drops.js');
             const declared = new Set(
               (liveStack.allObjects() as Array<{ name?: unknown } | null>)
                 .map((o) => o?.name)
                 .filter((name): name is string => typeof name === 'string' && name.length > 0)
                 .map((name) => StorageNameMapping.resolveTableName({ name })),
             );
-            for (const table of tables) {
-              if (!proposed.has(table)) {
-                outcomes.push(
-                  declared.has(rotationBaseOf(table) ?? table)
-                    ? { table, outcome: 'not-proposed', detail: 'the drift differ proposed no drop for it' }
-                    : { table, outcome: 'not-declared' },
-                );
-              }
-            }
-            if (entries.length === 0) return outcomes;
-            const { applied, skipped } = await liveStack.applyMigrationEntries(entries, { allowDestructive: true });
-            for (const d of applied) outcomes.push({ table: String(d.table), outcome: 'dropped' });
-            for (const d of skipped) {
-              outcomes.push({ table: String(d.table), outcome: 'failed', detail: String((d as { message?: unknown }).message ?? 'skipped by the schema-drift ceremony') });
-            }
-            return outcomes;
+            return dropColumnsThroughDrift(
+              {
+                drift: liveStack,
+                isDeclared: (table) => declared.has(rotationBaseOf(table) ?? table),
+                indexName: (table, indexColumns, unique) => buildIndexName(table, [...indexColumns], unique),
+              },
+              columns,
+            );
           },
         },
         ledger,

packages/cli/src/utils/organization-ownership-apply.served-catalog.integration.test.ts

@@ -129,7 +129,7 @@ async function ceremony(posture: string, db: Database.Database): Promise<Organiz
     catalog,
     door: { save: async (type, name) => { throw new Error(`the door was asked to save ${type} ${name}`); } },
     templates: { find: async () => undefined },
-    columnDrops: { drop: async (tables) => tables.map((table) => ({ table, outcome: 'not-proposed' as const })) },
+    columnDrops: { drop: async (columns) => columns.map((c) => ({ table: c.table, column: c.column, outcome: 'not-proposed' as const })) },
     ledger: { read: async () => checkpoint, write: async (cp) => { checkpoint = cp; } },
   });
 }