@jantstack/adonis-authz 2.0.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`,
@@ -105,6 +140,38 @@ export interface ScopedWriteOptions extends WriteOptions {
      */
     within?: ScopeRef;
 }
+/**
+ * Opciones de las TRES notificaciones del árbol (`scopes.attached/moved/
+ * detached`) — 3b-2d. Añaden la transacción del consumidor, que solo se usa
+ * cuando hay `scopes.outbox` declarada: es lo que hace que el cambio del
+ * árbol y su encolado confirmen (o se vayan) juntos.
+ */
+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 — **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;
+}
 export interface GrantOptions extends ScopedWriteOptions {
     /**
      * Caducidad de la asignación, en TRES estados (L0.4):
@@ -162,7 +229,133 @@ export type NormalizedRoleQuery = {
     slug?: undefined;
     scopeType?: undefined;
 };
+/**
+ * **Lo que un driver DECLARA de sí mismo** (3b-2e · E2). No es documentación:
+ * el manager lo LEE (el gate de deriva del árbol, E3) y la suite de contrato
+ * exige a cada capacidad su caso —el del valor declarado, nunca un `skip`—.
+ *
+ * Todas son opcionales de declarar (un driver de 2.x que no traiga
+ * `capabilities` se trata como todo `false`), pero declarar `true` lo que no
+ * se cumple es una promesa sin juez: el contrato lanza al registrarse.
+ */
+export interface AuthorizationDriverCapabilities {
+    /**
+     * El ÁRBOL de scopes vive como hechos del backend y el backend es el PDP
+     * (`openfga` con `hierarchy: 'facts'`). Con `true` el manager exige la
+     * mitigación de la deriva (`scopes.outbox` o la firma explícita): el árbol
+     * está en dos sitios y un `rollback` del consumidor deja al backend
+     * adelantado (cruce 4 · S5).
+     */
+    hierarchyFacts: boolean;
+    /**
+     * `authorize` es UNA sola llamada al backend: no consulta el árbol del
+     * consumidor (`resolveChain`) y el catálogo solo a través del memo.
+     */
+    singleCheckAuthorize: boolean;
+    /**
+     * El backend resuelve la MEMBRESÍA por sí mismo. **`false` en los dos
+     * drivers del paquete, también en `facts`** (panel 2, cruce 6): `hasRole`,
+     * `listRoles`, `listRoleScopes`, `listSubjects` y `listScopes` siguen
+     * usando `resolveChain`. Por eso el titular «sin SQL en el camino caliente»
+     * está PROHIBIDO a secas: lo cierto es «sin SQL por request en `authorize`».
+     */
+    roleInheritanceNative: boolean;
+    /**
+     * Los `list*` enumeran también lo HEREDADO. **`false` siempre en este
+     * paquete** (invariante 7): enumerar descendientes sería abierto, y en
+     * `openfga` además obligaría a `ListObjects`, que trunca al tope del
+     * servidor sin ninguna señal (S16). Los `list*` devuelven hechos DIRECTOS.
+     */
+    listObjectsInherited: boolean;
+    /** El driver implementa `purgeRole` de verdad (sin él no hay roles locales). */
+    purgeRole: boolean;
+    /**
+     * El driver sabe CONTAR los hechos vigentes de un rol
+     * (`countRoleAssignments`, 3b-2j). Es lo que hace verdadero el
+     * `stillGranting` de `pruneOrphanRoles`, que se lee justo antes de un
+     * borrado destructivo. Con `false` el barrido no lo sabe y lo dice
+     * (`undefined`), nunca `false`: «no lo sé» no puede degradar a «no
+     * concede».
+     */
+    countRoleAssignments: boolean;
+    /**
+     * Las LECTURAS canonizan la ortografía del scope contra el árbol del
+     * consumidor antes de buscar los hechos (3b-2k · K1 · R2 (c)). Con `true`
+     * (driver `database`) `authorize` resuelve la cadena y usa `chain[0]`, la
+     * identidad canónica (invariante 17), así que un alias del uuid que TU
+     * tabla funde con la fila real —una columna `uuid` de PostgreSQL, una
+     * collation `*_ci` de MySQL— encuentra los mismos hechos. Con `false`
+     * (`openfga` en modo `facts`) la decisión no pasa por el árbol —es la
+     * contrapartida de `singleCheckAuthorize`— y el objeto del store se compone
+     * con la ortografía del LLAMANTE: un alias responde `false` donde la forma
+     * canónica concede. Es fail-CLOSED y no evade ningún deny, pero no es la
+     * misma respuesta: **pasa los uuids exactamente como los guarda tu tabla**.
+     * La ESCRITURA canoniza en los dos (3b-2h · 🟠 3).
+     */
+    canonicalScopeReads: boolean;
+    /**
+     * El driver sabe ser el **ORIGEN** de una migración: implementa
+     * `enumerateFacts` y entrega sus hechos paginados, sin filtrar y con su
+     * caducidad (3b-3b). Con `true` es lo que `authz:reconcile --to=<otro>`
+     * pasa como `source.facts`. Con `false` el driver no puede ser origen por
+     * el puerto y `authz:reconcile` lo DICE (500 `E_AUTHZ_UNSUPPORTED`
+     * nombrando `enumerateFacts`), nunca una migración vacía en silencio — que
+     * es exactamente el fail-dangerous que se evita: un origen que devuelve
+     * cero hechos y un `--prune` detrás borran el destino entero.
+     *
+     * **`false` en el driver `database` a propósito**: sus hechos son
+     * `authz_assignments`/`authz_denies`, el esquema publicado del paquete, y
+     * 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;
     /**
      * ¿El holder tiene el permiso en el scope? Evalúa la cadena completa:
      * sin deny en la cadena Y alguna asignación vigente cuyo rol concede el
@@ -181,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
@@ -192,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[]>;
     /**
@@ -303,6 +496,102 @@ export interface AuthorizationDriver {
      * `defineScopedRole` lo dice antes de escribir nada (3E · P4).
      */
     purgeRole?(roleUuid: string): Promise<void>;
+    /**
+     * Cuántos hechos VIGENTES tiene cada rol, en TODOS los scopes (3b-2j,
+     * decisión del dueño del 2026-08-31 (3)). Un hecho es una asignación del
+     * rol a un holder que no ha caducado (`expiresAt` nulo o futuro, con el
+     * reloj del driver); el rol se identifica por su uuid y la respuesta va
+     * POR POSICIÓN, como `authorizeMany`. Un rol sin hechos —o que el backend
+     * no conoce— es `0`; `uuid` mal formado ⇒ 422 `E_AUTHZ_INVALID_IDENTITY`.
+     *
+     * Es lo que `pruneOrphanRoles` (`authz:catalog:prune-orphans`) necesita
+     * para decir si un rol huérfano TODAVÍA CONCEDE, y es una pregunta del
+     * PUERTO porque los hechos son del driver: hasta 3b-2j el barrido contaba
+     * filas de `authz_assignments` —la tabla del driver `database`— y con
+     * `openfga` en modo `facts`, donde viven en el store, decía siempre que
+     * no. El campo se lee justo antes de un borrado destructivo y su contrato
+     * publicado es «falso ⇒ este rol seguro que no concede», así que ese
+     * `false` era fail-dangerous.
+     *
+     * Es CONSERVADOR a propósito: cuenta hechos, no comprueba si el scope de
+     * cada uno sigue resolviendo. Cero ⇒ no concede seguro; más de cero ⇒
+     * míralo antes de purgar.
+     *
+     * OPCIONAL en el puerto (**breaking para un driver de 2.2 que no lo
+     * traiga**, y por eso opcional y no obligatorio): sin él
+     * `pruneOrphanRoles` deja `assignments` y `stillGranting` en `undefined`
+     * —jamás en `false`— y el comando lista esos roles APARTE, como los que sí
+     * conceden. Capacidad `countRoleAssignments`.
+     */
+    countRoleAssignments?(roleUuids: string[]): Promise<number[]>;
+    /**
+     * Rehace la **proyección derivada** del catálogo para UN rol (3b-2e · E4).
+     * Opcional: solo la implementa un driver que mantenga esa proyección (el
+     * `openfga` en modo `facts`, donde lo que un rol concede son tuplas y no
+     * el catálogo local). El manager la llama después de `defineScopedRole` y
+     * `updateScopedRole` —las dos escrituras de catálogo que cambian los
+     * vínculos de un rol fuera de `syncAuthzCatalog`—, porque si no un rol
+     * recién definido no concedería NADA y un rol al que se le quita un permiso
+     * lo seguiría concediendo (fail-open). En `database` no existe: el catálogo
+     * es la fuente y no hay espejo que rehacer.
+     */
+    projectCatalogRole?(roleUuid: string): Promise<void>;
+    /**
+     * La **proyección derivada del catálogo entero** de este driver (3b-2a ·
+     * A5), para inyectarla en `syncAuthzCatalog`/`syncCatalogs`. Opcional por
+     * el mismo motivo que `projectCatalogRole`: solo la trae un driver que
+     * mantenga un espejo del catálogo en su backend (el `openfga` en modo
+     * `facts`).
+     *
+     * Está en el PUERTO porque el camino de recuperación documentado —«un
+     * `authz:catalog:sync` reescribe la proyección»— lo ejecuta un comando que
+     * solo ve `AuthorizationDriver` (3b-8 · A1): sin esto, el CLI sincronizaba
+     * `authz_*` y dejaba el espejo del store SIN TOCAR, o sea que en `facts`
+     * un permiso quitado del catálogo seguía concediendo y un rol nuevo no
+     * concedía nada.
+     */
+    catalogProjection?(): CatalogProjection;
+    /**
+     * **Reconstruye el estado de ESTE driver desde `authz_*` + el árbol del
+     * consumidor** (3b-3a). Es lo que hay detrás de `authz:reconcile --to=<este
+     * driver>`: hechos, árbol y proyección del catálogo, idempotente
+     * (la segunda pasada escribe cero), reanudable por lotes con cursor y
+     * **nunca silenciosa** (el reporte cuenta lo escrito, lo actualizado, lo
+     * igual, lo que sobra, lo borrado y lo que NO se migró con su motivo).
+     *
+     * `dryRun` es el VERIFICADOR: mismo recorrido, cero escrituras. Es
+     * **read-only por contrato** (panel 2, cruce 4 · S18) — un `--fix` sería un
+     * mecanismo de concesión y queda PROHIBIDO.
+     *
+     * Opcional en el puerto: un driver que no lo trae dice «no sé
+     * reconstruirme» y el manager responde 500 `E_AUTHZ_UNSUPPORTED` nombrando
+     * el método, nunca una migración a medias en silencio. El driver
+     * `database` NO lo implementa: sus tablas SON el origen, y llenarlas desde
+     * un store es la otra dirección (3b-3b).
+     */
+    reconcile?(source: ReconcileSource, options: ReconcileOptions): Promise<ReconcileReport>;
+    /**
+     * **Los hechos de ESTE driver, paginados, para que otro se reconstruya
+     * desde ellos** (3b-3b). Es la otra mitad de `reconcile`: `reconcile` es
+     * ser el DESTINO de `authz:reconcile`, `enumerateFacts` es ser el ORIGEN.
+     *
+     * Contrato: como mucho `limit` hechos por página (más ⇒ 500), orden total
+     * y estable, cursor opaco que tiene que AVANZAR (repetirlo ⇒ 500, jamás un
+     * bucle), y **nada se filtra**: una asignación caducada sale con su
+     * `expiresAt` para que el destino la cuente en `skipped` con su motivo. Lo
+     * que el origen no sabe expresar como hecho del puerto sale en `skipped`
+     * de la página, nunca descartado en silencio.
+     *
+     * Opcional: capacidad `enumerateFacts`. El driver `database` **no lo
+     * trae** a propósito — sus hechos son `authz_assignments`/`authz_denies`,
+     * el esquema publicado del paquete, y el destino los lee de ahí (es lo que
+     * hace `openfga.reconcile`). Un driver de terceros que quiera migrar
+     * DESDE otro sitio sí lo necesita.
+     */
+    enumerateFacts?(page: {
+        limit: number;
+        after?: string;
+    }): Promise<ReconcileFactPage>;
     /**
      * Roles DIRECTOS vigentes del holder en cada scope de `chain` (2D · G5),
      * como pares `{ scope, role }`; solo roles que EXISTEN en ese scope (D5 +
@@ -330,6 +619,317 @@ export interface AuthorizationDriver {
  * `authorization.expandExcludedSubtrees(excluded)` (usa tu `descendantsOf`)
  * o resta el subárbol en tu propia consulta (CTE recursiva, `path LIKE`…).
  */
+/**
+ * Lo que el manager le presta al driver para reconciliar: el árbol del
+ * consumidor (entero y paginado) y su resolutor. El driver pone lo suyo —qué
+ * hechos guarda y cómo—; el paquete no le dice cómo migrar, le da la FUENTE.
+ */
+export interface ReconcileSource {
+    enumerateEdges: ScopeEdgesEnumerator;
+    resolveChain: ScopeChainResolver;
+    /**
+     * Los HECHOS del origen, paginados (3b-3b). Solo hace falta en la
+     * dirección en la que el origen NO es `authz_*`: `--to=database` los lee
+     * del store con este enumerador, mientras que `--to=openfga` lee las
+     * tablas del paquete directamente (son su propio esquema publicado, no el
+     * secreto de un driver).
+     *
+     * Es **perezoso a propósito**: el manager solo resuelve el driver de
+     * ORIGEN cuando el destino lo pide, así que una migración que no necesita
+     * hechos del puerto no construye nada. Sin origen que lo implemente, la
+     * primera llamada es 500 `E_AUTHZ_UNSUPPORTED` nombrando `enumerateFacts`.
+     */
+    facts?: ReconcileFactsEnumerator;
+    /**
+     * **Quién es la FUENTE DE VERDAD de los hechos en esta pasada** (3b-5, los
+     * dos 🔴 del auditor final). Lo decide el MANAGER, que es el único que sabe
+     * qué driver está sirviendo (`config.default`) y qué declara cada uno
+     * (`capabilities.hierarchyFacts`), y el destino lo OBEDECE.
+     *
+     * Sin esto, `--to=openfga` leía siempre `authz_assignments`/`authz_denies`,
+     * y en un despliegue `hierarchy: 'facts'` esas tablas **no son** la fuente
+     * de verdad de los hechos —lo son las tuplas del store—: la pasada
+     * reescribía lo revocado después del cutover, `--prune` borraba los denies
+     * vivos y el barrido de visibilidad del invariante 18 no se aplicaba nunca
+     * (`forbidden` salía vacío porque `wanted.facts` salía vacío).
+     *
+     *  - `authzTables: true` ⇒ los hechos son las tablas del paquete y el
+     *    destino las lee él mismo (es la MIGRACIÓN `database` → `openfga`);
+     *  - `authzTables: false` ⇒ los hechos llegan por el PUERTO (`facts`,
+     *    `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 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 {
+    /** Cómo se NOMBRA el origen en el reporte (clave de `drivers`, o `authz_*`). */
+    name: string;
+    /** `true` ⇒ los hechos son `authz_assignments`/`authz_denies` y los lee el destino. */
+    authzTables: boolean;
+}
+/**
+ * Un hecho del ORIGEN en el vocabulario del PUERTO, no en el del backend
+ * (3b-3b). Es lo que un driver entrega cuando le toca ser el origen de una
+ * migración: el destino no sabe si detrás hay tuplas, filas o un fichero.
+ *
+ * La identidad del rol es el **uuid** (3D · M1), nunca el slug: dos owners
+ * definen `lead@unit` y el slug no identifica nada. La del permiso es el
+ * **slug**, que es lo que el catálogo local sabe traducir a uuid.
+ */
+export interface ReconcileFact {
+    kind: 'assignment' | 'deny';
+    holder: SubjectRef;
+    /** El scope tal como lo guarda el ORIGEN; el destino lo canoniza con SU árbol. */
+    scope: ScopeRef;
+    /** `assignment`: uuid del rol. */
+    roleUuid?: string;
+    /** `deny`: slug del permiso. */
+    permission?: string;
+    /**
+     * `assignment`: la caducidad tal como está guardada, **sin filtrar**. Una
+     * caducada tiene que LLEGAR para poder contarse en `skipped` con su motivo;
+     * un origen que la filtre por su cuenta la haría desaparecer en silencio,
+     * que es justo lo que la migración no puede hacer.
+     */
+    expiresAt?: Date | null;
+    /** Cómo lo nombra el origen (para `details`): un motivo sin la fila no se arregla. */
+    detail: string;
+}
+/**
+ * Una página de hechos del origen. `cursor` es opaco y tiene que AVANZAR
+ * (repetirlo ⇒ 500, nunca un bucle); `skipped` es lo que el ORIGEN no supo
+ * expresar como hecho del puerto (basura de otra versión, un holder type que
+ * el config no declara…) y que el destino suma a su reporte.
+ */
+export interface ReconcileFactPage {
+    facts: ReconcileFact[];
+    skipped?: ReconcileSkip[];
+    cursor?: string;
+}
+export type ReconcileFactsEnumerator = (page: {
+    limit: number;
+    after?: string;
+}) => Promise<ReconcileFactPage>;
+export interface ReconcileOptions {
+    /** Mismo recorrido, CERO escrituras. Es el verificador (read-only por contrato). */
+    dryRun?: boolean;
+    /**
+     * Borra del destino los HECHOS que el origen no respalda: los de un scope
+     * que ya no resuelve (3b-0b · AA4, «resurrección») y los que sobran (un
+     * store escrito por una versión anterior). Sin él se REPORTAN y no se
+     * borran. Lo derivado —marcador de raíz, proyección del catálogo y árbol—
+     * se rehace siempre: es un espejo de datos locales que nadie más escribe.
+     */
+    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;
+    /**
+     * **La cota del volcado del destino** (3b-3b · B5). Reconciliar exige
+     * comparar contra el estado ENTERO del destino, y ese volcado entra en
+     * memoria: el ORIGEN se lee por lotes con cursor, el destino no. En vez de
+     * dejarlo como una sorpresa (un OOM en producción), se declara: pasar de
+     * `maxTuples` es 500 `E_AUTHZ_RECONCILE_TOO_LARGE` **antes de escribir
+     * nada**, nombrando la cota y cómo subirla. Default
+     * `DEFAULT_RECONCILE_MAX_TUPLES`.
+     */
+    maxTuples?: number;
+}
+/**
+ * Cuántas tuplas/filas del destino caben en una pasada de `authz:reconcile`
+ * (3b-3b · B5). No es una garantía de memoria: es la cota DECLARADA por
+ * encima de la cual la pasada se niega en vez de intentarlo.
+ */
+export declare const DEFAULT_RECONCILE_MAX_TUPLES = 1000000;
+/**
+ * Algo que la pasada NO migró (una fila del origen) o NO tocó (una tupla del
+ * destino), con su motivo. Nunca un contador a secas: un motivo sin la fila
+ * no se puede arreglar.
+ */
+export interface ReconcileSkip {
+    kind: 'assignment' | 'deny' | 'edge' | 'tuple';
+    reason: string;
+    detail: string;
+}
+/** Los cinco números de una fase (o del total). */
+export interface ReconcileCounts {
+    /** Tuplas nuevas en el destino. */
+    written: number;
+    /** Tuplas que estaban con OTRA caducidad y se han rehecho (delete + write). */
+    updated: number;
+    /** Tuplas que ya estaban exactamente igual. */
+    unchanged: number;
+    /** Tuplas del destino que el origen NO respalda. */
+    extra: number;
+    /** De las anteriores, las que la pasada borra (las que sobran de lo derivado, y con `prune` también los hechos). */
+    deleted: number;
+}
+/**
+ * Lo que movió una pasada de `authz:reconcile`. Los contadores describen el
+ * PLAN: con `dryRun` son exactamente los mismos números y no se escribe nada
+ * (lo dice `dryRun: true`), que es lo que hace del verificador un simulacro
+ * fiel y no una segunda implementación.
+ */
+export interface ReconcileReport extends ReconcileCounts {
+    /** El driver de destino (`--to`). */
+    to: string;
+    /**
+     * **De dónde salieron los HECHOS de esta pasada** (3b-5): el nombre del
+     * driver ORIGEN, o `authz_*` si fueron las tablas del paquete. No es
+     * decoración: es la diferencia entre una migración y una pasada de
+     * mantenimiento contra el driver activo, y el comando la imprime — una
+     * pasada que lee los hechos del sitio equivocado no puede ser silenciosa.
+     */
+    factsFrom?: string;
+    /**
+     * **La garantía del freeze, publicada en vez de supuesta** (3b-7, juez C4).
+     * Solo en la pasada que ESCRIBE (el `--dry-run` no congela). `lapsed: true`
+     * 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 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;
+    /** Los mismos números por fase: qué es catálogo, qué es árbol y qué son hechos. */
+    phases: Record<'root' | 'catalog' | 'tree' | 'facts', ReconcileCounts>;
+    /**
+     * Motivo → cuántas cosas se quedaron fuera: filas del origen que no se
+     * migraron y tuplas del destino que esta pasada no tocó (`extra-fact`, las
+     * que solo se van con `--prune`).
+     */
+    skipped: Record<string, number>;
+    /** Y cuáles (acotado por `maxSkipDetails`): un contador no permite arreglar nada. */
+    details: ReconcileSkip[];
+    /** Ciclos del árbol del ORIGEN: sus aristas NO se escriben (FGA los evalúa y son fail-open). */
+    cycles: string[][];
+    drift: {
+        /** Faltaba el marcador de raíz: sin él el store entero DENIEGA (3b-2i). */
+        rootMarker: boolean;
+        /** Scopes con más de un padre en el destino (3b-2h · 🟠 4): cruce de tenants. */
+        multiParent: string[];
+        /**
+         * Aristas `scope#binding` que el destino tenía mal (invariante 18): la
+         * escritura de visibilidad que `scopes.moved`/`projectCatalogRole`
+         * pudieron perder si el relay no pasó.
+         */
+        roleVisibility: number;
+        /** Cambios del árbol encolados y sin relevar: la VENTANA del relay, medida. */
+        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;
     /** Siempre `true`: recuerda que lo excluido es el subárbol entero. */
@@ -395,35 +995,529 @@ export type AuthorizationDriverFactory = () => AuthorizationDriver | Promise<Aut
  */
 export type ScopeChainResolver = (scope: ScopeRef) => Promise<ScopeRef[] | null>;
 /**
- * Resolutor de DESCENDIENTES de un scope (2.1, B2): todos los nodos del
- * subárbol (cualquier tipo, cualquier profundidad), sin el propio scope y
- * sin orden exigido. Lo implementa el consumidor (o `sqlDescendantsOf`, el
- * helper opt-in del paquete): el paquete NO lo suple con N+1 llamadas a
- * `resolveChain`. `null` = scope desconocido. Más de `maxNodes` nodos ⇒
- * el consumidor lanza; si devuelve de más, lanza el manager (422
- * `E_AUTHZ_TOO_MANY_SCOPES`). Nunca se llama desde `authorize`/`hasRole`/
- * `list*` (test de arquitectura): solo desde `authorizedScopes`.
+ * Una arista del árbol del consumidor: «`child` cuelga de `parent`» (3b-3a).
+ * `parent` puede ser `APP_SCOPE`; `child` nunca es la raíz.
+ */
+export interface ScopeEdge {
+    child: ScopeRef;
+    parent: ScopeRef;
+}
+/** Una página de `scopes.enumerateEdges`. Sin `cursor` = no queda nada más. */
+export interface ScopeEdgePage {
+    edges: ScopeEdge[];
+    /**
+     * Continuación OPACA para la siguiente llamada (`after`). Ausente o
+     * `undefined` significa «se acabó»: devolver siempre un cursor es un bucle
+     * infinito, y el llamante lo denuncia (500) si el cursor no avanza.
+     */
+    cursor?: string;
+}
+/**
+ * **El árbol ENTERO, paginado** (3b-3a). Es la otra mitad de
+ * `resolveChain`: aquel responde «¿de qué cuelga ESTE scope?» y este
+ * «¿cuáles son todas las aristas?», que es lo que hace falta para
+ * reconstruir el árbol de un backend que lo guarda como hechos propios
+ * (`authz:reconcile --to=openfga`) y para ver las que sobran (las que el
+ * consumidor ya no respalda).
+ *
+ * Contrato:
+ *  - devuelve **como mucho `limit`** aristas por página (más ⇒ 500: el
+ *    llamante no puede paginar lo que no cabe en su lote);
+ *  - el orden tiene que ser TOTAL y ESTABLE entre llamadas (la clave
+ *    primaria vale): si no, una pasada reanudada se salta nodos;
+ *  - `cursor` es opaco para el paquete y vuelve tal cual en `after`; que no
+ *    avance es 500, nunca un bucle;
+ *  - una arista cuyo padre no existe en la tabla NO se emite (es un nodo que
+ *    `resolveChain` tampoco resuelve): el destino la ve como sobrante y
+ *    `authz:reconcile` la cuenta y la reporta.
+ *
+ * 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 — 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;
+    after?: string;
+}) => Promise<ScopeEdgePage>;
+/**
+ * Un cambio del ÁRBOL, tal como lo encola la outbox (3b-2d). Es exactamente
+ * lo que el consumidor notifica por `manager.scopes.*`, con la identidad ya
+ * CANÓNICA (invariante 17): se resuelve al encolar, mientras la fila del
+ * consumidor todavía existe, no al relevarla.
+ */
+export type ScopeTreeChange = {
+    op: 'attached';
+    child: ScopeRef;
+    parent: ScopeRef;
+} | {
+    op: 'moved';
+    child: ScopeRef;
+    parent: ScopeRef;
+} | {
+    op: 'detached';
+    child: ScopeRef;
+};
+/** Un cambio pendiente en la outbox, con la identidad de su registro. */
+export interface PendingScopeTreeChange {
+    /** Identificador estable del registro; el relay lo devuelve al marcarlo. */
+    id: string | number;
+    change: ScopeTreeChange;
+    /** Intentos fallidos previos, si la outbox los lleva (el reporte los muestra). */
+    attempts?: number;
+    /** La última causa de fallo, si la outbox la guarda (`dead()` la enseña). */
+    lastError?: string;
+    /**
+     * Quién ordenó el cambio, si el call-site lo declaró y la outbox lo
+     * guarda. El relay lo pone en el `AuthzWriteEvent` del `scope_purged` que
+     * dispara un `detached`: la auditoría no debe perder al autor por pasar
+     * 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 {
+    id: string | number;
+    change: ScopeTreeChange;
+    attempts?: number;
+    /** 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.
+ */
+export interface ScopeRelayReport {
+    /** Aplicados en esta pasada, en orden. Vacío en `dryRun`. */
+    applied: RelayedScopeChange[];
+    /**
+     * El PRIMER cambio que falló, con la causa (`failures[0]`). Se conserva
+     * porque es lo que mira un supervisor; la lista completa está en
+     * `failures`.
+     */
+    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. `transient`
+     * (alpha.5 · R2a) distingue la caída del backend, que no consume intento,
+     * del fallo de la entrada, que sí.
+     */
+    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.
+     */
+    busy: boolean;
+    /** Quedan cambios sin aplicar tras la pasada (vuelve a ejecutar). */
+    remaining: boolean;
+    dryRun: boolean;
+    /** Solo con `dryRun`: lo que se aplicaría, en orden. */
+    wouldApply: RelayedScopeChange[];
+}
+/**
+ * El lease de una pasada del relay (3b-2h · 🟠 4). Lo devuelve
+ * `ScopeOutbox.acquire()` y lo suelta el manager en un `finally`.
  */
+export interface ScopeOutboxLease {
+    release(): Promise<void>;
+}
+/** Contexto del encolado: la transacción del consumidor y quién lo ordena. */
+export interface ScopeOutboxContext {
+    /**
+     * Lo que el llamante pasó en `ScopeTreeWriteOptions.transaction`: para
+     * Lucid, el `TransactionClientContract` de la transacción en curso. El
+     * 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;
+}
 /**
- * El árbol del consumidor hacia ABAJO (2.1): todos los descendientes de
- * `scope`, en cualquier orden y sin incluirlo. `null` = «este árbol no conoce
- * ese scope».
+ * 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).
+ *
+ * Sin él, `manager.scopes.attached/moved/detached` escribe en el backend
+ * DENTRO de la transacción del consumidor y un `rollback` posterior deja el
+ * árbol de FGA diciendo una cosa y la BD del consumidor otra —una escalada
+ * persistente e invisible, porque la aplicación lista y audita contra SQL—.
+ * Con él, el manager no toca el driver: ENCOLA el cambio con la transacción
+ * del consumidor, así que el cambio del árbol y su intención de propagación
+ * confirman o se van juntos. Lo aplica después `authz:scopes:relay`.
+ *
+ * El paquete no impone tabla: define este puerto y publica un stub de
+ * migración (`stubs/scopes_outbox_migration.stub`) y una implementación
+ * sobre Lucid (`sqlScopeOutbox`) para quien no quiera escribir la suya.
  *
- * Contrato con un scope que `resolveChain` YA NO conoce (3G · W2, auditor
- * pregunta 2): **el consumidor es la autoridad sobre su tabla y puede
- * devolver los hijos** (una ruta materializada, o un `where parent_id = X`,
- * no necesitan la fila del padre) **o `null`**; el paquete no asume ninguna
- * de las dos. La consecuencia está en `scopes.detached`: si el scope no
- * resuelve y por debajo no llega nada, la purga NO se puede declarar
- * completa (`ScopeDetachOutcome.truncated: true`). Y lo que se devuelva se
- * trata como el subárbol real: los roles de esos owners se purgan con la
- * policy de rango medida en la cadena de CADA owner (3G · W1), nunca en la
- * del scope notificado.
+ * Lo que NO arregla, y hay que leerlo así: durante el lag del relay
+ * (segundos) FGA decide con el árbol VIEJO. Es un fail-open temporal — el
+ * tenant antiguo conserva acceso tras un `moved`, y los denies heredados no
+ * aplican tras un `attached`—. No hay 2PC; es el precio de tener el árbol en
+ * dos sitios.
+ */
+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 | {
+        id: string | number;
+    }>;
+    /**
+     * Los pendientes MÁS ANTIGUOS primero: el orden del árbol es el del
+     * 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.
+     *
+     * `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.
+     * `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
+     * arregla sola: la outbox puede dejar de ofrecerla en `pending()` tras N
+     * intentos y enseñarla aquí. El relay las REPORTA en cada pasada y el
+     * comando sale ≠ 0 mientras haya alguna: un aparcado es una divergencia
+     * permanente del árbol del backend, no un incidente resuelto.
+     */
+    dead?(limit: number): Promise<PendingScopeTreeChange[]>;
+    /**
+     * **El lease del escritor ÚNICO** (3b-2h · 🟠 4), opcional. `pending()` no
+     * reserva nada, así que dos pasadas a la vez (un `CronJob` con
+     * `concurrencyPolicy: Allow`, dos réplicas, una pasada más larga que su
+     * intervalo) trabajan sobre el MISMO lote: la rezagada re-aplica un
+     * `attached` viejo después de que la otra aplicara el `moved` nuevo y deja
+     * el árbol del store REVERTIDO —con un solo padre, así que nada lo
+     * delata— (medido). Con `acquire`, la segunda pasada no hace nada y lo
+     * dice (`busy`). `null` = otra pasada lo tiene.
+     *
+     * CONTRATO: el lease se toma UNA vez al inicio de la pasada y se sostiene
+     * hasta el `finally`; el relay NO lo re-verifica ni lo renueva dentro del
+     * bucle (a diferencia del freeze durable, que sí se re-afirma por lote).
+     * Por eso la implementación DEBE ser un cerrojo SOSTENIDO mientras dura la
+     * pasada, no un TTL que pueda vencer a mitad: los que trae el paquete lo
+     * cumplen (`pg_try_advisory_xact_lock` vive con la transacción; `get_lock`
+     * de MySQL con la sesión; SQLite en proceso). Un `acquire` con TTL
+     * 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
+ * `scope` (cualquier tipo, cualquier profundidad), en cualquier orden y sin
+ * incluirlo. Lo implementa el consumidor (o `sqlDescendantsOf`, el helper
+ * opt-in del paquete): el paquete NO lo suple con N+1 llamadas a
+ * `resolveChain`. `null` = «este árbol no conoce ese scope».
  *
  * Más de `maxNodes` nodos ⇒ el resolutor puede devolver la lista larga (el
  * paquete la caza con 422 `E_AUTHZ_TOO_MANY_SCOPES`) o lanzar; en
- * `authorizedScopes` eso es un 422 y en `scopes.detached`/`defineScopedRole`
- * DEGRADA (3F · S2, y ver el aviso de `#assertLevelUnderOwner`).
+ * `authorizedScopes` eso es un 422 y en `defineScopedRole`/`updateScopedRole`
+ * DEGRADA a la regla de nivel mínima (3F · S2, y ver el aviso de
+ * `#assertLevelUnderOwner`).
+ *
+ * Solo se llama desde `authorizedScopes`/`expandExcludedSubtrees` y desde la
+ * regla de nivel de la delegación; NUNCA desde `authorize`/`hasRole`/`list*`
+ * (test de arquitectura) ni desde `scopes.detached`, que purga hechos del
+ * scope EXACTO y no baja por el árbol (invariante 11; 3b-0 · Z1).
+ *
+ * (D7: hasta 3G había DOS docblocks seguidos aquí y el viejo contradecía al
+ * nuevo sobre qué se espera al pasarse de `maxNodes`. Queda uno.)
  */
 export type ScopeDescendantsResolver = (scope: ScopeRef, options: {
     maxNodes: number;
@@ -479,63 +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;
     /**
-     * Solo en `scope_purged`: el árbol ya NO conoce el scope notificado —el
-     * consumidor borró su fila y avisa después, que es el orden que el paquete
-     * admite— o alguno de los roles purgados tenía un owner que tampoco
-     * resuelve (3F · S1; 3G · W1/W2). `'owner-detached-unknown'` significa dos
-     * cosas a la vez, y las dos importan a quien audita: (a) la purga procede
-     * igual —bloquearla dejaba vivos el rol, sus asignaciones y los denies de
-     * un scope borrado (auditor N2), sin ninguna salida con `requireActor:
-     * true`— y (b) para ESOS roles —los que no tienen dónde medir el rango— la
-     * policy de 3E · P3 no se pudo evaluar. Para los demás sí se evalúa: el
-     * rango se mide en la cadena del OWNER de cada rol (3G · W1), así que un
-     * `detached` de un ancestro desconocido ya NO destruye los roles de
-     * descendientes vivos. Sale también con `purgedRoles: 0`.
-     */
-    reason?: 'owner-detached-unknown';
-    /**
-     * Solo en `scope_purged`: la purga de roles se acotó al scope EXACTO
-     * porque el subárbol no se pudo enumerar (3F · S2). Ver
-     * `ScopeDetachOutcome.truncated`.
-     */
-    truncated?: true;
-}
-/**
- * Lo que devuelve `scopes.detached` (3F · S1/S2). Hasta 3E era `void` y no
- * había forma de saber si la purga alcanzó a todo el subárbol ni si la
- * policy de rango se llegó a evaluar.
- */
-export interface ScopeDetachOutcome {
-    /** Roles LOCALES purgados (los del scope y, con `descendantsOf`, los del subárbol). */
-    purgedRoles: number;
-    /**
-     * `true` cuando el subárbol NO se pudo enumerar (más de `maxDescendants`,
-     * o un `descendantsOf` que falló) y la purga se acotó al scope EXACTO
-     * (3F · S2). Degradar en vez de tumbar la operación es la regla: declarar
-     * `scopes.descendantsOf` nunca puede dejarte peor que no declararlo, y
-     * hasta 3E un subárbol grande dejaba el `detached` en 503 sin purgar ni
-     * los roles ni los hechos (auditor N3). Los roles que quedan abajo no son
-     * visibles en ninguna parte —su owner ya no cuelga del árbol—, pero siguen
-     * ocupando su `(slug, nivel)`: hay que volver a notificar nodo a nodo o
-     * subir la cota.
-     *
-     * También es `true` cuando el árbol ya NO conoce el scope y `descendantsOf`
-     * no devolvió nada debajo (3G · W2, auditor P2): el puerto no le exige
-     * responder por un scope que `resolveChain` desconoce —puede devolver sus
-     * hijos o `null`, ver `ScopeDescendantsResolver`—, así que un vacío ahí no
-     * demuestra que debajo no quedara nada. Decir `truncated: false` era
-     * afirmar «purga completa» con el rol de la unit hija vivo y concediendo.
-     */
-    truncated: boolean;
-    /**
-     * Igual que en `AuthzWriteEvent`: el scope notificado (o el owner de algún
-     * rol purgado) ya no está en el árbol, así que para esos roles la policy
-     * de rango no se pudo evaluar. Presente aunque `purgedRoles` sea 0.
-     */
-    reason?: 'owner-detached-unknown';
+     * `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 {
@@ -628,10 +1683,9 @@ export interface ScopedRoleChanges {
 export interface AuthzCatalogWriteEvent {
     action: 'role_defined' | 'role_updated' | 'role_purged';
     /**
-     * Quién lo ordenó. La API de delegación lo exige siempre; ausente solo en
-     * los `role_purged` que arrastra `scopes.detached` (3D · M4), donde el
-     * actor es el `WriteOptions.actor` de esa notificación del árbol y puede
-     * no venir.
+     * Quién lo ordenó. La API de delegación lo exige siempre; ausente en los
+     * `role_purged` de `authz:catalog:prune-orphans` (3b-0 · Z2), que es una
+     * operación de PLATAFORMA y no de un actor del árbol.
      */
     actor?: SubjectRef;
     role: CatalogRole;
@@ -652,4 +1706,403 @@ export interface AuthzCatalogWriteEvent {
      */
     shadowedByAncestor?: CatalogRoleRef[];
 }
+/**
+ * Un rol del catálogo tal como lo ve la PROYECCIÓN: su uuid (la identidad, 3A
+ * · A1) y los slugs de los permisos que vincula.
+ */
+export interface CatalogProjectionRole {
+    uuid: string;
+    permissions: string[];
+}
+/**
+ * Foto del catálogo confirmado que un driver puede materializar en su
+ * backend. Se lee de `authz_*` dentro de la transacción del sync: es
+ * DERIVADA, y por eso se puede reconstruir entera (`authz:reconcile`).
+ */
+export interface CatalogProjectionSnapshot {
+    /** Todos los slugs de permiso del catálogo (no solo los del spec que se sincroniza). */
+    permissions: string[];
+    /** Todos los roles con sus vínculos rol→permiso. */
+    roles: CatalogProjectionRole[];
+}
+/** Lo que una pasada de proyección movió. Nunca un booleano: una proyección silenciosa no se vigila. */
+export interface CatalogProjectionReport {
+    /** Tuplas nuevas escritas. */
+    written: number;
+    /** Tuplas que sobraban (el catálogo ya no las respalda) y se han borrado. */
+    deleted: number;
+    /** Tuplas que ya estaban exactamente igual. */
+    unchanged: number;
+}
+/**
+ * **Proyección derivada del catálogo en el backend de un driver** (regla del
+ * catálogo reescrita — panel 2, cruce 7; decisión del dueño 2026-08-28).
+ *
+ * El catálogo es propiedad LOCAL siempre: roles y permisos viven en `authz_*`
+ * y ningún driver es su fuente de verdad. Un driver PUEDE mantener una
+ * proyección (el modo `facts` de openfga: permisos como relaciones del modelo
+ * + vínculos rol→permiso como tuplas `role:<uuid>#permits_<P>@<holder>:*`) si
+ * y solo si: (a) es reconstruible desde `authz_*`, (b) `authz:reconcile` la
+ * vigila y (c) NUNCA se lee como catálogo.
+ *
+ * Se inyecta en `syncAuthzCatalog` en vez de importarse: `src/catalog.ts` es
+ * la ruta de un consumidor solo-database y no puede tirar del SDK de OpenFGA
+ * (regla 3 de `check_purity.mjs`).
+ */
+export interface CatalogProjection {
+    /**
+     * ¿El catálogo que va a quedar es publicable en este backend? Se llama
+     * ANTES de escribir nada (cotas de nombre y techo del modelo, A3/A4): un
+     * catálogo que no se puede proyectar no se escribe a medias.
+     */
+    assertPublishable(permissions: readonly string[]): void;
+    /** Rehace la proyección del catálogo ya confirmado: escribe lo que falta y BORRA lo que sobra. */
+    project(snapshot: CatalogProjectionSnapshot): Promise<CatalogProjectionReport>;
+}
+/** Un objeto de relaciones: `document:<id>`, `folder:<id>`, `group:<id>`… */
+export interface RelObject {
+    /** El tipo FGA del objeto (`document`, `folder`, `space`…), declarado en `defineRelationsConfig`. */
+    type: string;
+    /** El id del objeto dentro de su partición. Sin `|`/`#`/`:` (los pone el driver al componer). */
+    id: string;
+}
+/**
+ * Un userset como sujeto: `group:eng#member` (todos los miembros del grupo).
+ * Es lo que hace que un `relate(group:g#member, viewer, doc)` conceda `viewer`
+ * a todo el que sea `member` de `g` (`usersetsOf`, un nivel).
+ */
+export interface RelUserset {
+    object: RelObject;
+    relation: string;
+}
+/**
+ * El sujeto de una relación: un HOLDER (`{type,uuid}`, como `SubjectRef`) o un
+ * USERSET (`{object, relation}`). El puerto lo tipa explícito porque los dos
+ * viajan por `relate`/`listSubjects`/`check`; un userset de OTRA partición se
+ * corta por comparación de string en el driver (nunca cruza).
+ */
+export type RelSubject = SubjectRef | RelUserset;
+/** Discriminador: ¿este sujeto es un userset (`group:g#member`) y no un holder? */
+export declare function isRelUserset(subject: RelSubject): subject is RelUserset;
+/**
+ * La referencia COMPLETA a una tupla de relación, tal como la ve `assertWrite`
+ * (R-13) y `onRelationWrite`: sujeto + relación + objeto + partición, más la
+ * operación. Es puro dato: quien lo recibe decide (auditar, rechazar), nunca
+ * muta el store.
+ */
+export interface RelationRef {
+    operation: 'relate' | 'unrelate';
+    subject: RelSubject;
+    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;
+}
+/**
+ * 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 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 {
+    limit?: number;
+    after?: string;
+}
+/**
+ * Lo que un `RelationsDriver` DECLARA que puede hacer. Cada valor lleva su par
+ * de casos `{ whenTrue, whenFalse }` en `runRelationsDriverContract` — nunca
+ * un `skip` (3b-2e · E2). El runner FALLA si una capacidad declarada no tiene
+ * poblada la cara que corresponde a su valor.
+ */
+export interface RelationsDriverCapabilities {
+    /** `check` es UNA sola llamada al backend (`openfga`: un `Check`). */
+    singleCheckRelations: boolean;
+    /**
+     * Los `listObjects` enumeran también lo HEREDADO. **`false` siempre** en
+     * este paquete (invariante 7): en `openfga` obligaría a `ListObjects`, que
+     * trunca al tope del servidor. Devuelven hechos DIRECTOS + lo derivado.
+     */
+    listObjectsInherited: boolean;
+    /** `listSubjects` devuelve también sujetos USERSET (`group:g#member`), no solo holders. */
+    usersetSubjects: boolean;
+    /**
+     * El driver implementa `membersOf` (membresía TRANSITIVA a través de
+     * usersets). Solo `database` (CTE recursiva); `openfga` es `false` (la
+     * transitiva sería `ListUsers`, que trunca) ⇒ `membersOf` es 500
+     * `E_AUTHZ_UNSUPPORTED`.
+     */
+    membersOfNative: boolean;
+    /** El driver sabe ser ORIGEN de `authz:reconcile` de relaciones (`enumerateRelations`). */
+    enumerateRelations: boolean;
+    /**
+     * `listObjects` SEÑALA el truncamiento cuando el backend corta al tope
+     * (`openfga` con `ListObjects`): la página devuelve `truncated: true`, nunca
+     * una lista parcial muda (S16). Capacidad NUEVA, distinta del
+     * `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
+ * consumidor que lo ve sabe que hay MÁS y no toma la lista por completa.
+ */
+export interface RelationObjectsPage {
+    objects: RelObject[];
+    cursor?: string;
+    truncated?: boolean;
+}
+export interface RelationSubjectsPage {
+    subjects: RelSubject[];
+    cursor?: string;
+    truncated?: boolean;
+}
+/** Una tupla de relación tal como la enumera `enumerateRelations` (origen de reconcile). */
+export interface RelationTuple {
+    subject: RelSubject;
+    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[];
+    cursor?: string;
+}
+/**
+ * El puerto de ReBAC. `partition: ScopeRef` es OBLIGATORIA en TODA operación
+ * (`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:
+ * `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;
+    /** Crea la relación `subject —relation→ object` en `partition`. Idempotente. */
+    relate(subject: RelSubject, relation: string, object: RelObject, partition: ScopeRef, options?: RelationWriteOptions): Promise<void>;
+    /** Retira la relación. No-op seguro si no existe (invariante 6). */
+    unrelate(subject: RelSubject, relation: string, object: RelObject, partition: ScopeRef, options?: RelationWriteOptions): Promise<void>;
+    /** ¿`subject` tiene `relation` sobre `object` en `partition` (directo o derivado por includes/userset)? */
+    check(subject: RelSubject, relation: string, object: RelObject, partition: ScopeRef): Promise<boolean>;
+    /** Los objetos de tipo `objectType` sobre los que `subject` tiene `relation`. Directos + derivados, sin herencia abierta. */
+    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` (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
+     * `listSubjects(member, group)`, que devuelve solo los hechos DIRECTOS. Solo
+     * 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 (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
+ * `AuthorizationDriverFactory` para el puerto de relaciones. El consumidor la
+ * declara en `config.relations.drivers`, y `authz:relations:reconcile` la
+ * invoca para construir el ORIGEN y el DESTINO de una migración de tuplas. El
+ * driver `openfga` de relaciones entra por el subpath `/openfga` DENTRO de la
+ * factory (como el de roles), así que el comando nunca toca el SDK (pureza).
+ */
+export type RelationsDriverFactory = () => RelationsDriver | Promise<RelationsDriver>;
 //# sourceMappingURL=types.d.ts.map