@jantstack/adonis-authz 2.0.0-alpha.1 → 2.4.0-alpha.2

package/build/src/drivers/openfga_driver.d.ts

@@ -1,27 +1,35 @@
 import type { ClientBatchCheckItem, ClientBatchCheckSingleResponse } from '@openfga/sdk';
-import type { AuthorizationDriver, DenyRef, GrantOptions, GrantOutcome, HolderTypeMap, RoleQuery, ScopeChainResolver, ScopeRef, ScopeType, SubjectRef } from '../types.js';
-import { CatalogCache } from '../catalog_cache.js';
-import type { CatalogRevalidate, CatalogRoleRef } from '../catalog_cache.js';
+import type { AuthorizationDriver, CatalogProjection, DenyRef, GrantOptions, GrantOutcome, HolderTypeMap, ReconcileFactPage, ReconcileOptions, ReconcileReport, ReconcileSource, RoleQuery, ScopeChainResolver, ScopeOutbox, ScopeRef, ScopeType, SubjectRef, WriteOptions } from '../types.js';
+import { CatalogCache } from '../catalog/catalog_cache.js';
+import type { CatalogRevalidate, CatalogRoleRef } from '../catalog/catalog_cache.js';
+import { assertHolderTypes } from './openfga_facts.js';
+import type { FactsRelationsConfig } from './openfga_facts.js';
 import type { Clock } from '../clock.js';
 /**
- * Driver `openfga` — los HECHOS (asignaciones y denies) viven en un servidor
- * OpenFGA; el CATÁLOGO (roles/permisos/vínculos) y la JERARQUÍA (orgs/units)
- * siguen siendo metadata local en las tablas del chasis (split de propiedad
- * de datos del análisis: cambiar de driver = migrar una tabla de hechos).
+ * Driver `openfga` — **modo `facts` y solo `facts`** (3b-2k · K2). Los
+ * HECHOS (asignaciones y denies), el ÁRBOL de scopes y la PROYECCIÓN del
+ * catálogo viven en un servidor OpenFGA, que es el PDP: `authorize` es UN
+ * solo `Check` y no consulta el árbol del consumidor. El CATÁLOGO sigue
+ * siendo propiedad local en las tablas `authz_*` (la proyección es derivada,
+ * reconstruible y nunca se lee como catálogo).
  *
- * Modelo FGA genérico (ver `openFgaAuthorizationModel()`):
- *  - `role_binding:<scopeKey>|<roleUuid>`       #assignee → asignación de rol
- *  - `deny_binding:<scopeKey>|<permissionUuid>` #denied   → deny explícito
- *    (3A · A1: el id lleva el UUID del catálogo, nunca el slug. Un store
- *    escrito por 1.x/2.0–2.1 —ids con slug— NO lo lee 2.2: `openfga:import
- *    --reconcile` lo cuenta como `extra` y `--prune` lo borra. No hay comando
- *    de migración por decisión del dueño: no había stores en producción.)
+ * Modelo (c2r), en `openfga_facts.ts` (`openFgaFactsModel`):
+ *  - `role:<roleUuid>#permits_<P>@<holder>:*`   → la proyección del catálogo
+ *  - `role_binding:<scopeKey>|<roleUuid>`       #assignee → la asignación
+ *    (3A · A1: el id lleva el UUID del catálogo, nunca el slug; se parsea
+ *    desde la derecha), `#role` → su rol
+ *  - `scope:<scopeKey>` con `#parent` (el árbol), `#binding` (dónde es
+ *    visible el rol), `#denied_<P>` (el deny explícito) y `#rooted` (la
+ *    alcanzabilidad de la raíz: `can_<P> = (<P> but not denied_<P>) and
+ *    rooted`, 3b-2i)
  *  - Expiración vía condition `not_expired` (valid_until en la tupla,
  *    current_time en cada check) — ni scheduler necesita.
  *
- * La herencia se resuelve igual que en el driver database: la cadena de
- * scopes se calcula localmente (el árbol lo declara el consumidor vía
- * `resolveChain`) y se consulta FGA por batchCheck sobre la cadena.
+ * **El modo `resolver` ya no existe** (3b-2k · K2, breaking): hasta 2.2 este
+ * driver expandía la cadena del consumidor a un `batchCheck` de N×M y
+ * guardaba los denies en objetos `deny_binding` propios. Con (c2r) esa rama
+ * era código muerto: se borró entera, y con ella `openFgaAuthorizationModel`
+ * y `openfga:import` (su sustituto es `authz:reconcile`, 3b-3).
  *
  * NADA del dominio está cableado: los holders llegan como `holderTypes`
  * (morph name → tipo FGA) y los niveles de scope se derivan del propio
@@ -35,18 +43,16 @@ import type { Clock } from '../clock.js';
  */
 export type { HolderTypeMap };
 /**
- * `holderTypes` tiene que ser INYECTIVO. Si dos morph names caen en el mismo
- * tipo FGA, para el store son un solo holder: un grant a `users:U` autoriza a
- * `integrations:U`, `listSubjects` devuelve el morph equivocado y un revoke
- * borra al otro (invariante 4, L0.2). El generador del modelo lo "sabía"
- * (deduplicaba con un Set) y publicaba sin quejarse: ahora lanza aquí, al
- * construir el driver y al generar el modelo, antes de tocar nada.
+ * La inyectividad de `holderTypes` la comprueba el módulo del modelo
+ * (`openfga_facts.ts`, compartido por los dos generadores). Se re-exporta
+ * desde aquí porque el subpath `/openfga` es la puerta publicada.
  */
