@happyvertical/smrt-users 0.51.36 → 0.51.39

package/AGENTS.md

@@ -12,6 +12,7 @@ are not prerequisites for unrelated user-package work.
 | `src/services/PermissionResolver.ts` | permission precedence, inherited memberships, guards, RLS, role seeding | [agents/permissions.md](agents/permissions.md) |
 | `src/services/OidcLoginService.ts`, collections and OIDC handlers | identity reconciliation, transaction boundaries, migration readiness | [agents/oidc-provisioning.md](agents/oidc-provisioning.md) |
 | `src/services/MobileAuthService.ts` | mobile handshake, bearer sessions, bootstrap extension boundary | [agents/mobile-auth.md](agents/mobile-auth.md) |
+| `src/services/TerminalAuthService.ts`, `src/collections/CliAuthApproveLimitCollection.ts` | terminal approval concurrency, shared attempt budget, retry-safe database fixtures | [agents/terminal-auth-testing.md](agents/terminal-auth-testing.md) |
 | `src/retention.ts` | expired session/token/CLI-auth reaping and retention sweep wiring | [agents/retention.md](agents/retention.md) |
 
 ## Models and authority

package/agents/mobile-auth.md

@@ -0,0 +1,45 @@
+# Mobile authentication
+
+Read for `src/services/MobileAuthService.ts` and `/sveltekit` mobile handlers.
+
+`createMobileAuthHandlers(options)` (from `/sveltekit`) returns the mountable
+server side of the KMP mobile contract: `authStart` (`POST auth/start`,
+server-brokered PKCE via `OidcLoginService`), `authComplete`
+(`POST auth/complete`, code + echoed `state`/`codeVerifier` → bearer
+session), `session.GET`/`session.DELETE` (bootstrap/logout), and
+`guard`/`withSession` — the bearer middleware for app-owned mobile routes.
+Core logic lives in `MobileAuthService` (framework-agnostic; exported from
+the package root).
+
+- **Bearer = session id** (same convention as `TerminalAuthService`); 401
+  bodies are `{ error, code }` and drive the mobile client's re-auth flow.
+- **Stateless handshake**: the OAuth `state` is an HMAC-signed token
+  (secret: `stateSecret` ?? provider `clientSecret`) carrying
+  nonce/provider/createdAt — full ID-token nonce verification with no
+  server-side pending state. The `codeVerifier` never enters a URL: it is
+  client-held per the frozen contract.
+- **Wire DTOs** come from `@happyvertical/smrt-mobile-contract`
+  (`MobileAuthStartRequest` etc.) — one owning package for the Kotlin,
+  Swift, and TypeScript shapes (compile-checked descriptors + parity test).
+- **Tenant options** honor `Role.inheritsToDescendants` (#1867): direct
+  ACTIVE memberships plus descendants of flagged memberships (nearest
+  flagged ancestor labels the option; any direct row pins; inactive direct
+  rows exclude). Session binding defaults to the first DIRECT tenant —
+  override with `resolveTenantId`.
+- **Hooks**: `resolveUser` (invite-gating; default provisions via
+  `getOrCreateFromOidc`), `resolveTenantId`, `buildExtras` (bootstrap
+  `extras`; model JSON must use `toPublicJSON({ permissions })` — #1822).
+  `buildExtras` is the only app-domain bootstrap extension point. Never emit
+  app fields such as `dashboard` at the response top level: they are outside
+  `MobileSessionBootstrap` and the Kotlin decoder ignores them.
+- **Guard** wraps `withSessionPermissionContext`, so
+  `assertOperationPermission`, tenancy context, and Postgres RLS all see the
+  bearer caller; `OperationPermissionError` maps to 403 with a
+  machine-readable `reason`.
+- **Uploads**: `resolveMobileUploadDedupKey` + the documented contract in
+  `docs/content/architecture/mobile-upload-contract.md` (`clientCaptureId`
+  field, `Idempotency-Key` header fallback); domain ingestion stays
+  app-side. Framework-model writes ride `sync/apply`, not this path.
+- Configure `redirectUris` in production — RFC 8252 scheme rules always
+  apply, but the allow list is the defense against redirecting authorization
+  responses to attacker-controlled URIs.

package/agents/oidc-provisioning.md

@@ -0,0 +1,97 @@
+# OIDC provisioning
+
+Read for changes to `src/collections/UserCollection.ts`, `src/services/OidcLoginService.ts`,
+OIDC handlers, or identity migrations. The canonical scenario matrix is
+`packages/profiles/src/testing/oidcProvisioningDecisionMatrix.ts`.
+
+- **OIDC `email_verified` is enforced.** `UserCollection.getOrCreateFromOidc`
+  refuses to provision a user when the IdP explicitly returns
+  `email_verified: false` (opt out with `{ allowUnverifiedEmail: true }`). An
+  absent claim makes no assertion and is not enforced.
+- **RFC 9207 response issuer is exact.** OIDC callbacks validate a supplied
+  `iss` against discovered metadata with exact string comparison before trusting
+  a code or error. If metadata advertises issuer-response support, `iss` is
+  required.
+- **Verified-email Profile reuse is fail-closed.** The typed canonical scenarios
+  live in
+  `packages/profiles/src/testing/oidcProvisioningDecisionMatrix.ts`; both
+  package suites execute that matrix and public docs reference it rather than
+  maintaining another behavioral table. Default provisioning reuses only one
+  unowned, global `Person`. Tenant-scoped, non-Person, duplicate-email,
+  and already-owned matches fail before User/session creation. An existing
+  issuer/subject link without a User must still be the unique global Person for
+  the current verified claim email; once owned, the stable issuer/subject link
+  reuses its canonical Person and owner.
+  Issuer and subject are opaque, case-sensitive identifiers; preserve their
+  exact value and use trim only to reject blank claims.
+- **`resolveProfile` is the application reconciliation boundary.** The
+  SvelteKit handlers, `OidcLoginService`, and `getOrCreateFromOidc` accept the
+  same hook inside the provisioning transaction. The service/handler path
+  supplies protocol-validated claims; direct collection callers must validate
+  and trust their claim source before calling `getOrCreateFromOidc`.
+  Token/userinfo merging keeps `email` and `email_verified` paired to the same
+  claim source; verification is never borrowed across sources.
+  Resolver reads/writes use the supplied `db`, and the hook must be idempotent
+  because a concurrent unique-key conflict can retry it. `undefined` chooses
+  the secure default and `null` rejects, including exact issuer/subject reuse.
+  For a new identity, a supplied Profile is still validated as the unique,
+  unowned global Person for the verified email. For an exact existing identity,
+  it must be the already-linked Profile and cannot rebind identity authority;
+  stable-link owner and canonical-Person checks still apply. The hook receives a
+  separate frozen claims snapshot; internal retry and persistence state is not
+  exposed for mutation.
+- **Owned first binding requires `authorizeProfileOwner`.** An invitation or
+  approval workflow may explicitly return both its pre-provisioned canonical
+  global `Person` and existing approved `User` from this transaction-bound
+  hook. `undefined` keeps the secure `profile_owned` default and `null`
+  rejects. SMRT treats only the selected IDs as input, reloads them in the
+  provisioning transaction, and requires `email_verified === true`, the unique
+  canonical global Person for the normalized claim email, exactly one owner,
+  that owner as the selected User, and the same normalized User email. The
+  hook runs before identity/User/session creation and may be retried, so use
+  only its supplied `db` and `users` handles and keep application authorization
+  idempotent. Never authorize from email matching alone. Existing exact
+  identities cannot be rebound; when `resolveProfile` is also present both
+  hooks must select the same Profile.
+- **OIDC first login is atomic.** The Profile, `OidcIdentity`, and User are one
+  transaction. The database arbiters are `OidcIdentity.identityKey`,
+  private `oidc_profile_email_reservations.email_key`, `User.emailKey`, and the
+  unique `User.profileId`; local callbacks acquire exact issuer/subject and normalized
+  email locks in deterministic order so changed email claims also serialize.
+  SQLite and DuckDB callbacks additionally serialize every root-handle statement
+  the coordinator owns per database URL — `_smrt_backfills` initialization, the
+  transaction, and the post-commit rebind — because one adapter multiplexes a
+  single native connection and cannot safely overlap unrelated root
+  transactions. Never overlap two statements on one such handle, inside a
+  transaction or not: rebind and owner/email candidate reads are sequential,
+  never `Promise.all`. Owner-authorized DuckDB callbacks use that same
+  root-handle serialization;
+  PostgreSQL deadlock and serialization errors use a bounded transaction retry.
+  Newly provisioned Profiles use non-semantic per-profile slugs so equal IdP
+  display names cannot trigger a natural-key upsert;
+  run
+  `smrt db:status`, `smrt db:migrate`, then `smrt db:status` before deployment.
+  Stop or upgrade old writers first. Before migration, group
+  non-null `users.profile_id` values, then reconcile duplicates. After
+  migration, run public `backfillProfileEmailKeys(db)`,
+  `backfillUserEmailKeys(db)`, then `backfillLegacyUserProfiles(db)` from one
+  deploy process. The first two use the shared
+  TypeScript `normalizeIdentityEmail()` implementation transactionally and are
+  idempotent; the User backfill fails before writes if normalized duplicates
+  remain. The legacy Profile backfill transactionally creates canonical global
+  Persons for null/blank User links without creating OIDC identities or
+  inferring ownership; reconcile any same-email Profile or reservation before
+  retrying. Its marker records a completed pass but never skips newly imported
+  legacy Users on a later run. Every OIDC path requires the Profile email-key
+  readiness marker; creating a User or checking User email uniqueness
+  additionally requires the User marker. A stable issuer/subject with an
+  existing owning User skips only the User email-key lookup and marker. Full
+  scans remain in the explicit deploy step; guarded runtime paths use indexed
+  keys and validate only returned candidates. Multiple null links remain valid.
+  Legacy race keys backfill only after canonical validation. Pass a root
+  database on adapters such as DuckDB that cannot create nested savepoints.
+  Root adapters must expose `beginTransaction`; transaction-only handles are
+  ambiguous and fail closed before provisioning writes. Caller-owned
+  transactions never run `_smrt_backfills` DDL and require that table to
+  already exist; use the root database when initialization or recovery is
+  needed.

package/agents/permissions.md

@@ -0,0 +1,186 @@
+# Permissions and tenant inheritance
+
+Read for `src/services/PermissionResolver.ts`, operation guards, role seeding,
+RLS, and tenant-hierarchy changes. Integration examples live in README's
+manifest-derived permission catalog and PostgreSQL RLS sections.
+
+## Membership selection
+
+1. A direct target-tenant membership pins resolution: active resolves normally;
+   pending/suspended returns empty. Never union direct and ancestor roles.
+2. Otherwise walk hierarchyPath nearest-first for the nearest active ancestor
+   membership whose role has inheritsToDescendants. Skip inactive/unflagged
+   ancestors; they neither grant nor block. No qualifying ancestor means empty.
+3. Run later layers against the target tenant. Only target-tenant groups apply;
+   membership overrides travel with the chosen ancestor membership.
+   inheritedFromTenantId reports that ancestor, null for direct resolution.
+
+Verify hierarchyPath link-by-link against loaded parentTenantId rows before
+trusting it: excess depth, self-reference, duplicates or inconsistent paths
+fail closed. Bound traversal by MAX_TENANT_HIERARCHY_DEPTH. Tenant status is not
+consulted, matching direct resolution. Long-lived user/tenant caches must
+invalidate ancestor membership changes and inheritsToDescendants flips;
+request-scoped caches do not survive those requests.
+
+`loadSessionContext().tenantAuthorization` is authoritative for required-tenant
+consumers; membership null can mean inherited authority.
+
+4. If no membership resolved at all, apply the opt-in ancestor-read policy
+   (smrt#2939): the user's ACTIVE memberships on VERIFIED DESCENDANTS of the
+   target, whose role slug is declared in `permissions.ancestorRead.roles` and
+   within `maxDepth` hops, contribute `<collection>.read` for declared
+   collections, intersected with BOTH that role's own catalog grants (so a
+   descendant-side tenant GRANT, group role, or membership GRANT cannot widen
+   it) AND the principal's effective permissions in that descendant (so its
+   DENY cascade and membership DENY apply). Only a SYSTEM
+   role (`tenantId` null, `isSystem: true`) matches a declared slug: slugs are
+   not unique across a hierarchy, so a tenant-scoped custom role of the same
+   name must not opt its tenant in. Off by default;
+   read-only; never lateral; never reached when a direct or inherited
+   membership already decided. The target tenant's DENY still subtracts.
+   `ancestorReadFromTenantIds` reports the contributing descendants. The grant
+   carries no membership, so `membershipId`/`tenantAuthorization.membershipId`
+   stay null and a consumer requiring a non-empty membership still refuses.
+
+## Permission precedence
+
+Apply these layers in order, later layers overriding earlier ones:
+
+1. Ancestor TenantPermissionOverride cascade (GRANT adds, DENY removes).
+2. Selected membership role permissions.
+3. Target-tenant group-role permissions.
+4. Tenant cascade's net DENY removes role/group grants.
+5. Membership GRANT may re-add a tenant-denied slug.
+6. Membership DENY removes last and always wins.
+
+The tenant block is the cascade's net result, not the union of historical DENYs:
+a child's more-specific GRANT can override a parent DENY. Use a direct child
+membership or tenant DENY to attenuate inherited role authority.
+`getGroupIdsForTenant(userId, tenantId)` is required; getGroupIds is cross-tenant.
+
+## Hierarchies and seeding
+
+- `Tenant.save()` derives hierarchyPath/hierarchyLevel from the REAL
+  parentTenantId chain on every save (never from an ancestor's stored path),
+  refuses missing parents, cycles and over-depth before writing, and
+  re-materializes descendants by raw column update (so STI subclass columns
+  are never clobbered). createChild/moveToParent/makeRoot are thin wrappers.
+  `materializeTenantHierarchy(db, { dryRun })` / `smrt
+  db:materialize-tenant-hierarchy` backfills legacy rows: idempotent, one
+  transaction, refuses a broken chain without writing (#3036). A NEW or
+  CHANGED parent link is authority-bearing, so `Tenant.save()` first loads the
+  parent through TenantCollection (the caller's tenancy scope) and refuses an
+  invisible one on every path — helpers, `create({ parentTenantId })`, or a
+  plain assignment + save; system context bypasses as usual, and an unchanged
+  link is never re-checked. getTree(rootId?)
+  returns UI structure. Maximum depth is 10.
+- Tenant override cascade requires parent cascadePermissions and child
+  inheritPermissions. These flags do not gate the independent, per-role
+  inheritsToDescendants membership flow.
+- `permissions.ancestorRead` in the `users` package config declares upward,
+  read-only visibility: `{ roles, collections, maxDepth? }`. Both lists are
+  required and non-empty and `maxDepth >= 1`, else the policy is OFF — there is
+  no partially valid declaration. `isAncestorReadableSlug()` is the single place
+  the read-only bound is enforced; only a two-segment `<collection>.<action>`
+  slug whose action normalizes to `read` on a declared collection passes.
+  `PermissionResolver.create(options, { ancestorReadPolicy })` binds one
+  resolver; `null` forces it off. It grants the OPERATION at the ancestor, never
+  row visibility — sibling rows stay scoped by the tenancy interceptor and RLS.
+- seedSystemRoles({ inheritsToDescendants: ['owner', 'admin'] }) flags listed
+  slugs additively, never unflags omitted ones, and rejects unknown slugs.
+  Default seeds are exact-tenant.
+- RolePermissionCollection.seedRolePermissions() or
+  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.
+- 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.
+
+## Guards and RLS
+
+PermissionCatalogService derives collection.action slugs from manifests,
+including custom actions; list/get map to read. Guards derive a class's slug
+through the same resolution (explicit `collection`, manifest entry, then its
+STI base's), so an STI subtype resolves its STI base's collection
+(`Network extends Tenant` -> `tenants.update`) in every build, including a
+bundle decorated before its manifest loads (#3125). Hand-written mutations in form
+handlers, endpoints, CLI and jobs use assertOperationPermission(). It requires
+catalog presence then resolves permissions, throwing fail-closed by default.
+Use onDeny: 'return', checkOperationPermission or hasOperationPermission only
+when the caller handles a structured/boolean denial.
+
+Generated SvelteKit write routes (POST/PUT/PATCH/DELETE CRUD and mutating
+custom actions) enforce the same `collection.action` slug (custom actions use
+`collection.<method>`; actions hosted on a collection class use the item collection, which the catalog now emits) after authentication: the slug must be in the request's
+session permission snapshot (`locals.permissions`/`permissionSet`/
+`smrtPermissions` or `locals.tenantContext.permissions`), otherwise 403. Only
+`locals.tenantContext.superAdminBypass` skips it; `api.public: true` stays open.
+
+Resource-anchored guards receive the resource tenant ID. When it differs from
+the session tenant, omit the session membership so the resolver selects the
+appropriate authority; mismatched supplied membership/tenant fails closed.
+Inherited root-admin authority can then authorize descendant resources without
+application-side membership fan-out.
+
+Resolution cost must not scale with catalog size in objects (#3047): role →
+permission ids and ids → slugs are `list({ select })` projection reads (the
+collections' beforeList interceptors still run; no RolePermission/Permission
+is hydrated), so an owner mapped to the whole catalog costs two queries and
+no per-permission objects. Keep new resolver reads projections when only ids
+or slugs are needed, and do not add public collection methods for them — each
+becomes a custom-action slug in the manifest-derived catalog. The resolver's
+collections never inherit `defaultListLimit`/`maxListLimit` from the caller's
+options, and id-list reads chunk at `IN_LIST_CHUNK_SIZE` with an explicit
+limit: a truncated authorization read would narrow the result silently.
+`issue-3047-permission-resolution-cost-postgres.test.ts` pins the hydration
+budget and a golden equivalence matrix recorded on the hydrating resolver.
+
+The same rule holds for every framework-internal authorization read (#3048):
+collections that back a decision — the resolver's, the ResourceGrant exact-tuple
+read in `checkResourceOperationPermission()` (DENY wins only if every row is
+read), and TenantService's owned-tenant quota count — are created through
+`withoutListBounds()` (`src/services/authorization-read-options.ts`), which
+strips only the caller's list bounds. Use it for any new decision read;
+`issue-3048-authorization-list-bounds-postgres.test.ts` pins it.
+
+PermissionResolver runs every resolution inside smrt-tenancy's system context
+(#3036). Its reads are deliberately cross-tenant and framework-owned — the
+ancestor TenantPermissionOverride batch, ancestor memberships for
+inheritsToDescendants, descendant memberships for ancestor-read — and are keyed
+by the explicit (userId, tenantId); with those classes registered tenant-scoped
+(`autoFilter`) the consumer's filter otherwise threw TenantIsolationError or
+silently narrowed them. It returns slugs and ids only, never rows, and the
+caller's own reads stay filtered. Do not move a resolver read back under the
+ambient tenant; the Postgres regression suite
+`issue-3036-hierarchy-resolution-postgres.test.ts` pins this. Because nothing
+backstops those reads any more, the tenant-override cascade verifies its chain
+too: it uses hierarchyPath only when it agrees link-by-link with
+parentTenantId, otherwise walks the real parent links (so a forged path cannot
+cascade an unrelated tenant in, and a never-materialized row still gets its real
+ancestors' DENYs — and GRANTs), and throws TenantHierarchyError on a broken
+real chain: a per-request failure for that tenant's whole subtree, which
+`smrt db:materialize-tenant-hierarchy --dry-run` reports ahead of time (see
+README "Upgrading an existing fleet").
+`getTenantInheritanceChain()` returns Tenant rows, so it is NOT run in system
+context; it reports the same verified chain the cascade applies when the
+caller can read every ancestor. Otherwise it never reports PARENT_NOT_FOUND
+for a row the caller simply cannot see: an interceptor refusal surfaces as
+TenantIsolationError, and a silently filtered row (e.g. RLS) ends the chain at
+the nearest readable ancestor. Descendant path rewrites are raw column updates recorded through
+`bumpChangeFeed`; `updated_at` is intentionally not bumped (derived columns;
+every save recomputes them). They are not atomic with the moving row's save —
+an interrupted subtree fails closed until re-saved or backfilled.
+
+System context and super-admin bypass are honored. Pass
+allowSuperAdminBypass: false for money or separation-of-duties operations that
+require an explicit grant.
+
+generatePostgresPermissionSql/applyPostgresPermissionPolicies enforce generated
+RLS using smrt.permissions and smrt.tenant_id, installed with set_config by
+withSessionPermissionContext. This bounds REST, MCP and in-process database
+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.

package/agents/retention.md

@@ -0,0 +1,52 @@
+# smrt-users/credential retention
+
+Module semantics for `src/retention.ts` and the three `deleteExpired()` paths
+it drives. Package orientation, the permission model, and the security rules
+that apply before editing anything live in [../AGENTS.md](../AGENTS.md) — read
+that first.
+
+## Credential retention (#2375)
+
+`SessionCollection.deleteExpired()`,
+`UsersMagicLinkTokenCollection.deleteExpired()` and
+`UsersCliAuthRequestCollection.deleteExpired()` all existed, and all waited for
+an application to remember to call them. Expired credential rows are the worst
+kind of unbounded growth: worthless the moment they expire, and exactly the
+rows an attacker would like to still find in the table.
+
+`src/retention.ts` contributes the three to the framework retention sweep in
+`@happyvertical/smrt-core`, so `smrt db:prune` and a running jobs `TaskRunner`
+reap them.
+
+- **The entry point registers on import.** `src/index.ts` calls
+  `registerUserRetentionTasks()`, so any process that loaded this package
+  contributes the tasks — including `smrt db:prune`, which imports the package
+  optionally for exactly that reason. Registering is not scheduling: nothing is
+  deleted until something runs a sweep.
+- **Task names** are `users-sessions`, `users-magic-link-tokens`,
+  `users-cli-auth-requests` — prefixed with the package's short name because
+  the retention registry is one process-global namespace. Opt one out with
+  `runRetentionSweep(db, { tasks: { 'users-sessions': false } })` or
+  `smrt db:prune --skip users-sessions`; `unregisterUserRetentionTasks()`
+  removes all three.
+- **There is no retention window to configure.** An expired credential has
+  nothing worth retaining, so each task deletes only already-expired rows. An
+  application that keeps expired sessions for audit should opt the task out and
+  archive them itself.
+- **All three are a single counted DELETE**, not a hydrate-and-delete loop.
+  They now run unattended on a timer, and a per-row delete that throws part-way
+  leaves the rest of the expired rows un-reaped — the #1400 reasoning that
+  already applied to sessions, now applied to the other two. Counting first
+  also gives a usable figure where `rowCount` is not populated, and is what
+  makes `{ dryRun }` preview the same predicate rather than an estimate. The
+  count and the delete are not one transaction, so the figure is approximate
+  under concurrent writers.
+- **`expiresAt` is `@field({ indexed: true })`** on `Session`,
+  `UsersMagicLinkToken` and `UsersCliAuthRequest`: the prune predicate scans
+  that column on every pass.
+- **CLI bearer handoff is single-use.** An approved request becomes `consumed`
+  and clears its `sessionId` when one poller wins the exchange. The CLI
+  retention task deletes pending requests past their TTL, requests already
+  marked `expired` by lazy expiry, and consumed history; it retains approved
+  requests until exchange so a near-expiry approval cannot orphan its bearer
+  session.

package/agents/terminal-auth-testing.md

@@ -0,0 +1,32 @@
+# Terminal approval storage and regression matrix — #3076
+
+The failed-approval budget is shared storage, keyed by unique `user_id`.
+Each UPSERT candidate uses a unique private slug, so concurrent first inserts do
+not also collide on the inherited `(slug, context)` index. Existing rows require
+no migration: their slug is not used for lookup or authorization. The guarded
+UPSERT continues to reserve at most the configured count across service instances
+and processes. Unknown database failures propagate; they are not authentication
+successes or silently converted to a rate-limit response.
+
+Risk: high (terminal authentication and shared rate-limit authority). No public
+API, schema, session, tenant or approval contract changes.
+
+| Behavior / trigger | Positive | Negative / failure | Actor / executor | Runtime / edge | Validation |
+|---|---|---|---|---|---|
+| First reservation candidates | Distinct private insert slugs, one user budget | Third reservation denied at limit2; old code deterministically repeats slug | Same user, real SQL observed without replacing executor | SQLite; independent PostgreSQL service connections | users `test`, `test:postgres` |
+| Concurrent invalid approvals | Three attempts reach ordinary auth denial | Ten rejected, exactly seven typed rate limits; zero attacker sessions | One attacker/user+tenant, two instances, atomic UPSERT | SQLite and PostgreSQL18 | users `test`, `test:postgres` |
+| Concurrent approval/exchange | Eight approvals share one session, one of eight exchanges succeeds | Seven exchanges expired, consumed row clears session ID | UUID user/tenant, owning services | PostgreSQL; SQLite existing lifecycle coverage | users `test`, `test:postgres` |
+| Window/release | Successful attempts release their reservation | Old-window release cannot erase new-window failure; cleanup failure cannot reverse committed approval | Existing storage executor, no retry change | SQLite | users `test` |
+| Fixture retry/reseed | Two complete fixture cycles use the same emails | No duplicate email from prior committed fixture rows | Test-owned UUIDs, explicit cleanup through public database interface | PostgreSQL; intentionally independent connections outside rollback | users `test:postgres` |
+
+Before the repair, the candidate regression fails (one slug instead of two),
+and the second PostgreSQL fixture cycle fails its fixed-email insert. Actual CI
+also captured a PostgreSQL duplicate `(slug, context)` error during concurrent
+first reservations. The fixture cleans only its own IDs in FK order, then rolls
+back its isolated handle; it must not replace real connections with one shared
+transaction, weaken count assertions, or disable retries.
+
+Run documented users build, typecheck (including Svelte), test, test:postgres and
+verify:pack gates. PostgreSQL runs use the canonical disposable-database wrapper.
+Root knowledge checks follow all producers. No new dialect is introduced; the
+terminal auth regression suite declares SQLite and PostgreSQL coverage.