@jantstack/adonis-authz 2.4.0-alpha.1 → 2.4.0-alpha.10

package/build/src/types.d.ts

@@ -76,6 +76,41 @@ export interface WriteOptions {
      * quién puede conceder qué es policy del consumidor (invariante 8).
      */
     actor?: SubjectRef;
+    /**
+     * **La transacción ABIERTA del consumidor** (`TransactionClientContract` de
+     * Lucid: el `trx` de `db.transaction()`), para que la escritura del paquete
+     * confirme o revierta CON la tuya — L-2, panel `{trx}` (C).
+     *
+     * **Encolar ≠ escribir.** Son dos promesas distintas y este campo hace UNA
+     * u OTRA según la operación:
+     *
+     *  - En `grant`/`revoke`/`deny`/`removeDeny` (los HECHOS) significa
+     *    **ESCRIBIR en tu transacción**: «los dos o ninguno» entre el hecho y
+     *    tus filas, en el mismo motor transaccional. Solo lo cumple un driver
+     *    que declare `capabilities.transactionalWrites: true` (`database`, con el
+     *    `trx` de SU conexión: otra conexión, un `QueryClient` o el `db` entero
+     *    son 500 `E_AUTHZ_CONFIG`, `assertCallerTransaction`). Con un driver
+     *    que declare `false` —`openfga`: una tupla no entra en una transacción
+     *    SQL, no hay 2PC— la llamada es **500 `E_AUTHZ_UNSUPPORTED`** nombrando
+     *    driver y operación, **antes de tocar el driver** (cero llamadas):
+     *    nunca se ignora, nunca un aviso. Quien quiera fallar al ARRANCAR en
+     *    vez de en una ruta poco transitada declara `requireTransactionalWrites:
+     *    true` en el config (500 `E_AUTHZ_CONFIG` al resolver el driver).
+     *  - En `scopes.attached/moved/detached` significa **ENCOLAR en tu
+     *    transacción** (3b-2d, `ScopeTreeWriteOptions.transaction`): el INSERT
+     *    de la outbox cae dentro de ella; el backend NO se toca dentro de tu
+     *    transacción y no pasa por la puerta de la capacidad.
+     *  - En la API de delegación (`defineScopedRole`/`updateScopedRole`/
+     *    `deleteScopedRole`) **no se admite** (500 `E_AUTHZ_UNSUPPORTED`): esas
+     *    escriben el catálogo por `withAuthzCatalogWrite`, que ES el
+     *    serializador entre procesos (cerrojo + bump como última sentencia,
+     *    invariante 14); moverlas al commit del consumidor lo anularía.
+     *
+     * Lo que NUNCA viaja por ella, en ninguna de las tres: **la autoridad**
+     * (L-1 · 🟠 8) — la barrera del freeze, el catálogo y `resolveChain` se leen
+     * por la conexión del motor, así que `{ transaction }` exige **pool ≥ 2**.
+     */
+    transaction?: unknown;
 }
 /**
  * Opciones de las NUEVE escrituras del manager (`grant`, `revoke`, `deny`,
@@ -116,9 +151,24 @@ export interface ScopeTreeWriteOptions extends ScopedWriteOptions {
      * La transacción ABIERTA del consumidor (`TransactionClientContract` de
      * Lucid, o lo que use su outbox). El paquete no la interpreta: se la pasa
      * tal cual a `scopes.outbox.enqueue` para que el INSERT del encolado caiga
-     * dentro de ella. Sin outbox declarada no hace nada; con outbox declarada
+     * dentro de ella — **ENCOLAR, no escribir**: el backend no se toca dentro
+     * de tu transacción. Sin outbox declarada no hace nada; con outbox declarada
      * y sin transacción, el encolado se confirma solo y vuelve a haber dos
      * confirmaciones distintas (la outbox lo avisa si puede).
+     *
+     * **Lo que NUNCA viaja por ella: la autoridad** (L-1 · 🟠 8). La barrera
+     * del freeze se lee por la conexión del motor, jamás por esta transacción
+     * (su snapshot puede ser anterior al freeze). Por eso exige **pool ≥ 2**:
+     * con pool 1 (SQLite `:memory:`) la barrera no consigue conexión mientras
+     * tú sostienes la única y la notificación sale 503 `E_AUTHZ_BACKEND_TIMEOUT`
+     * (`freezeTimeoutMs`) — fail-closed, nunca un bypass. Y `sqlScopeOutbox`
+     * exige que sea una transacción ABIERTA de SU conexión: otra conexión, un
+     * `QueryClient` o el `db` entero son 500 `E_AUTHZ_CONFIG` (🟠 9).
+     *
+     * **Encolar ≠ escribir** (L-2): aquí la transacción ENCOLA; en
+     * `grant`/`revoke`/`deny`/`removeDeny` (`WriteOptions.transaction`) ESCRIBE
+     * el hecho dentro de ella y pasa por la puerta de `transactionalWrites`.
+     * Esta notificación no pasa por esa puerta: un driver `openfga` la acepta.
      */
     transaction?: unknown;
 }
@@ -258,7 +308,51 @@ export interface AuthorizationDriverCapabilities {
      * el destino los lee de ahí directamente (`openfga.reconcile`).
      */
     enumerateFacts: boolean;
+    /**
+     * El driver puede inscribir sus escrituras en la transacción del consumidor
+     * (`{ transaction }` en `grant`/`revoke`/`deny`/`removeDeny`). `true`
+     * significa EXACTAMENTE «los dos o ninguno con TU transacción», nunca «no
+     * se pierde». `database` = true (con el `trx` de SU conexión; L-3).
+     * `openfga` = false, y no puede ser otra cosa: una tupla no entra en una
+     * transacción SQL — el store es otro servicio y no hay 2PC. No hay valor
+     * intermedio y no se publica ninguno (panel `{trx}`, veredicto (C)).
+     *
+     * Dos puertas la hacen verdad: con `false`, `{ transaction }` es 500
+     * `E_AUTHZ_UNSUPPORTED` por llamada, con cero llamadas al driver; y con
+     * `requireTransactionalWrites: true` en el config un driver `false` es 500
+     * `E_AUTHZ_CONFIG` al RESOLVER (el despliegue no arranca). **Mismo nombre
+     * en `RelationsDriverCapabilities`**: un driver de terceros no aprende dos.
+     *
+     * `database` la cumple desde L-3: la ESCRITURA (y la lectura «¿ya existe?»
+     * que forma parte de ella) va por la transacción ABIERTA del llamante
+     * (`assertCallerTransaction` contra la conexión primaria de Lucid); la
+     * AUTORIDAD (barrera del freeze, catálogo, `resolveChain`) nunca — por eso
+     * exige pool ≥ 2, y un despliegue con pool 1 declara `false` en las opciones
+     * del driver. Un choque del UNIQUE dentro de la transacción del llamante es
+     * 409 `E_AUTHZ_WRITE_CONFLICT` («envenena tu transacción»); un deadline
+     * vencido ahí sigue siendo `indeterminate: true` y el evento lleva
+     * `transactional: true`.
+     */
+    transactionalWrites: boolean;
 }
