@jantstack/adonis-authz 2.5.0-alpha.1 → 2.5.0-alpha.3

package/README.md

@@ -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,13 @@ 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). **`denyPhase` (2.5.0-alpha.3) is judged by the driver
+runner**: with `relationDenies: true`, `runRelationsDriverContract` asks your driver, built on the contract's deny config,
+for the phase of each type (`document` 'write', `workspace` 'read', `note` none) and checks that it is the truth about
+`deny()` ('write' ⇒ the deny lands and `check` is false; 'read' and none ⇒ 422 `E_AUTHZ_RELATION_NOT_DENYABLE`, nothing
+written) plus F-05 (undeclared type, undeclared or missing relation ⇒ 422); with `relationDenies: false`, a `denyPhase` you
+still expose must claim no phase (`null`). It is the gate `authz:relations:reconcile` uses before writing a deny into your
+driver; what the runner cannot see is a driver whose `deny()` and `check` agree with each other and both ignore the opt-in.
 
 ### Identity is validated, once and everywhere
 
@@ -374,7 +380,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
@@ -597,6 +603,166 @@ nothing asked); a per-item `error` inside a 200 `batchCheck` is a **503 for the
 `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.
 
+**Deny on relations (2.5.0).** A relation can be **denied** to a subject on an object: `deny(subject, relation,
+object, partition)` writes the tuple `object#denied_<relation>@subject` (in `authz_relations` on `database`, in the store
+on `openfga`) and **every read honours it** — `check`, `checkMany`, `decideMany`, `listObjects`. It is opt-in **per
+type and in two phases** (`deny: 'read' | 'write'` on the object type in `defineRelationsConfig`; there is no `deny:
+true` — that would be the single switch with no safe rollout order):
+
+- `deny: 'read'` (phase 1): the published model declares `denied_<rel>` (`<rel> … but not denied_<rel>`) and all reads
+  honour it; `deny()` on that type is still 422 `E_AUTHZ_RELATION_NOT_DENYABLE`.
+- `deny: 'write'` (phase 2): writes are accepted too.
+
+The rollout is two deployments: (1) the whole fleet on ≥ 2.5.0-alpha.3 with the type in `'read'`, the model
+republished (`openfga:provision`) and **every pod pinned to the new `modelId`**; (2) verify; (3) a second deployment
+moves the type to `'write'`. With any type in either phase the `openfga` relations driver **requires a pinned
+`modelId`** (500 `E_AUTHZ_CONFIG` at construction otherwise) and checks, once per process, that the pinned model
+declares `denied_<rel>` for every relation of those types **and that `<rel>` subtracts it** (`<rel> … but not
+denied_<rel>`) — a pinned model without it is 500 `E_AUTHZ_CONFIG` on first use, never a grant over a denied object.
+**`decideMany` on `openfga` requires a pinned `modelId` always**, also without deny types (500 `E_AUTHZ_CONFIG`
+naming D14 and the recipe "provision → pin `modelId` → deploy", with zero calls): it picks which `denied_*` to ask
+with the model it read once, and unpinned the server checks with the *latest* model — after a republish with deny it
+would answer `none` where `check` answers `false`. A relation of a deniable type measures **at most 43 characters**
+(`DENIABLE_RELATION_NAME_MAX`: `denied_<rel>` has to fit FGA's 50); a type without `deny` keeps the 50.
+
+**The semantics is a path cut** (decision D5, the 64-state table T1 in the suite): a deny on `Y` cuts every grant of
+`T` with `Y ∈ up*(T)` (everything that includes `T`), with all that derives from it. With `owner ⊆ editor ⊆ viewer`:
+
+| allows | deny | `viewer` / `editor` / `owner` | case |
+|---|---|---|---|
+| owner | viewer | F / F / F | *"D-06 · un deny en viewer bloquea al owner"* |
+| owner | editor | F / F / F | *"D-07 · un deny en editor anula el grant de owner ENTERO"* |
+| owner + viewer | editor | T / F / F | *"D-08 · …salvo un viewer directo"* |
+| viewer | editor | T / F / F | *"D-11 · un deny en una relación MÁS FUERTE no toca un grant más débil"* |
+
+A deny reaches the subject **directly or through `group#member`** (nested groups too), and a group membership that
+expires stops carrying it (a deny itself does not expire). Rules that go with it, each with its case: **no expiry**
+(`expiresAt` on `deny`/`removeDeny` is 422 `E_AUTHZ_DENY_EXPIRY_UNSUPPORTED` — measured on OpenFGA 1.19: a live
+deny's condition cannot be changed without a window in which it stops blocking); no `*` subject and no deny on
+`group` (422 `E_AUTHZ_RELATION_NOT_DENYABLE`); a userset subject must be `group#member`; `deny`/`removeDeny` go
+through the same gates as `relate` (`{ transaction }`, the freeze, F-05, `actor`, `assertWrite` with `operation:
+'deny' | 'removeDeny'`, invariant 13) and notify `onRelationWrite`; `removeDeny` and `listDenies` accept **any declared
+type** (retiring the opt-in must be reversible); `listSubjects` **does not** subtract (it lists facts) and
+`listDenies(relation, object, partition)` lists the direct denies; `listObjects` **does** subtract (on `openfga` the
+server does, so a page cut at the server's cap is a subset — never a denied object), and so does `membersOf` on
+`database` (one `check` per candidate, only when the object has a deny row — at most `RELATIONS_MEMBERS_DENY_CHECK_MAX`
+candidates, 1,000, past it 500 `E_AUTHZ_MEMBERS_DENY_LIMIT` and never a partial list, under one total deadline, 503);
+the purges delete denies too. **On `openfga` a purge that fits in one `Write` is one `Write`**
+(`RELATIONS_PURGE_WRITE_MAX`, 100 tuples — the server's `--max-tuples-per-write` default, measured: 101 is a 400 and
+nothing applies), which FGA applies atomically; a larger one deletes the allows first, then **the subject's group
+memberships in a `Write` of their own** (a membership carries denies too), then the denies — so **a purge cut halfway
+grants nothing that neither the state before nor the state after granted**
+(*"purgeSubject cortada, deny por grupo (holder)"*, *"purgeSubject cortada, deny anidado (userset g#member)"*, and the
+symmetric row — the membership carries the allow, the deny is direct —
+*"purgeSubject cortada, allow por grupo × deny DIRECTO (holder)"*; the same table runs without a server in the surface
+guard, with the five order mutants in `npm run check:guard-mutants`).
+**Declared row:** with more than 100 group memberships of the subject, a membership that carries a deny can fall in an earlier `Write` than one that carries an
+allow, and a purge cut between the two grants until it is repeated (it stays marked `indeterminate: true`; the purge is
+not refused before deleting — a purge does not wait) (*"FILA DECLARADA · purgeSubject con más de 100 membresías de grupo"*).
+**The order of the purge is the same function as the reconcile's** (`relationTransitionOrder`,
+`src/relations/tuple_order.ts`; closure 2 of D2): allows, then memberships (by the precedence graph), then denies; one
+ordering point for every multi-request write or delete of relations.
+**Renewing a membership that carries a deny is refused on `openfga`** (closure 2 of sublot D2, owner's decision): `relate`
+on an EXISTING `group:*#member` tuple with another expiry is, on `openfga`, two `Write`s (delete, write: FGA does not
+replace the same key in one `Write`), and between them the membership is not there — if that group, or a group that
+contains it, is the subject of a live deny of the partition, the subject would be granted (for good, if the second
+`Write` failed). So that renewal is **409 `E_AUTHZ_RENEWAL_UNSAFE` with zero writes** (always zero: closure 4) and an
+honest recipe in the message (closure 5 of D2): on `openfga` **there is no window-free way** to change that expiry (see
+*The limit* below); the recommended pattern is memberships WITHOUT expiry in groups that carry a deny, ended with
+`unrelate`; if the expiry must change, `unrelate` + `relate` **accepting the window**, said as such. (Until closure 5 the
+message also offered "retire the deny first, renew, write it again" as if it were the safe way out: it opens the same
+window.) Cost: only on a membership renewal, one `Read` per deny type and one for the parents, per group up the nesting.
+Every other renewal stays two `Write`s, and if the second fails the error is marked as a **partial write**
+(`isPartialWrite`; `onRelationWrite` gets `indeterminate: true`) — until closure 2 it was a 503 that said nothing was
+written while the tuple was gone. **Declared window** (closure 3 of D2): the carrier check reads, then the two `Write`s
+follow; a `deny` on that group (or one containing it) written CONCURRENTLY, between the check and the delete, does not
+reach the subject during the two `Write`s — and for good if the second one fails, because the membership is gone. The
+driver re-checks after the two `Write`s (and after a failed second one) and the window stops being silent: if the renewal
+went through, it throws **409 `E_AUTHZ_RENEWAL_RACED`** (`RenewalRacedError`; its own code since closure 4 of D2 —
+until then it shared `E_AUTHZ_RENEWAL_UNSAFE`, and automating that code's recipe, `unrelate` + `relate`, here would
+reopen the window with the deny already inside the group) marked partial with `renewalApplied: true` and `carriedDeny`
+naming the deny (the final state is right: there is nothing to rewrite; review that subject's decisions in the window);
+if the second `Write` failed, the 503
+keeps its class and code, is marked partial and carries `carriedDeny` and the recipe (write the membership again: it is
+gone, so `relate` is ONE `Write`). It does not close the window: FGA has no primitive to serialise a `deny` against a
+renewal. A membership that is ALREADY EXPIRED carries nothing (it connects nothing), so rewriting it is not refused,
+and neither is a membership whose only path to a deny is an expired nesting edge. `database` renews in one transaction
+and does not refuse.
+The same rule holds for the role facts' twin: `grant` with another expiry on `openfga` is `deleteTuples` +
+`writeTuples`; if the second fails the `assignee` is already gone (fail-closed: the grant is lost), and since closure 3
+of D2 the 503 is marked partial and `onWrite` gets `indeterminate: true` (until then: "not written", no event); so is
+`purgeScope` of roles on `openfga` (several `Write`s: structure, facts, denies, batches of 100) cut after its first one
+(closure 4 of D2; `indeterminate: true`, as its relations twin). The capability is
+**`atomicRenewal`** (optional, normalised to `false`; `database` `true`, `openfga` `false`): a driver without it must
+refuse that renewal the same way — the runner judges both faces — and `authz:relations:reconcile` does not ask it to renew
+a carrying membership: the plan lists it as the destination residue `renewal-unsafe` (same numbers in `--dry-run` and the
+real pass, a line starting with `sin renovar (renewal-unsafe) destino:` with the recipe, exit ≠ 0). **Not renewing is not
+neutral over time**: the destination would keep the OLD expiry, and from it (an extension) the membership no longer
+carries its deny, or until it (a shortening) it still grants what the source stopped granting. **So the PARTITION is
+refused** (closure 5 of D2, owner's decision: option A): a partition with at least one `renewal-unsafe` or
+`deny-conditional` (below) gets **zero writes and zero deletes** — with `--prune` too, expired leftovers included —, its
+destination stays **exactly as it was**, with its previous drift in view, and **every other partition migrates**. The plan
+decides it, so `--dry-run` and the real pass give the same numbers; `report.partitionsRefused` lists each one with its
+causes, its recipe and what is pending (`write`/`update`/`delete`), its row in `report.partitions` has `status:
+'refused'`, and the command prints one line starting with `partición NEGADA <partition>:` that names the partition and
+the causes and says that its destination stays as it was (exit ≠ 0 while it exists). Refusing does not make the
+destination more restrictive than the source: it leaves it as it was — what it already granted, it still grants, and
+the line shows what is pending. **And "as it was" is not static** (closure 6 of D2): a refused partition IS "not
+renewing", so the drift over time stays — from the old expiry of an extended carrying membership the destination no
+longer carries its deny and **grants what that deny cuts** (if another path grants it) while the source still denies.
+The line says when and what (`a partir de <date> el destino concederá a <subject> lo que cortan <denies>`; in the report,
+`partitionsRefused[].evolves`). Ways out for a refused partition, none free: `unrelate` the membership in the SOURCE and
+repeat; or `unrelate` + `relate` it in the DESTINATION with the source's expiry (or none), accepting the window; or wait
+for the destination's old expiry — then the tuple is absent for the plan, the rewrite is a plain write and the partition
+migrates on its own, with the interval above in between. Making the membership expiry-less in the SOURCE does NOT unlock
+it (the destination's still expires: that is still an expiry change). (Closure 4 withheld, tuple by tuple, what the lost deny would let grant, with a
+pass-wide refusal `carrier-conflict`; measured, that left grants the destination already gave in place without saying so,
+and one tenant could block every other partition with `--prune`. Both are gone.)
+**The limit: changing the expiry of a deny-carrying membership on `openfga`.** FGA cannot replace the same key in one
+`Write` (no upsert: [openfga/openfga#2151](https://github.com/openfga/openfga/issues/2151)), so a renewal is two `Write`s,
+and between them the subject does not get the group's deny. Therefore, on `openfga`: `relate` with another expiry on a
+membership whose group (or a group containing it) carries a live deny is **409 `E_AUTHZ_RENEWAL_UNSAFE`, zero writes**;
+the reconcile refuses that partition when its plan counts that deny (a deny EXPIRED at the pass's `now` carries nothing,
+for the plan and for the driver alike — closure 6 of D2; until then the driver counted it and the real pass aborted with
+a 409 the dry run had not announced). A deny the plan does NOT see can still reach the driver's 409 and abort the pass
+instead (not measured; e.g. a leftover deny on a relation the destination no longer declares).
+**There is no window-free way to do it.** The recommended pattern, for the future: memberships
+**without expiry** in groups that carry a deny, ended with `unrelate`. If an expiry must change: `unrelate` + `relate`,
+**accepting the window** — while it lasts the subject does not get the group's deny and is granted whatever another path
+gives it and that deny cuts. **Declared window (TOCTOU of N1):** a NEW deny on a group written while ANOTHER membership of
+that group is being renewed (its two `Write`s) does not reach that subject in between — the driver re-checks after the
+renewal and says so (`E_AUTHZ_RENEWAL_RACED`), but it cannot close it. `database` renews in one transaction and has
+none of this. **When OpenFGA offers an upsert, the renewal will be one `Write` and `atomicRenewal` will become `true`**
+on `openfga`, without touching the model. **A destination tuple
+that is expired at the pass's `now` is ABSENT for the plan** (closure 3 of D2): rewriting it is a plain write (never a
+renewal, never `renewal-unsafe`), it is not part of the order's context (no carrier, no edge of the self-cut, no
+"renewal" in phase 4), and with `--prune` the expired leftovers are deleted first and outside the order (they connect
+nothing). Until closure 3 an expired carrying membership was taken as live: the pass refused to "renew" it while it
+wrote the new allow, and the destination granted to a subject the source denied, pass after pass.
+**`database` honours a `denied_*` row always**, also on a type without the opt-in (a deny row is a fact): retiring
+`deny` from a type with live denies does not switch them off — remove them with `removeDeny`. Both drivers declare the
+capability `relationDenies` (optional, normalised to `false`); a driver without it answers the four deny operations
+with 500 `E_AUTHZ_UNSUPPORTED` and zero calls.
+
+**`decideMany` is the chain primitive.** `decideMany(subject, relation, objects, partition)` →
+`('allow' | 'deny' | 'none')[]` by position, with the same guarantees as `checkMany` (1..50 objects, `[]` and 51 are 422
+`E_AUTHZ_CHECK_MANY_BATCH`, F-05 per item, one `now` per batch, a per-item error is a 503 for the whole batch — never
+`none`). `allow` if `check` grants on that object; otherwise `deny` if the subject has a live deny (direct or through a
+group) on any relation of `up*(down*(R))` on it; otherwise `none`. *`decideMany` is the chain primitive: walk from the
+leaf up and stop at the first non-`none`. `deny` means "do not inherit past this object"; it is broader than `check` on
+purpose (fail-closed). A deny given to `org#member` does not reach a guest who is not a member: to make a folder grant
+only what it holds directly, break inheritance in your evaluator (`inherits = false`).* It answers **by the partition of
+the object**: a guest holder with an allow in organisation A and a deny on the same object id in organisation B gets
+`allow` in A and `deny` in B (and `check`/`checkMany` agree). Do not use `checkMany` for a chain: with the deny on the
+middle object and the allow on its parent, `checkMany` says `[false, false, true]` and `decideMany` says `[none, deny,
+allow]`.
+
+**Writes that remove access can GIVE access back — declared rows, each with its case.** With a deny on `g#member`:
+`unrelate(u, member, g)` gives `u` back the allow it holds directly (S8), `purgeObject(group:g)` does the same (S9), and
+`purgeSubject(g#member)` deletes the group's denies (S10) (*"S8–S10 · FILAS DECLARADAS"*). A policy that treats "leave a
+group" or "purge" as safe has to know it. And an `openfga` pod still pinned to a model **without** `denied_*` grants
+over a denied object (S11, *"S11 · FILA DECLARADA"*): that is why the rollout above pins every pod before phase 2.
+
 **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
@@ -641,10 +807,15 @@ 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 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
+`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 thirteen operations of the port** — the eight of alpha.3 plus
+`checkMany` (per item) since 2.5.0 and `deny`, `removeDeny`, `listDenies` and `decideMany` (per item) since
+2.5.0-alpha.3 —, 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
@@ -674,28 +845,136 @@ 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. **Never towards the
+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. **Denies migrate as denies (2.5.0-alpha.3):**
+`enumerateRelations` marks every tuple with `kind` (`denied_viewer` is enumerated as `viewer` + `kind: 'deny'`), the key
+carries it, and the pass applies the WHOLE transition of each partition —writes, renewals and, with `--prune`, deletes—
+as **one sequence**, in the order of ONE function shared with the `openfga` purges (`relationTransitionOrder`,
+`src/relations/tuple_order.ts`), in five phases: (1) new denies (`deny`); (2) with `--prune`, leftover allows on
+non-`group` objects; (3) the group memberships (`group:*#member`) that come in and go out, in the order of a
+**precedence graph** (computed in the union of both states: between two memberships of a common subject, one that brings
+a deny on X goes before one that brings an allow on X; one that leaves carrying an allow on X before one that leaves
+carrying a deny on X; one that leaves before one that comes in on the same nested path when the composed path would
+carry an allow; one that comes in carrying a deny before one that leaves carrying a deny that protects an allow of the
+subject; since closure 4 of D2 a membership RENEWAL is in that graph too, as the entry —or, if it shortens, the exit— it
+becomes at the shorter of its two expiries); (4) new allows and the renewals of allows that extend (one that shortens
+goes with the deletes of phase 2); (5) with `--prune`, the leftover denies **last** (`removeDeny`, never
+`unrelate`). Never the source's enumeration order (`database` enumerates by creation: a document shared on Monday, its
+user put in a denied group on Tuesday). Until closure 2 of sublot D2 every write went before every delete, and a former
+member composed with a new allow (U ∈ g leaves, `g#member viewer X` arrives: cut after the first write, U was granted X).
+**What that guarantees, exactly — demonstrated by brute force, not by hand-made tables**: **if the precedence graph has
+no cycle, no state of a pass cut after any write grants something neither the initial nor the final state granted, and
+no subject denied in both is granted in any.** The **residue is the cycle** — two memberships changed in the same pass
+whose order constraints contradict each other; the typical shape: the same subject joins (or leaves) two groups at once,
+and each brings a deny that cuts an allow the other brings — and there, in general, **no order of the diff is safe**;
+the pass applies them in a fixed order and reports them (`report.orderResidue`, a warning line starting with
+`orden SIN garantía`: the final state is right, so it is not drift; if the window matters, apply them in two passes). The
+demonstration (`tests/relations_order_exhaustive.spec.ts`, oracle = the package's own path cut, both with `--prune` and
+without): **exhaustive** over 1 user, 2 groups with one nesting level, 2 objects and one relation with deny (10 possible
+tuples, every (initial, final) pair: 2,097,152 pairs, ~23 s) — 0 pairs grant without a declared residue; 4,176 pairs have
+a cycle, 816 of them grant in some prefix and 352 of those admit no safe order of the diff at all — plus a seeded sample
+of 30,000 pairs per mode of the universe with 2 users and direct/group allows and denies (21 tuples) and of one with three
+groups and two nesting levels (20 tuples): 0 without residue. **Group membership counts as a grant** (closure 5 of D2):
+the oracle also judges `(user, group:G)` — being a member is itself a grant (`check(member)`, `membersOf`) —, so a pass
+cut between `+U ∈ h` and `−h ⊂ g` must not make U a member of g, which neither state did; the order gives that pair a
+precedence (the price, declared: more pairs with a cycle in the two-level universe, 4,188 of 60,000 sampled, all of them
+reported as order residue). **Validity and the time HORIZON are part of the universe**
+(closures 3 and 4 of D2): every destination tuple is live (expiring at `now + 1 h`), expired or absent, and the source
+has it absent or live with the same, a LATER or an EARLIER expiry (8 states per tuple); the plan is derived by the same
+rules as the pass (`liveInDestination`: expired = absent; `deny-conditional` in the plan; a partition with a
+`renewal-unsafe` or a `deny-conditional` is refused — zero writes, so its state is the initial one at every instant: the
+ONLY exclusion), renewals are steps (one write on an `atomicRenewal` destination; two `Write`s with the gap checked as a
+prefix on `openfga`), and **every prefix and the final state are judged at
+`now` and at every later expiry** (`+30 min`, `+1 h`), each tuple with ITS expiry (the destination's if the pass did not
+touch it, the source's if it wrote or renewed it, none for a deny it wrote). Property: at no instant of the horizon does a
+prefix grant outside initial ∪ source, or to a subject denied in both, without a declared order residue; and the final
+state never grants what the source denies at that instant — no exception (closure 4 counted a `preexisting` grant as
+declared; it is gone with the withholding). **Exhaustive** over the reduced
+universe (8 tuples: 33,554,432 combinations per destination kind, `AUTHZ_ORDER_VIGENCIA_EXHAUSTIVE=1`) and seeded
+samples of the four universes in the default suite — 0 grant without a declared residue. Without the destination's config (`toConfig`) the order does
+not assume any allow is cut by a deny (more precedences, more residue, never less guarantee). Surface-guard properties
+`relations.order.exhaustive` (the brute force over a reduced universe, 131,072 pairs, plus a declared sample of 50,000
+combinations per mode with validity and horizon, on every mutant of the order),
+`relations.reconcile.order` and `openfga.purge.order`, the last two judged with the source enumerated in both orders. **The destination driver decides, before the first write, whether it can take each deny**
+(`capabilities.relationDenies` and its own `denyPhase(type, relation)`: the opt-in of ITS config, and on `openfga` its
+pinned model, D-31 — never the persisted spec): a source deny that the destination cannot write (`no-capability`,
+`no-deny-phase`, `phase` — the type is not in `deny: 'write'` there —, `undeclared`, `model`, `unmarked` — a source driver
+that does not mark `kind`, on either side —, `invalid`) makes the pass refuse with 500 `E_AUTHZ_DENY_MIGRATION_REFUSED` and **zero
+writes** in every partition — never `skipped`: writing the allows without the deny would grant what the source denies.
+`--dry-run` does not throw: one line per refusal starting with `deny NO migrable`, and exit ≠ 0. **Each refusal carries
+the recipe of ITS reason** (`DenyRefusal.recipe`): `phase` — the type in `deny: 'write'` in the destination's config
+(provision → pin → deploy); `undeclared` — a relation RETIRED with live denies: re-declare the relation temporarily in the
+config of the process that writes the source (the relation is enough; `removeDeny` needs no opt-in), `removeDeny` those
+denies, retire it again and repeat (`removeDeny` on an undeclared pair is 422, F-05; executed in the suite); `model` —
+publish and pin the destination's model; `unmarked` — update the driver that does not mark `kind`; `invalid` — delete
+the row by hand (the API would reject `removeDeny` too); `no-capability`/`no-deny-phase` — a destination that can write
+denies. (A partition refused by the plan, above, writes nothing, so its denies do not ask for a phase.) A deny already present in a destination WITHOUT the opt-in is refused too (`phase`) although `database` would
+honour the row (D8): `denyPhase = null` means «no opt-in» and the pass does not certify what the destination does not
+declare. **A destination deny with an expiry** (only writable from outside the package, D3) —live with another expiry, or
+ALREADY EXPIRED— that the source has is rewritten permanent on `database`; on a destination without `atomicRenewal`
+(`openfga`: it cannot replace the same key in a `Write`, M5, and its `deny` there is 500 `E_AUTHZ_CONFIG` with the recipe
+`removeDeny` + `deny`, a declared window between the two) **the plan decides it** (closure 4 of D2; same numbers in
+`--dry-run` and the real pass): the destination residue `deny-conditional` (exit ≠ 0), not rewritten, and **its partition
+is refused** (closure 5, above) — an expired one denies nothing, and until closure 4 the pass still wrote the allow it cut
+(the destination granted, and `--dry-run` reported a different count). A driver that declares
+`atomicRenewal` and still answers that 500 contradicts its capability: the error propagates. The report carries
+`denies: { written, updated, deleted, unchanged, extra }` (a subset of the totals, printed as its own `denies:` line),
+`denyRefused` (dry-run) and `partitions` (one row per partition with its status); a pass that blows up halfway throws
+with `error.report` (`partial: true`: the partitions `done`, the one that `failed` with what it wrote, the `pending`
+ones) and the command prints it, one `pasada PARCIAL:` line per partition; one that fails before writing anything has
+`partial: false` and prints `pasada FALLIDA sin escribir nada:`. **The totals `written`/`unchanged`/`extra` include the
+denies** (2.5.0-alpha.3, a change of meaning): subtract `denies` to count allows only. **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, the one public way is `runRelationsReconcile`** —
-`import { runRelationsReconcile } from '@jantstack/adonis-authz/commands/authz_relations_reconcile'` and
+`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
@@ -779,8 +1058,14 @@ driver tolerates old `NULL` rows on read meanwhile.
 | `unrelate` | `subject`, `relation`, `object`, `partition`, `actor` | — |
 | `purgeObject` | `object`, `partition`, `actor` | no `subject`, no `relation` |
 | `purgeSubject` | `subject`, `partition`, `actor` | no `object`, no `relation` |
+| `deny` (2.5.0) | `subject`, `relation` (the public name, never `denied_<rel>`), `object`, `partition`, `actor` | no `expiresAt` (a deny does not expire) |
+| `removeDeny` (2.5.0) | `subject`, `relation`, `object`, `partition`, `actor` | no `expiresAt` |
 
-A purge notifies **one event per call** — even when the driver sweeps both spellings of the partition uuid underneath, and even when it deletes many tuples — and it **does not count**: the port returns `void` (a count would break the port for third-party drivers, and inside `{ transaction }` it would be a number your rollback contradicts). If you need the "how many", call `enumerateRelations` (or `listSubjects`) before purging — inside your transaction, through your transaction. And a purge that deletes nothing notifies all the same: the auditable fact is *someone asked to delete the keys of X*, whether or not there were any. `scopes.detached` on the roles port emits one `scope_purged` per spelling because there the **manager** canonicalises; the relations manager does not, so the divergence is on purpose and pinned (*"E6 · UN evento por llamada aunque el driver barra DOS ortografías"*). A purge does not go through `assertWrite` — `RelationRef.operation` is `'relate' | 'unrelate'`, the published type of the R-13 hook — and that is pinned too (*"E9 · negativo declarado"*). But F-05 runs first on the purges too (2.4.0-alpha.3, closing the audit's critical finding): `purgeObject` validates the object type and `purgeSubject` the userset of its subject **before** the actor, the scope and the driver, so a purge of a `role_binding` is 422 with zero driver calls and zero events — see [F-05 on the seven operations](#relations-rebac-24) above. `purgeSubject` also validates its subject like `relate` does (a malformed holder or `{}` is 422 `E_AUTHZ_INVALID_IDENTITY` and never reaches the event).
+**`operation` widened in 2.5.0 with `deny` and `removeDeny`** — on the event and on the `RelationRef` that `assertWrite`
+receives. TypeScript does not warn about a widened union inside an `if`/`else`: **a handler that treats everything that is
+not `unrelate` as an addition grants too much** (it would index a deny as a share). Switch on the operation.
+
+A purge notifies **one event per call** — even when the driver sweeps both spellings of the partition uuid underneath, and even when it deletes many tuples — and it **does not count**: the port returns `void` (a count would break the port for third-party drivers, and inside `{ transaction }` it would be a number your rollback contradicts). If you need the "how many", call `enumerateRelations` (or `listSubjects`) before purging — inside your transaction, through your transaction. And a purge that deletes nothing notifies all the same: the auditable fact is *someone asked to delete the keys of X*, whether or not there were any. `scopes.detached` on the roles port emits one `scope_purged` per spelling because there the **manager** canonicalises; the relations manager does not, so the divergence is on purpose and pinned (*"E6 · UN evento por llamada aunque el driver barra DOS ortografías"*). A purge does not go through `assertWrite` — `RelationRef.operation` is `'relate' | 'unrelate' | 'deny' | 'removeDeny'` (the four writes on ONE tuple), the published type of the R-13 hook — and that is pinned too (*"E9 · negativo declarado"*). But F-05 runs first on the purges too (2.4.0-alpha.3, closing the audit's critical finding): `purgeObject` validates the object type and `purgeSubject` the userset of its subject **before** the actor, the scope and the driver, so a purge of a `role_binding` is 422 with zero driver calls and zero events — see [F-05 on the seven operations](#relations-rebac-24) above. `purgeSubject` also validates its subject like `relate` does (a malformed holder or `{}` is 422 `E_AUTHZ_INVALID_IDENTITY` and never reaches the event).
 
 **The four guarantees, on the four writes** (`relate`, `unrelate`, `purgeObject`, `purgeSubject`):
 
@@ -832,7 +1117,7 @@ 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); an `openfga` relations purge against a server whose `--max-tuples-per-write` is below `RELATIONS_PURGE_WRITE_MAX` (100) — the server's 400 `exceeded_entity_limit`, marked as a partial write if an earlier `Write` already deleted (2.5.0) |
 | `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) |
@@ -840,7 +1125,11 @@ Every error the package raises carries `status` and `code`. A standard AdonisJS
 | `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_RENEWAL_UNSAFE` | 409 | `relate` on `openfga` (closure 2 of sublot D2) renewing — another expiry on an existing tuple — a `group:*#member` membership whose group, or a group containing it, is the subject of a live deny of the partition: the renewal is two `Write`s there and between them the subject would be granted. **Always zero writes**; the message carries the honest recipe (closure 5 of D2): there is no window-free way on `openfga` (openfga/openfga#2151); memberships without expiry in groups with a deny, or `unrelate` + `relate` accepting the window. A driver declaring `atomicRenewal: false` must answer it the same way. An already EXPIRED membership is not refused (closure 3 of D2) |
+| `E_AUTHZ_RENEWAL_RACED` | 409 | `RenewalRacedError` (closure 4 of D2; until then the same `E_AUTHZ_RENEWAL_UNSAFE`): an allowed two-`Write` renewal on `openfga` WENT THROUGH, and the re-check after it finds a deny that arrived concurrently and did not reach the subject between the two `Write`s. Marked partial (`indeterminate: true`), `renewalApplied: true`, `carriedDeny`. The final state is right: do NOT apply the `E_AUTHZ_RENEWAL_UNSAFE` recipe (it would reopen the window with the deny inside); review the subject's decisions in the window |
+| `E_AUTHZ_DENY_MIGRATION_REFUSED` | 500 | `authz:relations:reconcile` / `runRelationsReconcile` (2.5.0-alpha.3): the source carries a live deny the **destination driver** cannot take — no `relationDenies`, no `denyPhase`, the type not in `deny: 'write'` in ITS config, the pair undeclared there, its pinned model without `denied_*`, or a source that does not mark `kind`. Decided in the plan phase: **zero writes** in every partition, never `skipped` (the allows alone would grant what the source denies). `error.refusals` lists them; `--dry-run` flags `report.denyRefused` instead of throwing (`deny NO migrable (<reason>)`, exit ≠ 0) |
 | `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_MEMBERS_DENY_LIMIT` | 500 | `membersOf` on `database` over an object with a live deny and more than `RELATIONS_MEMBERS_DENY_CHECK_MAX` (1,000) candidates; never a partial list. 500 and not 422: it is not an invalid question from the caller but a bound of the deployment (precedent `E_AUTHZ_TOO_MANY_LOCAL_ROLES`) (2.5.0) |
 | `E_AUTHZ_TOO_MANY_LOCAL_ROLES` | 500 | more local roles than `maxLocalRoles` (10 000) in a `prune-orphans` pass; never a partial list |
 | `E_AUTHZ_UNSUPPORTED` | 500 | a primitive needs an optional port method the active driver lacks: `listDenies` (2.1; also behind `defineScopedRole`), `purgeRole` (2.2 — behind `deleteScopedRole`, `authz:catalog:prune-orphans` and, before writing anything, `defineScopedRole`; the `openfga` driver until 2.3); `reconcile` (2.3 — `authz:reconcile --to=<driver>`); `enumerateFacts` (2.3 — being the *source* of `authz:reconcile`; the `database` driver does not implement it: its facts are `authz_*`. Also raised when `--to` is the **active** driver and declares `hierarchyFacts`: its facts are its own, so the pass has to be able to read them instead of rebuilding it from `authz_*`). Also `{ transaction }` on `grant`/`revoke`/`deny`/`removeDeny` or `relate`/`unrelate`/`purge*` when the active driver declares `transactionalWrites: false` (2.4 — the message names the driver and the operation, nothing was called; the way out is the `database` driver or `requireTransactionalWrites`; the `openfga` drivers raise it themselves too, so `manager.driver()` is not a way out — see [the recipe by direction](#openfga-the-recipe-by-direction)), and `{ transaction }` on the delegation API (`defineScopedRole`/`updateScopedRole`/`deleteScopedRole`: the catalog is written through `withAuthzCatalogWrite`, the cross-process serializer, which a caller's transaction would defeat) |
 | `E_AUTHZ_MODEL_TOO_LARGE` | 500 | the catalog does not fit in an OpenFGA authorization model (262,144 **bytes** — around **450 permissions with realistic slugs**; see [the model ceiling](#the-model-ceiling-is-bytes-not-permissions)): checked in `syncAuthzCatalog` **before** writing, with a warning past 80 % |
@@ -1261,7 +1550,13 @@ 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 |
-| 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` |
+| `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` / `decideMany` | `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` |
+| `membersOf` candidates judged one by one when the object has a deny (`database`) | `RELATIONS_MEMBERS_DENY_CHECK_MAX` | 1,000 | the `database` relations driver (2.5.0) | 500 `E_AUTHZ_MEMBERS_DENY_LIMIT` before the first `check`, never a partial list; the whole loop also runs under one total deadline (`timeoutMs`), 503 `E_AUTHZ_BACKEND_TIMEOUT` past it. Without a deny row on the object there is no extra query and no bound |
+| Tuples a relations purge deletes in one atomic `Write` | `RELATIONS_PURGE_WRITE_MAX` | 100 | the `openfga` relations driver (2.5.0) | the server's `--max-tuples-per-write` default (101 is a 400, measured on v1.19.0). Up to it a purge is one `Write`; past it, allows → the subject's group memberships in their own `Write` → denies. With more than 100 memberships a cut purge can grant until repeated (declared row, [Relations](#relations-rebac-24), «Deny on relations»). **Requires `--max-tuples-per-write` ≥ 100 on the server**: below it, the `Write` that passes the server's cap — not necessarily the first — is 500 `E_AUTHZ_CONFIG` naming the requirement (never a 503 that looks transient: repeated, the purge would fail the same way forever), marked as a partial write (`indeterminate: true`) if an earlier `Write` already deleted |
+| `openfga:provision --store-id` sweep for live denies of a dropped relation | — (no cap: streamed page by page) | — | `openfga:provision --store-id` (2.5.0-alpha.3), only when some model of the store declared a `denied_*` the new one does not | it reads the WHOLE store, page by page, keeping only a count and three examples (memory does not grow with the store, time does: O(store) per run); a server that does not advance (a repeated continuation token) or a page without `tuples` is exit 1 (`provision NEGADO:`) without writing the model — "zero live denies" is never assumed from a sweep that did not finish. Until closure 2 of sublot D2 the sweep stopped at 1,000,000 tuples, and since the store's model history keeps a retired opt-in forever, a bigger store could never be provisioned again |
+| Models of the store `openfga:provision --store-id` reads to judge the store's state (every published model is one) | `PROVISION_MODEL_HISTORY_MAX` | 10,000 | `openfga:provision --store-id` (2.5.0-alpha.3) | exit 1 (`provision NEGADO:`) without writing the model — never judged on a truncated history |
+| Relation name in a type with `deny` | `DENIABLE_RELATION_NAME_MAX` | 43 | `defineRelationsConfig` and the `openfga` model generator (2.5.0) | 422 `E_AUTHZ_RELATION_CONFIG` at definition: `denied_<rel>` has to fit FGA's 50. A type without `deny` keeps 50 |
 | `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` / `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 |
@@ -1441,13 +1736,134 @@ in the same line). Three things change for an installation on `2.4.0-alpha.x`:
    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.
+   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.
 
@@ -1643,6 +2059,83 @@ DDL of the published migration (`stubs/migration.stub`) and copy the rows. The d
 row per tuple: if the two rows raced with different expiries, the survivor is the first written. The `openfga`
 driver needs nothing — a tuple is unique by construction.
 
+### Upgrading to 2.5.0-alpha.3: rolling out the deny on relations, migrating it, and why there is no rollback below 2.5
+
+Nothing changes until a type opts in: with no `deny` in `defineRelationsConfig` the fused model is byte for byte the
+one of 2.4.0-alpha.10 and there is no DDL (a deny is a row of `authz_relations` with `relation = 'denied_<rel>'`).
+
+**Turning the deny on is two deployments, in this order: provision → pin `modelId` → deploy.** A pod still pinned to a
+model without `denied_*` grants over a denied object (S11, declared row), and a pod running < 2.5.0-alpha.3 on
+`database` never looks at the `denied_*` rows — so no deny may be written until the whole fleet serves the new model with
+the new code:
+
+1. Put the type in **`deny: 'read'`** and publish the model from that config: `node ace openfga:provision
+   --store-id=$OPENFGA_STORE_ID` (it prints a new `OPENFGA_MODEL_ID`).
+2. Pin **every** pod to that `modelId` and deploy the fleet on ≥ 2.5.0-alpha.3 with `deny: 'read'`: reads honour
+   denies, `deny()` is still 422 `E_AUTHZ_RELATION_NOT_DENYABLE`. A pod with the new config and the old pin is 500 on
+   first use (D-31), never a grant.
+3. Verify, then a **second** deployment moves the type to **`deny: 'write'`** (same model: the two phases publish the
+   same rules). Only now are denies written.
+
+The job `cutover-runbook` runs exactly this (steps 20 and 21, against pg and sqlite-file with a real OpenFGA): phase 1 ⇒
+`deny` 422 on both drivers; phase 2 ⇒ the deny lands, `authz:relations:reconcile` carries it to the store (`denies:
+escritos 1`), `check` is false on both drivers; and the S11 table — a pod that was not redeployed, pinned to the old
+model, grants; the same pod with the new `modelId` does not (the server subtracts); a pod with the new config and the
+old pin is 500.
+
+**`openfga:provision --store-id` refuses to mutilate the model.** Publishing from a process whose config lacks the opt-in
+(a refactor, another branch of the config, an old binary) would drop `denied_*` and switch every deny of that type off,
+silently. Before writing, the command judges the **state of the store**, not just its last model: it reads every model the
+store has (`PROVISION_MODEL_HISTORY_MAX`) and, if any of them declared a `<type>#denied_<rel>` of a relation type that the
+new one does not, it sweeps the store (all of it, streamed page by page with no tuple cap — closure 2 of sublot D2; it
+costs O(store) per run, and a store with a retired opt-in pays it on every `provision --store-id`) — a live deny of those
+relations is exit 1
+(`provision NEGADO: …`) and nothing is written, also when a model without `denied_*` was published in between (a rollback
+rehearsal with an older binary). Dropping one the **latest** model declares also needs `--allow-drop-deny` (the way to
+retire an opt-in for real, said out loud); the flag **never switches off a live deny**. Right before
+`writeAuthorizationModel` the sweep is repeated (`provision NEGADO: el RECUENTO …` if a deny arrived meanwhile: the fleet
+is still writing denies). **The recount narrows the window, it does not close it**: a deny that lands on a page the
+recount already read, or between the recount and `writeAuthorizationModel`, is not seen — **step 0 (the whole fleet on
+`deny: 'read'` before counting) is what closes it**. A sweep that fails halfway is exit 1 too. (`database` honours `denied_*` rows always, also
+without the opt-in: retiring it there does not switch them off either — remove them with `removeDeny`.)
+
+**Rolling back below 2.5 with live denies is not supported (D12 · S17, declared row).** A process < 2.5.0-alpha.3 ignores
+every deny: on `database` its `check` never reads `denied_*`; its `defineRelationsConfig` drops the `deny` key in
+silence; its `openfga:provision` republishes a model without `but not`; its `authz:relations:reconcile` counts the denies
+as undeclared relations and migrates the allows. There is no command that makes that safe. **Before any rollback, stop
+the denies, count them and take them to zero — in this order:**
+
+0. **Move the whole fleet to `deny: 'read'`** for every type with the opt-in, and deploy it, **before** counting, sweeping
+   or publishing anything: every `deny()` is then 422 `E_AUTHZ_RELATION_NOT_DENYABLE` on every pod and reads still honour
+   the denies. Skipping this leaves a window — counting, publishing, redeploying — in which a tenant's `deny()` lands and
+   is then switched off in silence, for good.
+1. Count the live denies (below).
+2. Retire them: `removeDeny` (or the purges) on the active driver and `authz:relations:reconcile … --prune` on the mirror,
+   until the count is 0.
+3. Publish the model without the opt-in: `node ace openfga:provision --store-id=… --allow-drop-deny` (it sweeps, and
+   re-counts right before writing the model — the recount narrows the window, it does not close it: step 0 does).
+4. **Count again: it must still be 0.** If it is not, a pod was still in `'write'`: do not pin the new model, go back to 0.
+5. Pin, redeploy, roll back.
+
+The count, on `database` (the three engines; executed by the suite):
+
+```sql
+-- D12 · live relation denies (rollback below 2.5 requires 0)
+SELECT count(*) AS n FROM authz_relations WHERE substr(relation, 1, 7) = 'denied_';
+```
+
+On `openfga`, `node ace authz:relations:reconcile --to=<other> --from=openfga --dry-run` per partition prints a
+`denies:` line (`escritos + iguales` are the store's live denies). Retire them with `removeDeny` (or the purges) on the
+active driver and `authz:relations:reconcile … --prune` on the mirror until the count is 0. Step 21 of the runbook executes
+this procedure with its EFFECT: with the denies alive both `provision` attempts exit 1 without touching the store; an
+operator who skips step 0 retires the denies to zero and a pod still in `'write'` writes one more — the count is 1 again
+and `provision --allow-drop-deny` exits 1 instead of publishing; with the fleet in `'read'` the concurrent `deny` is 422 on
+both drivers, the count reaches 0 and stays 0, and only then the model is published.
+
+**A pass of 2.5 never classifies a deny as `undeclared`**: it migrates it as a deny or refuses the whole pass (above).
+Never run `authz:relations:reconcile` from a process < 2.5.0-alpha.3 once there are denies in a store: it counts them as
+undeclared, and its `--prune` hands them to `unrelate`.
+
 ## Compatibility
 
 | | |