@happyvertical/smrt-users 0.51.39 → 0.53.3

package/README.md

@@ -113,6 +113,8 @@ Catalog sync is additive and fail-closed:
 - it updates `name`, `description`, and `category` by slug
 - it does not auto-grant permissions to roles
 - it does not delete stale permissions in v1
+- it commits created/updated rows in small batched transactions; when calling
+  it inside your own transaction, pass that transaction's database handle
 
 ### App-defined permissions in `smrt.config.ts`
 
@@ -918,3 +920,43 @@ for authentication, deduplication, and status semantics.
 ## License
 
 MIT
+
+### Upgrade duplicate role grants (#3329)
+
+`RolePermission` now has a unique natural key `(role_id, permission_id)`.
+Concurrent seeders converge through core's conflict-tolerant writes, preserving
+one grant ID per pair. Permissions already use `(slug, context)` and system
+roles use the tenant-aware natural key. System-role bootstrap holds a
+PostgreSQL transaction advisory lock across its read/create sequence so two
+seeders also return the same global (`tenant_id = NULL`) role IDs. The concurrent cold-seed test
+checks all three catalogs. Seeding still uses bounded batches and is additive
+unless `prune: true`; concurrent passes must use the same catalog/matrix.
+
+Existing deployments need a maintenance window **before ordinary schema
+migration**: adding the new unique index directly fails if duplicates exist.
+Back up the database, stop every application writer and bootstrap/seed process,
+and run the following once with the new package from an operator process:
+
+```typescript
+import { getDatabase } from '@happyvertical/sql';
+import { deduplicateRolePermissions } from '@happyvertical/smrt-users';
+
+const db = await getDatabase(databaseConfig);
+console.log(await deduplicateRolePermissions(db, { dryRun: true }));
+console.log(await deduplicateRolePermissions(db, {
+  maintenanceConfirmed: true,
+}));
+```
+
+The migration keeps the earliest `created_at` per pair (lowest `id` breaks ties;
+null timestamps sort last), deletes only extra grants, and creates
+`role_permissions_role_id_permission_id_idx` in the same transaction. Other
+pairs and surviving grant data remain intact. Failure rolls the transaction
+back; after resolving its cause, rerun the migration. Dry runs change nothing.
+The helper requires transaction support and supports SQLite, DuckDB and
+PostgreSQL; PostgreSQL locks the grant table while repairing it. Writer shutdown
+is still required because older application versions cannot seed safely
+against the new constraint. Apply the remaining application schema migrations,
+run `smrt doctor --db` / `db:status --parity`, deploy the new version to every
+writer, then resume traffic. Do not roll back application writers without also
+restoring the pre-upgrade schema/database backup.

package/agents/permissions.md

@@ -93,7 +93,11 @@ membership or tenant DENY to attenuate inherited role authority.
   seedSystemRoles({ seedPermissions: true }) maps owner/admin to all catalog
   permissions, member to ordinary-resource read/create, viewer to read. Member
   create excludes identity/RBAC/security resources and their joins/overrides.
-  Seeding is additive/idempotent; removal requires prune: true.
+  Seeding is additive/idempotent; removal requires prune: true. Catalog sync
+  and grants plan from one read, then commit in `SEEDING_BATCH_SIZE` batches
+  (#3323): never one durable commit per row (an fsync each on local SQLite),
+  and never one catalog-wide transaction (`@happyvertical/sql` transaction
+  scopes cost superlinearly per statement). Pass a caller transaction's handle.
 - When a package adds built-in self-personalization permissions after role
   creation, explicitly call seedDefaultRolePersonalizationPermissions(). It
   upgrades owner/admin/member/viewer idempotently and never grants custom roles.
@@ -184,3 +188,10 @@ access once principal context is set. Child-tenant sessions receive resolved
 inherited permissions automatically, but RLS row filtering remains bound to the
 session tenant: a root session's app-level guard authorization does not itself
 permit child rows through RLS. Preserve this distinction.
+
+RolePermission's natural key is `(role_id, permission_id)` (#3329); repeated or
+concurrent inserts converge without changing the grant ID. Existing deployments
+must run `deduplicateRolePermissions()` with stopped writers before ordinary
+schema migration; see README's "Upgrade duplicate role grants". It keeps the
+oldest row and installs uniqueness atomically. Runtime seeding never performs
+this schema repair.