+/**
+ * Las claves de `AuthorizationDriverCapabilities`, LITERALES (2.4.0-alpha.4):
+ * lo que `authorization.capabilities()` normaliza. Una capacidad nueva que no
+ * se añada aquí saldría como `undefined` de la lectura publicada, que es
+ * justo lo que la API promete no devolver — el caso D-3 de la suite lo ve.
+ */
+export declare const AUTHORIZATION_DRIVER_CAPABILITY_KEYS: ReadonlyArray<keyof AuthorizationDriverCapabilities>;
+/**
+ * **La copia CONGELADA y NORMALIZADA que publica `authorization.capabilities()`**
+ * (2.4.0-alpha.4; 🟠 3 y 🟡 5 del auditor). Todas las claves conocidas
+ * presentes; solo `true` es `true` — la MISMA lectura que aplican las puertas
+ * de `{ transaction }` (`=== true`)—, así que `undefined`, un valor a medias
+ * de un driver de terceros o un driver de 2.x sin `capabilities` salen como
+ * `false`, nunca como `undefined` (repetiría el bug de `stillGranting`: «no lo
+ * sé» degradando a «no»). Y es una copia: mutarla no toca el objeto que leen
+ * las puertas del manager.
+ */
+export declare function normalizeAuthorizationCapabilities(declared: Partial<AuthorizationDriverCapabilities> | undefined): Readonly<AuthorizationDriverCapabilities>;
 export interface AuthorizationDriver {
     /** Lo que este driver declara poder hacer (3b-2e · E2). Ver `AuthorizationDriverCapabilities`. */
     readonly capabilities?: AuthorizationDriverCapabilities;
@@ -280,7 +374,7 @@ export interface AuthorizationDriver {
      * el catálogo para `scope.type` (422 si no, como `grant`); la asignación
      * puede no existir (no-op).
      */
-    revoke(subject: SubjectRef, role: RoleQuery, scope: ScopeRef): Promise<void>;
+    revoke(subject: SubjectRef, role: RoleQuery, scope: ScopeRef, options?: WriteOptions): Promise<void>;
     /**
      * ¿El holder tiene el rol (vigente) en el scope o en un ancestro?
      * Misma regla de herencia hacia abajo que `authorize`. Es MEMBRESÍA: el
@@ -291,12 +385,12 @@ export interface AuthorizationDriver {
      * Deny explícito de UN permiso al holder en un scope (y sus descendientes).
      * El permiso debe existir en el catálogo (throw si no). Idempotente.
      */
-    deny(subject: SubjectRef, permission: string, scope: ScopeRef): Promise<void>;
+    deny(subject: SubjectRef, permission: string, scope: ScopeRef, options?: WriteOptions): Promise<void>;
     /**
      * Levanta el deny en ese scope exacto. El permiso debe existir en el
      * catálogo (422 si no, como `deny`); el deny puede no existir (no-op).
      */
-    removeDeny(subject: SubjectRef, permission: string, scope: ScopeRef): Promise<void>;
+    removeDeny(subject: SubjectRef, permission: string, scope: ScopeRef, options?: WriteOptions): Promise<void>;
     /** Holders con asignación VIGENTE del rol en ese scope exacto (sin herencia). */
     listSubjects(role: RoleQuery, scope: ScopeRef): Promise<SubjectRef[]>;
     /**
@@ -565,12 +659,36 @@ export interface ReconcileSource {
      *    `enumerateFacts`) del origen `name`, que puede ser **el propio
      *    destino** cuando el destino es el driver ACTIVO y sus hechos son
      *    suyos (la pasada de MANTENIMIENTO: rehace lo derivado —marcador,
-     *    catálogo, árbol y visibilidad— y no inventa ni borra un solo hecho).
+     *    catálogo, árbol y visibilidad— y no inventa hechos; con `--prune` borra
+     *    los que ya no respaldan nada: scopes que ya no resuelven, caducados,
+     *    roles/permisos retirados y los que sobran).
      *
      * Ausente = `{ name: 'authz_*', authzTables: true }`: el comportamiento de
      * 3b-3a, que es el que vale cuando el origen es el esquema publicado.
      */
     factsOrigin?: ReconcileFactsOrigin;
+    /**
+     * **El techo de profundidad con el que se juzga el árbol del origen**
+     * (2.4.0-alpha.5 · R0): `scopes.maxDepth` del config si el consumidor lo
+     * declaró; sin él, el destino usa su propia cota (`openfga`:
+     * `FACTS_MAX_RESOLVE_DEPTH`, 22 saltos). Las cadenas que lo superan salen
+     * en `drift.tooDeep`. Un solo mando: quien subió
+     * `OPENFGA_RESOLVE_NODE_LIMIT` en su servidor sube esto y el verificador
+     * lo sigue.
+     */
+    maxDepth?: number;
+    /**
+     * **Los tipos de objeto que OTRO subsistema gobierna en el mismo backend**
+     * (2.4.0-alpha.9 · B · S4): los declarados en `relations.config`, que pone
+     * el manager. Con `openfga` los dos subsistemas comparten store, así que la
+     * pasada de hechos ve tuplas que no son suyas; esto es **solo para el
+     * REPORTE** —parte `foreign` en `relations` (declaradas) y `unknown` (no
+     * las reclama nadie)— y **jamás decide un borrado**: eso lo decide la lista
+     * blanca congelada del driver de destino, que no lee nada en runtime. Un
+     * proceso sin `relations.config` —el caso de un cutover— tiene que
+     * respetar lo ajeno igual, y lo hace.
+     */
+    relationTypes?: readonly string[];
 }
 /** Ver `ReconcileSource.factsOrigin` (3b-5). */
 export interface ReconcileFactsOrigin {
@@ -635,6 +753,14 @@ export interface ReconcileOptions {
     prune?: boolean;
     /** La salida humana de `E_AUTHZ_MASS_RECONCILE_REFUSED`. */
     allowMassDelete?: boolean;
+    /**
+     * La salida humana de `E_AUTHZ_STALE_SOURCE_REFUSED` (2.4.0-alpha.10): deja
+     * correr `--to=<driver ACTIVO> --from=<otro>`, la dirección que re-escribe en
+     * el driver que sirve hechos que el origen ya no refleja (resucita las
+     * revocaciones hechas desde el cutover). Lo lee el MANAGER; el driver lo
+     * ignora.
+     */
+    allowStaleSource?: boolean;
     /** Filas por lote en las lecturas del origen y por `Write` en el destino (default 100). */
     batchSize?: number;
     /**
@@ -700,15 +826,37 @@ export interface ReconcileReport extends ReconcileCounts {
      * significa que el lease se perdió a mitad —una pausa más larga que el
      * lease, la base caída, otro dueño— y hubo una ventana en la que otros
      * procesos pudieron escribir: la pasada NO se certifica y el comando sale
-     * distinto de cero. `leaseMs: null` = ventana sin renovación (el freeze de
-     * OPERADOR dentro del que corrió la pasada, o un lease infinito). Lo pone
-     * el MANAGER: el driver no sabe de ventanas.
+     * distinto de cero. `leaseMs: null` = ventana que no caduca (el freeze de
+     * OPERADOR sin `--lease-ms` dentro del que corrió la pasada). Lo pone el
+     * MANAGER: el driver no sabe de ventanas.
      */
     frozen?: {
         durable: boolean;
         lapsed: boolean;
         leaseMs: number | null;
         fence: number;
+        /**
+         * Solo si la pasada corrió dentro de la ventana del OPERADOR (2.4.0-alpha.10):
+         * cuándo caduca esa ventana (ms de pared, de la fila), o `null` si no caduca.
+         * Entonces `leaseMs` es lo que le quedaba al adoptarla, y es `null` solo si
+         * `untilMs` es `null`.
+         */
+        untilMs?: number | null;
+        /** En QUÉ ventana corrió (alpha.10, S2): la del operador, una propia, o la que ya sostenía el manager. */
+        window?: 'operator' | 'own' | 'enclosing';
+    };
+    /**
+     * **La dirección RANCIA** (2.4.0-alpha.10): esta pasada tenía como destino
+     * el driver ACTIVO (`config.default`) y como origen OTRO driver — la que
+     * resucita las revocaciones hechas desde el cutover. Sin `allowStaleSource`
+     * solo llega aquí un `--dry-run` (la pasada que escribe es 500
+     * `E_AUTHZ_STALE_SOURCE_REFUSED`), y es deriva: exit ≠ 0. `allowed: true` =
+     * el operador la levantó a sabiendas. Lo pone el MANAGER.
+     */
+    staleSource?: {
+        to: string;
+        from: string;
+        allowed: boolean;
     };
     dryRun: boolean;
     prune: boolean;
@@ -739,9 +887,48 @@ export interface ReconcileReport extends ReconcileCounts {
         pendingRelay: number;
         /** Entradas APARCADAS de la outbox: divergencia permanente, no una ventana. */
         deadRelay: number;
+        /**
+         * Scopes del ORIGEN cuya cadena supera el techo de profundidad
+         * (2.4.0-alpha.5 · R0): `ReconcileSource.maxDepth`, o la cota del destino
+         * (`FACTS_MAX_RESOLVE_DEPTH` en `openfga`). Legales en `database`, un 503
+         * en `facts` para todo el que pregunte por ellos: el verificador los
+         * cuenta como deriva (exit ≠ 0). Opcional: un driver de terceros que no
+         * lo calcula no lo reporta, y `reconcileLines` lo trata como vacío.
+         */
+        tooDeep?: string[];
+        /** El techo con el que se calculó `tooDeep`. */
+        tooDeepLimit?: number;
     };
     /** La pasada tiene la firma de un origen ciego (ver `E_AUTHZ_MASS_RECONCILE_REFUSED`). */
     massDelete: boolean;
+    /**
+     * **Lo que esta pasada vio en el destino y NO gobierna** (2.4.0-alpha.9 · B):
+     * el store es COMPARTIDO con otro subsistema (con `openfga`, las tuplas de
+     * `relations/`) y sus tipos de objeto no son los de este reconcile. Ni se
+     * borran —tampoco con `--prune`—, ni cuentan como deriva, ni entran en
+     * `phases`: se cuentan aquí, con el desglose por TIPO que es lo único que
+     * permite reconocer un tipo que ya no se declara.
+     *
+     * Va FUERA de `skipped` a propósito: ahí dentro `clean` era `false` para
+     * siempre en cualquier despliegue con relaciones (el corolario del 🔴 3 del
+     * quinto informe de COGNITIV), y fuera de `details`, cuyo tope de 200
+     * entradas expulsaría los `extra-fact` REALES, que son los que conceden.
+     *
+     * `relations`/`unknown` solo aparecen si el manager pasó los tipos
+     * declarados (`ReconcileSource.relationTypes`); sin ellos todo es
+     * `unknown`, que es la verdad. Opcional: un driver de terceros que no lo
+     * calcule simplemente no lo trae y `reconcileLines` lo trata como cero.
+     */
+    foreign?: {
+        /** Cuántas tuplas del destino son de otro subsistema. */
+        tuples: number;
+        /** Cuántas por TIPO de objeto, en orden estable. */
+        types: Record<string, number>;
+        /** De ésas, las de un tipo declarado en `relations.config` (más `group`). */
+        relations?: number;
+        /** Las que no reclama nadie: otro modelo anterior, o un tipo ya retirado. */
+        unknown?: number;
+    };
 }
 export interface ExcludedSubtree {
     scope: ScopeRef;
@@ -846,7 +1033,13 @@ export interface ScopeEdgePage {
  *
  * Sin él, `authz:reconcile --to=openfga` no puede migrar el árbol y lo dice
  * (500 `E_AUTHZ_CONFIG`): NO se inventa un árbol plano.
- * `sqlScopeEdges(...)` lo implementa sobre una tabla con columna padre.
+ * `sqlScopeEdges(...)` lo implementa sobre UNA tabla con columna padre — y
+ * **concatenar varios `sqlScopeEdges` NO cubre un árbol repartido en varias
+ * tablas** (2.4.0-alpha.4): cada uno hace su `LEFT JOIN` contra su propia
+ * tabla y descarta EN SILENCIO la fila cuyo padre vive en otra, con lo que
+ * `--prune` borraría esas aristas del store y el subárbol entero denegaría.
+ * Ahí se escribe un `enumerateEdges` propio (UNION ALL, cursor por uuid,
+ * `parent IS NULL` = `app`); ver el README de `authz:reconcile`.
  */
 export type ScopeEdgesEnumerator = (options: {
     limit: number;
@@ -886,6 +1079,20 @@ export interface PendingScopeTreeChange {
      * por una cola.
      */
     actor?: SubjectRef;
+    /**
+     * **Cuándo se encoló** (2.4.0-alpha.8; panel relay 2, cuestión 5). Es el
+     * sello de `created_at` con el reloj de QUIEN ENCOLÓ (`sqlScopeOutbox` lo
+     * devuelve tal cual: la columna ya existía). Con él el relay publica la
+     * EDAD de la cabeza global de la cola (`ScopeRelayReport.queue`), que es la
+     * alarma que faltaba cuando el store está caído (un 503 no consume intento,
+     * así que `attempts` y `dead` se quedan a cero durante horas). OPCIONAL: una
+     * outbox de terceros que no lo traiga deja el campo AUSENTE —jamás `0` ni
+     * «ahora»— y el reporte dice `null` (patrón `stillGranting`/
+     * `countRoleAssignments`: «no lo sé» no degrada a un número). Es un sello,
+     * no una decisión: nada del paquete decide con él (README, «audit stamps are
+     * not decisions»).
+     */
+    createdAt?: Date;
 }
 /** Lo que el relay aplicó (o aplicaría), pieza a pieza. */
 export interface RelayedScopeChange {
@@ -895,6 +1102,83 @@ export interface RelayedScopeChange {
     /** La causa, en lo que FALLÓ, se APARCÓ o se APLAZÓ (nunca en lo aplicado). */
     error?: string;
 }
+/**
+ * Un fallo de la pasada (2.4.0-alpha.5 · R2a). `transient` dice si la causa
+ * fue el BACKEND (503: no respondió, venció el deadline, está congelado) y
+ * no la entrada: entonces `markFailed` se llamó con `{ transient: true }` y
+ * `sqlScopeOutbox` NO le contó el intento — una caída del store es común a
+ * todas las entradas y no dice nada de ninguna; `maxAttempts` existe para
+ * converger sobre lo IRREPARABLE (422, 500, el padre borrado). Un
+ * `ScopeOutbox` de terceros que ignore el tercer parámetro cuenta igual.
+ */
+export interface ScopeRelayFailure {
+    id: string | number;
+    change: ScopeTreeChange;
+    error: string;
+    transient: boolean;
+}
+/** Qué fue de una entrada en la pasada (2.4.0-alpha.5 · R1, `ScopeRelayReport.entries`). */
+export type ScopeRelayEntryStatus = 'applied' | 'deferred' | 'failed' | 'dead';
+/**
+ * **El resultado por ENTRADA** (2.4.0-alpha.5 · R1; COGNITIV comparaba
+ * claves de `applied[].change` a mano, y dos cambios iguales encolados dos
+ * veces no se distinguen así). Una fila por cada entrada que la pasada
+ * miró, en orden de proceso, con las aparcadas al final:
+ *
+ *  - `applied`: aterrizó en el driver y está marcada;
+ *  - `deferred`: NO se intentó, y `reason` dice por qué, en una de dos formas
+ *    —`depends-on:<id>`: una entrada ANTERIOR sin aplicar comparte clave de
+ *    scope con ella (falló en esta pasada, quedó aplazada, o está pendiente y
+ *    no entraba en `only`); `parked:<id>`: la entrada aparcada `<id>` nombra
+ *    uno de sus scopes y esta concede o recuelga (`attached`/`moved`)—;
+ *  - `failed`: se intentó y el driver lanzó; `reason` es el mensaje;
+ *  - `dead`: aparcada por la outbox; `reason` es su última causa.
+ *
+ * Con `only`, las entradas son las pedidas (y las que de ellas estén
+ * aparcadas); las que no estaban ni pendientes ni aparcadas salen en
+ * `missing`, nunca desaparecen en silencio.
+ */
+export interface ScopeRelayEntry {
+    id: string | number;
+    change: ScopeTreeChange;
+    status: ScopeRelayEntryStatus;
+    reason?: string;
+    attempts?: number;
+    /**
+     * Solo en `deferred` (2.4.0-alpha.8): el ORIGEN —transitivo, la causa
+     * raíz— del bloqueo que la aplazó. `parked` = una entrada APARCADA (la
+     * exención de la purga, invariante 11, mira SOLO este valor); `failed` =
+     * un fallo real de esta pasada; `pending` = bajo `only`, una anterior
+     * pendiente de verdad que no se pidió (se aplicaría en la pasada
+     * completa). Hasta alpha.8 esto solo estaba en la prosa de
+     * `deferred[].error`, y `depends-on:` no distinguía `pending` de
+     * `failed`. Se deriva del bloqueo, nunca del prefijo de `reason`.
+     */
+    origin?: ScopeRelayBlockOrigin;
+}
+/** El origen de un bloqueo por clave (2.4.0-alpha.8). Ver `ScopeRelayEntry.origin`. */
+export type ScopeRelayBlockOrigin = 'parked' | 'pending' | 'failed';
+/**
+ * **La edad de la cola** (2.4.0-alpha.8; panel relay 2, cuestión 5; el B2 del
+ * auditor de COGNITIV: diez pasadas con el store caído decían `attempts = 0`,
+ * `dead = 0` y nada de tiempo). Es la CABEZA GLOBAL de la cola —el
+ * `pending(1)` que la pasada ya hacía al final para `remaining`, cero
+ * consultas nuevas— y su edad medida con el reloj INYECTABLE del manager
+ * (`config.clock`, jamás `Date.now()` en `src/`): `Math.max(0, ahora −
+ * createdAt)`, nunca negativa (el `created_at` lo selló el reloj de OTRA
+ * réplica, con su skew). **Siempre global**, también bajo `only` (como
+ * `remaining` y `dead`): no filtra identidad de nadie, como mucho dice «hay
+ * backlog». `null` en los dos campos si no hay nada PENDIENTE (cola vacía, o
+ * solo aparcadas: lo aparcado tiene su propia alarma, `deadCount`) o si la
+ * outbox no trae `createdAt`. El comando la imprime y `--max-age=<ms>` sale
+ * ≠ 0 SOLO con umbral y por encima de él.
+ */
+export interface ScopeRelayQueue {
+    /** El `createdAt` de la pendiente más antigua de TODA la cola, o `null`. */
+    oldestPendingAt: Date | null;
+    /** `ahora − oldestPendingAt` con el reloj del manager, ≥ 0; `null` si no hay cabeza con fecha. */
+    pendingAgeMs: number | null;
+}
 /**
  * Reporte de `authz:scopes:relay` (3b-2d; 3b-2h · 🔴 2). Dice QUÉ se aplicó,
  * no un contador: la pasada no es atómica y un número no permite retomar nada.
@@ -907,34 +1191,76 @@ export interface ScopeRelayReport {
      * porque es lo que mira un supervisor; la lista completa está en
      * `failures`.
      */
-    failed: {
-        id: string | number;
-        change: ScopeTreeChange;
-        error: string;
-    } | null;
+    failed: ScopeRelayFailure | null;
     /**
      * TODO lo que falló en esta pasada (3b-2h · 🔴 2). Un fallo ya no para la
      * pasada entera: para lo que DEPENDE de él —los cambios que nombran alguno
-     * de sus scopes, que salen en `deferred`— y el resto sigue.
+     * de sus scopes, que salen en `deferred`— y el resto sigue. `transient`
+     * (alpha.5 · R2a) distingue la caída del backend, que no consume intento,
+     * del fallo de la entrada, que sí.
      */
-    failures: Array<{
-        id: string | number;
-        change: ScopeTreeChange;
-        error: string;
-    }>;
+    failures: ScopeRelayFailure[];
     /**
      * Lo que NO se intentó porque toca un scope contaminado por un fallo o por
      * otro aplazado de esta misma pasada. Es lo que mantiene el ORDEN del árbol
      * (aplicar un `moved` antes que el `attached` de su padre da un árbol que
      * nunca existió) sin dejar que una fila envenenada bloquee a los demás.
+     *
+     * Desde 2.4.0-alpha.5 también contamina lo APARCADO (R2a): las claves de
+     * `dead()` siembran el bloqueo al inicio de la pasada, pero solo para lo
+     * que concede o recuelga (`attached`/`moved`) — un `detached` de esa clave
+     * se aplica igual (invariante 11: una purga nunca queda bloqueada). Y con
+     * `only` (R1) también lo que depende de una pendiente ANTERIOR que no se
+     * pidió: `deferred`, nunca aplicado fuera de orden.
      */
     deferred: RelayedScopeChange[];
     /**
      * Entradas APARCADAS por la outbox tras agotar sus intentos (`dead()`), si
      * la implementación lo soporta. No se van a aplicar solas: el árbol del
      * backend está permanentemente divergente en esos nodos y hay que mirarlas.
+     * **Siempre GLOBAL**, también con `only` (como `remaining`): un reporte
+     * filtrado que callara lo aparcado sería un reporte en verde sobre una cola
+     * que no converge. Por lo mismo, este reporte enumera actividad de otros
+     * tenants: no lo devuelvas por HTTP (README).
      */
     dead: RelayedScopeChange[];
+    /**
+     * **Cuántas entradas APARCADAS hay en TODA la cola** (2.4.0-alpha.8),
+     * siempre y global. `dead` está acotado a `batchSize` (100), así que
+     * `dead.length` MIENTE cuando hay más; la alarma «la cola no converge» se
+     * sostiene con este número, no con la lista. Sale del censo que la pasada
+     * ya lee para el tapón por clave (cero consultas nuevas); `0` con una outbox
+     * sin `dead()`.
+     */
+    deadCount: number;
+    /** La edad de la cabeza GLOBAL de la cola (2.4.0-alpha.8). Ver `ScopeRelayQueue`. */
+    queue: ScopeRelayQueue;
+    /**
+     * El resultado por ENTRADA (2.4.0-alpha.5 · R1): qué fue de cada una, con
+     * su motivo. Ver `ScopeRelayEntry`. Con o sin `only`.
+     */
+    entries: ScopeRelayEntry[];
+    /**
+     * Con `only`: los ids pedidos que NO están en la cola —ni pendientes ni
+     * aparcados— ya aplicados por una pasada anterior (la receta inline con un
+     * cron detrás), o inexistentes; el relay no puede distinguirlo. Vacío sin
+     * `only`. Nunca un reporte vacío en verde por un id que no era.
+     *
+     * **Desde el cierre-2 de 2.4.0-alpha.10 · C2** un id PENDIENTE que la pasada no
+     * llegó a evaluar NO va aquí sino en `notEvaluated`: hasta entonces
+     * `only: [a, b], limit: 1` metía `b` en `missing` —«ya lo aplicó otra pasada, o no
+     * existe»— con `b` pendiente.
+     */
+    missing: Array<string | number>;
+    /**
+     * **Con `only`: los ids pedidos que SIGUEN PENDIENTES y esta pasada no evaluó**
+     * (cierre-2 de 2.4.0-alpha.10 · C2, campo aditivo): la pasada alcanzó `limit`
+     * antes de llegar a ellos (en `dryRun`, `wouldApply` se cortó en `limit`). No se
+     * aplicaron ni se aplazaron: no se miraron. Se distingue de `missing` con UNA
+     * lectura más de la cola filtrada por esos ids, solo si hay ids pedidos sin ver.
+     * Vacío sin `only` y en un reporte `busy` (ahí no se evaluó nada y lo dice `busy`).
+     */
+    notEvaluated: Array<string | number>;
     /**
      * Otra pasada tenía el lease de la cola y esta no ha hecho NADA (3b-2h ·
      * 🟠 4). No es un error: el relay es escritor ÚNICO.
@@ -958,11 +1284,75 @@ export interface ScopeOutboxContext {
     /**
      * Lo que el llamante pasó en `ScopeTreeWriteOptions.transaction`: para
      * Lucid, el `TransactionClientContract` de la transacción en curso. El
-     * paquete no lo interpreta —no conoce la BD del consumidor—: lo pasea.
+     * manager no lo interpreta —no conoce la BD del consumidor—: lo pasea.
+     * `sqlScopeOutbox` SÍ lo juzga (L-1 · 🟠 9, `assertCallerTransaction`):
+     * tiene que ser una transacción ABIERTA de la conexión de la cola, o 500
+     * `E_AUTHZ_CONFIG` antes del INSERT. Una outbox propia hereda el deber.
      */
     transaction?: unknown;
     actor?: SubjectRef;
 }
+/**
+ * **El recibo del encolado** (2.4.0-alpha.5 · R1). Lo devuelven
+ * `manager.scopes.attached/moved/detached`: los ids que la outbox asignó a
+ * lo que acaba de encolar — en PLURAL, porque `scopes.detached` encola una
+ * fila por ortografía del uuid cuando la fila del consumidor ya no existe
+ * (invariante 17). Es lo que se le pasa a `relayScopeChanges({ only })` para
+ * relevar «lo mío» en la misma petición sin pagar la cola de los demás.
+ *
+ * **Vacío = no hay nada que relevar**: sin outbox el manager aplicó el cambio
+ * en línea en el driver; con una outbox de terceros cuyo `enqueue` devuelve
+ * `void` tampoco hay id, y entonces `only` no se puede usar con esa outbox
+ * (el manager lo dice con 500 al recibir `only: []`, jamás relevando la cola
+ * entera en silencio).
+ */
+export interface ScopeEnqueueReceipt {
+    queued: Array<string | number>;
+}
+/** El filtro de `ScopeOutbox.pending` (2.4.0-alpha.5 · R1): SOLO estos ids. */
+export interface ScopeOutboxPendingFilter {
+    ids: Array<string | number>;
+}
+/** El tercer parámetro de `ScopeOutbox.markFailed` (2.4.0-alpha.5 · R2a). */
+export interface ScopeOutboxFailure {
+    /**
+     * `true` = la causa fue el BACKEND (503), no la entrada: la implementación
+     * escribe la causa y NO cuenta el intento. Una implementación que lo
+     * ignore cuenta siempre (lo de hasta alpha.4: degrada hacia lo seguro).
+     */
+    transient?: boolean;
+}
+/**
+ * Un conflicto de `requeue` (2.4.0-alpha.5 · R2b): la entrada APARCADA que se
+ * quiere devolver a la cola y las entradas APLICADAS posteriores (id mayor)
+ * que comparten clave de scope con ella — lo que reaplicarla REVERTIRÍA.
+ * Es el diff que `authz:scopes:requeue` imprime y que `--force` acepta.
+ */
+export interface ScopeRequeueConflict {
+    parked: PendingScopeTreeChange;
+    /** Las primeras `DEFAULT_RELAY_BATCH` (100), en orden de id. */
+    applied: PendingScopeTreeChange[];
+    /** `true` = había MÁS de las listadas: el diff que lee el operador está cortado, y se dice (cierre alpha.5, ⚪ 6). */
+    truncated?: boolean;
+}
+/**
+ * Reporte de `manager.requeueScopeChanges` (2.4.0-alpha.5 · R2b). `overrides`
+ * solo viene poblado con `force: true`: sin él, un conflicto es 500
+ * `E_AUTHZ_REQUEUE_REFUSED` y nada se reencola.
+ */
+export interface ScopeRequeueReport {
+    /** Lo que volvió a `pending()`, con su id de siempre. Con `apply` y el lease ocupado: vacío (cero filas tocadas). */
+    requeued: PendingScopeTreeChange[];
+    /** Los conflictos que `force` saltó (vacío sin conflictos). */
+    overrides: ScopeRequeueConflict[];
+    forced: boolean;
+    /**
+     * Solo con `apply: true` (2.4.0-alpha.8): el reporte de la pasada que relevó
+     * SOLO los ids reencolados, bajo el mismo lease. `relay.busy === true` =
+     * otra pasada tenía el lease y NO se reencoló nada (todo o nada).
+     */
+    relay?: ScopeRelayReport;
+}
 /**
  * **El puerto de la outbox del árbol** (3b-2d, panel 2 cruce 4 · S5).
  *
@@ -989,22 +1379,66 @@ export interface ScopeOutbox {
      * Encola el cambio en la transacción del consumidor. Debe escribir y
      * volver: nada de aplicarlo aquí. Si lanza, la escritura del manager falla
      * (y la transacción del consumidor se lleva las dos cosas).
+     *
+     * **Recibo** (2.4.0-alpha.5 · R1): devuelve `{ id }` con el identificador
+     * del registro —el MISMO que `pending()` devolverá en `id`— y el manager lo
+     * entrega al llamante en `ScopeEnqueueReceipt.queued`. Es covariante: una
+     * implementación que siga devolviendo `void` compila y funciona, y su
+     * consumidor recibe `queued: []` (sin recibo no hay `only`).
      */
-    enqueue(change: ScopeTreeChange, context: ScopeOutboxContext): Promise<void>;
+    enqueue(change: ScopeTreeChange, context: ScopeOutboxContext): Promise<void | {
+        id: string | number;
+    }>;
     /**
      * Los pendientes MÁS ANTIGUOS primero: el orden del árbol es el del
-     * encolado. `after` (3b-2h · 🔴 2) es el id del último registro que el
+     * encolado. **Y ENTEROS** (cierre alpha.5, auditor 🟡 3): `pending()` no
+     * puede ESCONDER una entrada sin aplicar que el relay no haya filtrado con
+     * `filter.ids` —ni por tenant, ni por scope, ni por nada—. La garantía de
+     * orden por clave del relay (que un `attached` no aterrice antes que el
+     * `moved` del que depende) se apoya en que la cola que ve es la cola
+     * entera; una implementación que filtre por su cuenta reabre la escalada
+     * medida en `relay-auditor-2.ts` y ningún guardián del manager la ve. Es
+     * un deber del puerto y `runScopeOutboxContract` lo juzga (O-08).
+     * `after` (3b-2h · 🔴 2) es el id del último registro que el
      * relay ya vio en ESTA pasada: como una entrada que falla ya no para la
      * pasada, se queda pendiente y volvería a salir la primera para siempre.
      * Una implementación que lo ignore sigue siendo válida —el relay detecta
      * que no avanza y termina la pasada—, pero solo drenará hasta el primer
      * lote atascado.
-     */
-    pending(limit: number, after?: string | number): Promise<PendingScopeTreeChange[]>;
+     *
+     * `filter` (2.4.0-alpha.5 · R1, opcional): SOLO los pendientes cuyo id esté
+     * en `filter.ids`, mismo orden. Es lo que hace que `relayScopeChanges({
+     * only })` no lea la cola de los demás (medido: 4 507 ms → 19 ms con 500
+     * entradas ajenas por delante). Una implementación que lo IGNORE devuelve
+     * lo que no se pidió, y el manager lo detecta y para (500 `E_AUTHZ_CONFIG`
+     * nombrando el puerto) en vez de aplicar el backlog ajeno dentro de tu
+     * petición: el filtro tiene que estar AQUÍ, no en memoria.
+     */
+    pending(limit: number, after?: string | number, filter?: ScopeOutboxPendingFilter): Promise<PendingScopeTreeChange[]>;
     /** Aplicado en el backend: no se vuelve a relevar. */
     markApplied(id: string | number): Promise<void>;
-    /** Falló al aplicarse: se queda pendiente, con la causa a la vista. */
-    markFailed(id: string | number, error: string): Promise<void>;
+    /**
+     * Falló al aplicarse: se queda pendiente, con la causa a la vista.
+     * `options.transient` (2.4.0-alpha.5 · R2a): la causa fue el backend, no la
+     * entrada — escribe la causa y NO cuentes el intento. Ignorarlo es válido
+     * (cuenta siempre, lo de hasta alpha.4).
+     */
+    markFailed(id: string | number, error: string, options?: ScopeOutboxFailure): Promise<void>;
+    /**
+     * **La sonda de dependencia de `only`** (2.4.0-alpha.5 · R1), opcional:
+     * la entrada PENDIENTE más antigua anterior a `id` (menor id, sin aplicar,
+     * NO aparcada) que nombre —como hijo o como padre— alguno de `scopes`, o
+     * `null`. Con ella, `relayScopeChanges({ only })` decide si una entrada
+     * pedida depende de una que no se pidió sin leer la cola entera: una sonda
+     * de existencia (0,69 ms medidos sobre 501 pendientes con el índice
+     * `(applied_at, id)`). Un nivel basta: si una cadena de pendientes llega
+     * hasta `id`, su último eslabón comparte clave con ella por definición de
+     * la contaminación por clave.
+     *
+     * Sin ella el manager hace lo mismo paginando `pending()` desde el
+     * principio hasta `id` — correcto, pero O(cola).
+     */
+    earlierPending?(id: string | number, scopes: ScopeRef[]): Promise<PendingScopeTreeChange | null>;
     /**
      * **Las entradas APARCADAS** (3b-2h · 🔴 2), opcional. Una entrada que ya
      * no se puede aplicar —su scope padre se borró antes de la pasada— no se
@@ -1034,6 +1468,35 @@ export interface ScopeOutbox {
      * reabriría la ventana del doble escritor que este lease cierra.
      */
     acquire?(): Promise<ScopeOutboxLease | null>;
+    /**
+     * **Reencola entradas APARCADAS** (2.4.0-alpha.5 · R2b), opcional y
+     * MECÁNICO: la política —la sonda anti-reversión— es del manager
+     * (`requeueScopeChanges`), porque necesita las claves de scope del cambio y
+     * una implementación de terceros no las tiene. Todo o nada: cada id tiene
+     * que existir y estar aparcado (sin aplicar, intentos agotados); si alguno
+     * no lo está —no existe, sigue pendiente, ya se aplicó— se lanza
+     * nombrándolo y NO se toca ninguna fila (una entrada aplicada no revive
+     * jamás: reencolar un `detached` aplicado volvería a purgar). La entrada
+     * vuelve a `pending()` con su id de siempre y **`attempts = maxAttempts −
+     * 1`** (decisión del dueño del 2026-09-09 (2)): si la causa sigue rota
+     * vuelve a aparcarse en UNA pasada —y contamina su clave solo esa pasada—,
+     * y si el operador la arregló entra a la primera. Sin columna nueva.
+     * `sqlScopeOutbox` lo implementa; el manager lo exige junto a
+     * `laterApplied` (sin sonda no hay requeue: 500 `E_AUTHZ_UNSUPPORTED`).
+     */
+    requeue?(ids: Array<string | number>): Promise<void>;
+    /**
+     * **La sonda anti-reversión de `requeue`** (2.4.0-alpha.5 · R2b), opcional
+     * en el puerto pero exigida por `requeueScopeChanges`: las entradas
+     * APLICADAS con id MAYOR que `id` que nombren —como hijo o como padre—
+     * alguno de `scopes`, en orden de id y hasta `limit`. Espejo de
+     * `earlierPending`. Es lo que el manager mira antes de devolver una
+     * aparcada a la cola: reaplicar un `moved` viejo después de otro `moved`
+     * ya aplicado deja el store con el padre VIEJO y un solo padre (medido:
+     * `assertOneParent` no lo delata). Las filas vuelven con la forma de
+     * `pending()`; `attempts`/`lastError` son los que tenían al aplicarse.
+     */
+    laterApplied?(id: string | number, scopes: ScopeRef[], limit: number): Promise<PendingScopeTreeChange[]>;
 }
 /**
  * El árbol del consumidor hacia ABAJO (2.1, B2): todos los descendientes de
@@ -1110,8 +1573,24 @@ export interface AuthzWriteEvent {
      * propagar el 503 para que la auditoría registre un resultado desconocido
      * en vez de un silencio (que se lee como "no pasó nada"). Un 503 que no es
      * timeout (conexión rechazada) no lo lleva: esa escritura no ocurrió.
+     *
+     * **Con `{ transaction }` (L-3) sigue siendo `true` en el deadline**, junto
+     * a `transactional: true`: la sentencia puede haber aterrizado DENTRO de la
+     * transacción del llamante (SQLite no cancela; MySQL la mata y la
+     * transacción sigue; PostgreSQL deja la transacción abortada) y confirmar
+     * o no es del llamante, que el paquete no ve. Invariante 13 intacto.
      */
     indeterminate?: boolean;
+    /**
+     * `true` cuando la escritura se inscribió en la transacción del llamante
+     * (`{ transaction }`, L-3): en el momento del evento la fila existe SOLO
+     * dentro de esa transacción, y es un hecho si y solo si el llamante
+     * confirma — cosa que el paquete no ve. Un sink que registre esto como
+     * firme registra algo que un rollback deshace; si necesita la última
+     * palabra, que se cuelgue del commit (`trx.after('commit', …)` en Lucid).
+     * Ausente en el resto (encolar en `scopes.*` no es escribir y no lo lleva).
+     */
+    transactional?: boolean;
 }
 /** Un rol del catálogo tal como lo ve el motor (3A · A2/A3, 3B · B2). */
 export interface CatalogRole {
@@ -1317,16 +1796,116 @@ export interface RelationRef {
     relation: string;
     object: RelObject;
     partition: ScopeRef;
+    /**
+     * La caducidad pedida en `relate` (R-15), en sus tres estados: omitida
+     * (preserva la vigente), `null` (la quita) o `Date` (la fija). Solo viaja en
+     * `relate`; `assertWrite` puede rechazar una compartición sin plazo.
+     */
+    expiresAt?: Date | null;
+}
+/**
+ * El evento de escritura de relaciones (auditoría del consumidor, sin
+ * `AsyncLocalStorage`), notificado a `onRelationWrite` DESPUÉS de que el
+ * driver vuelva. **Espeja la forma de `AuthzWriteEvent`** (2.4.0-alpha.3,
+ * paridad con roles): un solo tipo con campos opcionales, no una unión.
+ *
+ * - `relate`/`unrelate`: `subject`, `relation`, `object` y `partition` (y
+ *   `expiresAt` en `relate` si se pasó) — la `RelationRef` que vio
+ *   `assertWrite`, más `actor`.
+ * - `purgeObject`: `object` y `partition`; **sin `subject` ni `relation`**.
+ * - `purgeSubject`: `subject` y `partition`; **sin `object` ni `relation`**.
+ *   Una purga notifica **UN evento por llamada**, aunque el driver barra las
+ *   dos ortografías del uuid de partición, y **sin conteo**: el puerto
+ *   devuelve `void` (un conteo obligaría a romperlo para los drivers de
+ *   terceros y dentro de una `{ transaction }` sería un número que un
+ *   rollback desmiente). Quien necesite el «cuántas» tiene
+ *   `enumerateRelations`/`listSubjects` ANTES de purgar. Las purgas NO pasan
+ *   por `assertWrite` (su `RelationRef.operation` es `'relate' | 'unrelate'`,
+ *   tipo publicado del hook R-13).
+ */
+export interface RelationWriteEvent {
+    operation: 'relate' | 'unrelate' | 'purgeObject' | 'purgeSubject';
+    /** Ausente solo en `purgeObject` (afecta a todos los sujetos del objeto). */
+    subject?: RelSubject;
+    /** Ausente en `purgeObject`/`purgeSubject` (afectan a todas las relaciones). */
+    relation?: string;
+    /** Ausente solo en `purgeSubject` (afecta a todos los objetos del sujeto). */
+    object?: RelObject;
+    partition: ScopeRef;
+    /** La caducidad pedida en `relate` (R-15), si se pasó. Solo en `relate`. */
+    expiresAt?: Date | null;
+    /** Quién ordenó la escritura (`actor` de las opciones), ya validado (422 si mal formado). Ausente si no lo pasó. */
+    actor?: SubjectRef;
+    /**
+     * `true` cuando la escritura se inscribió en la transacción del llamante
+     * (`{ transaction }`, L-4): en el momento del evento la tupla existe SOLO
+     * dentro de esa transacción y es un hecho si y solo si el llamante
+     * confirma — cosa que el paquete no ve. Un sink que quiera la última
+     * palabra se cuelga de `trx.after('commit', …)`. **Ausente** sin
+     * `{ transaction }` (nunca `false`).
+     */
+    transactional?: true;
+    /**
+     * `true` cuando el paquete NO sabe si el backend aplicó la escritura
+     * (invariante 13, el MISMO de roles): venció el deadline (503
+     * `E_AUTHZ_BACKEND_TIMEOUT`) **o la escritura era multi-request y falló
+     * DESPUÉS de haber aplicado parte** (la purga de `openfga`: ortografías ×
+     * tipos, cada una `Read`+`deleteTuples`+`Read`; el driver marca el error
+     * con `markPartialWrite`, cierre de alpha.3). Se notifica ANTES de
+     * propagar el error. Un 422, el freeze o un `assertWrite` que lanza no lo
+     * llevan: esa escritura no ocurrió y no hay evento. Un 503 que no es
+     * timeout tampoco **cuando llega antes de la primera sentencia/`Write`**
+     * — en `database` una purga es UN `DELETE`, así que siempre; en `openfga`
+     * solo si aún no se había borrado nada. Con `{ transaction }` sigue siendo
+     * `true` junto a `transactional: true`. **Ausente** en el resto.
+     */
+    indeterminate?: true;
+}
+/**
+ * Opciones de `purgeObject`/`purgeSubject` (L-2): solo la transacción del
+ * consumidor. Ver `RelationTransactionOptions.transaction`.
+ */
+export interface RelationTransactionOptions {
+    /**
+     * **La transacción ABIERTA del consumidor** (`TransactionClientContract` de
+     * Lucid), para que la escritura de la tupla confirme o revierta CON la tuya
+     * — L-2, panel `{trx}` (C). Aquí significa **ESCRIBIR en tu transacción**
+     * («los dos o ninguno» en el mismo motor transaccional) — **encolar ≠
+     * escribir**: no es la outbox de `scopes.*`, que solo ENCOLA. Solo lo
+     * cumple un driver con `capabilities.transactionalWrites: true` (`database`,
+     * con el `trx` de SU conexión, L-4); con `false` (`openfga`: una tupla no
+     * entra en una transacción SQL) la llamada es **500 `E_AUTHZ_UNSUPPORTED`**
+     * nombrando driver y operación, antes de tocar el driver. Con
+     * `requireTransactionalWrites: true` (`config.relations`, o heredado del
+     * raíz) un driver `false` es 500 `E_AUTHZ_CONFIG` al resolver. La
+     * AUTORIDAD (barrera del freeze) nunca viaja por ella: pool ≥ 2.
+     */
+    transaction?: unknown;
 }
-/** El evento de escritura de relaciones (auditoría del consumidor, sin `AsyncLocalStorage`). */
-export interface RelationWriteEvent extends RelationRef {
-    /** Quién ordenó la escritura (`RelationWriteOptions.actor`), ya validado. Ausente si no lo pasó. */
+/**
+ * Opciones de `purgeObject`/`purgeSubject` del `RelationsManager`
+ * (2.4.0-alpha.3): la transacción del consumidor Y el `actor`. Una purga es
+ * la escritura que MÁS actor necesita (un borrado masivo de llaves), así que
+ * está sujeta a `requireActor` como el `scopes.detached` de roles.
+ */
+export interface RelationPurgeOptions extends RelationTransactionOptions {
+    /** Quién ordena la purga; validado (422) y viaja en `RelationWriteEvent.actor`. */
     actor?: SubjectRef;
 }
 /** Opciones comunes a `relate`/`unrelate`. */
-export interface RelationWriteOptions {
-    /** Quién ordena la escritura; viaja en `RelationWriteEvent.actor`. */
+export interface RelationWriteOptions extends RelationTransactionOptions {
+    /** Quién ordena la escritura; validado (422 `E_AUTHZ_INVALID_IDENTITY` si mal formado) y viaja en `RelationWriteEvent.actor`. */
     actor?: SubjectRef;
+    /**
+     * **Caducidad de la tupla de relación** (R-15, 2.4.0-alpha.2) — los MISMOS
+     * tres estados que `grant` (invariante 10): omitida ⇒ preserva una caducidad
+     * VIGENTE (una ya caducada revive sin caducidad: es una relación nueva);
+     * `null` ⇒ la quita; `Date` ⇒ la fija (también a un instante pasado: caduca).
+     * Caducidad ESTRICTA: lo que vence AHORA ya no cuenta (`expires_at > now`;
+     * `current_time < valid_until`). Solo la lee `relate`; `unrelate` la ignora.
+     * Cualquier otro valor ⇒ 422 `E_AUTHZ_INVALID_IDENTITY` antes del driver.
+     */
+    expiresAt?: Date | null;
 }
 /** Una página de una enumeración de relaciones (cursor opaco que AVANZA, no filtra herencia). */
 export interface RelationPage {
@@ -1366,7 +1945,40 @@ export interface RelationsDriverCapabilities {
      * `truncationSignal` de los `list*` de roles.
      */
     listObjectsTruncation: boolean;
+    /**
+     * El driver acepta un reloj inyectado (R-15, paridad con el par
+     * `injectableClock` de roles, 2.5 · J1): `withClock(now)` devuelve una
+     * vista del driver cuyo `now()` decide la caducidad de las tuplas. Con
+     * `true` el juez observa la caducidad EXACTA (T−1 ms concede, T no) y los
+     * tres estados de `expiresAt` sin dormir; con `false` solo puede observarlos
+     * en tiempo real (y el driver NO debe traer `withClock`: declara lo que se
+     * observa).
+     */
+    injectableClock: boolean;
+    /**
+     * El driver puede inscribir sus escrituras en la transacción del consumidor
+     * (`{ transaction }` en `relate`/`unrelate`/`purgeObject`/`purgeSubject`).
+     * `true` significa EXACTAMENTE «los dos o ninguno con TU transacción»,
+     * nunca «no se pierde». `database` = **`true`** desde L-4 (la escritura va
+     * por el `trx` ABIERTO de SU conexión, `assertCallerTransaction`; la
+     * AUTORIDAD —barrera del freeze, F-05— nunca; exige pool ≥ 2, y un
+     * despliegue con pool 1 declara `false` con la opción
+     * `DatabaseRelationsDriverOptions.transactionalWrites`). `openfga` = false,
+     * y no puede ser otra cosa: una tupla no entra en una transacción SQL — el
+     * store es otro servicio y no hay 2PC. **Mismo nombre que en
+     * `AuthorizationDriverCapabilities`**. Con `false`, `{ transaction }` es 500
+     * `E_AUTHZ_UNSUPPORTED` por llamada (cero llamadas al driver); con
+     * `requireTransactionalWrites: true` un driver `false` es 500
+     * `E_AUTHZ_CONFIG` al resolver. La cara `true` del runner juzga el rollback
+     * POR CENSO (cero tuplas nuevas para las cuatro escrituras; `purge*`
+     * revierten juntos) y que una transacción ajena no recibe ni una sentencia.
+     */
+    transactionalWrites: boolean;
 }
+/** Las claves de `RelationsDriverCapabilities`, literales: lo que `relations.capabilities()` normaliza (2.4.0-alpha.4). */
+export declare const RELATIONS_DRIVER_CAPABILITY_KEYS: ReadonlyArray<keyof RelationsDriverCapabilities>;
+/** La copia congelada y normalizada de `relations.capabilities()`; misma regla que `normalizeAuthorizationCapabilities`. */
+export declare function normalizeRelationsCapabilities(declared: Partial<RelationsDriverCapabilities> | undefined): Readonly<RelationsDriverCapabilities>;
 /**
  * Una página de `listObjects`/`listSubjects`/`enumerateRelations`. `truncated`
  * dice si el backend cortó al tope (solo con `listObjectsTruncation`): un
@@ -1388,6 +2000,13 @@ export interface RelationTuple {
     relation: string;
     object: RelObject;
     partition: ScopeRef;
+    /**
+     * La caducidad de la tupla tal como está ESCRITA (R-15): `null`/ausente = no
+     * caduca. `enumerateRelations` NO filtra la caducada: tiene que LLEGAR al
+     * destino de `reconcile` con su `expiresAt` para contarse en `skipped`
+     * (la lección de la 3b); filtrarla en el origen la haría desaparecer sin rastro.
+     */
+    expiresAt?: Date | null;
 }
 export interface RelationTuplePage {
     tuples: RelationTuple[];
@@ -1398,7 +2017,34 @@ export interface RelationTuplePage {
  * (`APP_SCOPE` es válida para mono-tenant): el aislamiento de tenant se corta
  * por la partición, y el driver la serializa en el id del objeto y del
  * userset. La whitelist de tipo/relación (F-05) la aplica el manager ANTES de
- * llamar al driver, pero el driver la re-valida por defensa en profundidad.
+ * llamar al driver, pero el driver la re-valida por defensa en profundidad:
+ * `relate`/`unrelate` de `database` y de `openfga` rechazan 422
+ * (`E_AUTHZ_RELATION_TYPE_UNKNOWN` / `E_AUTHZ_RELATION_UNKNOWN`, la MISMA
+ * función y el mismo `code` que el manager, `assertRelationDeclared`) un
+ * `object.type` no declarado o una `relation` no declarada para ese tipo,
+ * ANTES de tocar el backend (cero `Write`, cero INSERT). Es la red para quien
+ * entra por `manager.driver()` o por `reconcileRelations` (L-0): hasta
+ * entonces esta frase era falsa en los dos drivers y, en el store compartido,
+ * `driver.relate(evil, 'assignee', {type:'role_binding', id:<roleUuid>}, S)`
+ * escalaba a `roles.authorize` (medido). **Y desde `2.4.0-alpha.3` en las
+ * OCHO operaciones** (cierre del 🔴 1 / 🟠 2 del auditor; cierre-2 · 🟡 3):
+ * `purgeObject` (el tipo, `assertObjectTypeDeclared`), `purgeSubject` (el
+ * userset del sujeto), `check`/`listSubjects`/`membersOf` (el par) y
+ * `listObjects` (tipo y relación) también la aplican, en el manager y en los
+ * dos drivers, con cero llamadas al backend — sin ella
+ * `purgeObject({type:'role_binding', id:R}, S)` BORRABA el binding real del
+ * store compartido y `listSubjects('assignee', role_binding)` enumeraba sus
+ * asignados (medido contra el `:8101`). **La relación es OBLIGATORIA** donde
+ * se nombra (cierre-2 · 🟠 1: `undefined` ⇒ 422 `E_AUTHZ_RELATION_UNKNOWN`,
+ * nunca una tupla escrita, un 503 del servidor ni la unión de `listSubjects`).
+ * El runner publicado lo exige a un driver de terceros en las seis.
+ *
+ * **Invariante 13 y las purgas multi-request**: un driver cuya purga NO sea
+ * una sola sentencia/`Write` y falle DESPUÉS de haber borrado parte debe
+ * propagar el error marcado con `markPartialWrite` (exportado): el
+ * `RelationsManager` notifica entonces `onRelationWrite` con
+ * `indeterminate: true` antes de propagar. `openfga` lo hace; `database`
+ * (un `DELETE`) no lo necesita.
  */
 export interface RelationsDriver {
     readonly capabilities?: RelationsDriverCapabilities;
@@ -1412,10 +2058,10 @@ export interface RelationsDriver {
     listObjects(subject: RelSubject, relation: string, objectType: string, partition: ScopeRef, page?: RelationPage): Promise<RelationObjectsPage>;
     /** Los sujetos DIRECTOS de `relation` sobre `object` (holders y usersets). Nunca la membresía transitiva (eso es `membersOf`). */
     listSubjects(relation: string, object: RelObject, partition: ScopeRef, page?: RelationPage): Promise<RelationSubjectsPage>;
-    /** Borra todas las tuplas cuyo OBJETO es `object` y demuestra cero, o lanza 500 `E_AUTHZ_PURGE_INCOMPLETE` (invariante 11). */
-    purgeObject(object: RelObject, partition: ScopeRef): Promise<void>;
-    /** Borra todas las tuplas cuyo SUJETO es `subject` y demuestra cero, o lanza 500. */
-    purgeSubject(subject: RelSubject, partition: ScopeRef): Promise<void>;
+    /** Borra todas las tuplas cuyo OBJETO es `object` (F-05 sobre el TIPO, alpha.3) y demuestra cero, o lanza 500 `E_AUTHZ_PURGE_INCOMPLETE` (invariante 11). Si falla tras borrar parte, marcado con `markPartialWrite`. */
+    purgeObject(object: RelObject, partition: ScopeRef, options?: RelationTransactionOptions): Promise<void>;
+    /** Borra todas las tuplas cuyo SUJETO es `subject` (F-05 sobre el userset, alpha.3) y demuestra cero, o lanza 500. Si falla tras borrar parte, marcado con `markPartialWrite`. */
+    purgeSubject(subject: RelSubject, partition: ScopeRef, options?: RelationTransactionOptions): Promise<void>;
     /**
      * La membresía TRANSITIVA de un objeto-grupo: todos los holders que son
      * `member` directa o a través de grupos anidados. DISTINTO de
@@ -1423,8 +2069,32 @@ export interface RelationsDriver {
      * lo trae el driver con `membersOfNative: true`.
      */
     membersOf?(object: RelObject, relation: string, partition: ScopeRef, page?: RelationPage): Promise<RelationSubjectsPage>;
-    /** ORIGEN de `authz:reconcile` de relaciones: las tuplas paginadas, sin filtrar. Solo con `enumerateRelations: true`. */
+    /** ORIGEN de `authz:reconcile` de relaciones: las tuplas paginadas, sin filtrar (la caducada LLEGA con su `expiresAt`). Solo con `enumerateRelations: true`. */
     enumerateRelations?(partition: ScopeRef, page?: RelationPage): Promise<RelationTuplePage>;
+    /**
+     * **K particiones en UNA pasada** (2.4.0-alpha.6, opcional). La MISMA
+     * semántica que `enumerateRelations` por cada partición pedida —exhaustiva,
+     * la caducada llega, el cursor avanza— y cada tupla trae SU `partition`
+     * (la referencia pedida, casada por clave ENTERA): el llamante reparte por
+     * ella. Existe porque en `openfga` `enumerateRelations` es un barrido del
+     * store entero por llamada (no hay `Read` por prefijo: responde 200 con cero
+     * tuplas) y K particiones costaban K barridos; con esto cuestan uno.
+     * `reconcileRelations({ partitions })` lo usa si el driver lo trae y si no
+     * cae a K llamadas de `enumerateRelations` (correcto, más caro). Un driver
+     * que lo implemente tiene que enumerar EXHAUSTIVAMENTE o fallar ruidoso:
+     * jamás «vacío = éxito» para una partición que no pudo leer entera.
+     */
+    enumerateRelationsMany?(partitions: ScopeRef[], page?: RelationPage): Promise<RelationTuplePage>;
+    /**
+     * Vista de este driver con OTRO reloj de pared (R-15, paridad con
+     * `AuthorizationDriver.withClock`, 2.5 · J1): mismo backend, solo cambia el
+     * `now()` que decide la caducidad (`expires_at > now` en SQL; el
+     * `current_time` del `Check` en FGA; el filtro en cliente de `listSubjects`).
+     * Opcional: el `RelationsManager` lo aplica si recibe `clock` (500
+     * `E_AUTHZ_CONFIG` si el driver no lo trae) y el juez lo usa con
+     * `injectableClock: true`.
+     */
+    withClock?(now: () => Date): RelationsDriver;
 }
 /**
  * Factory de un `RelationsDriver` (Fase 4, lote 4-6) — el análogo de