@jantstack/adonis-authz 2.4.0-alpha.9 → 2.5.0-alpha.2

package/README.md

@@ -35,7 +35,7 @@ node ace authz:catalog:sync
 
 > **Upgrading to 2.4.0-alpha.4 — how the commands are registered.** `@jantstack/adonis-authz/commands` is now a real ace loader (it exports `getMetaData()`/`getCommand()`, built with `ListLoader` over the nine command classes, next to the named class exports). Until alpha.4 it only re-exported the classes, so the line `configure` writes — `commands: [() => import('@jantstack/adonis-authz/commands')]` — made **the whole `node ace` crash** at boot (`TypeError: loaderInstance.getMetaData is not a function`). If you registered the commands by wrapping the barrel in a `ListLoader(Object.values(m))` (the only way it worked before alpha.4), remove the wrapper and register the module directly: `() => import('@jantstack/adonis-authz/commands')`, which is what `node ace configure` writes. The wrapper now fails with `TypeError: command.serialize is not a function`, because the module also exports the loader functions: `Object.values(m)` includes them and `ListLoader.getMetaData()` calls `serialize()` on each value. The module has no `default` export on purpose — ace calls `getMetaData()` on the module namespace and never unwraps `default` (same shape as `@adonisjs/core/commands`).
 
-For the OpenFGA driver, also install its SDK (optional peer): `npm i @openfga/sdk`. Everything that touches the SDK lives behind the **`@jantstack/adonis-authz/openfga` subpath** (`OpenFgaAuthorizationDriver`, `provisionOpenFgaStore`, `importAuthzFactsToOpenFga`, `openFgaAuthorizationModel`, `assertHolderTypes`); the main entry never imports it, so a database-only install boots without the SDK (the suite loads `index.ts` in a child process with `@openfga/sdk` blocked to prove it: *"index.ts (la entrada principal) carga con el SDK bloqueado"*). The published config imports the driver from that subpath *inside* the factory.
+For the OpenFGA driver, also install its SDK (optional peer): `npm i @openfga/sdk`. Everything that touches the SDK lives behind the **`@jantstack/adonis-authz/openfga` subpath** (`OpenFgaAuthorizationDriver`, `OpenFgaRelationsDriver`, `provisionOpenFgaStore`, `openFgaFactsModel`, `assertHolderTypes`); the main entry never imports it, so a database-only install boots without the SDK (the suite loads `index.ts` in a child process with `@openfga/sdk` blocked to prove it: *"index.ts (la entrada principal) carga con el SDK bloqueado"*). The published config imports the driver from that subpath *inside* the factory.
 
 ## Semantics (what every driver guarantees)
 
@@ -139,7 +139,7 @@ The package **does not impose a table**: the contract is the `ScopeOutbox` port
 
 The relay is resumable and never silent: the report says *which* changes were applied, not a count. A change that cannot be applied **defers what depends on it and lets the rest through**: the failure poisons the scopes that change names, every later change naming one of them is reported as `deferred` and not attempted (transitively), and everything else is applied. That is what keeps the tree order — `attached(P, org)` before `attached(C, P)`, a `moved` before the `detached` of the same node — without letting one tenant freeze the queue for all of them. Until 2.0 the pass stopped at the first failure, and a single change that can never be applied (its parent scope was deleted before the pass) then blocked every later change of every tenant, indefinitely. `sqlScopeOutbox` also **parks** an entry after `maxAttempts` failures (default 5): it stops being retried, it is reported in `dead` on every pass, and the command exits non-zero while any exists — a parked entry is a permanent divergence of the backend's tree, not a resolved incident. The command exits non-zero on any failure too, so a supervisor notices. Applying a queued `detached` runs `purgeScope` and only then removes the edge, and it emits the `scope_purged` audit event at that point, carrying the actor that ordered it.
 