-export declare function assertHolderTypes(holderTypes: HolderTypeMap): void;
+export { assertHolderTypes };
 /**
  * Id de binding (`<scopeKey>|<uuid>`: `app|<uuid>` o `<tipo>|<uuidScope>|<uuid>`)
- * → scope + uuid del catálogo (del rol en `role_binding`, del permiso en
- * `deny_binding`). Se parsea DESDE LA DERECHA (3A · A1): el último componente
+ * → scope + uuid del ROL (3b-2k · K2: el `deny_binding`, que era el otro
+ * consumidor de esta gramática, se fue con el modo `resolver`; el deny es hoy
+ * una relación del scope). Se parsea DESDE LA DERECHA (3A · A1): el último componente
  * es el uuid y el resto la clave del scope, que tiene 1 parte (`app`) o 2
  * (`<tipo>|<uuid>`). Antes el último componente era el slug codificado
  * (`docs~read`) y el parseo contaba partes: ambiguo en cuanto la clave del
@@ -57,7 +63,7 @@ export declare function assertHolderTypes(holderTypes: HolderTypeMap): void;
  * gramática —el scope, la de identidad; el uuid, la de UUID canónico del
  * catálogo—: un id que el driver no escribiría no es un hecho del motor
  * aunque esté en el store. Los ids de 1.x/2.0–2.1 (con slug) caen aquí:
- * 2.2 no los lee, y `openfga:import --reconcile` los cuenta como `extra`.
+ * 2.2 no los lee, y `authz:reconcile` (3b-3) los reportará como deriva.
  * Exportada para probarla sin servidor.
  */
 export declare function parseBindingId(id: string): {
@@ -74,18 +80,30 @@ export declare function parseBindingId(id: string): {
  */
 export declare function correlateBatchResults(checks: ClientBatchCheckItem[], results: ClientBatchCheckSingleResponse[]): ClientBatchCheckSingleResponse[];
 /**
- * El authorization model en formato JSON del API de FGA, generado a partir
- * de los holders del consumidor. El mismo mapa debe usarse al construir el
- * driver: si difieren, los checks no encuentran las tuplas.
- */
-export declare function openFgaAuthorizationModel(holderTypeMap: HolderTypeMap): any;
-/**
- * Crea un store nuevo + escribe el authorization model derivado de los
- * holders del consumidor. Para bootstrap de un appliance o del harness de
- * tests. El `name` lo decide el caller (el comando openfga:provision
- * resuelve APP_NAME del entorno — el motor no lee env).
+ * Crea un store nuevo + escribe el authorization model **`facts` (c2r)**
+ * derivado de los holders y de los PERMISOS del consumidor (3b-2k · K2:
+ * antes escribía el modelo del modo `resolver`, que ya no existe). Para
+ * bootstrap de un appliance o del harness de tests. El `name` lo decide el
+ * caller (el comando `openfga:provision` resuelve APP_NAME del entorno — el
+ * motor no lee env).
+ *
+ * Los permisos entran aquí porque el modelo (c2r) declara CUATRO relaciones
+ * por permiso: un store provisionado sin ellos no puede responder a ninguna
+ * pregunta. `assertFactsModelPublishable` comprueba antes las cotas (nombre
+ * de relación y techo de 262.144 bytes ⇒ 500 `E_AUTHZ_MODEL_TOO_LARGE`).
+ * Añadir un permiso al catálogo obliga a republicar el modelo: es lo que
+ * hace `syncAuthzCatalog` con la proyección inyectada, y por eso el modelo
+ * versionado del store se escribe con `--store-id`.
+ *
+ * **Y los tipos de RELACIÓN (ReBAC) van FUSIONADOS** (Fase 4-8): si el
+ * consumidor declaró `relations.config`, `openfga:provision` los pasa aquí y
+ * el modelo publicado los incluye, de modo que un store recién aprovisionado
+ * ya acepta tuplas de relación (`document#viewer`…) SIN un
+ * `authz:catalog:sync` previo. Sin ellos el modelo es facts-only y una tupla
+ * de relación es un `validation_error` del servidor («type 'document' not
+ * found»). El gate de bytes mide el modelo FUSIONADO.
  */
-export declare function provisionOpenFgaStore(apiUrl: string, name: string, holderTypeMap: HolderTypeMap): Promise<{
+export declare function provisionOpenFgaStore(apiUrl: string, name: string, holderTypeMap: HolderTypeMap, permissions: readonly string[], relations?: FactsRelationsConfig): Promise<{
     storeId: string;
     modelId: string;
 }>;
@@ -96,8 +114,15 @@ export declare function provisionOpenFgaStore(apiUrl: string, name: string, hold
  * "alguien escribió antes" y se propagan clasificados, con el error del SDK
  * como causa (D6). Verificado contra OpenFGA v1.19: el duplicado llega como
  * HTTP 400 con `apiErrorCode: 'write_failed_due_to_invalid_input'` y el
- * mensaje "cannot write a tuple which already exists"; un 409 se acepta por
- * si una versión del servidor lo devuelve así.
+ * mensaje "cannot write a tuple which already exists".
+ *
+ * **Y el 409 tiene nombre propio** (3b-2f · R3, medido contra el servidor):
+ * es el `Aborted` de un `Write` transaccional cuyas tuplas escribió otra
+ * transacción a la vez ("transactional write failed due to conflict: one or
+ * more tuples to write were inserted by another transaction"). Dice lo mismo
+ * —otro escritor llegó antes— y se trata igual: releer y re-aplicar. Lo que
+ * NO dice es QUÉ tupla chocó, así que quién existía lo decide la relectura y
+ * nunca el mensaje.
  */
 export declare function isDuplicateWrite(error: unknown): boolean;
 export interface OpenFgaDriverOptions {
@@ -169,7 +194,44 @@ export interface OpenFgaDriverOptions {
      * producción lo normal es `clock` en el config del manager (`withClock`).
      */
     now?: Clock;
+    /**
+     * La outbox del árbol del config (`scopes.outbox`), la MISMA instancia
+     * (3b-2d). El driver no la usa para nada: quien encola es el manager. Está
+     * aquí como EVIDENCIA del gate — un driver `facts` que se construye sin
+     * ella y sin `acceptScopeDriftRisk` es un montaje en el que un `rollback`
+     * del consumidor deja una escalada persistente e invisible (cruce 4 · S5),
+     * y eso se descubre al construir, no en la primera escritura de un tenant.
+     */
+    outbox?: ScopeOutbox;
+    /**
+     * «Sé que sin outbox un rollback de mi transacción deja el árbol de FGA
+     * adelantado al mío, y lo asumo». Es la salida explícita del gate para
+     * quien mueve el árbol solo desde la plataforma, en un proceso que no
+     * comparte transacción con nada. Tiene que ser el booleano `true`: un
+     * valor «truthy» no es una aceptación.
+     */
+    acceptScopeDriftRisk?: boolean;
 }
+/**
+ * **El gate de construcción de `facts`** (3b-2d, panel 2 cruce 4 · S5).
+ *
+ * En `hierarchy: 'facts'` el árbol vive en el store de FGA y FGA es el PDP.
+ * El consumidor notifica `scopes.moved` dentro de su transacción, el paquete
+ * escribe la arista en FGA… y si esa transacción hace `rollback` —una
+ * constraint, una validación, un timeout de pool: no hace falta un crash—
+ * la escritura de FGA NO se deshace. SQL sigue diciendo que la unit es del
+ * tenant A y FGA que es del B: todos los holders con rol en B tienen acceso
+ * a una unidad de A, y la aplicación, que lista y audita contra SQL, no
+ * puede verlo. La ventana no es un hueco entre dos operaciones: dura hasta
+ * que alguien lo descubra.
+ *
+ * Por eso `scopes.outbox` no puede ser una recomendación: una recomendación
+ * no es un mecanismo. O está el puerto, o está la firma del dueño.
+ */
+export declare function assertScopeDriftGuarded(options: {
+    outbox?: ScopeOutbox;
+    acceptScopeDriftRisk?: boolean;
+}): void;
 export declare const DEFAULT_TIMEOUT_MS = 5000;
 /**
  * Cota de páginas de una enumeración (1.000.000 de tuplas a 100 por página).
@@ -178,68 +240,37 @@ export declare const DEFAULT_TIMEOUT_MS = 5000;
  * el deadline es por llamada (D12, auditor H7).
  */
 export declare const MAX_READ_PAGES = 10000;
-export interface ImportFactsResult {
-    /** Tuplas nuevas escritas. */
-    written: number;
-    /** Tuplas que existían con OTRA condición y se reescribieron (delete+write). */
-    updated: number;
-    /** Tuplas que ya estaban exactamente igual. */
-    unchanged: number;
-    /**
-     * Tuplas `role_binding`/`deny_binding` del store SIN correspondencia en SQL
-     * (un grant revocado en SQL, un holder que nunca estuvo, una asignación ya
-     * expirada). Solo se cuentan con `reconcile` (D14); sin `prune` siguen
-     * concediendo y el reporte lo dice.
-     */
-    extra: number;
-    /** De las `extra`, las borradas (`prune`). En `dryRun`, las que se borrarían. */
-    deleted: number;
-    /** Asignaciones ya expiradas en SQL, no se copian. */
-    skippedExpired: number;
-    dryRun: boolean;
-}
-export interface ImportFactsOptions {
-    dryRun?: boolean;
-    /**
-     * Permite importar sobre un store CON tuplas: por cada hecho se lee la
-     * tupla exacta; ausente ⇒ write, presente con otra condición ⇒ delete+write
-     * (`updated`), igual ⇒ `unchanged`. Además se lee el store ENTERO
-     * (`Read({})` paginado) y lo que SQL no tiene se cuenta como `extra` (D14).
-     * Sin esto, un store no vacío es 409 `E_AUTHZ_STORE_NOT_EMPTY`.
-     */
-    reconcile?: boolean;
-    /**
-     * Con `reconcile`: borra las tuplas `extra` (`deleted`). Es lo que hace que
-     * el reconcile CONVERJA: sin prune, un reporte de ceros no distingue "en
-     * sync" de "sobra algo que sigue concediendo". Sin `reconcile` es 500
-     * `E_AUTHZ_CONFIG`.
-     */
-    prune?: boolean;
-    /** Reloj con el que se decide qué asignación de SQL ya expiró (`skippedExpired`). Default: la hora del proceso. */
-    now?: Clock;
-}
 /**
- * Migración de hechos database → openfga: copia las asignaciones vigentes y
- * los denies de las tablas `authz_*` como tuples del store FGA.
- *
- * - COPIA, no mueve: las tablas locales quedan intactas → el rollback es
- *   volver a AUTHZ_DRIVER=database (solo se pierde lo escrito mientras se
- *   operó con openfga). El catálogo y la jerarquía nunca migran: son
- *   metadata local para ambos drivers.
- * - Las asignaciones ya expiradas se saltan (no tiene sentido copiarlas);
- *   las de expiración futura viajan con la condition `not_expired`.
- * - NUNCA `onDuplicateWrites: Ignore` (S7): en FGA la condición no es parte
- *   de la clave, así que "ignorar el duplicado" dejaba la caducidad vieja y
- *   reportaba éxito. Un store con tuplas exige `reconcile`, que compara
- *   tupla a tupla, reescribe las que difieren y cuenta las que SQL no tiene
- *   (`extra`); con `prune` las borra (`deleted`) y el reconcile converge
- *   (D14). Nunca silencioso: el reporte distingue written / updated /
- *   unchanged / extra / deleted / skippedExpired.
- *
- * Herramienta explícitamente de OpenFGA: los errores del SDK salen crudos.
+ * Tope de saltos al subir el árbol DEL STORE (3b-2e · E1). No es el techo de
+ * decisión —ese lo pone el servidor al evaluar (c2) y está medido en
+ * `FACTS_MAX_RESOLVE_DEPTH`—: es la red del recorrido, para que un árbol con
+ * una deriva que el anti-ciclos no vio no deje el proceso dando vueltas.
  */
-export declare function importAuthzFactsToOpenFga(options: OpenFgaDriverOptions & ImportFactsOptions): Promise<ImportFactsResult>;
+export declare const MAX_SCOPE_CHAIN_HOPS = 1000;
 export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
+    /**
+     * Lo que este driver declara (3b-2e · E2). Depende del MODO, así que es un
+     * getter y no un campo: una vista por prototipo (`withChainResolver`,
+     * `withClock`) declara lo mismo que su original.
+     *
+     * `roleInheritanceNative` y `listObjectsInherited` son `false` **también en
+     * `facts`**, y eso es el cruce 6 del panel: `hasRole`/`listRoles`/
+     * `listRoleScopes`/`listSubjects`/`listScopes` siguen usando `resolveChain`
+     * (en (c2) no hay alternativa, y está medido), y los `list*` enumeran con
+     * `Read` paginado, nunca con `ListObjects` (que trunca al tope del servidor
+     * sin señal). Lo único que `facts` cambia es `authorize`.
+     */
+    get capabilities(): Readonly<{
+        hierarchyFacts: true;
+        singleCheckAuthorize: true;
+        roleInheritanceNative: false;
+        listObjectsInherited: false;
+        purgeRole: true;
+        countRoleAssignments: true;
+        canonicalScopeReads: false;
+        enumerateFacts: true;
+        transactionalWrites: false;
+    }>;
     private client;
     private chainResolver;
     private holderTypes;
@@ -277,8 +308,10 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
     private chain;
     /** La cadena o 422: una escritura no puede ir a un scope que nadie reconoce. */
     private knownScope;
-    /** El scope canónico para `revoke`/`removeDeny`/`purgeScope` (ver `canonicalScope`). */
+    /** El scope canónico para `scopes.detached`/`purgeScope` (ver `canonicalScope`). */
     private canonicalOrSelf;
+    /** Los destinos de un delete de hechos (`revoke`/`removeDeny`): canónico, o el fan-out de alias (3b-8 · A4). */
+    private canonicalTargets;
     /**
      * Vista de este driver con OTRO resolutor de ancestros y el mismo estado
      * (cliente, memo del catálogo, deadline, diagnósticos). Es lo que usa
@@ -326,14 +359,30 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      * la cadena del scope del BINDING (desde él hacia la raíz).
      */
     private declaredRole;
+    authorize(subject: SubjectRef, permission: string, scope: ScopeRef): Promise<boolean>;
     /**
-     * Los checks de UNA pregunta (subject, permiso, cadena): los denies de cada
-     * nivel y los roles del catálogo que conceden el permiso en cada nivel.
-     * Sin rol que conceda ⇒ `null`: la respuesta es `false` digan lo que digan
-     * los denies y no se pregunta al backend (2A).
+     * **`authorize` del modo `facts` (3b-2c): UN solo `Check`.**
+     *
+     * `can_<P>` sobre `scope:<key>` con el subject como user. El modelo (c2)
+     * ya lleva dentro las tres cosas que el modo `resolver` compone aquí:
+     * la herencia hacia abajo (`<P> from parent`), el deny explícito heredado
+     * (`denied_<P> from parent`) y la resta que hace ganar al deny
+     * (`can_<P> = <P> but not denied_<P>`). No hay `batchCheck`, no se expande
+     * la cadena y **no se llama al resolutor del consumidor** (cruce 6 del
+     * panel 2, que es también el literal que el README puede prometer).
+     *
+     * Lo único local que queda es el MEMO del catálogo, y es OBLIGATORIO: lo
+     * comprueba el llamante antes de llegar aquí. Sin esa guardia un permiso
+     * desconocido sería un `Check` de una relación que el modelo no declara —
+     * un 400 del servidor que saldría como 503— en vez del `false` que exige el
+     * invariante 5.
+     *
+     * Un scope que el árbol del consumidor no conoce no tiene tuplas en el
+     * store: responde `false` sin preguntar por él (invariante 9), pero aquí
+     * eso lo decide el propio store, no `resolveChain`. Cualquier fallo del
+     * backend sale como 503 desde el cliente envuelto; jamás un `false` mudo.
      */
-    private checksFor;
-    authorize(subject: SubjectRef, permission: string, scope: ScopeRef): Promise<boolean>;
+    private factsAuthorize;
     /**
      * `authorize` sobre N scopes con UN batchCheck (2.1, B6): los checks de
      * todas las cadenas viajan juntos (el SDK trocea a 50 y paraleliza) y se
@@ -343,13 +392,46 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      * Scope desconocido o sin rol que conceda ⇒ false sin checks.
      */
     authorizeMany(subject: SubjectRef, permission: string, scopes: ScopeRef[]): Promise<boolean[]>;
+    /**
+     * `authorizeMany` del modo `facts` (3b-2c): **UN `batchCheck` de N items**,
+     * uno por scope DISTINTO. En el modo `resolver` cada scope aporta los
+     * denies de su cadena más un check por (nivel, rol que concede): el lote
+     * crecía como N×M. Aquí cada scope es exactamente una pregunta,
+     * `can_<P>@scope:<key>`, y un scope repetido comparte item y respuesta
+     * (G2, CR9) en vez de duplicar el lote.
+     *
+     * Un `error` en cualquier check sigue siendo 503 entero (invariante 5, D1):
+     * lo lanza `batchCheckAll` antes de mirar un solo `allowed`.
+     */
+    private factsAuthorizeMany;
+    /**
+     * **`{ transaction }` se rechaza también AQUÍ** (L-5, defensa en
+     * profundidad como F-05 en L-0): la puerta 1 vive en el manager, pero
+     * `manager.driver()` es la salida documentada de las barreras y por ahí un
+     * `{ transaction }` llegaría al driver; sin esta guarda el driver
+     * escribiría la tupla en el store IGNORANDO la transacción — una escritura
+     * que finge ir en tu transacción y no se deshace con tu rollback, que es
+     * exactamente el fail-open que `transactionalWrites: false` declara no
+     * poder evitar. Primera línea de las cuatro escrituras, antes de la
+     * identidad, del catálogo y del store: CERO llamadas al cliente.
+     */
+    private rejectTransaction;
     grant(subject: SubjectRef, role: RoleQuery, scope: ScopeRef, options?: GrantOptions): Promise<GrantOutcome>;
     /**
-     * Write directo; si la key ya existía (409), camino largo. Devuelve si
-     * existía. Cualquier otro fallo se propaga tal cual (ya clasificado).
+     * Write directo de la asignación CON su estructura (3b-2f · R3); si algo ya
+     * estaba, camino largo. Devuelve si existía la ASIGNACIÓN —lo dice la
+     * relectura, no el error: el choque puede ser de las aristas, que en (c2)
+     * las comparten todos los holders del mismo rol en el mismo scope—.
+     * Cualquier otro fallo se propaga tal cual (ya clasificado).
      */
     private writeAssignment;
-    /** delete + write (dos llamadas: FGA no admite ambas sobre la misma key en una). */
+    /**
+     * delete + write (dos llamadas: FGA no admite ambas sobre la misma key en
+     * una). El write repone la ESTRUCTURA junto a la asignación: si un
+     * `purgeScope` concurrente se llevó la arista `scope#binding` entre medias,
+     * lo que queda vuelve a ser coherente en vez de una asignación inerte que
+     * `listRoles` ve y `authorize` no (3b-2f · R3).
+     */
     private replaceAssignment;
     /**
      * Estado actual de una asignación, con TRES resultados posibles y no dos.
@@ -361,10 +443,24 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      * que quien no pueda seguir sin él lo propague.
      */
     private readAssignment;
-    revoke(subject: SubjectRef, role: RoleQuery, scope: ScopeRef): Promise<void>;
+    revoke(subject: SubjectRef, role: RoleQuery, scope: ScopeRef, options?: WriteOptions): Promise<void>;
     hasRole(subject: SubjectRef, role: RoleQuery, scope: ScopeRef): Promise<boolean>;
-    deny(subject: SubjectRef, permission: string, scope: ScopeRef): Promise<void>;
-    removeDeny(subject: SubjectRef, permission: string, scope: ScopeRef): Promise<void>;
+    deny(subject: SubjectRef, permission: string, scope: ScopeRef, options?: WriteOptions): Promise<void>;
+    removeDeny(subject: SubjectRef, permission: string, scope: ScopeRef, options?: WriteOptions): Promise<void>;
+    /**
+     * El hecho de un deny (3b-2c): una relación DEL SCOPE,
+     * `scope:<key>#denied_<P>@<holder>`. Así el modelo lo hereda hacia abajo
+     * por `parent` y `can_<P>` puede restarlo dentro del mismo `Check`
+     * (invariante 2) sin que el paquete pasee la cadena. Hasta 3b-2k · K2 el
+     * modo `resolver` lo guardaba en un objeto propio
+     * (`deny_binding:<scopeKey>|<permissionUuid>`) y el paquete expandía la
+     * cadena a un check por nivel; ese tipo se borró con el modo.
+     *
+     * La relación lleva el SLUG proyectado (no el uuid) porque el modelo la
+     * declara por nombre. El slug que llega aquí es el del catálogo: el
+     * llamante ya pasó por `findPermission`, que es quien decide qué existe.
+     */
+    private denyTuple;
     /**
      * Holders con asignación vigente del rol en el scope exacto: `Read` por
      * objeto exacto, paginado, con la caducidad filtrada en cliente. Antes era
@@ -378,6 +474,17 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
     private listBindings;
     /** Scopes (por clave) donde el subject tiene un deny directo del permiso (por su uuid). */
     private deniedScopeKeys;
+    /**
+     * Los denies DIRECTOS del holder en el modo `facts`, ya traducidos a
+     * `(scope, permiso)`. No hay `deny_binding` que enumerar: se leen de una
+     * pasada las tuplas del holder sobre objetos `scope:` y se quedan las de la
+     * familia `denied_<P>`. La vuelta de relación a slug la da el CATÁLOGO —una
+     * relación que ya no declara ningún permiso no es un deny (D5), igual que
+     * un `deny_binding` de un permiso retirado—, y una clave de scope que el
+     * motor no entiende se cuenta y se registra, nunca se descarta en silencio
+     * (L0.16).
+     */
+    private factsDenies;
     private parseBindings;
     private warn;
     listRoles(subject: SubjectRef, scope: ScopeRef): Promise<string[]>;
@@ -394,23 +501,523 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
     listRoleScopes(subject: SubjectRef, scopeType: ScopeType): Promise<ScopeRef[]>;
     listScopes(subject: SubjectRef, permission: string): Promise<ScopeRef[]>;
     /**
-     * Denies directos del holder (2.1, B5): `Read` paginado de sus
-     * `deny_binding` (nunca ListObjects, L0.7), filtrados por el catálogo (un
-     * permiso retirado no es un deny, D5), por scope exacto si se pide, y por
-     * scopes que el árbol conoce (D8).
+     * Denies directos del holder (2.1, B5): `Read` paginado de sus relaciones
+     * `denied_<P>` sobre objetos `scope:` (nunca ListObjects, L0.7), filtrados
+     * por el catálogo (un permiso retirado no es un deny, D5), por scope exacto
+     * si se pide, y por scopes que el árbol conoce (D8).
      */
     listDenies(subject: SubjectRef, scope?: ScopeRef): Promise<DenyRef[]>;
+    /**
+     * Un nodo tiene como mucho UN padre. El paquete nunca escribe dos (cada
+     * `moved` sustituye la arista entera dentro de un `Write`), así que dos
+     * padres son DERIVA: alguien más escribe en el store, y mientras tanto la
+     * herencia está trayendo hechos de dos ramas. Se lanza; no se "arregla",
+     * porque elegir cuál sobrevive sería adivinar cuál de las dos concesiones
+     * vivas es la buena (cruce 8: «si devuelve >1 ⇒ drift ⇒ lanza»).
+     */
+    private assertOneParent;
+    /**
+     * El consumidor colgó un scope nuevo (o recolgó uno que ya existía: un
+     * `attach` sobre un nodo conocido ES un move). En modo `facts` eso es UNA
+     * tupla `scope:<hijo>#parent@scope:<padre>`; en modo `resolver` no es nada
+     * (la jerarquía la resuelve el paquete en cada pregunta).
+     */
+    onScopeAttached(child: ScopeRef, parent: ScopeRef): Promise<void>;
+    /**
+     * El consumidor movió un scope. Procedimiento fijado en el cruce 8 del
+     * panel 2: un `Read` del padre actual —obligatorio, porque FGA rechaza
+     * borrar una tupla inexistente—, la cadena del padre NUEVO en el store
+     * (3b-8 · A5: el anti-ciclos del consumidor no ve un store
+     * desincronizado) y **UN solo `Write`** con el delete del padre viejo y el
+     * write del nuevo, que es atómico dentro de la request. O(profundidad)
+     * requests, UNA mutación.
+     */
+    onScopeMoved(child: ScopeRef, newParent: ScopeRef): Promise<void>;
+    /**
+     * **Anti-ciclos, en el PAQUETE y antes de escribir** (cruce 3 del panel 2,
+     * bloqueante S2). Medido contra OpenFGA v1.19: el servidor ACEPTA una
+     * arista que cierra un ciclo, no se cuelga, responde en 2-7 ms y la
+     * herencia se vuelve bidireccional —un grant en un descendiente concede en
+     * el ancestro, y con la raíz dentro del ciclo concede en todo el store—.
+     * Fail-open mudo: no hay nada que capturar. La suite lo reproduce contra el
+     * `:8101` para que nadie proponga delegar esto en el backend.
+     *
+     * Las tres validaciones del cruce 8, en orden y sin escribir nada si
+     * fallan: (i) la raíz no cuelga de nadie; (ii) el padre EXISTE según el
+     * árbol del consumidor; (iii) el hijo no es ancestro-o-igual del padre.
+     * Las mismas que hace `AuthorizationManager.#assertEdge`: aquí se repiten
+     * por defensa en profundidad, porque `manager.driver()` es la salida
+     * documentada de todas las barreras del paquete.
+     *
+     * Devuelve las dos claves CANÓNICAS (invariante 17): un alias del uuid ni
+     * evade la comprobación de ciclo ni abre una segunda rama en el store.
+     */
+    private assertEdge;
+    /**
+     * El consumidor sacó un scope del árbol. En modo `facts` se borra su
+     * arista `#parent` — y **la arista es lo ÚLTIMO** (S6, cruce 9): el
+     * manager llama primero a `purgeScope`, que borra los hechos del scope y
+     * DEMUESTRA cero o lanza (invariante 11).
+     *
+     * **El motivo del orden cambió con (c2r) y el orden NO** (3b-2i). La razón
+     * que se escribió en 3b-2b —«un scope sin ancestro dejaría de heredar los
+     * denies del padre y sus permisos serían INDENEGABLES»— ya no es cierta:
+     * ése era exactamente el 🔴 1 del auditor R2 y hoy un scope que no alcanza
+     * `app` no concede nada (`can_<P>` exige `rooted`). Lo que sigue justificando
+     * el orden es lo otro: una purga que muere a medias tiene que dejar denies
+     * de MÁS, nunca de menos, y borrar la arista antes convertiría el fallo en
+     * «se quedaron hechos vivos en un nodo que ya nadie purga» (los recoge
+     * `authz:reconcile`, pero mientras tanto el nodo es invisible para el
+     * árbol). Con la arista al final, una purga fallida se reintenta.
+     *
+     * No se tocan las aristas de los HIJOS (`scope:<hijo>#parent@scope:<este>`):
+     * el consumidor notifica un `detached` por nodo, o un `moved` para
+     * recolgarlos — y **desde (c2r) esos hijos, mientras tanto, DENIEGAN** (su
+     * cadena ya no llega a la raíz) en vez de conceder de más. Lo que quede sin
+     * nodo arriba lo ve `authz:reconcile` (3b-3).
+     */
+    onScopeDetached(child: ScopeRef): Promise<void>;
+    /**
+     * Escribe la arista del árbol dejando UNA sola: se lee la que hay y se
+     * sustituye en el mismo `Write`. Sin diferencia no se llama al servidor
+     * (invariante 6: re-anexar al mismo padre es un no-op seguro, y además
+     * escribir una tupla que ya está sería un conflicto con los defaults
+     * estrictos del SDK).
+     *
+     * **Y el choque con otro escritor del árbol no es una caída** (3b-2h ·
+     * 🟠 4, invariante 6). Medido contra el `:8101`: dos `attached` del mismo
+     * nodo al mismo padre a la vez —lo que hacen dos pasadas del relay sobre el
+     * mismo lote, porque `pending()` no reserva nada— y el perdedor se llevaba
+     * un **503 «el backend no respondió»**, cuando el backend respondió
+     * perfectamente («cannot write a tuple which already exists»). Aquí se hace
+     * lo que el invariante 6 manda desde `grant`: releer y re-aplicar sobre lo
+     * que quedó —así el re-intento ve la arista del otro y sale por el no-op—,
+     * y una contención que no cede en `TREE_WRITE_ATTEMPTS` vueltas sale como
+     * 409 `E_AUTHZ_WRITE_CONFLICT`, nunca como un 503.
+     *
+     * Esto NO convierte dos escritores en uno: dos `attached` del mismo nodo a
+     * padres DISTINTOS siguen pudiendo dejar dos aristas (FGA no tiene
+     * compare-and-set y el `Read` de arriba es un check-then-write). Lo que
+     * impide esa carrera es el ESCRITOR ÚNICO del relay (`ScopeOutbox.acquire`).
+     */
+    private reparent;
+    /**
+     * **El barrido del rol local** (3b-2e · E1; decisión del dueño del
+     * 2026-08-30, opción 1).
+     *
+     * En (c2) el modelo no tiene `owner`, así que `authorize` NO vuelve a
+     * decidir con el árbol de hoy si un rol LOCAL sigue siendo visible: un
+     * `role_binding` concede mientras su scope alcance al que pregunta. Sin
+     * esto, mover una unit fuera de la organización dueña de un rol local
+     * dejaría de retirar lo concedido (el invariante 18 en `database`), que es
+     * un **fail-open** — y encima uno que solo se ve comparando drivers.
+     *
+     * Lo que se toca es la arista `scope#binding`, que es lo que hace
+     * ALCANZABLE la asignación: se BORRA donde el owner del rol ya no está en
+     * la cadena y se REESCRIBE donde vuelve a estarlo (invariante 18: volver la
+     * unit a su sitio restaura). No se toca el `assignee` —el hecho de la
+     * asignación no cambia porque el árbol se mueva, igual que en `database`—
+     * ni nada de un rol GLOBAL, cuya visibilidad no depende del árbol.
+     *
+     * **Por subárbol, no por nodo** (consecuencia 2): los descendientes del
+     * nodo movido también cambian de cadena.
+     *
+     * Coste: si el catálogo no tiene NI UN rol local —el caso de todo consumidor
+     * que no usa delegación— son **cero** requests y `moved` sigue siendo el
+     * `Read` + `Write` del cruce 8. Con roles locales: una lectura por rol local
+     * (sus bindings, por `role_binding#role`), la bajada del subárbol y un
+     * `Write` por lote.
+     */
+    private sweepLocalRoleBindings;
+    /**
+     * **El barrido por NIVEL** (3b-2g · R1; decisión del dueño del 2026-08-30
+     * (2), mismo mecanismo que E1).
+     *
+     * El modelo (c2) tampoco lleva el NIVEL (`scope_type`) del rol: la
+     * proyección dice qué permisos vincula, no en qué nivel se declara. Sin
+     * esto, cambiar el `scope_type` de un rol retira lo concedido en `database`
+     * —donde `declaredRoleAt` se evalúa en cada pregunta— y **sigue
+     * concediendo** en `facts`, que es la divergencia R1 del lote 2e.
+     *
+     * Se cierra igual que el owner: barriendo la arista `scope#binding` de los
+     * bindings de ESE rol con la regla única de visibilidad. Lo llama
+     * `projectCatalogRole`, que es el hook de «una escritura de catálogo cambió
+     * este rol»: el manager lo dispara tras `defineScopedRole`/`updateScopedRole`
+     * y un escritor «a mano» de `authz_*` tiene el mismo deber que ya tenía con
+     * el espejo de permisos (sin él, en `facts` un rol recién definido no
+     * concedería nada y quitarle un permiso seguiría concediéndolo).
+     *
+     * Coste: una lectura (los bindings del rol) y, **solo si el rol es LOCAL y
+     * tiene bindings**, la cadena del store de cada scope distinto donde cuelga
+     * uno; un `Write` por lote si hay algo que barrer. Un rol sin bindings —el
+     * caso de todo `defineScopedRole`— son 0 escrituras.
+     */
+    private sweepRoleVisibility;
+    /**
+     * La arista `scope#binding` de un binding, a escribir o a borrar según la
+     * **regla única de visibilidad** (`declaredRoleAt`, la misma que evalúa
+     * `database` en cada pregunta): el rol tiene que estar declarado para el
+     * NIVEL de ese scope (3b-2g · R1) y ser global o tener a su owner en la
+     * cadena (3b-2e · E1). Visible ⇒ la arista se (re)escribe; no visible ⇒ se
+     * borra. El `assignee` no se toca: la asignación existe igual, lo que
+     * cambia es dónde se la ve.
+     */
+    private classifyBindingEdge;
+    /**
+     * Aplica el barrido en lotes ≤ 100 (el límite del `Write`).
+     *
+     * `Ignore` en las dos direcciones: el barrido dice el estado que DEBE
+     * quedar, no el delta — borrar lo que ya no está y reescribir lo que ya
+     * estaba son no-ops, no errores (invariante 6).
+     */
+    private applyBindingSweep;
+    /**
+     * `[key, ...ancestros]` según el ÁRBOL DEL STORE (3b-2e · E1), subiendo por
+     * `scope#parent`. Es la cadena con la que FGA va a decidir, que es la que
+     * tiene que gobernar el barrido; el resolutor del consumidor no participa.
+     * Un nodo con más de un padre es deriva y se dice (`assertOneParent`), y el
+     * recorrido está acotado por el mismo tope de páginas que las
+     * enumeraciones: un ciclo escrito a mano no cuelga el proceso.
+     */
+    private storeChain;
     /**
      * Purga del scope exacto en FGA (N7, S6, B2). No hay "borrar todo lo de
      * este objeto": se leen por objeto EXACTO los bindings posibles — un
-     * `role_binding` por cada rol del catálogo de ese `scope_type` y un
-     * `deny_binding` por cada permiso — paginando `Read` (nunca ListObjects:
-     * trunca sin avisar, L0.7), se borra en lotes ≤ 100 (límite del Write) y
-     * se vuelve a leer cada objeto: si queda algo, se lanza. Un rol retirado
-     * del catálogo deja bindings inalcanzables por esta vía; es el precio de no
-     * tener un índice por objeto, y lo vigilará `authz:reconcile` (3b).
+     * `role_binding` por cada rol del catálogo de ese `scope_type` — más el
+     * objeto `scope:<key>` (donde viven los `denied_<P>` y el `#binding`),
+     * paginando `Read` (nunca ListObjects: trunca sin avisar, L0.7), se borra
+     * en lotes ≤ 100 (límite del Write) y se vuelve a leer cada objeto: si
+     * queda algo, se lanza. Un rol retirado del catálogo deja bindings
+     * inalcanzables por esta vía; es el precio de no tener un índice por
+     * objeto, y lo vigilará `authz:reconcile` (3b).
      */
     purgeScope(purged: ScopeRef): Promise<void>;
+    /**
+     * La **proyección derivada del catálogo** en el store (3b-2a · A5; regla
+     * del catálogo reescrita, panel 2 cruce 7). Se pasa a `syncAuthzCatalog`,
+     * que la usa en dos momentos: comprueba que el catálogo que va a quedar es
+     * publicable (cotas de nombre y techo del modelo) ANTES de escribir, y
+     * rehace las tuplas `role:<uuid>#permits_<P>@<holder>:*` con el catálogo ya
+     * confirmado.
+     *
+     * Sigue sin ser el catálogo: es un espejo reconstruible que ningún camino
+     * de LECTURA de este driver consulta para responder qué permisos tiene un
+     * rol (A6). Quien decide es `authz_*` a través del memo.
+     */
+    catalogProjection(): CatalogProjection;
+    /**
+     * **El marcador de raíz de (c2r)** (3b-2i): `scope:app#rooted@<holder>:*`,
+     * una tupla por holder type en todo el store y CERO por scope.
+     *
+     * Va aquí —en la proyección del catálogo, o sea en cada `syncAuthzCatalog`—
+     * y no en `attached`, porque el evento que hace falta cubrir es **añadir un
+     * holderType al `config`**: sin esto ese holder denegaría en TODO el store
+     * aunque el modelo se haya republicado, que es la única forma realista de
+     * quedarse sin marcador en un store vivo. Es idempotente: un `Read` y, solo
+     * si falta algo, un `Write` con lo que falta (0 escrituras en el caso
+     * normal).
+     *
+     * Solo en modo `facts`: el modelo del modo `resolver` no declara `rooted` y
+     * escribirlo sería un 400 del servidor.
+     *
+     * ⚠️ Sin marcador el store entero DENIEGA (fail-closed, medido). Por eso se
+     * repone en cada sync y `authz:reconcile` (3b-3) tiene el deber escrito de
+     * reportarlo como deriva cuando falte.
+     */
+    private ensureFactsRoot;
+    /**
+     * Espeja los vínculos rol→permiso: escribe lo que falta y BORRA lo que
+     * sobra, en UN `Write` por lote con deletes y writes juntos (cruce 8:
+     * queda prohibido el patrón `deleteTuples()` + `writeTuples()`, que no es
+     * atómico). Con (c2) quitar un permiso de un rol son tantos deletes como
+     * holders y ninguna reescritura del modelo.
+     *
+     * Sin diferencias no se llama al servidor: un `sync` que no cambió el
+     * catálogo escribe CERO tuplas.
+     */
+    private projectCatalog;
+    /**
+     * **Purga un ROL con sus hechos** (3b-2e · E4; hasta aquí este driver no lo
+     * traía y por eso `defineScopedRole` era 500 `E_AUTHZ_UNSUPPORTED` antes de
+     * escribir, 3E · P4).
+     *
+     * Lo que lo hace posible es (c2): el binding APUNTA A SU ROL
+     * (`role_binding:…#role@role:<uuid>`), así que los bindings de un rol se
+     * enumeran filtrando por `user` — y con la arista `scope#binding` se sabe de
+     * qué scope cuelga cada uno. En el modo `resolver` esas dos aristas no
+     * existen y el método TAMPOCO: el constructor lo retira (el manager lo lee
+     * como «no sé purgar» y se niega antes de escribir).
+     *
+     * Orden: **hechos primero, catálogo después** (el mismo de `detached`, S6).
+     * No hay transacción que abarque FGA y SQL, así que lo que se garantiza es
+     * la dirección segura: mientras la fila del rol siga viva, lo que quede en
+     * el store es visible y reintentable; al revés quedarían hechos huérfanos
+     * que resucitarían al recrear el slug. Y se DEMUESTRA cero (invariante 11):
+     * si algo sobrevive, 500 `E_AUTHZ_PURGE_INCOMPLETE` y el catálogo no se
+     * toca.
+     */
+    purgeRole(roleUuid: string): Promise<void>;
+    /**
+     * Cuántos hechos VIGENTES tiene cada rol, en todos los scopes (3b-2j).
+     *
+     * Aquí los hechos son TUPLAS, no filas: `role_binding:<scope>|<rol>#assignee@<holder>`,
+     * con la caducidad en su *condition*. Por eso esta pregunta es del PUERTO
+     * y no del barrido: hasta 3b-2j `pruneOrphanRoles` contaba
+     * `authz_assignments` —la tabla del driver `database`, vacía con este— y
+     * el `stillGranting` que se lee justo antes de purgar decía SIEMPRE «este
+     * rol no concede», sobre roles que concedían (medido en el lote 2i).
+     *
+     * Lo hace posible lo mismo que hace posible `purgeRole`: el binding apunta
+     * a su rol (`role_binding:…#role@role:<uuid>`, (c2)), así que los bindings
+     * de un rol se enumeran filtrando por `user`. En modo `resolver` esa arista
+     * no existe y el método TAMPOCO (el constructor lo retira, y el manager lo
+     * lee como «no lo sé»).
+     *
+     * La arista estructural se lee con `includeExpired` —no caduca, la
+     * caducidad está en el `assignee`— y los assignees sin él: la caducidad es
+     * ESTRICTA y con el reloj del driver, igual que en `authorize`. Un `user`
+     * que no se entiende como holder se cuenta igual (a diferencia de
+     * `listSubjects`, que lo descarta): aquí contar de MÁS es el lado seguro —
+     * marca el rol para que un humano lo mire— y contar de menos es decir «no
+     * concede» sobre algo que sí.
+     *
+     * Coste: por rol preguntado, una lectura de sus bindings más una por
+     * binding. Lo llama `pruneOrphanRoles` con los HUÉRFANOS de la pasada (no
+     * con el catálogo entero) y corre en un comando de plataforma, no en el
+     * camino de una petición.
+     */
+    countRoleAssignments(roleUuids: string[]): Promise<number[]>;
+    /**
+     * **Rehace la proyección de UN rol** (3b-2e · E4). En (c2) lo que un rol
+     * concede son tuplas (`role:<uuid>#permits_<P>@<holder>:*`), no el catálogo
+     * local: una escritura de catálogo que no las toque deja un rol que no
+     * concede nada (`defineScopedRole`) o que sigue concediendo lo que ya no
+     * vincula (`updateScopedRole`) — lo segundo es un fail-open. `syncAuthzCatalog`
+     * ya lo hace para el catálogo entero cuando el consumidor le pasa la
+     * proyección; esto es lo mismo para las escrituras de la API de delegación,
+     * y cuesta una lectura por holder.
+     *
+     * **Y son DOS proyecciones, no una** (3b-2g · R1): lo que el rol concede
+     * (`permits_<P>`) y **dónde es visible** (`scope#binding`, `sweepRoleVisibility`).
+     * El modelo (c2) no lleva el NIVEL del rol, así que un `scope_type` que
+     * cambia sin barrer deja la asignación concediendo en un nivel que el
+     * catálogo ya no declara — retirado en `database` y vivo aquí, que es la
+     * divergencia R1 del lote 2e.
+     */
+    projectCatalogRole(roleUuid: string): Promise<void>;
+    /**
+     * **Reconstruye el store desde `authz_*` + el árbol del consumidor.**
+     *
+     * Es la razón de ser de la fase («todo en un driver o todo en otro, con una
+     * migración idempotente y bidireccional») y la ÚNICA primitiva de migración
+     * del paquete: `openfga:import` se borró en 3b-2k · K2 porque escribía las
+     * tuplas de un modelo que ya no existe.
+     *
+     * Migra las TRES cosas que hacen completo a este driver:
+     *  1. el **marcador de raíz** (`scope:app#rooted@<holder>:*`, 3b-2i) — sin
+     *     él el store entero DENIEGA, así que va primero;
+     *  2. la **proyección del catálogo** (`role:<uuid>#permits_<P>`), leída con
+     *     la MISMA función que usa `syncAuthzCatalog` (`readCatalogProjectionSnapshot`),
+     *     para que reconcile no "arregle" en cada pasada lo que el sync deja bien;
+     *  3. el **árbol** (`scope#parent`) desde `scopes.enumerateEdges`, y
+     *  4. los **hechos**: `authz_assignments` (assignee + las dos aristas de
+     *     (c2)) y `authz_denies` (`scope#denied_<P>`).
+     *
+     * **Qué borra y qué no.** Lo DERIVADO —marcador, catálogo y árbol— es un
+     * espejo de datos locales que nadie más escribe: lo que sobra se borra
+     * siempre (cruce 9 · S7 lo exige para las aristas que `enumerateEdges` no
+     * respalda, y es lo que repara un nodo con DOS padres, 3b-2h · 🟠 4). Los
+     * HECHOS solo se borran con `prune`: son irreversibles y su origen depende
+     * de qué driver esté vivo. La excepción, a propósito, es la arista
+     * `scope#binding` de una asignación que el origen SÍ respalda pero cuya
+     * regla de visibilidad dice que NO (invariante 18): dejarla es fail-OPEN
+     * —es justo la escritura que `scopes.moved`/`projectCatalogRole` pudieron
+     * perder si el relay no pasó—, así que se borra siempre y se cuenta en
+     * `drift.roleVisibility`.
+     *
+     * **Nada de `Ignore` a ciegas** (cruce 9 · S7): el importador viejo escribía
+     * con `onDuplicateWrites: Ignore` y por eso una tupla que ya estaba con OTRA
+     * caducidad se quedaba como estaba y encima se contaba como escrita —rompía
+     * los invariantes 3 y 6—. Aquí el estado del destino se LEE entero antes de
+     * decidir, la diferencia de caducidad se resuelve con delete + write, y los
+     * contadores salen del diff, no del write. `Ignore` se conserva solo como
+     * red contra una carrera (y por eso la migración va con `manager.freeze()`).
+     *
+     * `dryRun` es el VERIFICADOR: mismo recorrido, cero escrituras, mismos
+     * números. Read-only por contrato (cruce 4 · S18): **un `--fix` está
+     * prohibido** y no se implementa ni se deja preparado.
+     */
+    reconcile(source: ReconcileSource, options?: ReconcileOptions): Promise<ReconcileReport>;
+    /**
+     * Las relaciones `permits_<P>` que DECLARA el modelo publicado del store, o
+     * `null` si no se puede saber (un store sin modelo). No es una barrera de
+     * seguridad: es la diferencia entre contar un permiso que este store no
+     * puede llevar y morirse con un 400 a mitad de la migración.
+     */
+    private modelPermissions;
+    /**
+     * El árbol del ORIGEN, paginado (`scopes.enumerateEdges`), con los ciclos
+     * apartados. Un ciclo no se escribe NUNCA: FGA lo evalúa y la herencia pasa
+     * a ser bidireccional (un grant en un descendiente concede en el ancestro,
+     * cruce 3), así que aquí sale como reporte y sus nodos se quedan sin arista
+     * —o sea, sin `rooted`, o sea denegando (fail-closed)—.
+     */
+    private readSourceTree;
+    /**
+     * Los HECHOS del origen (`authz_assignments` y `authz_denies`), leídos **por
+     * lotes con cursor** sobre la clave primaria: una pasada interrumpida se
+     * repite y converge (es idempotente), y una base grande no entra entera en
+     * memoria de golpe. Los DOS barridos van en la MISMA transacción de lectura
+     * repetible (3b-6, `withSourceSnapshot`): sueltos, componían dos mitades de
+     * dos operaciones distintas y FABRICABAN un permiso.
+     *
+     * Cada fila que NO se migra sale contada y con su motivo:
+     *  - `unknown-scope`: el árbol del consumidor ya no resuelve ese scope
+     *    (`detached` de un ancestro). Sus tuplas del store son las de la
+     *    «resurrección» (3b-0b · AA4) y las borra `--prune`.
+     *  - `unknown-role` / `unknown-permission`: el catálogo ya no lo declara
+     *    (un rol retirado; invariante 11 dice que los recoge este comando).
+     *  - `expired`: la asignación ya no concede; migrarla sería escribir una
+     *    caducidad pasada.
+     *  - `role-not-visible`: la asignación existe (y `listRoles`/`hasRole` la
+     *    enumeran), pero el rol NO es visible en ese scope con el árbol y el
+     *    catálogo de HOY (invariante 18), así que su arista `scope#binding` no
+     *    se escribe — y si el store la tiene, se borra.
+     *  - `unknown-holder-type`: el `holderTypes` del config no declara ese
+     *    morph name, así que no hay usuario FGA que escribir.
+     */
+    private readSourceFacts;
+    /**
+     * **La foto CONSISTENTE del origen** (3b-6; 🔴 3 del panel 3, verificado en
+     * el código por el juez).
+     *
+     * `readSourceFacts` recorre `authz_assignments` y DESPUÉS `authz_denies`.
+     * Cada barrido se construía sobre la conexión global, así que entre los dos
+     * había un hueco —el tiempo de pasear la primera tabla entera por lotes de
+     * 100: segundos o minutos en una base real— por el que se colaban
+     * operaciones de negocio COMPUESTAS. Un offboarding es `revoke` +
+     * `removeDeny`: si cae ahí, la pasada se queda con la mitad de cada una y
+     * escribe en el destino **el rol sin su deny**, o sea un permiso que NI el
+     * estado anterior NI el posterior concedían, con el reporte diciendo
+     * `written=13 extra=0 skipped={} clean=true`. No es una pérdida: es una
+     * ESCALADA fabricada, y el operador no tiene ni un motivo para desconfiar
+     * del verde.
+     *
+     * Con los dos barridos dentro de UNA transacción de lectura repetible, el
+     * peor resultado de la ventana deja de ser «un estado que nunca existió» y
+     * pasa a ser «el estado consistente de `t0`»: la deriva recuperable que
+     * repite la pasada siguiente.
+     *
+     * **Qué garantiza cada motor, porque no es lo mismo** (Fase 2.5 dixit):
+     *  - **PostgreSQL**: `BEGIN TRANSACTION ISOLATION LEVEL REPEATABLE READ`.
+     *    La foto se toma en la primera sentencia de la transacción y no se
+     *    mueve; garantía del motor.
+     *  - **MySQL/InnoDB**: `SET TRANSACTION ISOLATION LEVEL REPEATABLE READ` +
+     *    `BEGIN`, y la lectura consistente queda fijada en la primera consulta.
+     *    REPEATABLE READ es su default, pero se DECLARA a propósito: el default
+     *    es config del servidor y no una promesa del paquete.
+     *  - **SQLite**: no acepta nivel de aislamiento —knex avisa y lo ignora—,
+     *    así que no se le pide: su transacción de LECTURA ya es una foto (en
+     *    WAL el lector conserva su snapshot mientras un escritor confirma; sin
+     *    WAL el escritor espera al lector). Por eso aquí se pregunta el
+     *    dialecto en vez de mandar el nivel a ciegas.
+     *
+     * **Lo que esto NO cubre y queda declarado**: cubre la dirección cuyo
+     * origen es `authz_*` (`--to=openfga`). Cuando la fuente de verdad de los
+     * hechos es el STORE (`readOriginFacts` → `enumerateFacts`: `--to=database`
+     * y la pasada de mantenimiento) las páginas de `Read` **tampoco son una
+     * foto consistente** y no hay REPEATABLE READ que valga: ahí la misma
+     * composición de media transacción sigue siendo posible. La instrumentación
+     * posible en esa dirección es `readChanges({ startTime })` —detectar y
+     * nombrar la tupla, no prevenirla—, y no está hecha.
+     */
+    private withSourceSnapshot;
+    /**
+     * **Los hechos por el PUERTO** (3b-5): la otra fuente de verdad posible.
+     *
+     * Se usa cuando `authz_*` NO manda —el caso que faltaba: el motor ya sirve
+     * desde este driver y sus hechos son las tuplas del store—, y también sirve
+     * para migrar desde otro driver que sepa `enumerateFacts`. El recorrido y
+     * los motivos son **los mismos** que los de `readSourceFacts` (`expired`,
+     * `unknown-scope`, `unknown-role`, `unknown-holder-type`,
+     * `role-not-visible`): lo único que cambia es de dónde salen las filas, que
+     * es justo la decisión que no se estaba tomando.
+     *
+     * Consecuencia buscada: con el store como origen, `wanted` describe lo que
+     * el store YA tiene, así que la pasada no escribe ni borra un solo hecho —y
+     * sí rehace lo DERIVADO (marcador, catálogo, árbol) y aplica el barrido de
+     * visibilidad del invariante 18 con el árbol y el catálogo de HOY, que es
+     * la reparación que el invariante promete y no existía.
+     *
+     * Disciplina del cursor idéntica a la de `--to=database`: como mucho
+     * `limit` por página, el cursor tiene que AVANZAR y la cota `maxTuples` se
+     * aplica también al origen.
+     */
+    private readOriginFacts;
+    /**
+     * Una ASIGNACIÓN del origen (venga de `authz_*` o del puerto) traducida a
+     * lo que el store debe tener: el `assignee` con su caducidad, la arista
+     * `role_binding#role` y —solo si el rol es VISIBLE ahí— la `scope#binding`.
+     * Es la única implementación de esa regla en esta dirección: tenerla dos
+     * veces era tenerla distinta según de dónde salieran los hechos.
+     */
+    private wantAssignment;
+    /** Un DENY del origen (permiso ya como slug) traducido a `scope#denied_<P>`. */
+    private wantDeny;
+    /**
+     * Pasea una tabla `authz_*` por lotes de `batchSize` con cursor sobre
+     * `uuid` (clave primaria: orden total y estable). Es lo que hace la pasada
+     * REANUDABLE y lo que impide que una base grande entre entera de golpe.
+     *
+     * **El cliente llega por parámetro** (3b-6): antes cada página se construía
+     * sobre el `db` global, así que dos barridos consecutivos eran dos fotos
+     * distintas. Quien decide la foto es `withSourceSnapshot`, y aquí solo se
+     * obedece — un call-site nuevo que pase `db` vuelve a abrir el hueco, y por
+     * eso el parámetro es obligatorio y no tiene default.
+     */
+    private eachRow;
+    /**
+     * **Los hechos de este store, paginados** (3b-3b): la mitad ORIGEN de la
+     * migración, la que hace posible `authz:reconcile --to=database`.
+     *
+     * Se lee con `Read` y su `continuation_token`, no con `ListObjects`: el
+     * plan lo dice con esas palabras y el motivo es que `ListObjects` **no
+     * tiene `continuation_token`** —corta al tope del servidor sin señal
+     * (S16)—, así que no hay forma de pasear un store entero con él. `Read`
+     * sin filtro es además lo único que ve la basura de una versión anterior,
+     * que es lo que sale en `skipped`.
+     *
+     * **Nada se filtra**: una asignación caducada sale con su `expiresAt` para
+     * que el DESTINO la cuente con su motivo. Si se filtrara aquí desaparecería
+     * sin dejar rastro en ningún contador, que es exactamente lo que una
+     * migración no puede hacer. Por lo mismo NO interviene el reloj del driver.
+     *
+     * Lo que no es un hecho —la estructura de (c2) (`parent`, `binding`,
+     * `role`, `rooted`) y la proyección del catálogo (`permits_<P>`)— no se
+     * emite ni se cuenta: es DERIVADO, se rehace desde el catálogo y el árbol
+     * del consumidor, y en esta dirección ni siquiera se migra. Lo que sí se
+     * cuenta es lo que TENDRÍA que ser un hecho y no se entiende.
+     */
+    enumerateFacts(page: {
+        limit: number;
+        after?: string;
+    }): Promise<ReconcileFactPage>;
+    /**
+     * El store ENTERO, con la caducidad de cada tupla. Un `Read` sin filtro es
+     * la única forma de ver lo que SOBRA —incluida la basura de una versión
+     * anterior, cuyos tipos el modelo de hoy ni declara (se lee y se borra, se
+     * comprobó contra el servidor)—: filtrando por objeto solo se ve lo que ya
+     * se sabe que existe. Paginado y acotado como todas las enumeraciones.
+     */
+    private readEveryTuple;
+    /**
+     * Aplica el plan en lotes ≤ 100 (el límite del `Write`). `Ignore` en las dos
+     * direcciones es RED, no política: el plan sale de un diff sobre el estado
+     * leído y la migración corre con las escrituras congeladas, así que un
+     * duplicado o un borrado que ya no está solo puede venir de una carrera —y
+     * en una carrera es preferible seguir a abortar la migración entera—.
+     */
+    private applyReconcileWrites;
     /**
      * TODAS las tuplas que casan con el filtro, paginando `Read` hasta agotar
      * el `continuation_token`, sin las caducadas. Es la única primitiva de