-**"Was mine applied?" — the receipt and `only` (2.4.0-alpha.5).** `scopes.attached/moved/detached` return a receipt, **`{ queued: [id] }`** — the outbox ids of what they just enqueued (plural on purpose: a `detached` whose row is already gone enqueues one entry per spelling of the uuid). Empty means there is nothing to relay: without an outbox the change was applied inline; with a third-party `ScopeOutbox` whose `enqueue` still returns `void` there is no id, and then there is no `only` either. Hand the receipt to the relay on the interactive path, right after your commit: **`await authorization.relayScopeChanges({ only: queued })`**. That is the fix for the cost a consumer measured: with 500 entries of another tenant ahead in the queue, the inline pass cost **4,507 ms and 2,004 OpenFGA calls** to land one change; with `only` it costs **19 ms and 4 calls**, because the filter lives in the port (`pending(limit, after, { ids })` — the primary key) and the pass never reads the other 500 rows (the suite spies on `pending` to pin that; a port implementation that ignores the filter is 500 `E_AUTHZ_CONFIG` before anything is applied, never a silent drain of the backlog inside your request). **The order by scope key is not relaxed — deferred, never out of order.** Before applying each requested entry the relay probes the *whole* queue (`earlierPending`: one existence query against the `(applied_at, id)` index, 0.69 ms measured; a port without it is paged through `pending()`): if an earlier unapplied entry names one of the same scopes and was not requested, yours is reported `deferred` with `depends-on:<id>` and not applied. Why, measured: with `#1 moved(unit → orgB)` pending and `only: [#2 attached(child, unit)]`, a filter without the probe wrote `child → unit` while the store still said `unit → orgA`, and the editor of the *old* organization authorised over the child (`authorize(A@orgA, docs:read, child) = true`, report all green). One level is enough — the last link of any chain of pending dependencies shares a scope with yours by definition of the key contamination — so the probe costs one query, not the queue. The report is **per entry**: `entries` names every entry the pass looked at, `applied` / `deferred` (reason `depends-on:<id>` or `parked:<id>`) / `failed` / `dead`, with or without `only`; and `missing` names the ids of `only` that were neither pending nor parked — already applied by an earlier pass, or unknown; the relay cannot tell — never an empty report in green. `only: []` is 500 `E_AUTHZ_CONFIG`: an empty `filter` on your side, or a receipt from an outbox without ids, cannot end up draining the whole queue under the lease of an HTTP request. **`remaining` and `dead` are always global**, with or without `only`: a filtered report that kept quiet about a queue that does not converge would be a green report over a broken tree. Three things this is **not**. `only` takes the ids from the receipt your own process just got, **never from the request body** — an endpoint that accepts `only` from a client is policy in an API that has no policy (the relay skips `requireActor`/`requireWithin` on purpose). **There is no filter by tenant or organization**: a `detached` whose row is already gone belongs to no organization (excluding it always is a permanent fail-open — its facts are never purged; including it always is "anyone relays anyone's `detached`"), and a `moved` would be attributed to its *destination*, which is the bias that keeps accesses. And `only` does not pull its dependencies along — that is transitive and ends up being the whole queue; if what you want is "the queue landed up to here", run the relay without `only`. **Do not return the relay report over HTTP**: it enumerates the tree activity of every tenant (ids, scope uuids, actors, the backend's error text); read it, log it, act on `entries`, and hand the client your own answer. Finally, **the inline pass returns a report, it does not throw**: a `deferred` or a `failures` does not abort your request unless you look at it — if `entries` says your change is `deferred`, it has not landed, and that is the fail-closed window described below.
+**"Was mine applied?" — the receipt and `only` (2.4.0-alpha.5).** `scopes.attached/moved/detached` return a receipt, **`{ queued: [id] }`** — the outbox ids of what they just enqueued (plural on purpose: a `detached` whose row is already gone enqueues one entry per spelling of the uuid). Empty means there is nothing to relay: without an outbox the change was applied inline; with a third-party `ScopeOutbox` whose `enqueue` still returns `void` there is no id, and then there is no `only` either. Hand the receipt to the relay on the interactive path, right after your commit: **`await authorization.relayScopeChanges({ only: queued })`**. That is the fix for the cost a consumer measured: with 500 entries of another tenant ahead in the queue, the inline pass cost **4,507 ms and 2,004 OpenFGA calls** to land one change; with `only` it costs **19 ms and 4 calls**, because the filter lives in the port (`pending(limit, after, { ids })` — the primary key) and the pass never reads the other 500 rows (the suite spies on `pending` to pin that; a port implementation that ignores the filter is 500 `E_AUTHZ_CONFIG` before anything is applied, never a silent drain of the backlog inside your request). **The order by scope key is not relaxed — deferred, never out of order.** Before applying each requested entry the relay probes the *whole* queue (`earlierPending`: one existence query against the `(applied_at, id)` index, 0.69 ms measured; a port without it is paged through `pending()`): if an earlier unapplied entry names one of the same scopes and was not requested, yours is reported `deferred` with `depends-on:<id>` and not applied. Why, measured: with `#1 moved(unit → orgB)` pending and `only: [#2 attached(child, unit)]`, a filter without the probe wrote `child → unit` while the store still said `unit → orgA`, and the editor of the *old* organization authorised over the child (`authorize(A@orgA, docs:read, child) = true`, report all green). One level is enough — the last link of any chain of pending dependencies shares a scope with yours by definition of the key contamination — so the probe costs one query, not the queue. The report is **per entry**: `entries` names every entry the pass looked at, `applied` / `deferred` (reason `depends-on:<id>` or `parked:<id>`) / `failed` / `dead`, with or without `only`; and `missing` names the ids of `only` that are not in the queue at all — neither pending nor parked: already applied by an earlier pass, or unknown; the relay cannot tell — never an empty report in green. **`notEvaluated` names the ids of `only` that are still pending and the pass never looked at** because it reached `limit` first (2.4.0-alpha.10): until then `{ only: [a, b], limit: 1 }` put the pending `b` in `missing` — "already applied, or unknown" — and the applying pass exited 0. Telling them apart costs one read of the queue filtered by those ids, only when some requested id was not seen. `authz:scopes:relay --only … --limit …` names each of them ("is PENDING and this pass did NOT evaluate it", saying whether it was `--dry-run` or the applying pass and which `--limit`) and exits ≠ 0, in both. `only: []` is 500 `E_AUTHZ_CONFIG`: an empty `filter` on your side, or a receipt from an outbox without ids, cannot end up draining the whole queue under the lease of an HTTP request. **`remaining` and `dead` are always global**, with or without `only`: a filtered report that kept quiet about a queue that does not converge would be a green report over a broken tree. Three things this is **not**. `only` takes the ids from the receipt your own process just got, **never from the request body** — an endpoint that accepts `only` from a client is policy in an API that has no policy (the relay skips `requireActor`/`requireWithin` on purpose). **There is no filter by tenant or organization**: a `detached` whose row is already gone belongs to no organization (excluding it always is a permanent fail-open — its facts are never purged; including it always is "anyone relays anyone's `detached`"), and a `moved` would be attributed to its *destination*, which is the bias that keeps accesses. And `only` does not pull its dependencies along — that is transitive and ends up being the whole queue; if what you want is "the queue landed up to here", run the relay without `only`. **Do not return the relay report over HTTP**: it enumerates the tree activity of every tenant (ids, scope uuids, actors, the backend's error text); read it, log it, act on `entries`, and hand the client your own answer. Finally, **the inline pass returns a report, it does not throw**: a `deferred` or a `failures` does not abort your request unless you look at it — if `entries` says your change is `deferred`, it has not landed, and that is the fail-closed window described below.
 
 **A 503 does not consume an attempt (2.4.0-alpha.5).** `maxAttempts` exists to converge on the *irreparable* — the parent of an enqueued `attached` was deleted and will not come back — and until alpha.4 a backend outage spent the same budget: measured, with the store down, **five requests of another tenant** running the inline relay parked an entry that was not theirs (one attempt per request: the entry at the head of the queue pays for everyone's pass), and from then on its dependants were applied without it. Now the manager tells the two apart by the nature of the error: an `AuthorizationBackendError` — the store did not answer, the deadline expired, any 503 — is reported in `failures` with `transient: true` and passed to `markFailed(id, error, { transient: true })`, and `sqlScopeOutbox` writes `last_error` **without** counting the attempt; a 422, a 500, `E_AUTHZ_SCOPE_TREE_DRIFT`, a missing parent or a bare error from a third-party driver count as before. A port implementation that ignores the third parameter counts everything — exactly the alpha.4 behaviour, degrading towards safe. For the inline recipe, with the numbers: an outage of the store lasting `N` requests leaves `N−1` entries deferred behind the failing head on request `N`, and none of them parked.
 
@@ -161,7 +161,7 @@ The relay is resumable and never silent: the report says *which* changes were ap
 
 **How old is the queue? `report.queue` and `--max-age` (2.4.0-alpha.8).** Measured in a consumer (panel relay 2, auditor B2): with the store down, ten relay passes in a row reported `attempts = 0` on every entry (a 503 does not consume an attempt, since alpha.5), `dead = 0` and **no notion of time anywhere** — the cron was red because of `failures`, but nobody could tell since when, and nothing distinguished a queue that has been stuck for an hour from one that was enqueued a second ago. Every relay report now carries **`queue: { oldestPendingAt, pendingAgeMs }`**: the `createdAt` of the **oldest pending entry of the whole queue** — the `pending(1)` the pass already ran at the end for `remaining`, so it costs no extra query — and its age, `max(0, now − createdAt)`, measured with the manager's injectable clock (`config.clock`; no `Date.now()` in the package sources, the suite greps for it). It is **always global, also under `only`**, like `remaining` and `dead`: it names nobody, it only says "there is backlog". Both fields are `null` when nothing is *pending* (an empty queue, or only parked entries — those have their own alarm, `deadCount`, below) and when the port does not provide `createdAt`: a third-party `ScopeOutbox` whose entries carry no `createdAt` reads as `null`, **never as `0` or "now"** (the same rule as `stillGranting`: "I do not know" does not degrade to a number). `sqlScopeOutbox` returns it from the `created_at` column it already had (`createdAt?: Date` is an optional field of `PendingScopeTreeChange`; the outbox contract has a `createdAt` capability pair). Read the number for what it is: **the age is the clock of whoever enqueued** — another replica with a skewed clock stamps its own `created_at`, so the age is clamped at zero and never negative, and it is not a decision the package takes (audit stamps are not decisions). The command prints it on every pass; **`--max-age=<ms>`** makes the pass exit ≠ 0 when the age is above the threshold — **only with a threshold**: without it the age is reported and never fails the run, because a cron that goes red for ever over a queue that simply has backlog is a cron nobody reads. Parking by age (`parkAfterMs`) is *not* offered, on purpose — see the changelog: it reintroduces, with another clock, the mass parking alpha.5 removed, and it was measured to make every pass a 500 once the census fills.
 
-**Enqueueing outside your transaction: `sqlScopeOutbox({ requireTransaction: true })` (2.4.0-alpha.8).** The mitigation above is *entirely* the `{ transaction: trx }` you hand to `scopes.attached/moved/detached`. Without it the call still enqueues — the row commits on its own, outside your unit of work — and if your transaction rolls back afterwards **the change stays in the queue and the relay applies it to the store**: your database says one parent, the PDP another, and nothing on your side can show it (the S5 leak, on the *correct-use* path; measured by the tester of panel relay 2, P13). With `requireTransaction: true` that call is **500 `E_AUTHZ_CONFIG` before the `INSERT`**, naming exactly that leak, through the manager and through the outbox alone; with an open transaction of the outbox's connection it enqueues as always. The default is **`false` in 2.4** — the published outbox contract (`runScopeOutboxContract`) enqueues without a transaction in its `ctx()`, and a `true` default would turn every third-party outbox red — and **the default becomes `true` in 2.5** (owner's decision), together with the contract passing the transaction in `ctx()` (a prerequisite of that release; without it the default cannot change). Turn it on today: it is the letter of the mitigation, and the only thing you lose is the ability to enqueue by mistake. A transaction that is **already committed or rolled back** is a different 500, below.
+**Enqueueing outside your transaction: `sqlScopeOutbox({ requireTransaction: true })` (2.4.0-alpha.8).** The mitigation above is *entirely* the `{ transaction: trx }` you hand to `scopes.attached/moved/detached`. Without it the call still enqueues — the row commits on its own, outside your unit of work — and if your transaction rolls back afterwards **the change stays in the queue and the relay applies it to the store**: your database says one parent, the PDP another, and nothing on your side can show it (the S5 leak, on the *correct-use* path; measured by the tester of panel relay 2, P13). With `requireTransaction: true` that call is **500 `E_AUTHZ_CONFIG` before the `INSERT`**, naming exactly that leak, through the manager and through the outbox alone; with an open transaction of the outbox's connection it enqueues as always. **The default is **`true` since 2.5.0** (lot B · B6, owner's decision; it was `false` in 2.4 because the published outbox contract enqueued without a transaction and a `true` default would have turned every third-party outbox red). `requireTransaction: false` is the explicit opt-out — the signature of code that enqueues outside any unit of work on purpose (a seeder, a harness) —, and the published contract now carries the capability pair **`requiresTransaction`** (optional, `false` when absent): with `true` the judge enqueues inside a transaction of your connection in every case, direct and through `scopes.*`, and pins the refusal (500 naming `requireTransaction`, zero rows, by the outbox alone and by the manager); with `false` it pins that enqueueing without one enters. Mind the pool: `{ transaction }` **through the manager** needs a pool of at least 2 (the freeze barrier reads through another connection; with a single one the notification is 503 `E_AUTHZ_BACKEND_TIMEOUT` at `freezeTimeoutMs`), so a deployment with **pool max 1 — knex's default for every SQLite connection, file or `:memory:`** — cannot use the default through `scopes.*`: declare `requireTransaction: false` there and say so (the 500 names the pool and that way out; following its first advice alone on a pool of 1 leads to the 503). A transaction that is **already committed or rolled back** is a different 500, below.
 
 **What the report says about the parked set — `deadCount`, `deadDetail`, and the `origin` of a deferral (2.4.0-alpha.8).** Three small corrections to the report, each measured in a consumer. **`deadCount`** is always present and always global: `dead[]` is capped at `batchSize` (100), so `dead.length` *lies* once more than that is parked; the alarm "the queue does not converge" now rests on the count, which comes from the census the pass already reads for the key plug (no extra query). **Under `only`, `dead[]` carries `id`, `change` and `attempts` and — by default — no `error`**: the inline recipe runs inside a tenant's request, and the error text is what the backend said about *another* tenant's tree; pass `deadDetail: 'full'` to get it back (without `only` nothing changes, and the entries you *asked for* keep their `reason` in `entries`, they are yours). Read this as the safe-fields rule for a report you might be tempted to surface: `deadCount` and the ids say "there is a parked backlog" and nothing else; `change` still names scopes of other tenants (the actor never travels in `dead[]`), so the rule above stands — do not return the report over HTTP. And every `deferred` entry now carries **`origin`**: `'parked'` (held, directly or transitively, by a parked entry — the only origin that lets a `detached` through, invariant 11), `'failed'` (held by a real failure of this pass), or `'pending'` (under `only`: held by an earlier entry that is genuinely pending and was not requested — it will land on the next full pass). Until alpha.8 `depends-on:<id>` did not distinguish the last two and the origin lived only in the Spanish prose of `deferred[].error`; it is derived from the block itself, never parsed back from the text of `reason`.
 
@@ -249,7 +249,7 @@ The *row* is inside your transaction; the *decision* that authorises writing it
 
 #### Third-party drivers, and what the suite can and cannot prove
 
-"Both or neither" is **a guarantee of this package's `database` driver**, measured on its own schema on three engines. For a driver of yours declaring `transactionalWrites: true`, the runner requires the census (the `transactions` hook: how to open a transaction of *your* connection and how to count *your* rows) and judges rollback ⇒ zero, commit ⇒ applied, the uncommitted write invisible to the authority and three foreign transactions ⇒ 500 with zero statements — but it **cannot prove that a third-party driver's write really lives and dies with the transaction it is handed**: the census it counts is the one your hook reports, and a driver that opens its own transaction underneath passes the answer checks. Two more honest boundaries: the `true` face only runs where a second connection exists (`sqlite-file`, PostgreSQL, MySQL — the engine jobs of CI are not optional for this capability), so a driver judged only on `:memory:` never sees those cases; and the 409/503 classification of the table above is the `database` driver's — a third-party driver that returns the raw engine error is not caught by the suite.
+"Both or neither" is **a guarantee of this package's `database` driver**, measured on its own schema on three engines. For a driver of yours declaring `transactionalWrites: true`, the runner requires the census (the `transactions` hook: how to open a transaction of *your* connection and how to count *your* rows) and judges rollback ⇒ zero, commit ⇒ applied, the uncommitted write invisible to the authority and three foreign transactions ⇒ 500 with zero statements — but it **cannot prove that a third-party driver's write really lives and dies with the transaction it is handed**: the census it counts is the one your hook reports, and a driver that opens its own transaction underneath passes the answer checks. Two more honest boundaries: the `true` face only runs where a second connection exists (`sqlite-file`, PostgreSQL, MySQL — the engine jobs of CI are not optional for this capability), so a driver judged only on `:memory:` never sees those cases; and the 409/503 classification of the table above is the `database` driver's — a third-party driver that returns the raw engine error is not caught by the suite. The same honesty for relations: the `listObjectsTruncation` pair of `runRelationsDriverContract` judges the **cap** only (`limits.listMaxResults`); **the runner does not judge the deadline** signal of a third-party `listObjects` (there is no way to observe it without sleeping), so a driver that does not implement it passes — the deadline cause is a property of this package's `openfga` driver, pinned by its own cases and by the surface guard. And the B3 case (a userset other than `group#member` as subject) observes your backend **through the port** — `listSubjects` and, under `enumerateRelations: true`, the whole partition — so a driver that stores the inert row and then throws the 422 goes red only through a port it declares: the minimal harness (`usersetSubjects: false`, `enumerateRelations: false`) has no port through which the runner can see that row, and such a driver passes (measured with that mutant on the double).
 
 ### Identity is validated, once and everywhere
 
@@ -317,7 +317,7 @@ await authorization.isWithin(unit, currentOrg)   // the same question on its own
 
 **Actor.** Every write (`grant`, `revoke`, `deny`, `removeDeny`, `scopes.*`) takes `{ actor }` — a `SubjectRef`, validated like any identity — which `onWrite` receives as `event.actor`. `requireActor: true` ⇒ a write without it is 422 `E_AUTHZ_ACTOR_REQUIRED` before the driver and before the hook. No `AsyncLocalStorage`: the actor is an explicit argument. For these six writes the engine never evaluates it (who may grant what is your policy) — **but the delegation API of 2.2 does**: there the `actor` is the whole policy, so it must come from the session and never from the request body. See [Scoped roles](#scoped-roles-22).
 
-**`manager.driver()` is the documented way out of all of that.** It returns the active driver as-is: writes through it skip `actor`/`requireActor`, `within`/`requireWithin` **and `onWrite`**; reads skip the per-request memo. It exists for platform code (seeders, commands, writing at the root under `'non-root'`) and for tests — a tenant call-site should never call it, and a code review can grep for it. Nothing else is offered through it on purpose.
+**`manager.driver()` is the documented way out of all of that.** It returns the active driver as-is: writes through it skip `actor`/`requireActor`, `within`/`requireWithin` **and `onWrite`**; reads skip the per-request memo. It exists for platform code (seeders, commands, writing at the root under `'non-root'`) and for tests — a tenant call-site should never call it, and a code review can grep for it. Nothing else is offered through it on purpose. **Grep for `relationsDriverFactory` and `relationsDriverKeys` too** (2.4.0-alpha.10): `manager.relationsDriverFactory(key)` returns the factory registered under `relations.drivers[key]` and `manager.relationsDriverKeys()` lists the keys — platform API next to `driver()`, used by `runRelationsReconcile` to resolve source and destination from the manager's own config. With the factory, any code holding the manager (a `forRequest()` view included) can build a relations driver that is **not** the active one and write to it with no `assertWrite`, no `requireActor`, no freeze and no `onRelationWrite`. It adds no real capability — `app.config` already hands out the factories — but it is one more thing to look for in a review. And `runRelationsReconcile(authorization, …)` takes the manager **structurally** (`Pick<AuthorizationManager, 'withFrozenWrites' | 'relationsDriverKey' | 'relationsDriverFactory'>`): an object that fakes `relationsDriverKey` or `relationsDriverFactory` decides which driver is active and which factories are compared, so pass it the service manager, never a hand-built or wrapped one.
 
 **Decisions in bulk.** `authorizeMany(subject, permission, scopes)` → `boolean[]` by position, identical to N `authorize` (duplicates, unknown scopes, denies); empty ⇒ `[]` without touching anything; a position that cannot be answered rejects the whole call. `openfga` answers with one `batchCheck` for all chains (a repeated scope shares one slot); `database` composes N `authorize` over a memoised view (one tree call per distinct scope). A third-party driver's `authorizeMany` is validated: a result that is not a `boolean[]` with exactly one position per scope is 500 `E_AUTHZ_INTERNAL` naming the driver (*"authorizeMany valida la respuesta de un driver de terceros"*).
 
@@ -374,7 +374,7 @@ router
 
 The middleware resolves the authenticated holder from its morph name and asks `authorize` at the **`app` scope**. It accepts **`{ permission }` only**: `appAccess({ role })` was removed in 2.0 — a gate over membership could not be denied — and passing `role` is a 500 `E_AUTHZ_ROLE_IS_NOT_ACCESS` with the recipe (create a permission, link it to the role, gate on the permission), thrown before authentication is checked (*"appAccess({ role }) es 500 E_AUTHZ_ROLE_IS_NOT_ACCESS con la receta"*). Per-organization or per-unit enforcement is your controller's or your own middleware's job: only your domain knows which scope a route belongs to. The holder must expose `uuid`; a numeric-PK model is rejected with an explicit error.
 
-### Per-resource enforcement: `resourceAccess` (2.5)
+### Per-resource enforcement: `resourceAccess` (2.4.0-alpha.1)
 
 `appAccess` gates a route at the `app` scope. To gate one **resource** — *this document, in that
 organization* — the `resourceAccess` middleware composes the same `authorize`: your code says how to
@@ -563,6 +563,48 @@ tenant — and it is **mandatory**: a relation in tenant A never resolves in ten
 the mono-tenant value). The partition lives in the object id (`document:<partitionKey>|<uuid>`), not
 in the model.
 
+**Spelling is identity (2.5.0, D4).** Relations have no resolver chain to canonicalise against (roles do,
+invariant 17), so the partition key is a string compared byte for byte — and until 2.5.0 the same tenant
+uuid written **without dashes** (32 hex, what PostgreSQL's `uuid` type or a `*_ci` collation fold into the
+dashed row elsewhere) was *another* partition that the canonical purge never saw. Since 2.5.0 **a partition
+uuid that is 32 hex once the dashes are removed and is not exactly `8-4-4-4-12` is 422 `E_AUTHZ_INVALID_IDENTITY`
+in every operation that takes a partition** — the manager, both drivers, the in-memory double,
+`authz:relations:reconcile --partition-uuid` — with zero backend calls, the message naming the canonical form.
+The rule is "every spelling an engine folds", not only "no dashes": PostgreSQL also reads `8-4-4-16`, four groups
+of eight or the canonical form minus one dash as the same `uuid` (`'a0eebc99-9c0b4ef8-bb6d6bb9-bd380a11'::uuid`
+is the canonical row), and each of those was a partition of its own that an offboarding by the canonical spelling
+left alive (the lot A audit, A2; pinned by a truth table of forms and, on PostgreSQL, by measuring the cast). A
+partition id that is *not* a uuid at all — 32 characters that are not all hex, 31 or 33 hex, `md5`-style ids with
+an underscore — is a legal id and is untouched. Rows written with a non-canonical spelling before 2.5.0 are
+**detected, listed and deleted** by [the upgrade recipe](#upgrading-to-250-non-canonical-partition-spellings)
+(fail-closed by default; re-keying them is the explicit `--rekey` step). **Object and
+subject ids are compared byte for byte; use one spelling.** They are *not* rejected: a 32-hex object id may
+be a legitimate non-uuid id, so `{ type: 'document', id: '0192…aa' }` and `{ id: '0192…-…-aa' }` are two
+documents in both directions (pinned by a case), exactly as a holder `uuid` is for roles.
+
+**Deciding in bulk: `checkMany` (2.5.0).** `checkMany(subject, relation, objects, partition)` → `boolean[]`
+by position, with the **same semantics as N `check`** (includes, usersets, strict expiry) for the ancestor
+chain or the list you already hold: `database` answers in **one query** (one `now` for the whole batch),
+`openfga` in **one `batchCheck`** (one `current_time` in every item, results aligned by `correlationId`,
+never by position), and a driver that does not implement it is composed by the manager as N `check`s
+(correct, N round trips, each with its own instant). Batches are **1..50** objects (`RELATIONS_CHECK_MANY_MAX`,
+the server's `batchCheck` cap): 51 and `[]` are 422 `E_AUTHZ_CHECK_MANY_BATCH` with zero calls; duplicates
+are allowed and answered by position (`[a, a, b]` ⇒ `[x, x, y]`); object types may be mixed as long as the
+relation is declared for each (F-05 runs **per item**, so a `role_binding` in position 21 of 21 is 422 with
+nothing asked); a per-item `error` inside a 200 `batchCheck` is a **503 for the whole batch**, never a
+`false`. **`checkMany` returns one boolean per object: `false` does not distinguish "denied here" from
+"nothing here", so it cannot implement deny-wins along a chain of objects that you walk yourself** — that is
+`decideMany` (2.5.0, lot D). A third-party driver's answer is validated: anything but a `boolean[]` with one
+position per object is 500 `E_AUTHZ_INTERNAL` naming the driver.
+
+**A pure, stable key for a tuple (2.5.0).** `relationTupleKey({ partition, object, relation, subject, kind? })`
+(root export) is deterministic and injective over exactly those five components — the expiry is not part of it
+(renewing a share keeps its key, even though `database` rewrites the row with a new uuid) and neither is any
+backend id. It is what `authz:relations:reconcile` matches source and destination with, and what you can index
+your own metadata by, without the package storing it. `kind` is `'allow'` by default and travels in the key from
+day one (`allow|unit|<uuid>|document:<id>#viewer@user:<uuid>`), so the key of an allow you already hold **does not
+change** when denies (`kind: 'deny'`) arrive in 2.5.0.
+
 **The model is shared with the catalog, and so is its byte budget.** In the `openfga` driver,
 relations fuse into the same `facts` model and the same store, so a single `Check` still answers
 each question. The price is one budget: the 262,144-byte model holds **both** your permissions and
@@ -599,10 +641,14 @@ platform escape hatch) and `authz:relations:reconcile` — which writes through
 { type: 'role_binding', id: <roleUuid> }, S)` turned `roles.authorize(evil)` from `false` to `true`
 (measured against a real server; the bridge spec keeps that case, and removing the driver guard puts
 it back in red). `manager.driver()` still skips the manager's *other* barriers (`actor`,
-`assertWrite`, `onRelationWrite`), as documented — F-05 is no longer one of them.
-
-**And since `2.4.0-alpha.3` F-05 covers **all eight operations of the port**, not only the two writes that
-compose a tuple.** The alpha.3 audit found the chokepoint one call-site short (pre-existing in alpha.2, in
+`assertWrite`, `onRelationWrite`), as documented — F-05 is no longer one of them. **The userset subject is part of
+that grammar (2.5.0 · B3)**: the only userset the fused model admits as a subject is `group#member`, so
+`{ object: document, relation: viewer }` as subject is 422 `E_AUTHZ_RELATION_USERSET_UNSUPPORTED` on every operation
+that takes a subject, through the same single function in the manager, both drivers and the published double — until
+2.5.0 `database` stored that row inert and `openfga` surfaced the server's 400 as a 503.
+
+**And since `2.4.0-alpha.3` F-05 covers **all nine operations of the port** — the eight of alpha.3 plus
+`checkMany` (per item) since 2.5.0 —, not only the two writes that compose a tuple.** The alpha.3 audit found the chokepoint one call-site short (pre-existing in alpha.2, in
 code alpha.3 had just rewritten): `purgeObject`/`purgeSubject`/`check`/`listObjects`/`listSubjects`/`membersOf`
 never called `assertRelationDeclared`, so in the shared store `purgeObject({ type: 'role_binding', id: R }, S)`
 composed — byte for byte — the id of a real binding and **deleted the real binding** with proof of zero
@@ -632,24 +678,77 @@ membership (through nested groups). Only the `database` driver has it (a recursi
 it is 500 `E_AUTHZ_UNSUPPORTED` naming it — the transitive form is `ListUsers`, which truncates
 without a reliable signal, and we never return a silent partial. `listSubjects` (direct facts,
 invariant 7) works in both. `listObjects` in `openfga` signals `truncated: true` when the server's
-`ListObjects` cap cuts the page, never a mute partial list.
-
-**The config is persisted, and republishing never mutilates the model.** `saveRelationsConfig(spec)`
-stores the relations config in `authz_relations_config` under the shared version gate (invariant 14).
-Because the catalog and the relations config share one model lifecycle, both `syncAuthzCatalog` and a
-config save republish the fused model — and they race for the `modelId`. `republishFusedModel` reads
-**both** persisted halves (catalog permissions + relation types) every time, so the published model
-is never "the model of one, the tuples of another"; the `modelId` is pinned with a bounded CAS, and
-contention that will not yield is 409 `E_AUTHZ_WRITE_CONFLICT`, never a half model.
+`ListObjects` cap cuts the page **and** when the call took **90 % or more of the server's `ListObjects`
+deadline** (`listObjectsDeadlineMs`, default 3,000 ms, OpenFGA's default `--listObjects-deadline`; set it to
+your server's **effective** cut, below) — past its deadline the server answers 200 with whatever it had resolved and **no signal**
+(measured, 2.5.0 · B4; until then the README promised no mute partial list at all, and that was only true of the
+cap). Both causes are one signal, through one envelope (`#listObjectsPage`, measured with a monotonic clock);
+the signal is conservative on purpose: a slow-but-complete call may be flagged, a cut one never passes as
+complete — the price is in [Limits](#limits). `listObjectsDeadlineMs` is the server's **effective** cut, whichever is
+lower of the three — `--listObjects-deadline` (when it is not 0), `--request-timeout` (3 s by default) and, over HTTP,
+the gateway's `--http-upstream-timeout` (5 s by default) — declare that lowest one: a server running with
+`--listObjects-deadline=0` has **no** "no deadline" — its `--request-timeout` still cuts `ListObjects` with a mute 200
+(measured on OpenFGA v1.19.0 by the audit of 2.5.0-alpha.2: `--request-timeout=30ms` answered `200` with 0 of 40,000
+objects; `list_objects.go` only sets its own timeout when the deadline is not 0 and inherits the request-timeout
+context otherwise) — so declare that value instead. `Infinity` is refused (500 `E_AUTHZ_CONFIG`): it would make the
+driver pass that mute list as complete. Both at 0 is not supported (what the HTTP gateway's `--http-upstream-timeout`
+does then is not measured for `ListObjects`; the package promises no "no deadline" it has not measured). And the
+driver's own `timeoutMs` (5 s by default) cannot be lower than `listObjectsDeadlineMs`: the signal has to be able to
+fire before the client cuts, so a deadline above the client timeout is 500 `E_AUTHZ_CONFIG` at construction
+(`Number.MAX_SAFE_INTEGER` was "no deadline" under another name, 2.5.0-alpha.2 · closure 3). A 200 **without
+`objects`** is 503, not an empty list. The `Read`-based enumerations — `listSubjects`, `enumerateRelations(Many)`,
+the purges — are **exhaustive or 503**: they page until the continuation token is empty and throw on a response
+without `tuples`, a repeating token or more than 10,000 pages (`E_AUTHZ_BACKEND_UNAVAILABLE`), never a short page.
+The roles driver's `Read`s (`readAllTuples`, the reconcile dump, `enumerateFacts`) hold the same rule since
+`2.5.0-alpha.2`.
+
+**The config can be persisted, and nothing republishes the model behind your back.** `saveRelationsConfig(spec)`
+stores the relations config in `authz_relations_config` under the shared version gate (invariant 14), so a
+process without `defineRelationsConfig` in memory can read the declared types (`readRelationsConfig()`,
+`null` when nothing was ever saved). **The fused model is published by one thing only: `node ace
+openfga:provision`**, from the *static* config (`relations.config` and the `catalogs`) — the command boots
+without a database and cannot read the table —, and re-publishing it is a manual operator step (single writer:
+the `modelId` goes to every pod by hand, see [the cutover window](#the-cutover-window)). Neither
+`syncAuthzCatalog` nor a config save republishes anything. The persisted copy has one reader today:
+`authz:relations:reconcile`, which uses it as the **destination's** config to flag model drift — and since
+2.5.0 a *failed* read of that table stops the command before any write (an unreadable config is not "no
+config"; `null` is).
 
 **Migrating tuples between drivers** is `node ace authz:relations:reconcile --to=<key>` — the relations
 analog of `authz:reconcile`, idempotent, bidirectional and never silent (it reports written / deleted
 / unchanged / extra). `--to`/`--from` are keys of `relations.drivers` in `config/authorization.ts`;
 `--dry-run` is the read-only verifier and also flags **model drift** (an object type in the source the
-destination does not declare); `--prune` deletes what the source no longer backs. It migrates **facts
+destination does not declare); `--prune` deletes what the source no longer backs — except a destination row the API
+does not admit (`details`: `invalid-identity`, `userset-unsupported`, `undeclared` — a relation or type the
+destination no longer declares), which no flag touches: listed, exit ≠ 0 in every mode, deleted by hand or, for
+`undeclared`, declared again ([Upgrading, 6](#upgrading-to-250)); a 422 of the relations family from the destination's
+`unrelate` is classified the same way and never aborts the pass. **Never towards the
+ACTIVE relations driver** (2.4.0-alpha.10): once `relations.default ?? config.default` is `--to`, any
+other source — with `--from` or picked by elimination — is 500 `E_AUTHZ_STALE_SOURCE_REFUSED` (it
+would resurrect shares revoked since the cutover and, with `--prune`, delete the new ones); `--dry-run`
+flags it, and `--allow-stale-source` is the human decision. It migrates **facts
 only** — there is no tree or catalog in `relations/` — and works **per partition** (`--partition-type`
-/`--partition-uuid`; default `app`; from code, `reconcileRelations({ partitions: [...] })` migrates several
-in one pass — see the sweep below). **The pass that writes runs under the durable freeze** (2.4.0-alpha.2,
+/`--partition-uuid`; default `app`). **From code, the one public way is `runRelationsReconcile`** —
+`import { runRelationsReconcile } from '@jantstack/adonis-authz/relations/reconcile'` (its own subpath since 2.5.0; until
+`2.5.0-alpha.1` it was `…/commands/authz_relations_reconcile`, which no longer exports it) and
+`runRelationsReconcile(authorization, { toKey, fromKey, partitions: [...] })` migrates several partitions in one
+pass (see the sweep below), with the same guard and the same durable window as the command. Source and
+destination are **keys of `relations.drivers`, resolved from the manager's own config**, and the guard compares
+the *resolved* driver, not the label: two keys that point at the same factory are the same driver (an alias of the
+active one is refused too; source = destination is 500 `E_AUTHZ_CONFIG`), and the active driver is always the
+manager's — there is no `activeKey` to contradict it. **Declared limit: identity is the factory reference, not the
+backend.** Two *different* factories that build the same store — `openfga: () => new OpenFgaRelationsDriver(…)` and an
+alias `fga: () => new OpenFgaRelationsDriver(…)` with the same `OPENFGA_STORE_ID`, which is how an alias is naturally
+written in a config — are **not** detected: `--to=fga --from=database` passes the guard and resurrects what was revoked.
+Nothing is built before the guard, so there is no backend to compare. Register an alias with the *same* reference
+(`const fga = () => …` and `{ openfga: fga, alias: fga }`) or do not register it; a backend identity declared by the
+driver is on the 2.5 list. Until the closing lot of 2.4.0-alpha.10 the primitive
+`reconcileRelations` was exported from the package root and this paragraph recommended it for K partitions: it
+never saw the active driver nor took the window, so a loop written after the cutover resurrected revoked shares
+with the fleet still writing. It is no longer public. **The guard reads the config of the process that runs it**:
+`relations.default ?? config.default` *there* — a job or pod started with another environment (say, without
+`AUTHZ_DRIVER`) believes another driver is active and the guard is off. Run it with the fleet's config; a durable
+seal of the active driver is on the 2.5 list. **The pass that writes runs under the durable freeze** (2.4.0-alpha.2,
 lot L-1), exactly like `authz:reconcile`: every write of the package — roles *and* relations — answers a
 retryable 503 `E_AUTHZ_FROZEN` fleet-wide while it runs; a live **operator** window (`authz:freeze`) is its
 own context (it runs inside, does not renew or lift it); a live freeze of another pass is 423; and the
@@ -667,7 +766,7 @@ means "this partition is empty" and in a purge "proved zero" without deleting an
 that way; the suite spies the filter of every `read` and it is always `{}`. What *is* cheaper is doing the
 sweep **once for K partitions**: `enumerateRelationsMany(partitions)` (optional port method, implemented by
 `openfga`; `RelationsManager` exposes it and falls back to K calls for a driver without it) and
-`reconcileRelations({ partitions })`, which enumerates source and destination once, decides the K diffs
+`runRelationsReconcile(authorization, { toKey, fromKey, partitions })`, which enumerates source and destination once, decides the K diffs
 first (the mass-delete guard R-17 is evaluated for every partition **before** writing anything) and then
 applies them; the report is the sum. Same output per partition, byte for byte, as K separate calls; `app`
 does not pull `appliance|…`, `org|U` does not pull `organization|U`, and each spelling of a uuid is its own
@@ -768,11 +867,13 @@ Every error the package raises carries `status` and `code`. A standard AdonisJS
 | `E_AUTHZ_FREEZE_HELD` | 423 | `freeze()` (or a second `authz:reconcile`) found a live freeze owned by someone else: two windows never interleave, and only the owner's token — or `authz:unfreeze` — lifts one. The message names the holder, the reason and the fence |
 | `E_AUTHZ_RESOLVER_FAILED` | 503 | your `resolveChain`, `parentOf` or `descendantsOf` threw or answered a malformed scope; `descendantsOf` and `resolveChain` disagree in `authorizedScopes`; a subtree to exclude cannot be enumerated |
 | `E_AUTHZ_WRITE_CONFLICT` | 409 | an `openfga` write kept clashing with another transaction over the same tuples (FGA answers `Aborted`/409, or 400 "cannot write a tuple which already exists"): the driver re-reads and re-applies, and only gives up after three rounds. The backend answered, so this is never a 503 — retry the write. Also (2.4.0-alpha.2, lot L-3) a `database` `grant`/`deny` **inside your transaction** (`{ transaction }`) that hits the UNIQUE because another transaction committed the same fact while yours was open: outside a transaction the driver re-reads and keeps the winner's row; inside yours it cannot (PostgreSQL has already aborted your transaction — every later statement is `25P02` until you roll back — and under REPEATABLE READ the re-read would not see the winner), so it **poisons your transaction**: roll back and retry. Measured on all three engines, see [writing inside your transaction](#writing-inside-your-transaction-240-alpha2). The same for a `database` `relate`/`unrelate`/`purge*` inside your transaction (lot L-4) — on a UNIQUE clash of a tuple (userset, and since lot L-4b holder too: `subject_relation` is `''`, never `NULL`), and on a **deadlock** (two transactions writing two tuples in crossed order: PostgreSQL `40P01`, MySQL `1213`; the engine's victim gets this 409, never a hang nor the raw error) |
-| `E_AUTHZ_CONFIG` | 500 | `relayScopeChanges({ only: [] })`, a `ScopeOutbox` that ignores `pending(limit, after, { ids })` and returns an entry that was not asked for, `requeueScopeChanges` with an id that is not parked (or an empty list), or a `scopes.maxDepth` that is not an integer ≥ 1 (2.4.0-alpha.5); contradictory config (`holderTypes` not injective or a holder type not declared in it, `scopes.*` without resolver, `appAccess` without `permission`, `catalog` together with `catalogRevalidate`, an invalid `maxAgeMs`); `bumpAuthzCatalogVersion` called without the writing transaction's client; a `{ transaction }` handed to `sqlScopeOutbox` that is not an open Lucid transaction of the outbox's own connection (another connection, a `QueryClient`, or the whole `db` — the message names both connections), **or one that is already committed or rolled back** (`isCompleted`, 2.4.0-alpha.8 — the same check in the roles and relations drivers; it used to surface as a 503); `sqlScopeOutbox({ requireTransaction: true })` enqueueing without `{ transaction }` (2.4.0-alpha.8; the default becomes `true` in 2.5); `relayScopeChanges({ deadDetail })` with a value other than `'full'`; `requireTransactionalWrites: true` (root, or `relations.requireTransactionalWrites`) with an active driver that does not declare `transactionalWrites: true` — raised **when the driver is resolved**, so reads fail too and the deployment does not start (2.4); a `relations.assertWrite` that returns a promise — or any value at all: `false`, `true`, a thenable function (it must be synchronous and it does not return verdicts: it throws or it does not; the write is refused before the driver, 2.4.0-alpha.3) |
+| `E_AUTHZ_CONFIG` | 500 | `relayScopeChanges({ only: [] })`, a `ScopeOutbox` that ignores `pending(limit, after, { ids })` and returns an entry that was not asked for, `requeueScopeChanges` with an id that is not parked (or an empty list), or a `scopes.maxDepth` that is not an integer ≥ 1 (2.4.0-alpha.5); contradictory config (`holderTypes` not injective or a holder type not declared in it, `scopes.*` without resolver, `appAccess` without `permission`, `catalog` together with `catalogRevalidate`, an invalid `maxAgeMs`); `bumpAuthzCatalogVersion` called without the writing transaction's client; a `{ transaction }` handed to `sqlScopeOutbox` that is not an open Lucid transaction of the outbox's own connection (another connection, a `QueryClient`, or the whole `db` — the message names both connections), **or one that is already committed or rolled back** (`isCompleted`, 2.4.0-alpha.8 — the same check in the roles and relations drivers; it used to surface as a 503); `sqlScopeOutbox()` enqueueing without `{ transaction }` (`requireTransaction`, 2.4.0-alpha.8; `true` by default since 2.5.0 · B6, `false` is the explicit opt-out); `relayScopeChanges({ deadDetail })` with a value other than `'full'`; `requireTransactionalWrites: true` (root, or `relations.requireTransactionalWrites`) with an active driver that does not declare `transactionalWrites: true` — raised **when the driver is resolved**, so reads fail too and the deployment does not start (2.4); a `relations.assertWrite` that returns a promise — or any value at all: `false`, `true`, a thenable function (it must be synchronous and it does not return verdicts: it throws or it does not; the write is refused before the driver, 2.4.0-alpha.3) |
 | `E_AUTHZ_ROLE_IS_NOT_ACCESS` | 500 | `appAccess({ role })` |
 | `E_AUTHZ_INTERNAL` | 500 | package invariant violated (empty scope set on a write, misaligned batch, a third-party `authorizeMany` answering the wrong shape, a `Read` continuation token that never advances or more than 10,000 pages, a corrupt `assignable_at`/`owner_scope_key` row) |
 | `E_AUTHZ_PURGE_INCOMPLETE` | 500 | `purgeScope` could not prove zero; on the relations port, `purgeObject`/`purgeSubject` of `openfga` could not prove zero after deleting — the error carries the `markPartialWrite` mark and the event was emitted with `indeterminate: true` (2.4.0-alpha.3) |
 | `E_AUTHZ_RECONCILE_TOO_LARGE` | 500 | the destination's dump does not fit the declared `--max-tuples` cap (default 1 000 000) and reconciling needs the whole snapshot to know what is left over. Nothing was written; raise the cap if your process can take it |
+| `E_AUTHZ_STALE_SOURCE_REFUSED` | 500 | `authz:reconcile --to=<config.default>` (or `authz:relations:reconcile --to=<relations.default ?? default>`) with any resolved source other than the destination itself — `--from`, picked by elimination, or `authz_*` (2.4.0-alpha.10): the stale direction — the source stopped seeing the active driver's facts at the cutover, so the pass would resurrect every revocation made since. Nothing was read, frozen or written; for roles the maintenance pass is `--to=<active>` without `--from`, and `--allow-stale-source` is the human decision (`--dry-run` flags `report.staleSource` instead of throwing) |
+| `E_AUTHZ_OPERATOR_WINDOW_EXPIRED` | 503 | `freeze()` — and with it `authz:reconcile`, `authz:relations:reconcile`, `withFrozenWrites`, `authz:freeze` — found the OPERATOR window expired (2.4.0-alpha.10): taking a freeze over it would erase the trace that writers resumed mid-cutover. Acknowledge it with `authz:unfreeze`, reopen with `authz:freeze` |
 | `E_AUTHZ_MASS_RECONCILE_REFUSED` | 500 | `authz:reconcile --prune` would delete facts from the destination while the source has not contributed a single **usable** one — empty, or every fact it returned was skipped (expired, on scopes your tree no longer resolves): the signature of a wrong connection, of the wrong source, or of a blind resolver. Nothing was deleted; pass `--allow-mass-delete` if you really mean to empty it (`--dry-run` flags it instead of throwing). A source that is merely **stale** but still usable is covered by reading the facts from whoever owns them |
 | `E_AUTHZ_MASS_PURGE_REFUSED` | 500 | `pruneOrphanRoles({ force: true })` would purge every distinct owner (or more than half the local roles): the signature of a blind `resolveChain`. Nothing was deleted; pass `allowMassPurge: true` (`--allow-mass-purge`) if the prune is real |
 | `E_AUTHZ_TOO_MANY_LOCAL_ROLES` | 500 | more local roles than `maxLocalRoles` (10 000) in a `prune-orphans` pass; never a partial list |
@@ -795,6 +896,42 @@ Both also take **`catalogRevalidate`** (`'always'`, the default, or `{ everyMs }
 
 Both take **`now`** (default `() => new Date()`): the wall clock every time-based *decision* uses — `expires_at > now()` in SQL, the `current_time` of every FGA check (one instant per operation: every check of a `batchCheck` carries the same `current_time`, and the two reads of `listScopes` filter with the same `now`), the client-side expiry filter of the enumerations and the three states of a re-grant. The audit stamps (`created_at`) are **not** decisions and use the system clock: with MySQL's `TIMESTAMP` an injected clock in 2040 made every write fail (*"… se escribe estando el reloj en 2040"*). Every driver of the package also implements `withClock(now)` on the port (a view bound to another clock, like `withChainResolver`), and the manager applies **`clock`** from the config to the driver it resolves — all `forRequest()` views share it; a config `clock` over a driver without `withClock` is 500 `E_AUTHZ_CONFIG`, never a clock silently ignored. It exists so that expiry is observable *without sleeping* (the contract fixes the exact instant: one millisecond before `expiresAt` grants, at `expiresAt` it does not — *"caducidad exacta con el reloj inyectado"*) and so that your own tests can freeze time; in production leave it alone and keep NTP running. It is not the monotonic clock of `forRequest({ maxAgeMs })`, which measures a window and must not move with NTP. Nothing else in `src/` reads the wall clock (a grep test pins it) — except the model trait `withAuthzScopes` (`whereRoles`/`wherePermissions`), which cannot see the manager: it decides "live" with the system clock unless you compose it with the same clock, `compose(BaseModel, withAuthzScopes({ clock }))` (*"withAuthzScopes({ clock }) decide la vigencia con ESE reloj"*). Its primary-key comparison is dialect-aware (on PostgreSQL a `uuid` primary key is cast to text against the `varchar` subquery: *"… con la clave primaria uuid nativa del modelo"*).
 
+### Testing expiry from your app (2.5.0)
+
+Expiry, renewal and "it expires right now" are decided by that one injectable clock, so your own tests can fix
+the instant instead of sleeping. `createTestClock(start?)` (from **`@jantstack/adonis-authz/testing/clock`** — a
+light module with no test-framework or Lucid import, so it is safe in a config file that production loads; `/testing`
+re-exports it but pulls `@japa/runner` and `@adonisjs/lucid/services/db`, which an `--omit=dev` deploy does not have) returns a
+**stable function over a mutable instant** — the same reference lives in your config for the whole test
+process; `set(at)`, `advance(ms)`, `now()` and `at(offsetMs)` move or read it — and it mutates nothing global
+(`systemClock`, the audit stamps and whatever does not receive the clock stay on wall time):
+
+```ts
+// config/authorization.ts
+import { createTestClock } from '@jantstack/adonis-authz/testing/clock' // never from '/testing' here: that module imports Japa and Lucid
+export const testClock = createTestClock('2030-01-01T00:00:00.000Z')
+export default defineConfig({ …, clock: app.inTest ? testClock : undefined })
+
+// tests/sharing.spec.ts
+await relations.relate(user, 'viewer', doc, tenant, { expiresAt: testClock.at(+3_600_000) })
+assert.isTrue(await relations.check(user, 'viewer', doc, tenant))
+testClock.advance(3_600_000)                                      // the share expires right now (strict)
+assert.isFalse(await relations.check(user, 'viewer', doc, tenant))
+```
+
+The provider hands `config.clock` to **both** managers (roles and relations), and each applies it to its driver
+with `withClock`, so one clock decides every expiry in the process — the suite pins that wiring with a case that
+turns red if the relations manager stopped receiving it (P5-1). **Two things to know.** First, **the same clock
+decides the freeze barrier and the reconcile lease**: a frozen window with a lease is "expired" for a process
+whose clock has moved past `untilMs` (advance it 16 s and a pass sees its 15 s lease lapsed; freeze it and an
+operator window with a lease never expires for that process). That is also what it means in production: **the
+lease is judged by the clock of the process that reads the freeze row**, against an `untilMs` written with the
+clock of the one that froze — a writer whose wall clock runs ahead by more than the lease writes inside the window
+of a running pass (pre-existing, not introduced by the injectable clock; windows without a lease are not affected).
+Keep NTP on every process that writes. Second, a `relate` that reads a *ticking* clock
+(one advancing per read) is fine, but it is your test's clock: production leaves `clock` alone and keeps NTP
+running.
+
 `openfga` additionally takes `holderTypes` (required, injective; a holder whose morph name is not in it is 500 `E_AUTHZ_CONFIG`), `modelId`, a `logger` (default `console`), **`retryParams`** (default `{ maxRetry: 0 }`, see `indeterminate` above) and **`consistency`**: `'higher_consistency'` (default) or `'minimize_latency'`. The default protects the "removing the deny restores" promise against a server started with `--check-query-cache-enabled`, where a fresh revoke or deny would keep granting for up to the cache TTL; `minimize_latency` is the explicit opt-out (*"todo check lleva context.current_time; toda llamada HIGHER_CONSISTENCY"*). `driver.diagnostics.unparseableBindings` counts store tuples the engine cannot interpret — binding ids it does not understand and malformed tuples alike; each one is logged, never skipped in silence.
 
 **The `openfga` driver *is* the `facts` mode, and there is no other (2.3, breaking).** The scope tree is materialised in the store as one `scope:<child>#parent@scope:<parent>` edge per node, which is what the model needs to inherit downwards without asking your database. `authorization.scopes.attached/moved/detached` maintain those edges: `moved` is one `Read` plus one atomic `Write` carrying the delete of the old parent and the write of the new one, and `detached` removes the edge **after** `purgeScope` has proved the facts of that scope are gone. Finding more than one parent for a scope is 500 `E_AUTHZ_SCOPE_TREE_DRIFT`: the package writes one edge per node, so two means something else writes to your store, and it is reported rather than silently "fixed".
@@ -1030,8 +1167,8 @@ This is the **only** migration and verification primitive of the package, and th
 
 **Whoever owns the facts is where they are read from (2.3, and it is the whole safety of this command).** `--to=openfga` used to read `authz_assignments` / `authz_denies` *always*. In a deployment that has already cut over to `facts` those tables are **not** the source of truth of the facts — the store is, and nothing keeps them in sync after the cutover — so a pass that rebuilt from them re-wrote grants you had revoked (no flag needed) and, with `--prune`, deleted the denies that only lived in the store. So the pass now asks first, and **says the answer in its first line** (`report.factsFrom`):
 
-- **`--to` is the *active* driver and its facts live in its own backend** (`capabilities.hierarchyFacts`, which is what `openfga` declares): then its facts are its own and it is read from *itself*. This is the **maintenance pass**: it rebuilds everything **derived** — root marker, catalog projection, tree — and applies the visibility sweep of invariant 18 with the tree and the catalog of *today*, and it **writes and deletes no fact at all**. It is also what makes `--dry-run` usable as the CI verifier of a `facts` deployment: a correct store now comes out **clean** instead of reporting every live fact as `extra-fact`. (A driver in that position that cannot enumerate its own facts is 500 `E_AUTHZ_UNSUPPORTED` naming `enumerateFacts` — reading `authz_*` for it would be the bug.)
-- **`--from=<driver>` is given**: you decide. If that driver's facts are `authz_*` (the package's `database`), `--to=openfga` is the **one-way migration** it always was, and it will happily overwrite the destination's facts with what those tables hold. That is what you want while migrating — and it is a loaded gun pointed at a store that is already live, which is why it now takes an explicit `--from` to fire it.
+- **`--to` is the *active* driver and its facts live in its own backend** (`capabilities.hierarchyFacts`, which is what `openfga` declares): then its facts are its own and it is read from *itself*. This is the **maintenance pass**: it rebuilds everything **derived** — root marker, catalog projection, tree — and applies the visibility sweep of invariant 18 with the tree and the catalog of *today*, and **it writes no fact; with `--prune` it deletes the facts of scopes that no longer resolve**, the expired ones and those of roles or permissions the catalog or the model no longer has (and the leftovers) — without `--prune` it deletes no assignment or deny (only the role-visibility edges invariant 18 forbids) and reports them as `extra-fact`. (Until 2.4.0-alpha.9 this line, and the command's first line, claimed the pass deleted nothing while `--prune` deleted them — measured by a consumer.) It is also what makes `--dry-run` usable as the CI verifier of a `facts` deployment: a correct store now comes out **clean** instead of reporting every live fact as `extra-fact`. (A driver in that position that cannot enumerate its own facts is 500 `E_AUTHZ_UNSUPPORTED` naming `enumerateFacts` — reading `authz_*` for it would be the bug.)
+- **`--from=<driver>` is given**: you decide. If that driver's facts are `authz_*` (the package's `database`), `--to=openfga` is the **one-way migration** it always was, and it will happily overwrite the destination's facts with what those tables hold. That is what you want while migrating — and it is a loaded gun pointed at a store that is already live, which is why it now takes an explicit `--from` to fire it. **Except towards the active driver (2.4.0-alpha.10, breaking):** if `--to` is `config.default`, the only legitimate source is `--to` itself (the maintenance pass above); any other **resolved** source — named with `--from`, picked by elimination without `--from` (with `database` active, `--to=database` alone picks `openfga`), or the `authz_*` tables — makes the manager refuse with 500 `E_AUTHZ_STALE_SOURCE_REFUSED` before resolving the source, reading or freezing anything. That is the **stale direction**: once the engine serves from `--to`, its facts are written there and the source stopped seeing them, so the pass would re-write what was revoked since the cutover (with or without `--prune`; and the mass-deletion guard does not fire, because the source is stale, not empty). The guard looks at `--to` and at the source it resolves, never at the flag — and at the *resolved* driver, not the key: the same factory registered under two keys is the same driver, so an alias of `config.default` is refused too (**declared limit**: identity is the factory *reference*, so two different factories that build the same backend are not detected and such an alias passes; register an alias with the same reference, and a backend identity declared by the driver is on the 2.5 list) — so the four rows are: maintenance pass — runs; initial cutover (`--to=<new>` while the engine still serves from the old one) — runs; going back **before** switching `default` — runs; re-running either of the two **after** switching `default` — refused. `authz:relations:reconcile` applies the same rule with the active relations driver (below). `--allow-stale-source` (`allowStaleSource: true`) is the human decision; `--dry-run` never throws, it flags `report.staleSource = { to, from, allowed }`, prints a warning and exits non-zero. **The guard is only as reliable as the `config.default` of the process that runs the command**: it has no durable record of what the fleet serves from, so a migration job or pod started with a different environment (`default: env.get('AUTHZ_DRIVER', 'database')` without that variable) believes another driver is active and the guard is silently off. Run it with the fleet's config; a durable seal of the active driver is on the 2.5 list.
 - **Otherwise** (the destination is not the active driver): the migration of always, facts read from `authz_*`.
 
 **It needs `scopes.enumerateEdges`** in your config: the whole tree, paginated with a cursor. `sqlScopeEdges({ table, uuidColumn, parentColumn, typeColumn })` implements it over a table with a parent column, exactly like `sqlDescendantsOf`. Without it the command refuses (500 `E_AUTHZ_CONFIG`) instead of assuming a flat tree — a flat tree would be an invented hierarchy, and an invented hierarchy grants.
@@ -1071,19 +1208,40 @@ The dangerous interval is not the pass: it is **[end of the last pass → the la
 ```bash
 node ace authz:freeze --reason="cutover to openfga"   # open the window: fleet-wide 503 on writes
 node ace authz:reconcile --to=openfga --from=database # the pass RECOGNISES the operator window
-# … switch config.default, redeploy, verify …
+# if you use relations/: one pass PER PARTITION, inside the same window
+node ace authz:relations:reconcile --to=openfga --from=database [--partition-type=<t> --partition-uuid=<id>]
+# VERIFY HERE, before switching config.default: openfga is not active yet, so this is a plain verifier
+node ace authz:reconcile --to=openfga --from=database --dry-run
+node ace authz:relations:reconcile --to=openfga --from=database --dry-run [--partition-type=<t> --partition-uuid=<id>]
+# … only when both come out clean: switch config.default (and relations.default, if you set it), redeploy …
+node ace authz:reconcile --to=openfga --dry-run        # after the switch: the MAINTENANCE verifier, no --from
 node ace authz:unfreeze                                # close the window
 ```
 
+**Verify before the switch, never with `--from` after it (2.4.0-alpha.10).** Once `config.default` is `openfga`,
+`--to=openfga --from=database` is the stale direction by definition — even inside the same live operator window,
+where nobody has written since the migration — so its `--dry-run` comes out as drift (exit 1) and the real pass is
+500 `E_AUTHZ_STALE_SOURCE_REFUSED`. There is deliberately **no exception for a live window**: a check that is only
+green in one narrow moment teaches operators to reach for `--allow-stale-source`, which is the one flag that must stay
+rare. So the runbook verifies while the destination is not active yet, and after the switch the roles verifier is the
+maintenance pass (`--to=openfga --dry-run`, no `--from`: it reads the store itself). Relations have no maintenance
+pass: their verification is the pre-switch `--dry-run`.
+
+**Relations move with `config.default` (2.4.0-alpha.10).** The relations service resolves its driver as **`relations.default ?? config.default`**: if you did not set `relations.default`, switching `config.default` switches `relations/` too — and a store with zero relation tuples denies every `check` (fail-closed, total), while `authz:reconcile --to=openfga --dry-run` comes out clean (it does not govern relation tuples). So the relations pass belongs to the cutover window, **one partition per pass** (`authz:relations:reconcile` is per partition; a multi-tenant migration is a loop you write), before the switch. If you set `relations.default`, it is that key — not `config.default` — that decides which relations driver serves, and the stale-direction guard of `authz:relations:reconcile` uses the same resolution: once `relations.default ?? config.default` is the destination, no other source is accepted (500 `E_AUTHZ_STALE_SOURCE_REFUSED`, with or without `--from`, unless `--allow-stale-source`; `--dry-run` flags it). There is no maintenance pass for relations: after the cutover the active relations driver *is* the source of truth.
+
 `authz:reconcile` treats a live **operator** freeze as its own context: it runs inside it, does not take a second freeze, does not renew it and does not lift it when the pass ends — and its report's `frozen.fence` names the window it ran in (with `lapsed: true` if the window did not survive the whole pass). A live freeze of *another* pass is 423 instead: two migrations never interleave. **The operator window does not expire by default** — a cutover has no known duration in advance (window length and outage tolerance are independent magnitudes, the same argument that killed a fixed TTL), and a window that expires mid-cutover silently hands back exactly the fail-open this mechanism exists to close. The declared price: forget `authz:unfreeze` and the fleet cannot write until someone runs it — a *loud* incident (every 503 names the reason and the command that lifts it), not an invisible loss. `--lease-ms` is the opposite opt-in: the window lifts itself after that many milliseconds with nobody renewing it (the command has exited), and *its* declared price is that a cutover slower than the lease resumes the writers silently, mid-cutover. `authz:unfreeze` lifts an operator window; it refuses to lift a live pass's freeze unless you pass `--fence=<n>` (the explicit human decision for a process that died without a lease — and a stale fence lifts nothing).
 
-**`--prune` refuses to run blind.** If it would delete facts while the source has not contributed a single **usable** one, it stops with 500 `E_AUTHZ_MASS_RECONCILE_REFUSED` before writing anything: that is the signature of a wrong connection, of the wrong source, or of a resolver that no longer resolves any of the source's scopes. Until 2.3 the guard looked at the *raw* count — incremented before each skip — so a source whose facts were **all discarded** (every one expired, or on scopes your tree no longer knows) disarmed it and `--prune` emptied the destination with a green report; now a fact only counts if it actually backs something the pass would keep, and the error says how many were read and discarded. `--allow-mass-delete` is the human decision; `--dry-run` never throws, it flags it. A source that is merely **stale** but still partially usable is not this guard's job: what protects you there is the rule above (the facts are read from whoever owns them).
+**An expired operator window is evidence, not free space (2.4.0-alpha.10).** A `reconcile` (roles or relations) — or any `freeze()` — that finds the operator window **expired** no longer takes a freeze of its own over it: until 2.4.0-alpha.9 it certified itself with its own 15 s window and, on release, cleared the row, erasing the only trace that writers had resumed mid-cutover. It is now 503 `E_AUTHZ_OPERATOR_WINDOW_EXPIRED` naming when the window expired; acknowledge it with `authz:unfreeze` and reopen it with `authz:freeze`. (An expired freeze of a *pass* is still taken over — that is the lease after a `SIGKILL`.) And both reconcile commands now always say **which window** the pass ran in: inside the operator window (fence N), or a window of its own because no operator window was live — until alpha.9 those two outputs were identical.
+
+**`authz:unfreeze` on a window that already EXPIRED is an error, not a no-op (2.4.0-alpha.10).** A window opened with `--lease-ms` that expired before `authz:unfreeze` used to look exactly like "there was no window" and the command said success — the last step of the cutover hid that the writers had resumed halfway, i.e. writes the new engine may not have seen. The row tells them apart (lifting clears the reason; an expired window keeps it, with its expiry in the past), so `authz:unfreeze` now prints an error naming when the window expired (ISO) and for how long the fleet has been writing, **exits non-zero**, and clears the row — a second `authz:unfreeze` is a plain success, and "there never was a window / already lifted" is still success. `manager.lastFreezeStatus()` is the reader that also returns the expired row (`expired: true`); `freezeStatus()` still returns only a live freeze. Don't call the cutover done: repeat the migration inside a window without expiry. And a pass that runs inside an operator window with an expiry now says so: `report.frozen.untilMs` is the window's expiry and `frozen.leaseMs` what it had left when the pass adopted it (`null` only for a window that does not expire).
+
+**`--prune` refuses to run blind.** If it would delete facts while the source has not contributed a single **usable** one, it stops with 500 `E_AUTHZ_MASS_RECONCILE_REFUSED` before writing anything: that is the signature of a wrong connection, of the wrong source, or of a resolver that no longer resolves any of the source's scopes. Until 2.3 the guard looked at the *raw* count — incremented before each skip — so a source whose facts were **all discarded** (every one expired, or on scopes your tree no longer knows) disarmed it and `--prune` emptied the destination with a green report; now a fact only counts if it actually backs something the pass would keep, and the error says how many were read and discarded. `--allow-mass-delete` is the human decision; `--dry-run` never throws, it flags it. A source that is merely **stale** but still partially usable is not this guard's job: what protects you there is the rule above (the facts are read from whoever owns them) and, when `--from` points at a stale source towards the active driver, `E_AUTHZ_STALE_SOURCE_REFUSED`.
 
 **The declared cap on the dump (2.3).** Reconciling means comparing against the **whole** state of the destination — without that snapshot there is no way to know what is left over, and "what is left over" is half the job. The *source* is read in batches with a cursor; the destination snapshot is not, and it is held in memory. That is declared rather than hidden: above `--max-tuples` (default 1 000 000) the pass refuses with 500 `E_AUTHZ_RECONCILE_TOO_LARGE` **before writing anything**, naming the cap. There is no partitioned migration in this version, and "resumable" means *idempotent and repeatable* — a pass that was interrupted is resumed by running it again; the second one converges and what was already written comes back as `unchanged` — not "a cursor persisted between runs".
 
 **Migration is not lossless, and the losses are declared.** Run `runMigrationContract` (below) against your own pair: it seeds a fixed fixture, asks **448 identical questions** on both ends and fails if a single answer changes without a declared loss, if the pass counted a skip you did not declare, or if a seeded fact is simply **missing from the destination** with nothing declaring it — that last one is the census, and it does not depend on any of the 448 moving.
 
-**The way out of a store written by the previous version.** After 2.3 "a store written by the previous version is not read by this one": the old importer wrote assignments without the two (c2) edges and denies as `deny_binding` objects, a type the current model does not declare. `authz:reconcile --to=openfga --from=database --prune` rebuilds the store from `authz_*` — the source of truth *of that migration*, named out loud because the store you are rebuilding may already be the live one (see [whoever owns the facts](#migrating-and-verifying-authzreconcile-23)) — and clears the leftovers — a tuple whose type the model no longer declares can still be read and deleted (measured against the server). That store grants again after one pass.
+**The way out of a store written by the previous version.** After 2.3 "a store written by the previous version is not read by this one": the old importer wrote assignments without the two (c2) edges and denies as `deny_binding` objects, a type the current model does not declare. `authz:reconcile --to=openfga --from=database --prune` rebuilds the store from `authz_*` — the source of truth *of that migration*, named out loud — and clears the leftovers — a tuple whose type the model no longer declares can still be read and deleted (measured against the server). That store grants again after one pass. **Run it while `database` is still `config.default`** (2.4.0-alpha.10): if `openfga` is already the active driver, that command is the stale direction and the manager refuses it with 500 `E_AUTHZ_STALE_SOURCE_REFUSED` before reading or freezing anything — `authz_*` stopped seeing the store's writes at the cutover, so rebuilding from them would resurrect every revocation since (and `--prune` would delete what was granted since). If the store is already live *and* you know for a fact that nothing has been written to it since — a store written by the previous version that nobody served from — `--allow-stale-source` is the explicit human decision; run the same command with `--dry-run` first, which flags `report.staleSource` instead of throwing.
 
 ### Operational notes for this driver
 
@@ -1138,8 +1296,10 @@ Every bound the package enforces or measured, in one place, each with the consta
 | Depth gate on writes (opt-in, 2.4.0-alpha.5) | `scopes.maxDepth` | none by default; set it to 22 for `facts` | the manager, `scopes.attached`/`scopes.moved`, every driver | 422 `E_AUTHZ_SCOPE_DEPTH_LIMIT` **before** writing or enqueueing; see below |
 | Authorization-model size | `FACTS_MODEL_MAX_BYTES` | 262,144 | `openfga`, `syncAuthzCatalog` | 500 `E_AUTHZ_MODEL_TOO_LARGE` before writing, warning past 80 % (`FACTS_MODEL_WARN_RATIO`); how many permissions those bytes are is [not a property of the model](#the-model-ceiling-is-bytes-not-permissions) |
 | Checks per `batchCheck` | `FGA_MAX_BATCH_CHECK` | 50 | `openfga`, `authorizeMany` | the driver splits into batches of 50 (the SDK's cap), nothing to do |
+| `ListObjects` effective cut of the server (relations `listObjects`) | `listObjectsDeadlineMs` (`DEFAULT_LIST_OBJECTS_DEADLINE_MS`) | 3,000 ms | the `openfga` relations driver (2.5.0 · B4) | a call that takes ≥ `LIST_OBJECTS_DEADLINE_RATIO` (0.9) × this value returns `truncated: true` — the server cuts at its deadline with a 200 and no signal; set it to the **lowest** of your server's `--listObjects-deadline` (when not 0), `--request-timeout` (3 s by default) and, over HTTP, `--http-upstream-timeout` (5 s by default) — declare that lowest one: with `--listObjects-deadline=0` the request timeout still cuts with a mute 200 (measured on OpenFGA v1.19.0), there is no "no deadline", `Infinity` is 500, both at 0 is not supported (the gateway's cut is not measured for `ListObjects`), and the driver's `timeoutMs` (5 s by default) cannot be lower than `listObjectsDeadlineMs` (500 at construction: the signal has to fire before the client cuts; `Number.MAX_SAFE_INTEGER` is caught by that). **The price of the conservative signal**: with the default, every `ListObjects` that takes 2,700 ms or more comes back `truncated` even when complete; a consumer that treats `truncated` as a 503 pays that p99 as user-facing 503s — raise the server's deadline (and this value) or handle `truncated` as a partial list, not as an outage |
+| Objects per `checkMany` | `RELATIONS_CHECK_MANY_MAX` | 50 | the `RelationsManager` and both relations drivers (2.5.0) | 422 `E_AUTHZ_CHECK_MANY_BATCH` with zero backend calls — split the list yourself; `[]` is 422 too. One batch is one `batchCheck` in `openfga` and one query in `database` |
 | `Read` page size (enumerations, `enumerateFacts`, `enumerateRelations`) | — | 100 | `openfga` | the server's hard cap: `pageSize: 1000` is a 400; the driver pages until the continuation token is empty — a page with zero tuples **and** a token is not the end; a token that repeats, more than 10,000 pages, or a response without `tuples` is 503 `E_AUTHZ_BACKEND_UNAVAILABLE`, never a shorter enumeration |
-| `enumerateRelations(partition)` / `enumerateRelationsMany(partitions)` cost | — | O(tuples in the store) **per sweep** — one sweep per `enumerateRelations` call, **one sweep for K partitions** with `enumerateRelationsMany` / `reconcileRelations({ partitions })` (2.4.0-alpha.6) | `openfga`, the *source* of `authz:relations:reconcile` | there is no prefix `Read` in OpenFGA (a prefix object answers 200 with **zero** tuples, measured: never "optimise" it that way — the suite spies the filter of every `read`, it is always `{}`); measured 15,000 tuples ⇒ 151 pages ≈ 0.5 s per sweep whatever the partition size; 3 partitions in a 5,000-tuple store: **150 reads / 502–558 ms** as three sweeps → **50 reads / 170–209 ms** as one ([the table](#the-source-sweep-measured)). Run it from a job or a cron, **never from a tenant request** |
+| `enumerateRelations(partition)` / `enumerateRelationsMany(partitions)` cost | — | O(tuples in the store) **per sweep** — one sweep per `enumerateRelations` call, **one sweep for K partitions** with `enumerateRelationsMany` / `runRelationsReconcile(…, { partitions })` (2.4.0-alpha.6) | `openfga`, the *source* of `authz:relations:reconcile` | there is no prefix `Read` in OpenFGA (a prefix object answers 200 with **zero** tuples, measured: never "optimise" it that way — the suite spies the filter of every `read`, it is always `{}`); measured 15,000 tuples ⇒ 151 pages ≈ 0.5 s per sweep whatever the partition size; 3 partitions in a 5,000-tuple store: **150 reads / 502–558 ms** as three sweeps → **50 reads / 170–209 ms** as one ([the table](#the-source-sweep-measured)). Run it from a job or a cron, **never from a tenant request** |
 | Hops the `only` probe walks back to inherit a block's origin | `RELAY_ORIGIN_MAX_HOPS` | 100 | the manager, `relayScopeChanges({ only })` | the origin is taken as a real block and the entry stays `deferred` (the purge waits for a full pass); one `earlierPending` query per hop |
 | Interval between `acquire()` retries under `waitForLeaseMs` | `RELAY_LEASE_POLL_MS` | 25 ms | the manager, `relayScopeChanges({ waitForLeaseMs })` and `requeueScopeChanges({ apply, waitForLeaseMs })` | the budget is spent in polls of this size; past it the pass reports `busy` (default `waitForLeaseMs` is 0: one attempt) |
 | Scopes a `pending()` pass reads per round trip | `DEFAULT_RELAY_BATCH` | 100 | `authz:scopes:relay` (`--batch-size`) | the pass keeps paging |
@@ -1274,6 +1434,284 @@ ALTER TABLE authz_roles
 ALTER TABLE authz_permissions ADD COLUMN assignable_at varchar(500) NULL;
 ```
 
+### Upgrading to 2.5.0: non-canonical partition spellings
+
+There is **no `2.4.0` stable**: the 2.4 line ends at `2.4.0-alpha.10` and the next stable is **2.5.0** (the
+plan 2.5: this lot is `2.5.0-alpha.1`; the tenancy work — deny, `decideMany`, `listObjectsForSubject` — follows
+in the same line). Three things change for an installation on `2.4.0-alpha.x`:
+
+1. **A relation partition whose uuid is 32 hex without its dashes and is not exactly `8-4-4-4-12` is 422** (D4,
+   above): the dashless spelling *and* every other placement of the dashes that PostgreSQL folds into the same
+   `uuid`. Those spellings were accepted until now, so any tuple written that way is unreachable from the API
+   after the upgrade — not granting, not purgeable, not enumerable. **It is also a grant the canonical purge never
+   saw**: a share written through the id of the URL (no dashes) survived `purgeSubject(user, <canonical tenant>)`
+   on 2.4, and an `unrelate` or a shorter `expiresAt` written by the canonical spelling never reached it. That is
+   why the recipe has **three branches and the default one writes nothing**: the default is the detector, the
+   list and two counts (rows *with* a canonical twin / rows *without* one) — read-only, run it as many times as
+   you like. The two branches that write are explicit: **`--delete`** (fail-closed: the rows go away — a grant
+   the canonical purge never saw does not survive the upgrade) and **`--rekey`** (the rows are re-keyed to the
+   canonical spelling; a non-canonical row whose canonical twin exists is dropped and the twin is left exactly
+   as it is — an expiry is **never extended**, `NULL` does not win — the rest are re-keyed with their own expiry).
+   **Which branch is yours depends on which population you are** — the detector lists the same rows for both,
+   so look at your ids, not at the count:
+   - *Population A — your tenant ids are uuids, written somewhere without their dashes (the id of a URL, a
+     `uuid` column read as hex, …).* The detector lists **some** of your partitions. These rows are aliases of
+     the canonical partition, invisible to its purge: **`--delete`** is your branch. `--rekey` cannot tell
+     "written dashless and never revoked" from "revoked by the canonical spelling and surviving through the
+     alias", so it is a decision taken after reading the list, not a default (the audit's scenario — purge by
+     the canonical spelling, then the recipe — is pinned as "still revoked" after `--delete` and "granted again,
+     as reviewed" after `--rekey`).
+   - *Population B — your tenant ids were never uuids: 32 hex characters by construction
+     (`randomBytes(16).toString('hex')`, md5, …), with or without dashes at non-uuid positions.* The detector lists
+     **every one of your partitions** (that is the signature) and nothing is an alias of anything: **`--rekey`** is
+     your branch — it keeps every relation and moves it under the `8-4-4-4-12` spelling of the same 32 hex
+     (pinned: a population-B store keeps all its tuples and answers `check` by the dashed id) — and from 2.5.0 on
+     you pass that spelling to the API (`dashedUuid(hex)` is exported). **Running `--delete` on this population
+     empties `authz_relations`**, which is why neither branch runs without its explicit statements.
+   All three branches are executed verbatim by the suite on PostgreSQL, MySQL and SQLite (`upgrade_recipe.spec`),
+   twice (idempotent), the default one pinned as zero writes. The detector uses the same rule as `assertPartition`:
+   what the API rejects, the detector lists (pinned). One statement per line, run each line whole. A partition id
+   that is not a uuid once the dashes are removed (31 or 33 hex, 32 characters that are not all hex) is untouched:
+   it is a legal id.
+2. **F-05 is demanded of the driver called directly** (D13): `runRelationsDriverContract` now calls the harness
+   driver without the manager and expects the same 422s — on `membersOf` too when the driver declares
+   `membersOfNative`, and `checkMany` called directly must refuse 51 objects and `[]`. A third-party harness
+   that seeded undeclared types straight through its driver breaks on purpose; the in-memory double already
+   behaved this way since lot 0. **Since `2.5.0-alpha.2` the same is demanded for B3** (closure 1 of lot B): a
+   userset subject that is not `group#member` must be 422 `E_AUTHZ_RELATION_USERSET_UNSUPPORTED` through the
+   manager *and* through the driver called directly, on `relate`/`unrelate`/`check`/`checkMany`/`listObjects`/
+   `purgeSubject` — through the manager with zero driver calls, spied — (29 core cases per harness). A third-party
+   driver that stored such a row inert, or answered 503, passed the contract until then.
+3. **`checkMany` and `relationTupleKey` are additive** (`relationTupleKey` demands `kind`: there is no default);
+   `contractRelationsConfig()` declares a second object type (`workspace`, same relations as `document`) so the
+   mixed-types case is observable — a harness that asserted on the published model of that config sees one type
+   more. `createTestClock` lives at **`@jantstack/adonis-authz/testing/clock`** (no Japa or Lucid import):
+   import it from there in a config file production loads.
+
+**Lot B (`2.5.0-alpha.2`) — the breaking changes decided for before the first 2.x stable**, each with how to adapt:
+
+4. **A cycle in `includes` is 422 at `defineRelationsConfig`** (B1): `editor ⊇ viewer ⊇ editor` (direct, two or more
+   relations) used to be accepted — `database` served it, `openfga:provision` could not publish it. The message names
+   the cycle (`document#editor → document#viewer → document#editor`). *Adapt*: remove the edge that closes it; a diamond
+   (`viewer ⊇ editor ⊇ owner` and `viewer ⊇ owner`) is fine.
+5. **An unknown key anywhere in the relations spec is 422 `E_AUTHZ_RELATION_CONFIG_UNKNOWN_KEY`** (B2), naming the path
+   (`objectTypes[1].deny`, `objectTypes[0].relations[1].denny`, `database.foo`) and the allowed keys of that level — until
+   now every unknown key was dropped in silence. **The roles `defineConfig` rejects unknown keys too** (500
+   `E_AUTHZ_CONFIG`, root and the `openfga`/`scopes`/`relations`/`hooks` blocks — and since `2.5.0-alpha.2` the roles
+   check also runs in the `AuthorizationManager` constructor and in the relations service, so a config exported without
+   `defineConfig` is judged too; a block that is not an object, `scopes: true`, is 500 as well). *Adapt*: fix the typo or
+   remove the key; if you were parking a key for a future version, it does not belong in the spec yet. **The persisted
+   copy is revalidated too**: `saveRelationsConfig` before 2.5.0 stored the spec *as given*, unknown keys included, so a
+   row written then that carries one (or an `includes` cycle, B1) makes `readRelationsConfig()` 422 and
+   `authz:relations:reconcile` stops with its own line — *"la config persistida en authz_relations_config NO valida en
+   2.5: <motivo>"* — distinct from the unreadable-table line (point 8). *Adapt*: re-save it once from a process with
+   the corrected static config, `saveRelationsConfig(<corrected spec>)` (the spec, not the frozen config: passing the
+   output of `defineRelationsConfig` is 422 with that hint), and run the pass again.
+6. **A userset subject that is not `group#member` is 422 `E_AUTHZ_RELATION_USERSET_UNSUPPORTED`** (B3) on `relate`/
+   `unrelate`/`check`/`checkMany`/`listObjects`/`purgeSubject`, in both drivers and the manager, before any backend
+   call. Until now `database` stored such a row inert and `openfga` answered a misclassified 503. *Adapt*: relate the
+   holder or the group, never the relation of another object. **Rows written before 2.5.0 with such a subject are a
+   residue the package lists but never deletes**: `listSubjects` still returns them (output is not validated),
+   `purgeSubject(userset)` no longer reaches them (422), and `purgeObject(<the tuple's own object>)` removes them only
+   together with every legitimate share of that object (`purgeObject` on the userset's object does not touch them).
+   `authz:relations:reconcile` classifies them **in the plan, before any driver call**, on both sides and with or
+   without the persisted config: one enumerated from the *source* counts in `skipped.usersetUnsupported` and is listed
+   in `details` (`side: 'origen'`, `reason: 'userset-unsupported'`); one found in the *destination* counts in `extra`
+   and is listed (`side: 'destino'`, `pruned: false` under `--prune`) — **`--prune` never deletes it** (no platform
+   `DELETE` on a row the API does not admit), the pass writes and prunes everything else, `--dry-run` and the real pass
+   give the same numbers (declared limit: if the persisted config and the destination driver's config differ —
+   `saveRelationsConfig` is manual — the dry-run classifies with the persisted one and the real pass with the driver's,
+   so the numbers can differ until you re-save the config), and the pass exits ≠ 0 with the residue, its side and the recipe on the line until you run
+   it. The **form** of the userset is judged before the pair's F-05, with or without the persisted config: a residue
+   whose userset names a type or a relation the destination does not declare is still this residue (with the recipe),
+   never `skipped.undeclared` with the false remedy "declare it in the destination". **One rule for every destination
+   row the API does not admit**: a tuple whose identity is outside the grammar (`reason: 'invalid-identity'` — an
+   `object_uuid` written by hand in upper case, say) and — since closure 3 of this release — a row whose **relation or
+   object type the destination no longer declares** (`reason: 'undeclared'`: a relation retired from the config while
+   its rows were still there; `enumerateRelations` filters by type, not by relation, and `unrelate` refuses the row by
+   F-05) have exactly the same semantics — `extra`, listed with `pruned: false` under `--prune`, never asked of the
+   driver when the persisted config is at hand (both package drivers would refuse it in `unrelate`: R-16 for the
+   grammar, F-05 for `undeclared`), exit ≠ 0 with or without `--prune`, the remedy on the line ("delete it by hand
+   (SQL/SDK)"; for `undeclared`, "or declare the relation again in the destination and re-save its persisted config"),
+   and never "repeat with `--prune`" (that advice is printed only for what `--prune` really deletes, and only when
+   `--prune` was not passed; the report carries `prune`). Without the persisted config (`reconcileRelations` called
+   with no `toConfig`) the plan cannot anticipate F-05 — `--dry-run` counts that row in `deleted`, the declared limit
+   of L-0 for `written` — and the real pass **catches only the 422s of the relations family** from `unrelate`
+   (`E_AUTHZ_RELATION_TYPE_UNKNOWN`, `E_AUTHZ_RELATION_UNKNOWN`, `E_AUTHZ_RELATION_USERSET_UNSUPPORTED`,
+   `E_AUTHZ_INVALID_IDENTITY`), classifies each by code, goes on with the other rows and lists it the same way; any
+   other error still propagates (that is the driver contradicting the plan for a reason the report cannot count).
+   Until `2.5.0-alpha.2` such a tuple was asked of the driver, a destination residue under `--prune` aborted the pass
+   mid-way (after writing), a source residue was counted as `skipped.undeclared` with a false remedy, and — until
+   closure 3 — a retired relation's row made `--prune` throw `E_AUTHZ_RELATION_UNKNOWN` mid-pass, after writing, on
+   every run (🟠 N9 of the final audit: `--prune` was unusable for that partition). The recipe — one detector and one `DELETE`, the same
+   statements on PostgreSQL, MySQL and SQLite, executed verbatim by the suite on the three (`upgrade_recipe.spec`) and
+   printed on the reconcile line:
+
+```sql
+-- B3 · userset residue (PostgreSQL, MySQL and SQLite: the same two statements)
+-- 1 · detector: every row whose subject is a userset other than group#member (zero rows = nothing to do)
+SELECT uuid, partition_key, object_type, object_uuid, relation, subject_type, subject_uuid, subject_relation FROM authz_relations WHERE subject_relation <> '' AND NOT (subject_type = 'group' AND subject_relation = 'member');
+-- 2 · delete them (holders have subject_relation = ''; a pre-L-4b NULL holder is excluded too: NULL <> '' is not true)
+DELETE FROM authz_relations WHERE subject_relation <> '' AND NOT (subject_type = 'group' AND subject_relation = 'member');
+```
+
+   (on `openfga` such tuples never existed: the server refused them).
+7. **`listObjects` of `openfga` signals `truncated: true` on the server's deadline too** (B4): a call that takes ≥ 90 % of
+   `listObjectsDeadlineMs` (default 3,000 ms, OpenFGA's default `--listObjects-deadline`). *Adapt*: set `listObjectsDeadlineMs`
+   to your server's **effective** cut in `OpenFgaRelationsDriver`; code that already handled `truncated` needs nothing else; code
+   that assumed the list complete on a slow server was wrong before and is told now. The value is the server's
+   **effective** cut — whichever is lower of the three: `--listObjects-deadline` (when it is not 0), `--request-timeout`
+   (3 s by default) and, over HTTP, the gateway's `--http-upstream-timeout` (5 s by default); declare that lowest one. A server that runs with **`--listObjects-deadline=0`** does **not** run without a deadline:
+   its `--request-timeout` still cuts `ListObjects` with a mute 200 (measured on OpenFGA v1.19.0 by the audit of this
+   release, 40,000 tuples: `--request-timeout=30ms` ⇒ `200`, 0 objects of 40,000, three runs; control with 30 s ⇒
+   40,000 of 40,000; in the source, `list_objects.go` sets its own timeout only when the deadline is not 0 and the
+   request-timeout interceptor returns the partial result without a signal) — declare *that* value. The earlier advice
+   of this release (`Infinity` on the driver for a deadline of 0) is withdrawn: it was measured against a
+   whole list that returned in 5 ms, which cannot tell "no deadline" from "deadline = request timeout", and it made
+   the driver pass the mute partial list as complete — strictly worse than the default; `Infinity` is now 500
+   `E_AUTHZ_CONFIG` ("the server always cuts at one of the two; declare the lower one"), like `NaN`, `0` and
+   negatives (`0` on the driver would mean "everything truncated"). Both at 0 is not supported: the HTTP gateway's
+   `--http-upstream-timeout` (5 s) is not measured for `ListObjects`, and the package promises no "no deadline" it
+   has not measured. And the driver's `timeoutMs` (5 s by default) cannot be lower than `listObjectsDeadlineMs`
+   (closure 3, ⚪ N10): a deadline the client cuts before the 0.9 threshold is a signal that can never fire — and if
+   the server cuts earlier, a mute list passes as complete — so `listObjectsDeadlineMs > timeoutMs` is 500
+   `E_AUTHZ_CONFIG` at construction ("the signal has to be able to fire before the client cuts"), which also closes
+   `Number.MAX_SAFE_INTEGER`, "no deadline" under another name. *Adapt*: a driver built with a `timeoutMs` below
+   3,000 ms must now declare a `listObjectsDeadlineMs` at or below it. And since `2.5.0-alpha.2` a `ListObjects` that answers 200 **without `objects`** is
+   503 `E_AUTHZ_BACKEND_UNAVAILABLE`, like a `Read` without `tuples` — the same for the three `Read`s of the roles
+   driver (`readAllTuples`, the reconcile dump, `enumerateFacts`), where such a response used to read as an empty
+   enumeration and `purgeScope` "proved" zero on it.
+8. **`authz:relations:reconcile` stops (exit 1) when `authz_relations_config` cannot be read** (B5) — before building,
+   freezing or writing anything; "no config persisted" (`null`) still runs and says so. A persisted config that **does
+   not validate in 2.5** (a pre-2.5 row with a key 2.4 dropped in silence, an `includes` cycle, corrupt JSON) is a
+   fourth branch with its own line, *"NO valida en 2.5: <motivo> … saveRelationsConfig(<spec corregida>)"* — never
+   sold as "the read failed" nor as "no config" (point 5). *Adapt*: nothing, unless a cron relied on the silent
+   continuation: give the command a readable database; for the fourth branch, re-save the corrected spec once.
+9. **`sqlScopeOutbox()` requires `{ transaction }` by default** (B6): `scopes.attached/moved/detached` (and
+   `outbox.enqueue`) without the open transaction of the outbox's connection are **500 `E_AUTHZ_CONFIG` before the
+   `INSERT`**. *Adapt*: pass `{ transaction: trx }` from `db.transaction()` as the recipe above shows; if you really
+   enqueue outside any unit of work (a seeder, a platform job), say so: `sqlScopeOutbox({ requireTransaction: false })`.
+   `{ transaction }` through the manager needs a pool ≥ 2 (the freeze barrier reads through another connection; with
+   one connection it is 503 `E_AUTHZ_BACKEND_TIMEOUT` at `freezeTimeoutMs`), so with **pool max 1 — knex's default for
+   every SQLite connection, file or `:memory:`** — keep the opt-out; the 500 says so too. A third-party outbox
+   judged by `runScopeOutboxContract` declares the new optional capability `requiresTransaction` (absent = `false`) and,
+   with `true`, hands the judge `transactions.begin()`.
+10. **`runRelationsReconcile` is imported from `@jantstack/adonis-authz/relations/reconcile`** (B7); the command module
+    `./commands/authz_relations_reconcile` no longer exports it (nor `RunRelationsReconcileOptions`). *Adapt*: change the
+    import path; the signature is the same.
+11. **The roles reconcile verifier reads the pinned model** (B8): with `modelId` set on `OpenFgaAuthorizationDriver`, the
+    pass checks the catalog against *that* model, not the latest one in the store. *Adapt*: nothing; a pass that used to
+    report `permission-not-in-model` for a permission only present in a newer model now projects it under the pinned one
+    — and one that used to die with a 503 mid-pass (permission in the latest model but not in the pinned one) now counts
+    it. The runbook rule stands: publish and roll out the model **before** the window, never inside it.
+
+**Default (read-only): detect, list, count.** Nothing is written. Statement 3 says, per branch, what `--rekey`
+would do: a row *with* a canonical twin is dropped by it, a row *without* one is re-keyed.
+
+```sql
+-- D4 · PostgreSQL
+-- 1 · detector: non-canonical partitions and how many tuples each one holds (zero rows = nothing to do)
+SELECT partition_key, COUNT(*) AS tuples FROM authz_relations WHERE replace(split_part(partition_key, '|', 2), '-', '') ~ '^[0-9a-f]{32}$' AND split_part(partition_key, '|', 2) !~ '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' GROUP BY partition_key;
+-- 2 · the list: every tuple that is about to be deleted — review it (an offboarded user in it is the reason this is the default)
+SELECT uuid, partition_key, object_type, object_uuid, relation, subject_type, subject_uuid, subject_relation, subject_partition, expires_at FROM authz_relations WHERE replace(split_part(partition_key, '|', 2), '-', '') ~ '^[0-9a-f]{32}$' AND split_part(partition_key, '|', 2) !~ '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' ORDER BY partition_key, object_type, object_uuid;
+-- 3 · the counts: rows WITH a canonical twin (--rekey drops them) and rows WITHOUT one (--rekey re-keys them); --delete removes both
+SELECT CASE WHEN EXISTS (SELECT 1 FROM authz_relations c WHERE c.partition_key = split_part(d.partition_key, '|', 1) || '|' || substr(replace(split_part(d.partition_key, '|', 2), '-', ''), 1, 8) || '-' || substr(replace(split_part(d.partition_key, '|', 2), '-', ''), 9, 4) || '-' || substr(replace(split_part(d.partition_key, '|', 2), '-', ''), 13, 4) || '-' || substr(replace(split_part(d.partition_key, '|', 2), '-', ''), 17, 4) || '-' || substr(replace(split_part(d.partition_key, '|', 2), '-', ''), 21, 12) AND c.object_type = d.object_type AND c.object_uuid = d.object_uuid AND c.relation = d.relation AND c.subject_type = d.subject_type AND c.subject_uuid = d.subject_uuid AND c.subject_relation = d.subject_relation) THEN 'with-canonical-twin' ELSE 'without-twin' END AS twin, COUNT(*) AS tuples FROM authz_relations d WHERE replace(split_part(d.partition_key, '|', 2), '-', '') ~ '^[0-9a-f]{32}$' AND split_part(d.partition_key, '|', 2) !~ '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' GROUP BY 1;
+```
+
+```sql
+-- D4 · MySQL
+-- 1 · detector: non-canonical partitions and how many tuples each one holds (zero rows = nothing to do)
+SELECT partition_key, COUNT(*) AS tuples FROM authz_relations WHERE partition_key LIKE '%|%' AND REPLACE(SUBSTRING_INDEX(partition_key, '|', -1), '-', '') REGEXP '^[0-9a-f]{32}$' AND SUBSTRING_INDEX(partition_key, '|', -1) NOT REGEXP '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' GROUP BY partition_key;
+-- 2 · the list: every tuple that is about to be deleted — review it (an offboarded user in it is the reason this is the default)
+SELECT uuid, partition_key, object_type, object_uuid, relation, subject_type, subject_uuid, subject_relation, subject_partition, expires_at FROM authz_relations WHERE partition_key LIKE '%|%' AND REPLACE(SUBSTRING_INDEX(partition_key, '|', -1), '-', '') REGEXP '^[0-9a-f]{32}$' AND SUBSTRING_INDEX(partition_key, '|', -1) NOT REGEXP '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' ORDER BY partition_key, object_type, object_uuid;
+-- 3 · the counts: rows WITH a canonical twin (--rekey drops them) and rows WITHOUT one (--rekey re-keys them); --delete removes both
+SELECT CASE WHEN EXISTS (SELECT 1 FROM authz_relations c WHERE c.partition_key = CONCAT(SUBSTRING_INDEX(d.partition_key, '|', 1), '|', SUBSTRING(REPLACE(SUBSTRING_INDEX(d.partition_key, '|', -1), '-', ''), 1, 8), '-', SUBSTRING(REPLACE(SUBSTRING_INDEX(d.partition_key, '|', -1), '-', ''), 9, 4), '-', SUBSTRING(REPLACE(SUBSTRING_INDEX(d.partition_key, '|', -1), '-', ''), 13, 4), '-', SUBSTRING(REPLACE(SUBSTRING_INDEX(d.partition_key, '|', -1), '-', ''), 17, 4), '-', SUBSTRING(REPLACE(SUBSTRING_INDEX(d.partition_key, '|', -1), '-', ''), 21, 12)) AND c.object_type = d.object_type AND c.object_uuid = d.object_uuid AND c.relation = d.relation AND c.subject_type = d.subject_type AND c.subject_uuid = d.subject_uuid AND c.subject_relation = d.subject_relation) THEN 'with-canonical-twin' ELSE 'without-twin' END AS twin, COUNT(*) AS tuples FROM authz_relations d WHERE d.partition_key LIKE '%|%' AND REPLACE(SUBSTRING_INDEX(d.partition_key, '|', -1), '-', '') REGEXP '^[0-9a-f]{32}$' AND SUBSTRING_INDEX(d.partition_key, '|', -1) NOT REGEXP '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' GROUP BY 1;
+```
+
+```sql
+-- D4 · SQLite
+-- 1 · detector: non-canonical partitions and how many tuples each one holds (zero rows = nothing to do)
+SELECT partition_key, COUNT(*) AS tuples FROM authz_relations WHERE instr(partition_key, '|') > 0 AND replace(substr(partition_key, instr(partition_key, '|') + 1), '-', '') GLOB '[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]' AND substr(partition_key, instr(partition_key, '|') + 1) NOT GLOB '[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]' GROUP BY partition_key;
+-- 2 · the list: every tuple that is about to be deleted — review it (an offboarded user in it is the reason this is the default)
+SELECT uuid, partition_key, object_type, object_uuid, relation, subject_type, subject_uuid, subject_relation, subject_partition, expires_at FROM authz_relations WHERE instr(partition_key, '|') > 0 AND replace(substr(partition_key, instr(partition_key, '|') + 1), '-', '') GLOB '[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]' AND substr(partition_key, instr(partition_key, '|') + 1) NOT GLOB '[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]' ORDER BY partition_key, object_type, object_uuid;
+-- 3 · the counts: rows WITH a canonical twin (--rekey drops them) and rows WITHOUT one (--rekey re-keys them); --delete removes both
+SELECT CASE WHEN EXISTS (SELECT 1 FROM authz_relations c WHERE c.partition_key = substr(d.partition_key, 1, instr(d.partition_key, '|')) || substr(replace(substr(d.partition_key, instr(d.partition_key, '|') + 1), '-', ''), 1, 8) || '-' || substr(replace(substr(d.partition_key, instr(d.partition_key, '|') + 1), '-', ''), 9, 4) || '-' || substr(replace(substr(d.partition_key, instr(d.partition_key, '|') + 1), '-', ''), 13, 4) || '-' || substr(replace(substr(d.partition_key, instr(d.partition_key, '|') + 1), '-', ''), 17, 4) || '-' || substr(replace(substr(d.partition_key, instr(d.partition_key, '|') + 1), '-', ''), 21, 12) AND c.object_type = d.object_type AND c.object_uuid = d.object_uuid AND c.relation = d.relation AND c.subject_type = d.subject_type AND c.subject_uuid = d.subject_uuid AND c.subject_relation = d.subject_relation) THEN 'with-canonical-twin' ELSE 'without-twin' END AS twin, COUNT(*) AS tuples FROM authz_relations d WHERE instr(d.partition_key, '|') > 0 AND replace(substr(d.partition_key, instr(d.partition_key, '|') + 1), '-', '') GLOB '[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]' AND substr(d.partition_key, instr(d.partition_key, '|') + 1) NOT GLOB '[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]' GROUP BY 1;
+```
+
+**`--delete` (population A, after reviewing the list): fail-closed, one statement per engine, run *instead of*
+`--rekey`.**
+
+```sql
+-- D4 · PostgreSQL · --delete
+-- 1 · fail-closed: delete every non-canonical row (grants invisible to the canonical purge do not survive the upgrade)
+DELETE FROM authz_relations WHERE replace(split_part(partition_key, '|', 2), '-', '') ~ '^[0-9a-f]{32}$' AND split_part(partition_key, '|', 2) !~ '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$';
+```
+
+```sql
+-- D4 · MySQL · --delete
+-- 1 · fail-closed: delete every non-canonical row (grants invisible to the canonical purge do not survive the upgrade)
+DELETE FROM authz_relations WHERE partition_key LIKE '%|%' AND REPLACE(SUBSTRING_INDEX(partition_key, '|', -1), '-', '') REGEXP '^[0-9a-f]{32}$' AND SUBSTRING_INDEX(partition_key, '|', -1) NOT REGEXP '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$';
+```
+
+```sql
+-- D4 · SQLite · --delete
+-- 1 · fail-closed: delete every non-canonical row (grants invisible to the canonical purge do not survive the upgrade)
+DELETE FROM authz_relations WHERE instr(partition_key, '|') > 0 AND replace(substr(partition_key, instr(partition_key, '|') + 1), '-', '') GLOB '[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]' AND substr(partition_key, instr(partition_key, '|') + 1) NOT GLOB '[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]';
+```
+
+**`--rekey` (population B, or population A as a reviewed decision): run these two statements *instead of*
+`--delete`.** Two non-canonical spellings of the *same*
+tenant without a canonical twin collide on the unique index of `authz_relations` and the `UPDATE` fails loudly
+(atomically: nothing is re-keyed, for any tenant, until the statement succeeds). Delete one of the two by hand
+first — **keep the row with the nearest expiry (a `NULL` expiry is the farthest) and delete the other one**, so the
+re-keyed tuple never outlives what either row already granted.
+
+```sql
+-- D4 · PostgreSQL · --rekey
+-- 1 · a non-canonical row whose canonical twin exists goes away; the twin is NOT touched (its expiry is never extended)
+DELETE FROM authz_relations d WHERE replace(split_part(d.partition_key, '|', 2), '-', '') ~ '^[0-9a-f]{32}$' AND split_part(d.partition_key, '|', 2) !~ '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' AND EXISTS (SELECT 1 FROM authz_relations c WHERE c.partition_key = split_part(d.partition_key, '|', 1) || '|' || substr(replace(split_part(d.partition_key, '|', 2), '-', ''), 1, 8) || '-' || substr(replace(split_part(d.partition_key, '|', 2), '-', ''), 9, 4) || '-' || substr(replace(split_part(d.partition_key, '|', 2), '-', ''), 13, 4) || '-' || substr(replace(split_part(d.partition_key, '|', 2), '-', ''), 17, 4) || '-' || substr(replace(split_part(d.partition_key, '|', 2), '-', ''), 21, 12) AND c.object_type = d.object_type AND c.object_uuid = d.object_uuid AND c.relation = d.relation AND c.subject_type = d.subject_type AND c.subject_uuid = d.subject_uuid AND c.subject_relation = d.subject_relation);
+-- 2 · the rest are re-keyed to the canonical spelling (and the subject_partition of their usersets with them)
+UPDATE authz_relations SET subject_partition = CASE WHEN subject_partition = partition_key THEN split_part(partition_key, '|', 1) || '|' || substr(replace(split_part(partition_key, '|', 2), '-', ''), 1, 8) || '-' || substr(replace(split_part(partition_key, '|', 2), '-', ''), 9, 4) || '-' || substr(replace(split_part(partition_key, '|', 2), '-', ''), 13, 4) || '-' || substr(replace(split_part(partition_key, '|', 2), '-', ''), 17, 4) || '-' || substr(replace(split_part(partition_key, '|', 2), '-', ''), 21, 12) ELSE subject_partition END, partition_key = split_part(partition_key, '|', 1) || '|' || substr(replace(split_part(partition_key, '|', 2), '-', ''), 1, 8) || '-' || substr(replace(split_part(partition_key, '|', 2), '-', ''), 9, 4) || '-' || substr(replace(split_part(partition_key, '|', 2), '-', ''), 13, 4) || '-' || substr(replace(split_part(partition_key, '|', 2), '-', ''), 17, 4) || '-' || substr(replace(split_part(partition_key, '|', 2), '-', ''), 21, 12) WHERE replace(split_part(partition_key, '|', 2), '-', '') ~ '^[0-9a-f]{32}$' AND split_part(partition_key, '|', 2) !~ '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$';
+```
+
+```sql
+-- D4 · MySQL · --rekey
+-- 1 · a non-canonical row whose canonical twin exists goes away; the twin is NOT touched (its expiry is never extended)
+DELETE d FROM authz_relations d JOIN authz_relations c ON c.partition_key = CONCAT(SUBSTRING_INDEX(d.partition_key, '|', 1), '|', SUBSTRING(REPLACE(SUBSTRING_INDEX(d.partition_key, '|', -1), '-', ''), 1, 8), '-', SUBSTRING(REPLACE(SUBSTRING_INDEX(d.partition_key, '|', -1), '-', ''), 9, 4), '-', SUBSTRING(REPLACE(SUBSTRING_INDEX(d.partition_key, '|', -1), '-', ''), 13, 4), '-', SUBSTRING(REPLACE(SUBSTRING_INDEX(d.partition_key, '|', -1), '-', ''), 17, 4), '-', SUBSTRING(REPLACE(SUBSTRING_INDEX(d.partition_key, '|', -1), '-', ''), 21, 12)) AND c.object_type = d.object_type AND c.object_uuid = d.object_uuid AND c.relation = d.relation AND c.subject_type = d.subject_type AND c.subject_uuid = d.subject_uuid AND c.subject_relation = d.subject_relation WHERE d.partition_key LIKE '%|%' AND REPLACE(SUBSTRING_INDEX(d.partition_key, '|', -1), '-', '') REGEXP '^[0-9a-f]{32}$' AND SUBSTRING_INDEX(d.partition_key, '|', -1) NOT REGEXP '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$';
+-- 2 · the rest are re-keyed to the canonical spelling (and the subject_partition of their usersets with them)
+UPDATE authz_relations SET subject_partition = CASE WHEN subject_partition = partition_key THEN CONCAT(SUBSTRING_INDEX(partition_key, '|', 1), '|', SUBSTRING(REPLACE(SUBSTRING_INDEX(partition_key, '|', -1), '-', ''), 1, 8), '-', SUBSTRING(REPLACE(SUBSTRING_INDEX(partition_key, '|', -1), '-', ''), 9, 4), '-', SUBSTRING(REPLACE(SUBSTRING_INDEX(partition_key, '|', -1), '-', ''), 13, 4), '-', SUBSTRING(REPLACE(SUBSTRING_INDEX(partition_key, '|', -1), '-', ''), 17, 4), '-', SUBSTRING(REPLACE(SUBSTRING_INDEX(partition_key, '|', -1), '-', ''), 21, 12)) ELSE subject_partition END, partition_key = CONCAT(SUBSTRING_INDEX(partition_key, '|', 1), '|', SUBSTRING(REPLACE(SUBSTRING_INDEX(partition_key, '|', -1), '-', ''), 1, 8), '-', SUBSTRING(REPLACE(SUBSTRING_INDEX(partition_key, '|', -1), '-', ''), 9, 4), '-', SUBSTRING(REPLACE(SUBSTRING_INDEX(partition_key, '|', -1), '-', ''), 13, 4), '-', SUBSTRING(REPLACE(SUBSTRING_INDEX(partition_key, '|', -1), '-', ''), 17, 4), '-', SUBSTRING(REPLACE(SUBSTRING_INDEX(partition_key, '|', -1), '-', ''), 21, 12)) WHERE partition_key LIKE '%|%' AND REPLACE(SUBSTRING_INDEX(partition_key, '|', -1), '-', '') REGEXP '^[0-9a-f]{32}$' AND SUBSTRING_INDEX(partition_key, '|', -1) NOT REGEXP '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$';
+```
+
+```sql
+-- D4 · SQLite · --rekey
+-- 1 · a non-canonical row whose canonical twin exists goes away; the twin is NOT touched (its expiry is never extended)
+DELETE FROM authz_relations WHERE instr(authz_relations.partition_key, '|') > 0 AND replace(substr(authz_relations.partition_key, instr(authz_relations.partition_key, '|') + 1), '-', '') GLOB '[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]' AND substr(authz_relations.partition_key, instr(authz_relations.partition_key, '|') + 1) NOT GLOB '[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]' AND EXISTS (SELECT 1 FROM authz_relations c WHERE c.partition_key = substr(authz_relations.partition_key, 1, instr(authz_relations.partition_key, '|')) || substr(replace(substr(authz_relations.partition_key, instr(authz_relations.partition_key, '|') + 1), '-', ''), 1, 8) || '-' || substr(replace(substr(authz_relations.partition_key, instr(authz_relations.partition_key, '|') + 1), '-', ''), 9, 4) || '-' || substr(replace(substr(authz_relations.partition_key, instr(authz_relations.partition_key, '|') + 1), '-', ''), 13, 4) || '-' || substr(replace(substr(authz_relations.partition_key, instr(authz_relations.partition_key, '|') + 1), '-', ''), 17, 4) || '-' || substr(replace(substr(authz_relations.partition_key, instr(authz_relations.partition_key, '|') + 1), '-', ''), 21, 12) AND c.object_type = authz_relations.object_type AND c.object_uuid = authz_relations.object_uuid AND c.relation = authz_relations.relation AND c.subject_type = authz_relations.subject_type AND c.subject_uuid = authz_relations.subject_uuid AND c.subject_relation = authz_relations.subject_relation);
+-- 2 · the rest are re-keyed to the canonical spelling (and the subject_partition of their usersets with them)
+UPDATE authz_relations SET subject_partition = CASE WHEN subject_partition = partition_key THEN substr(partition_key, 1, instr(partition_key, '|')) || substr(replace(substr(partition_key, instr(partition_key, '|') + 1), '-', ''), 1, 8) || '-' || substr(replace(substr(partition_key, instr(partition_key, '|') + 1), '-', ''), 9, 4) || '-' || substr(replace(substr(partition_key, instr(partition_key, '|') + 1), '-', ''), 13, 4) || '-' || substr(replace(substr(partition_key, instr(partition_key, '|') + 1), '-', ''), 17, 4) || '-' || substr(replace(substr(partition_key, instr(partition_key, '|') + 1), '-', ''), 21, 12) ELSE subject_partition END, partition_key = substr(partition_key, 1, instr(partition_key, '|')) || substr(replace(substr(partition_key, instr(partition_key, '|') + 1), '-', ''), 1, 8) || '-' || substr(replace(substr(partition_key, instr(partition_key, '|') + 1), '-', ''), 9, 4) || '-' || substr(replace(substr(partition_key, instr(partition_key, '|') + 1), '-', ''), 13, 4) || '-' || substr(replace(substr(partition_key, instr(partition_key, '|') + 1), '-', ''), 17, 4) || '-' || substr(replace(substr(partition_key, instr(partition_key, '|') + 1), '-', ''), 21, 12) WHERE instr(partition_key, '|') > 0 AND replace(substr(partition_key, instr(partition_key, '|') + 1), '-', '') GLOB '[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]' AND substr(partition_key, instr(partition_key, '|') + 1) NOT GLOB '[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]';
+```
+
+**On `openfga` the store is the tuples themselves**, and the package cannot address a non-canonical partition
+any more (the driver refuses to compose its id), so there is no `--partition-uuid` to reconcile *from* it. The
+non-canonical tuples left in the store grant nothing from the API on 2.5.0. The same three branches, with the SDK:
+the default is to **list** them (`client.read({})` and keep the objects whose partition segment is 32 hex but not
+`8-4-4-4-12`); `--delete` is `client.write({ deletes })` of that list; the `--rekey` equivalent is fail-closed
+while there are no denies (write the canonical tuple first, then delete the old one): if `database` holds the same
+facts, run the SQL `--rekey` there and **`authz:relations:reconcile --to=openfga --from=database
+--partition-type=<type> --partition-uuid=<canonical>`** writes the canonical tuples, then delete the old ones with
+the SDK — which is what the suite executes against a real server (`relations_openfga.spec`, "D4 recipe"). If the
+store is the only copy, read the old tuples with the SDK, write them under the canonical object id and delete the
+old ones in that order. **Roles have nothing to migrate but do have the same rule**: with the consumer's row alive
+the resolver chain canonicalises the scope (invariant 17); where there is no chain — `scopes.detached` after the
+row is gone, `revoke`/`removeDeny` on a scope the tree no longer knows — the purge covers the caller's spelling
+*and* the canonical one it can be an alias of, under `pgFusedSpellings`: **exactly the spellings PostgreSQL's
+`uuid` folds** (hyphens only after groups of four hex digits — dashless, `8-4-4-16`, `8-8-8-8`, `12-4-4-12`…;
+measured against PostgreSQL 18), which is deliberately *narrower* than the partition rule `isNonCanonicalUuid`
+(`-<32hex>`, `<32hex>-`, `a0e-…`, `--` are legal ids PostgreSQL rejects: a 422 too many is harmless, a purge too
+many is not). And a spelling the resolver still knows as a **live** scope is never purged by that fan-out: with
+text scope ids a tenant could otherwise create and delete `<32 hex of another tenant's unit>` and have
+`detached`/`removeDeny` reach the live unit (cierre-3 of lot A). If the resolver fails while checking, the write is
+a 503 — never "purge just in case".
+
 ### Upgrading from 2.4.0-alpha.1: `authz_relations.expires_at`
 
 An installation that migrated 2.4.0-alpha.1 runs **both** recipes below, **in this order** — `expires_at` first (additive, R-15), then `subject_relation` (lot L-4b) — in the **same deploy** as the package upgrade: until the second one is applied, every holder `relate` is refused by the old partition trigger (measured, below). Both are executed verbatim by the suite on the three engines.