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

package/build/src/drivers/openfga_driver.js

@@ -1,138 +1,215 @@
-import { Exception } from '@adonisjs/core/exceptions';
 import db from '@adonisjs/lucid/services/db';
-import { OpenFgaClient, ClientWriteRequestOnDuplicateWrites, ClientWriteRequestOnMissingDeletes, } from '@openfga/sdk';
-import { AuthorizationBackendError } from '../errors.js';
-import { APP_SCOPE, APP_SCOPE_TYPE } from '../types.js';
-import { APP_SCOPE_DB_UUID } from './database_driver.js';
-/** `:` no es válido en ids de FGA — se encodea (`audit:read` → `audit~read`). */
-function encodeSlug(slug) {
-    return slug.replaceAll(':', '~');
-}
-function decodeSlug(encoded) {
-    return encoded.replaceAll('~', ':');
-}
+import { OpenFgaClient, ClientWriteRequestOnDuplicateWrites, ClientWriteRequestOnMissingDeletes, ConsistencyPreference, } from '@openfga/sdk';
+import { AuthorizationBackendError, AuthorizationBackendTimeoutError, AuthorizationConfigError, AuthorizationInternalError, InvalidIdentityError, MassReconcileRefusedError, ReconcileTooLargeError, PurgeIncompleteError, ScopeCycleError, ScopeDriftUnguardedError, ScopeTreeDriftError, UnknownPermissionError, UnknownRoleError, UnsupportedOperationError, WriteConflictError, } from '../errors.js';
+import { APP_SCOPE_TYPE } from '../types.js';
+import { AUTHZ_TABLES_ORIGIN, RECONCILE_MAX_DETAILS, emptyReconcilePhases as emptyPhases, reconcileBatchSize, reconcileMaxTuples, sumReconcilePhases as sumPhases, } from '../reconcile.js';
+import { assertRoleAssignableAt, declaredRoleAt, fromDbScopeUuid, hasRoleTargets, resolveRoleQuery, rolesToRevoke, visibleRoleFor, } from './database_driver.js';
+import { assertCatalogUuid, assertIdentity, assertScope, chainKeysFrom, isCatalogUuid, isValidScope, normalizeRoleQuery, scopeFromKey, scopeKey, } from '../identity.js';
+import { resolveGrantExpiry, sameInstant, toExpiryDate } from '../expiry.js';
+import { assertKnownScope, canonicalScope, canonicalScopeTargets, guardSql, isAuthzError, isTimeoutLike, resolveChain, rootOnlyResolver, withDeadline, } from '../shared/backend_guard.js';
+import { CatalogCache, GLOBAL_OWNER_KEY, assertCatalogOptions, isRoleVisibleWith, withAuthzCatalogWrite } from '../catalog/catalog_cache.js';
+import { FACTS_ASSIGNEE_RELATION, FACTS_BINDING_RELATION, FACTS_BINDING_TYPE, FACTS_DENIED_PREFIX, FACTS_PARENT_RELATION, FACTS_PERMITS_PREFIX, FACTS_ROLE_RELATION, FACTS_ROLE_TYPE, FACTS_ROOTED_RELATION, FACTS_SCOPE_TYPE, assertFactsModelPublishable, assertHolderTypes, factsBindingObject, factsBindingTuples, factsCatalogTuples, factsDenyTuple, factsParentTuple, factsRelationsOf, factsRootTuples, factsScopeBindingTuple, factsScopeObject, factsTupleId, openFgaFactsModel, } from './openfga_facts.js';
+import { readCatalogProjectionSnapshot } from '../catalog/catalog.js';
+import { isSqliteDialect, sqlExpiryCodec } from '../shared/sql_expiry.js';
+import { isClock, systemClock } from '../clock.js';
 /**
- * Caracteres admitidos en un tipo de scope y en un uuid al construir la clave
- * del binding. `|` es el separador y `~` el escape de los slugs: si alguno
- * apareciera dentro de un componente, dos scopes DISTINTOS podrían producir
- * la misma clave —p. ej. `{org, 'anization|X'}` y `{'org|anization', 'X'}`—
- * y un grant en uno autorizaría en el otro (confusión de privilegios).
- *
- * El driver `database` es inmune por construcción (guarda tipo y uuid en
- * columnas separadas, sin codificar); esta validación protege la única ruta
- * que serializa el scope a un string.
+ * 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.
  */
-const SCOPE_COMPONENT_FORMAT = /^[a-zA-Z0-9_.:-]+$/;
-function assertScopeComponent(kind, value) {
-    if (!SCOPE_COMPONENT_FORMAT.test(value)) {
-        throw new Exception(`${kind} inválido para el driver openfga: '${value}'. ` +
-            `Solo se admiten letras, dígitos y . _ - : (ni '|' ni '~').`, { status: 500 });
-    }
-}
+export { assertHolderTypes };
+// La clave de scope del id del binding (`app` | `<tipo>|<uuid>`) es la
+// misma `scopeKey` del paquete (`identity.ts`; desde 3B también el owner de
+// un rol local): `|` es el separador y `assertScope` impide que un
+// componente lo lleve (dos scopes distintos no producen la misma clave) y
+// rechaza `{app, uuid}` (L0.10).
 /**
- * Clave de scope dentro del id del binding: `app` para la raíz,
- * `<tipo>|<uuid>` para el resto. Genérico: sirve para cualquier nivel que
- * defina el consumidor sin tocar el driver.
+ * Id de binding (`<scopeKey>|<uuid>`: `app|<uuid>` o `<tipo>|<uuidScope>|<uuid>`)
+ * → 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
+ * scope variara de longitud (panel 2026-08-28, §2-C), y con un escape no
+ * inyectivo desde el llamante (L0.8a).
+ *
+ * `null` si no tiene la forma del motor O si alguna parte no pasa su
+ * 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 `authz:reconcile` (3b-3) los reportará como deriva.
+ * Exportada para probarla sin servidor.
  */
-function scopeKey(scope) {
-    assertScopeComponent('Tipo de scope', scope.type);
-    if (scope.type === APP_SCOPE_TYPE)
-        return APP_SCOPE_TYPE;
-    assertScopeComponent('UUID de scope', String(scope.uuid ?? ''));
-    return `${scope.type}|${scope.uuid}`;
-}
-function parseBindingId(id) {
-    const parts = id.split('|');
-    if (parts.length === 2 && parts[0] === APP_SCOPE_TYPE) {
-        return { scope: { type: APP_SCOPE_TYPE, uuid: null }, slug: decodeSlug(parts[1]) };
+export function parseBindingId(id) {
+    const cut = id.lastIndexOf('|');
+    if (cut < 0)
+        return null;
+    const uuid = id.slice(cut + 1);
+    const keyParts = id.slice(0, cut).split('|');
+    let scope;
+    if (keyParts.length === 1 && keyParts[0] === APP_SCOPE_TYPE) {
+        scope = { type: APP_SCOPE_TYPE, uuid: null };
     }
-    if (parts.length === 3) {
-        return { scope: { type: parts[0], uuid: parts[1] }, slug: decodeSlug(parts[2]) };
+    else if (keyParts.length === 2) {
+        scope = { type: keyParts[0], uuid: keyParts[1] };
     }
-    return null;
+    else {
+        return null;
+    }
+    if (!isValidScope(scope) || !isCatalogUuid(uuid))
+        return null;
+    return { scope, uuid };
 }
 /** `<tipoFga>:<uuid>` a partir del morph name del holder. */
 function fgaSubjectWith(subject, holderTypes) {
     const fgaType = holderTypes[subject.type];
     if (!fgaType) {
-        throw new Exception(`Holder type '${subject.type}' no está en el modelo FGA ` +
+        // Contradicción de config (D15): el modelo del store no tiene ese tipo.
+        throw new AuthorizationConfigError(`Holder type '${subject.type}' no está en el modelo FGA ` +
             `(declarados: ${Object.keys(holderTypes).join(', ') || 'ninguno'}). ` +
-            `Añádelo a holderTypes y regenera el authorization model.`, { status: 500 });
+            `Añádelo a holderTypes y regenera el authorization model.`);
     }
     return `${fgaType}:${subject.uuid}`;
 }
-function checkContext() {
-    return { current_time: new Date().toISOString() };
-}
 /**
- * ¿La expiración almacenada y la pedida son la misma? Compara el instante,
- * no la cadena: `2026-01-01T00:00:00Z` y `2026-01-01T00:00:00.000Z` son el
- * mismo momento y no justifican reescribir la tuple.
+ * El `context` de TODA consulta que evalúe relaciones: checks de roles y de
+ * denies. Un único constructor a propósito (S17): en cuanto una tupla del
+ * camino lleva la condición `not_expired`, un check sin `current_time` falla
+ * entero (400 → 503). Hoy los denies no llevan condición; el modo facts (3b)
+ * evalúa deny y grant en un solo check, así que no hay margen. Las
+ * enumeraciones no evalúan nada (`Read` devuelve tuplas escritas): filtran
+ * la caducidad en cliente con el MISMO reloj del driver (`now()`, J1): el
+ * `current_time` que viaja en cada check es el instante que decide.
  */
-function sameExpiry(storedValidUntil, requested) {
-    if (!storedValidUntil && !requested)
-        return true;
-    if (!storedValidUntil || !requested)
-        return false;
-    const stored = Date.parse(storedValidUntil);
-    return Number.isFinite(stored) && stored === requested.getTime();
+function checkContext(now) {
+    return { current_time: now.toISOString() };
 }
 /**
- * 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.
+ * Alinea los resultados de un batchCheck con los checks pedidos por
+ * `correlationId`, no por posición (L0.14). El SDK reparte el lote en
+ * sub-lotes paralelos y concatena las respuestas según llegan: el orden no es
+ * el de los checks. Cardinalidad igual no basta —un id duplicado y otro
+ * ausente pasan el conteo—: cada check debe tener EXACTAMENTE un resultado y
+ * ningún resultado puede ser de un check que no se pidió.
  */
-export function openFgaAuthorizationModel(holderTypeMap) {
-    const holderTypes = [...new Set(Object.values(holderTypeMap))];
-    const direct = holderTypes.map((type) => ({ type }));
-    const directWithExpiry = [
-        ...direct,
-        ...holderTypes.map((type) => ({ type, condition: 'not_expired' })),
-    ];
-    return {
-        schema_version: '1.1',
-        type_definitions: [
-            ...holderTypes.map((type) => ({ type, relations: {}, metadata: null })),
-            {
-                type: 'role_binding',
-                relations: { assignee: { this: {} } },
-                metadata: {
-                    relations: { assignee: { directly_related_user_types: directWithExpiry } },
-                },
-            },
-            {
-                type: 'deny_binding',
-                relations: { denied: { this: {} } },
-                metadata: {
-                    relations: { denied: { directly_related_user_types: direct } },
-                },
-            },
-        ],
-        conditions: {
-            not_expired: {
-                name: 'not_expired',
-                expression: 'current_time < valid_until',
-                parameters: {
-                    current_time: { type_name: 'TYPE_NAME_TIMESTAMP' },
-                    valid_until: { type_name: 'TYPE_NAME_TIMESTAMP' },
-                },
-            },
-        },
-    };
+export function correlateBatchResults(checks, results) {
+    const byId = new Map();
+    for (const result of results) {
+        const id = result.correlationId;
+        if (byId.has(id)) {
+            throw new AuthorizationInternalError(`OpenFGA batchCheck devolvió dos resultados para el correlationId '${id}'`);
+        }
+        byId.set(id, result);
+    }
+    const aligned = checks.map((check) => {
+        const result = byId.get(check.correlationId);
+        if (!result) {
+            throw new AuthorizationInternalError(`OpenFGA batchCheck no devolvió resultado para el check '${check.correlationId}' (${check.relation} ${check.object})`);
+        }
+        return result;
+    });
+    if (byId.size !== checks.length) {
+        const requested = new Set(checks.map((c) => c.correlationId));
+        const foreign = [...byId.keys()].filter((id) => !requested.has(id));
+        throw new AuthorizationInternalError(`OpenFGA batchCheck devolvió resultados de checks no pedidos: ${foreign.join(', ')}`);
+    }
+    return aligned;
 }
 /**
- * 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 async function provisionOpenFgaStore(apiUrl, name, holderTypeMap) {
+export async function provisionOpenFgaStore(apiUrl, name, holderTypeMap, permissions, relations) {
     const client = new OpenFgaClient({ apiUrl });
     const store = await client.createStore({ name });
     const scoped = new OpenFgaClient({ apiUrl, storeId: store.id });
-    const model = await scoped.writeAuthorizationModel(openFgaAuthorizationModel(holderTypeMap));
+    const model = await scoped.writeAuthorizationModel(openFgaFactsModel(holderTypeMap, permissions, relations));
     return { storeId: store.id, modelId: model.authorization_model_id };
 }
+/**
+ * ¿El error (o su cadena de causas) es el rechazo de FGA a escribir una tuple
+ * key que ya existe? Es la ÚNICA señal de carrera check-then-write que
+ * `grant` acepta: un 400 de validación (`validation_error`) o un 5xx no son
+ * "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".
+ *
+ * **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 function isDuplicateWrite(error) {
+    let current = error;
+    for (let depth = 0; current && depth < 6; depth++) {
+        if (current.statusCode === 409)
+            return true;
+        if (current.apiErrorCode === 'write_failed_due_to_invalid_input' &&
+            /already exists/i.test(String(current.apiErrorMessage ?? current.message ?? ''))) {
+            return true;
+        }
+        current = current.cause;
+    }
+    return false;
+}
+/**
+ * ¿El `Write` de una arista del árbol chocó con OTRO escritor? (3b-2h · 🟠 4)
+ * Son los dos lados del mismo choque: la tupla que se escribe ya está
+ * (`isDuplicateWrite`) o la que se borra ya no está —la acaba de borrar el
+ * otro—. En `reparent` las dos vienen SIEMPRE de una carrera: la lista de
+ * deletes se acaba de leer del store. Cualquier otro fallo del write se
+ * propaga clasificado, como hasta ahora.
+ */
+function isTreeWriteRace(error) {
+    if (isDuplicateWrite(error))
+        return true;
+    let current = error;
+    for (let depth = 0; current && depth < 6; depth++) {
+        if (current.apiErrorCode === 'write_failed_due_to_invalid_input' &&
+            /does not exist/i.test(String(current.apiErrorMessage ?? current.message ?? ''))) {
+            return true;
+        }
+        current = current.cause;
+    }
+    return false;
+}
+/**
+ * Receta que acompaña al 503 de un `grant` SIN `expiresAt` cuando no se pudo
+ * leer la caducidad vigente: preservar exige saber qué hay, y asumir
+ * "permanente" sería L0.4 en modo degradado. Se añade al mensaje del error
+ * ya clasificado (mismo tipo, mismo `code`, misma causa).
+ */
+function withPreserveRecipe(error) {
+    error.message +=
+        `. 'grant' sin 'expiresAt' necesita leer la caducidad vigente para preservarla y no se ` +
+            `escribe a ciegas: si la intención es "permanente", pasa { expiresAt: null }; si es temporal, una Date.`;
+    return error;
+}
 /**
  * Devuelve el cliente con TODOS sus métodos envueltos: un fallo de red o un
  * 5xx sale como `AuthorizationBackendError` (503) y no como el `FgaError` del
@@ -148,21 +225,28 @@ export async function provisionOpenFgaStore(apiUrl, name, holderTypeMap) {
  * ahí el error del SDK es la información más útil y no rompe ninguna
  * abstracción.
  */
-function guardBackendErrors(client) {
+function guardBackendErrors(client, timeoutMs) {
     return new Proxy(client, {
         get(target, prop, receiver) {
             const value = Reflect.get(target, prop, receiver);
             if (typeof value !== 'function')
                 return value;
             return (...args) => {
-                const fail = (cause) => new AuthorizationBackendError('openfga', String(prop), cause);
+                const operation = String(prop);
+                const fail = (cause) => isTimeoutLike(cause)
+                    ? new AuthorizationBackendTimeoutError('openfga', operation, timeoutMs, cause)
+                    : new AuthorizationBackendError('openfga', operation, cause);
                 try {
                     const result = value.apply(target, args);
-                    return result instanceof Promise
-                        ? result.catch((error) => {
-                            throw fail(error);
-                        })
-                        : result;
+                    if (!(result instanceof Promise))
+                        return result;
+                    // Deadline TOTAL por llamada (reintentos del SDK incluidos): el
+                    // `timeout` de axios corta cada intento, pero el SDK reintenta los
+                    // errores de red con backoff y sin esto el llamante esperaría la
+                    // suma de todos. Un deadline es un deadline.
+                    return withDeadline(result.catch((error) => {
+                        throw fail(error);
+                    }), timeoutMs, () => new AuthorizationBackendTimeoutError('openfga', operation, timeoutMs));
                 }
                 catch (error) {
                     throw fail(error);
@@ -172,378 +256,2615 @@ function guardBackendErrors(client) {
     });
 }
 /**
- * Migración de hechos database → openfga: copia las asignaciones vigentes y
- * los denies de las tablas `authz_*` como tuples del store FGA.
+ * **El gate de construcción de `facts`** (3b-2d, panel 2 cruce 4 · S5).
  *
- * - 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.
- * - Idempotente: re-ejecutar no duplica (onDuplicateWrites: Ignore).
- * - Las asignaciones ya expiradas se saltan (no tiene sentido copiarlas);
- *   las de expiración futura viajan con la condition `not_expired`.
+ * 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 async function importAuthzFactsToOpenFga(options) {
-    const client = new OpenFgaClient({
-        apiUrl: options.apiUrl,
-        storeId: options.storeId,
-        authorizationModelId: options.modelId,
-    });
-    const now = new Date();
-    const result = {
-        assignments: 0,
-        denies: 0,
-        skippedExpired: 0,
-        dryRun: options.dryRun ?? false,
-    };
-    const tuples = [];
-    const assignments = await db
-        .from('authz_assignments as a')
-        .join('authz_roles as r', 'r.uuid', 'a.role_uuid')
-        .select('a.holder_type', 'a.holder_uuid', 'a.scope_type', 'a.scope_uuid', 'a.expires_at')
-        .select('r.slug as role_slug');
-    const rowScope = (row) => ({
-        type: row.scope_type,
-        uuid: row.scope_uuid === APP_SCOPE_DB_UUID ? null : row.scope_uuid,
-    });
-    for (const row of assignments) {
-        const expiresAt = row.expires_at ? new Date(row.expires_at) : null;
-        if (expiresAt && expiresAt <= now) {
-            result.skippedExpired++;
-            continue;
-        }
-        const scope = rowScope(row);
-        const key = {
-            user: fgaSubjectWith({ type: row.holder_type, uuid: row.holder_uuid }, options.holderTypes),
-            relation: 'assignee',
-            object: `role_binding:${scopeKey(scope)}|${encodeSlug(row.role_slug)}`,
-        };
-        tuples.push(expiresAt
-            ? {
-                ...key,
-                condition: { name: 'not_expired', context: { valid_until: expiresAt.toISOString() } },
-            }
-            : key);
-        result.assignments++;
-    }
-    const denies = await db
-        .from('authz_denies as d')
-        .join('authz_permissions as p', 'p.uuid', 'd.permission_uuid')
-        .select('d.holder_type', 'd.holder_uuid', 'd.scope_type', 'd.scope_uuid')
-        .select('p.slug as permission_slug');
-    for (const row of denies) {
-        const scope = rowScope(row);
-        tuples.push({
-            user: fgaSubjectWith({ type: row.holder_type, uuid: row.holder_uuid }, options.holderTypes),
-            relation: 'denied',
-            object: `deny_binding:${scopeKey(scope)}|${encodeSlug(row.permission_slug)}`,
-        });
-        result.denies++;
-    }
-    if (!result.dryRun && tuples.length > 0) {
-        // Chunks: el write transaccional de FGA tiene límite de tuples por request.
-        for (let i = 0; i < tuples.length; i += 50) {
-            await client.writeTuples(tuples.slice(i, i + 50), {
-                conflict: { onDuplicateWrites: ClientWriteRequestOnDuplicateWrites.Ignore },
-            });
-        }
-    }
-    return result;
+export function assertScopeDriftGuarded(options) {
+    if (options.outbox)
+        return;
+    if (options.acceptScopeDriftRisk === true)
+        return;
+    throw new ScopeDriftUnguardedError('OpenFgaAuthorizationDriver necesita la outbox del árbol: pasa la misma ' +
+        "'scopes.outbox' del config (el manager encola ahí los cambios del árbol dentro de TU transacción y " +
+        "'authz:scopes:relay' los aplica). Sin ella, un rollback de tu transacción deja el árbol de FGA " +
+        'adelantado al tuyo y esa escalada no se ve desde tu base. Si mueves el árbol solo desde la ' +
+        "plataforma y lo asumes, dilo por escrito con acceptScopeDriftRisk: true.");
 }
+export const DEFAULT_TIMEOUT_MS = 5_000;
+/**
+ * Opciones de un `Write` que da por buena una tupla que ya estaba. Solo se
+ * usa donde el duplicado es IDÉNTICO por construcción (las aristas de (c2),
+ * que no llevan condición) o donde ya se sabe que la asignación no existe:
+ * en FGA la condición NO es parte de la clave, así que ignorar duplicados
+ * sobre una tupla con caducidad se quedaría la vieja (S7).
+ */
+const IGNORE_DUPLICATE_WRITES = {
+    conflict: { onDuplicateWrites: ClientWriteRequestOnDuplicateWrites.Ignore },
+};
+/**
+ * Vueltas que da el `grant` ante un choque de escritura antes de rendirse con
+ * un 409 (3b-2f · R3). Dos bastan para el caso real —la primera descubre que
+ * la estructura ya estaba, la segunda la da por buena—; la tercera es el
+ * margen para una contención de verdad.
+ */
+const GRANT_WRITE_ATTEMPTS = 3;
+/** Vueltas de relectura de una arista del árbol antes de decir 409 (3b-2h · 🟠 4). */
+const TREE_WRITE_ATTEMPTS = 3;
+/** Tope de operaciones por `Write` en FGA (verificado: `exceeded_entity_limit` a partir de 100). */
+const PURGE_BATCH_SIZE = 100;
+/** Tamaño de página de `Read` (máximo del servidor). */
+const READ_PAGE_SIZE = 100;
+/**
+ * El deny del modo `resolver` (≤ 2.2), que el modelo de hoy ni declara pero
+ * un store de aquella versión sí tiene: `enumerateFacts` lo EMITE como deny
+ * (3b-8 · A2) porque `reconcile` es el sustituto documentado del importador
+ * y perderlo en silencio rompía el invariante 2 con el verificador en verde.
+ */
+const LEGACY_DENY_BINDING_TYPE = 'deny_binding';
+const LEGACY_DENIED_RELATION = 'denied';
+/**
+ * Cota de páginas de una enumeración (1.000.000 de tuplas a 100 por página).
+ * Un `continuation_token` que no avanza —un servidor roto, un proxy o una
+ * caché delante— era un bucle infinito que ningún deadline cortaba, porque
+ * el deadline es por llamada (D12, auditor H7).
+ */
+export const MAX_READ_PAGES = 10_000;
+/**
+ * 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 const MAX_SCOPE_CHAIN_HOPS = 1_000;
 export class OpenFgaAuthorizationDriver {
+    /**
+     * 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() {
+        return Object.freeze({
+            hierarchyFacts: true,
+            singleCheckAuthorize: true,
+            roleInheritanceNative: false,
+            listObjectsInherited: false,
+            // 3b-2e · E4 / 3b-2j: purgar un rol y contar sus hechos necesitan
+            // enumerar sus bindings, y eso lo permiten las aristas de (c2)
+            // (`role_binding#role` y `scope#binding`).
+            purgeRole: true,
+            countRoleAssignments: true,
+            // 3b-2k · K1 · R2 (c): la decisión no pasa por el árbol, así que el
+            // objeto del store se compone con la ortografía del LLAMANTE y un alias
+            // del uuid no encuentra sus hechos (fail-CLOSED).
+            canonicalScopeReads: false,
+            // 3b-3b: sabe ser el ORIGEN de una migración — sus hechos son tuplas
+            // del store, y solo él sabe volverlas a `(holder, rol, scope)`.
+            enumerateFacts: true,
+        });
+    }
     client;
-    resolveAncestors;
+    chainResolver;
     holderTypes;
+    /**
+     * Contadores observables del driver. `unparseableBindings`: ids del store
+     * que el motor no entiende (L0.16). Cada uno es un hecho que las
+     * enumeraciones NO muestran; se registra y se cuenta, jamás un `continue`
+     * mudo — quien opera el store tiene que poder verlo.
+     */
+    diagnostics = { unparseableBindings: 0 };
+    logger;
+    timeoutMs;
+    consistency;
+    /** Reloj de pared del driver (J1): el ÚNICO `now` de checks, filtros y re-grant. */
+    now;
+    /**
+     * Memo del catálogo (2A): permisos, roles por nivel y roles que conceden
+     * cada permiso se leen de aquí en el camino caliente; antes eran dos
+     * consultas SQL por `authorize`. Los hechos siguen en FGA en cada pregunta.
+     * Se revalida contra `authz_catalog_version` (2D · F1): cada operación
+     * toma la foto UNA vez (`view()`) y lee de ella todo lo que necesita.
+     * `catalog.invalidate()` fuerza la recarga de ESTE memo.
+     */
+    catalog;
     constructor(options) {
+        assertHolderTypes(options.holderTypes);
+        assertCatalogOptions('OpenFgaAuthorizationDriver', options);
+        if (options.now !== undefined && !isClock(options.now)) {
+            throw new AuthorizationConfigError(`OpenFgaAuthorizationDriver: 'now' debe ser una función () => Date (llegó ${typeof options.now})`);
+        }
+        this.now = options.now ?? systemClock;
+        const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.catalog =
+            options.catalog ?? new CatalogCache({ driver: 'openfga', timeoutMs, revalidate: options.catalogRevalidate });
         this.client = guardBackendErrors(new OpenFgaClient({
             apiUrl: options.apiUrl,
             storeId: options.storeId,
             authorizationModelId: options.modelId,
-        }));
-        this.resolveAncestors =
-            options.resolveAncestors ??
-                (async (scope) => (scope.type === APP_SCOPE_TYPE ? [] : [APP_SCOPE]));
+            // `baseOptions` se funde en la config de axios de cada request: es la
+            // única vía del SDK (no tiene `timeoutMs` propio; su default es 10 s).
+            baseOptions: { timeout: timeoutMs },
+            // Sin reintentos a escondidas (ver `OpenFgaDriverOptions.retryParams`).
+            retryParams: { maxRetry: 0, ...options.retryParams },
+        }), timeoutMs);
+        // Sin resolutor solo existe la raíz (L0.3: el default plano desapareció).
+        this.chainResolver = options.resolveChain ?? rootOnlyResolver;
         this.holderTypes = options.holderTypes;
+        assertScopeDriftGuarded(options);
+        this.logger = options.logger ?? console;
+        this.timeoutMs = timeoutMs;
+        this.consistency =
+            options.consistency === 'minimize_latency'
+                ? ConsistencyPreference.MinimizeLatency
+                : ConsistencyPreference.HigherConsistency;
+    }
+    /**
+     * `[scope canónico, ...ancestros]`, o `null` si el scope no existe
+     * (lecturas: denegar). `chain[0]` —la fila del consumidor, no lo que
+     * escribió el llamante— es el scope que va en la clave de cada binding
+     * (2.5-B · K1): un alias del uuid que el árbol funde con la fila real
+     * llega aquí ya canónico y el `deny_binding` escrito canónico casa.
+     */
+    chain(scope, operation) {
+        return resolveChain(this.chainResolver, scope, operation);
+    }
+    /** La cadena o 422: una escritura no puede ir a un scope que nadie reconoce. */
+    knownScope(scope, operation) {
+        return assertKnownScope(this.chainResolver, scope, operation);
+    }
+    /** El scope canónico para `scopes.detached`/`purgeScope` (ver `canonicalScope`). */
+    canonicalOrSelf(scope, operation) {
+        return canonicalScope(this.chainResolver, scope, operation);
+    }
+    /** Los destinos de un delete de hechos (`revoke`/`removeDeny`): canónico, o el fan-out de alias (3b-8 · A4). */
+    canonicalTargets(scope, operation) {
+        return canonicalScopeTargets(this.chainResolver, scope, operation);
+    }
+    /**
+     * 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
+     * `AuthorizationManager.forRequest()` para leer con un resolutor memoizado
+     * sin tocar el driver compartido: hereda por prototipo y solo sobrescribe
+     * el resolutor.
+     */
+    withChainResolver(resolveChain) {
+        const view = Object.create(this);
+        view.chainResolver = resolveChain;
+        return view;
+    }
+    /**
+     * Vista de este driver con OTRO reloj de pared (2.5 · J1): mismo cliente,
+     * store, memo y resolutor; solo cambia el `now` que viaja como
+     * `current_time` y filtra las enumeraciones. Lo aplica el manager con
+     * `config.clock` y el juez para fijar el instante.
+     */
+    withClock(now) {
+        if (!isClock(now)) {
+            throw new AuthorizationConfigError(`withClock: now debe ser una función () => Date (llegó ${typeof now})`);
+        }
+        const view = Object.create(this);
+        view.now = now;
+        return view;
+    }
+    /**
+     * El `context` de los checks de UNA operación, con el reloj de ESTE driver
+     * (o vista): se construye una vez por operación y viaja en todos sus
+     * checks (2.5-B · K9). Antes se leía el reloj por check y un mismo
+     * `authorize` evaluaba el deny en un instante y el rol en otro.
+     */
+    checkContext() {
+        return checkContext(this.now());
     }
-    async chain(scope) {
-        return [scope, ...(await this.resolveAncestors(scope))];
+    /**
+     * Consulta al catálogo local clasificando su fallo. Con este driver el
+     * catálogo SQL sigue siendo una dependencia dura de cada pregunta: su caída
+     * era un error crudo de Lucid que se presentaba como bug de aplicación (N3).
+     */
+    sql(operation, fn) {
+        return guardSql('openfga', operation, this.timeoutMs, fn);
     }
     fgaSubject(subject) {
         return fgaSubjectWith(subject, this.holderTypes);
     }
     /**
-     * batchCheck troceado al límite del servidor FGA (50 checks/request) y con
-     * verificación de completitud: TODOS los checks deben volver respondidos.
+     * Un batchCheck con TODOS los checks (el SDK trocea a 50 por request y
+     * paraleliza), cada uno con un `correlationId` propio, y la respuesta
+     * alineada por ese id: un resultado por check, ni uno más ni uno menos.
      */
     async batchCheckAll(checks) {
-        const results = [];
-        for (let i = 0; i < checks.length; i += 50) {
-            const slice = checks.slice(i, i + 50);
-            const response = await this.client.batchCheck({ checks: slice });
-            results.push(...response.result);
-        }
-        if (results.length !== checks.length) {
-            throw new Exception('OpenFGA batchCheck devolvió menos resultados que checks', {
-                status: 500,
-            });
+        if (checks.length === 0)
+            return [];
+        const withIds = checks.map((check, index) => ({
+            ...check,
+            correlationId: String(index),
+        }));
+        const response = await this.client.batchCheck({ checks: withIds }, { consistency: this.consistency });
+        const results = correlateBatchResults(withIds, response.result);
+        // Un 200 con `error` en un check individual (`input_error`,
+        // `internal_error`…) es una caída parcial del backend, no un "sin
+        // permiso": se clasifica igual que un 5xx (invariante 5, D1). Antes la
+        // fase de roles y `hasRole` lo colapsaban en `false`.
+        const failed = results.find((r) => r.error);
+        if (failed) {
+            throw new AuthorizationBackendError('openfga', `batchCheck (${failed.request?.relation} ${failed.request?.object})`, failed.error);
         }
         return results;
     }
-    // ── Catálogo local (compartido entre drivers) ─────────────────────────
+    // ── Catálogo local (compartido entre drivers), desde el memo (2A) ──────
+    // Una carga por driver/proceso en vez de una o dos consultas SQL por
+    // pregunta, más una revalidación por operación (2D · F1). Un fallo de
+    // carga sale como 503, igual que antes.
     async findPermission(slug) {
-        return db.from('authz_permissions').where('slug', slug).select('uuid').first();
-    }
-    async findRoleOrFail(slug, scopeType) {
-        const role = await db
-            .from('authz_roles')
-            .where('slug', slug)
-            .where('scope_type', scopeType)
-            .select('uuid')
-            .first();
-        if (!role) {
-            throw new Exception(`Rol '${slug}' no existe en el catálogo para el nivel '${scopeType}'`, {
-                status: 422,
-            });
-        }
+        return (await this.catalog.view()).permission(slug);
     }
-    /** Roles del catálogo que conceden el permiso, agrupados por scope_type. */
-    async rolesGranting(permissionUuid) {
-        const rows = await db
-            .from('authz_role_permissions as rp')
-            .join('authz_roles as r', 'r.uuid', 'rp.role_uuid')
-            .where('rp.permission_uuid', permissionUuid)
-            .select('r.slug', 'r.scope_type');
-        const byScopeType = new Map();
-        for (const row of rows) {
-            const list = byScopeType.get(row.scope_type) ?? [];
-            list.push(row.slug);
-            byScopeType.set(row.scope_type, list);
-        }
-        return byScopeType;
+    /**
+     * Filtro por catálogo de las lecturas de membresía (`listRoles`,
+     * `listRoleScopes`, `rolesInChain`, `listScopes`): un binding cuyo uuid ya
+     * no está en `authz_roles` —o está, pero declarado para OTRO nivel, o es
+     * local a un scope que no está en la cadena del binding (3B · B2)— es una
+     * tupla huérfana, no una membresía; igual que en `database`, donde el
+     * catálogo lo excluye (D5). La tupla la recoge `authz:reconcile`. Desde 3A
+     * la resolución es por uuid (`roleByUuid`), nunca por slug. `chainKeys` es
+     * la cadena del scope del BINDING (desde él hacia la raíz).
+     */
+    declaredRole(catalog, binding, chainKeys) {
+        return declaredRoleAt(catalog, binding.uuid, binding.scope.type, chainKeys);
     }
     // ── Contrato ──────────────────────────────────────────────────────────
     async authorize(subject, permission, scope) {
-        const perm = await this.findPermission(permission);
+        assertIdentity({ subject, permission, scope });
+        // Una foto del catálogo por pregunta: el permiso sale de la misma versión
+        // (y se paga una sola revalidación). Es lo ÚNICO local que queda.
+        const catalog = await this.catalog.view();
+        const perm = catalog.permission(permission);
         if (!perm)
             return false;
-        const user = this.fgaSubject(subject);
-        const chain = await this.chain(scope);
-        // 1. Denies en la cadena. FAIL-CLOSED: un check de deny con error se
-        //    trata como denegado (jamás se ignora un deny por un fallo puntual).
-        const denyChecks = chain.map((s) => ({
-            user,
-            relation: 'denied',
-            object: `deny_binding:${scopeKey(s)}|${encodeSlug(permission)}`,
-        }));
-        const denyResults = await this.batchCheckAll(denyChecks);
-        if (denyResults.some((r) => r.allowed || r.error))
-            return false;
-        // 2. Alguna asignación vigente en la cadena cuyo rol concede el permiso.
-        //    Aquí un error individual falla cerrado por sí solo (no concede).
-        const granting = await this.rolesGranting(perm.uuid);
-        const checks = chain.flatMap((s) => (granting.get(s.type) ?? []).map((roleSlug) => ({
+        // La jerarquía, el catálogo y los denies ya están en el store, así que la
+        // pregunta entera cabe en UN `Check` (3b-2c). Hasta 3b-2k había además un
+        // modo `resolver` que expandía la cadena del consumidor a un `batchCheck`
+        // de N×M: se borró con él.
+        return this.factsAuthorize(this.fgaSubject(subject), permission, scope);
+    }
+    /**
+     * **`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.
+     */
+    async factsAuthorize(user, permission, scope) {
+        const response = await this.client.check({
             user,
-            relation: 'assignee',
-            object: `role_binding:${scopeKey(s)}|${encodeSlug(roleSlug)}`,
-            context: checkContext(),
-        })));
-        if (checks.length === 0)
-            return false;
-        const results = await this.batchCheckAll(checks);
-        return results.some((r) => r.allowed && !r.error);
+            relation: factsRelationsOf(permission).can,
+            object: factsScopeObject(scopeKey(scope)),
+            context: this.checkContext(),
+        }, { consistency: this.consistency });
+        return response.allowed === true;
+    }
+    /**
+     * `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
+     * atribuyen a su scope por posición dentro del lote correlacionado
+     * (L0.14). Misma regla que `authorize`, por scope: `error` en cualquier
+     * check ⇒ 503 entero (D1); deny `allowed` ⇒ false; rol `allowed` ⇒ true.
+     * Scope desconocido o sin rol que conceda ⇒ false sin checks.
+     */
+    async authorizeMany(subject, permission, scopes) {
+        assertIdentity({ subject, permission });
+        for (const scope of scopes)
+            assertIdentity({ scope });
+        if (scopes.length === 0)
+            return [];
+        const catalog = await this.catalog.view();
+        const perm = catalog.permission(permission);
+        if (!perm)
+            return scopes.map(() => false);
+        // UN `batchCheck` con UN item por scope —no el N×M de la cadena por el
+        // catálogo del modo `resolver`, borrado en 3b-2k—, y un scope repetido
+        // comparte item.
+        return this.factsAuthorizeMany(this.fgaSubject(subject), permission, scopes);
+    }
+    /**
+     * `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`.
+     */
+    async factsAuthorizeMany(user, permission, scopes) {
+        const relation = factsRelationsOf(permission).can;
+        // Un instante para todo el lote (K9): N scopes, una pregunta.
+        const context = this.checkContext();
+        const batch = [];
+        const itemByScope = new Map();
+        const slots = [];
+        for (const scope of scopes) {
+            const id = scopeKey(scope);
+            let item = itemByScope.get(id);
+            if (item === undefined) {
+                item = batch.length;
+                batch.push({ user, relation, object: factsScopeObject(id), context });
+                itemByScope.set(id, item);
+            }
+            slots.push(item);
+        }
+        const results = await this.batchCheckAll(batch);
+        return slots.map((item) => results[item].allowed === true);
     }
     async grant(subject, role, scope, options = {}) {
-        await this.findRoleOrFail(role, scope.type);
+        assertIdentity({ subject, role, scope, expiresAt: options.expiresAt });
+        // El binding lleva la identidad canónica del árbol (K1), nunca la forma
+        // del llamante, y el uuid del rol, nunca su slug (3A · A1). El rol tiene
+        // que EXISTIR en ese scope (3B · B2: global, o local a un ancestro-o-igual)
+        // con una composición legal (B5).
+        const chain = await this.knownScope(scope, 'grant');
+        const [target] = chain;
+        const catalog = await this.catalog.view();
+        const declared = resolveRoleQuery(catalog, role, target, chainKeysFrom(chain)[0]);
+        assertRoleAssignableAt(catalog, declared);
+        const roleUuid = declared.uuid;
         const key = {
             user: this.fgaSubject(subject),
             relation: 'assignee',
-            object: `role_binding:${scopeKey(scope)}|${encodeSlug(role)}`,
+            object: `role_binding:${scopeKey(target)}|${roleUuid}`,
         };
-        const write = options.expiresAt
+        // **La forma nueva de los objetos (3b-2c), en UNA sola escritura
+        // (3b-2f · R3).** En (c2) la asignación no es alcanzable con el
+        // `assignee` a secas: el binding tiene que colgar del scope
+        // (`scope#binding`) y apuntar a su rol (`role_binding#role`). Son
+        // ESTRUCTURA —no llevan caducidad ni dicen quién está asignado, así que
+        // sin `assignee` no conceden nada—, pero mandarlas en un `Write` aparte
+        // (como hacía el 2c) hacía del `grant` una escritura NO atómica: contra
+        // un `purgeScope` concurrente quedaba el `assignee` sin su arista, y
+        // entonces `listRoles`/`hasRole` decían que la asignación existe y
+        // `authorize` que no concede — dos lecturas contradiciéndose sobre el
+        // mismo hecho, que es peor que perder la escritura. Ahora las TRES van
+        // en el mismo `Write` (transaccional en FGA): o están las tres o no está
+        // ninguna.
+        const structure = factsBindingTuples(scopeKey(target), roleUuid);
+        /** El write COMPLETO de una asignación: su estructura y ella. */
+        const writeSet = (tuple) => [...structure, tuple];
+        const tupleFor = (expiresAt) => expiresAt
             ? {
                 ...key,
                 condition: {
                     name: 'not_expired',
-                    context: { valid_until: options.expiresAt.toISOString() },
+                    context: { valid_until: expiresAt.toISOString() },
                 },
             }
             : key;
         // FGA no admite delete+write de la misma tuple key en una transacción, así
-        // que refrescar la expiración obliga a dos llamadas — y entre ellas hay un
+        // que cambiar la expiración obliga a dos llamadas — y entre ellas hay un
         // instante en el que authorize() responde false.
         //
         // Se mira primero qué hay, para NO pagar esa ventana cuando no hace falta:
         //  - si no existe la tuple → solo write (el caso del primer grant);
-        //  - si existe idéntica → no-op (re-ejecutar un seeder no toca nada);
-        //  - solo si la expiración CAMBIA de verdad se hace delete+write.
-        // La ventana pasa de "cada re-grant" a "cuando el llamante quiso cambiarla".
+        //  - si existe con la caducidad que toca → no-op (un seeder no toca nada);
+        //  - solo si la caducidad CAMBIA de verdad se hace delete+write.
+        // Y la lectura es lo que hace posible "omitido = preservar" (L0.4).
         const current = await this.readAssignment(key);
-        // Solo se salta la escritura si SABEMOS que lo almacenado ya es esto.
-        if (current.kind === 'present' && sameExpiry(current.validUntil, options.expiresAt))
-            return;
-        if (current.kind === 'absent') {
-            // No había nada: un write basta y no hay ventana de denegación. Si entre
-            // el read y el write otro proceso escribió la misma key, este write
-            // choca — y entonces sí toca el camino largo, para que gane el último
-            // escritor y no se pierda esta expiración en silencio.
+        if (current.kind === 'unknown') {
+            // Sin lectura no hay forma de preservar una caducidad vigente: asumir
+            // "permanente" sería exactamente el defecto en modo degradado. Con un
+            // objetivo explícito (`Date`/`null`) sí se puede escribir a ciegas.
+            if (options.expiresAt === undefined)
+                throw withPreserveRecipe(current.error);
+            const expiresAt = options.expiresAt;
+            const existed = await this.writeAssignment(key, tupleFor(expiresAt), structure);
+            return { existed, expiresAt };
+        }
+        if (current.kind === 'present') {
+            const expiresAt = resolveGrantExpiry(current.validUntil, options.expiresAt, this.now());
+            if (sameInstant(current.validUntil, expiresAt)) {
+                return { existed: true, previousExpiresAt: current.validUntil, expiresAt };
+            }
+            await this.replaceAssignment(key, tupleFor(expiresAt), structure);
+            return { existed: true, previousExpiresAt: current.validUntil, expiresAt };
+        }
+        // No había nada: un write basta y no hay ventana de denegación. Ese write
+        // puede chocar por DOS motivos distintos, y la diferencia importa
+        // (D6 + 3b-2f · R3):
+        //
+        //  - la ASIGNACIÓN ya existe — otro proceso la escribió entre el read y
+        //    el write, o dos `grant` simultáneos —: se relee y se re-aplica sobre
+        //    lo que quedó, para que gane el último escritor y no se pierda esta
+        //    caducidad;
+        //  - la ESTRUCTURA ya estaba — otro holder con el mismo rol en el mismo
+        //    scope, que es el caso más común que hay — o la escribió otro `grant`
+        //    a la vez: la asignación sigue sin existir, así que se repite el
+        //    MISMO write ignorando duplicados (las aristas no llevan condición,
+        //    así que un duplicado suyo es idéntico por construcción). Sigue
+        //    siendo UNA escritura y sigue siendo atómica.
+        //
+        // Cuál de los dos fue lo dice la RELECTURA, no el error: el conflicto
+        // transaccional de FGA (`Aborted`, HTTP 409) no nombra ninguna tupla.
+        // Cualquier otro fallo del write no es una carrera y se propaga (D6); y
+        // una contención que no cede en `GRANT_WRITE_ATTEMPTS` vueltas sale como
+        // 409 —el estado del destino no es el que esta escritura esperaba—,
+        // jamás como un 503 "el backend no respondió", porque respondió.
+        //
+        // El límite honesto: si entre la relectura y el write con `Ignore` un
+        // tercero escribe la asignación, la suya se queda y esta se pierde en
+        // silencio (FGA no tiene un compare-and-set). Es la misma ventana que ya
+        // tenía el `replace`, estrechada a dos llamadas seguidas.
+        const expiresAt = options.expiresAt ?? null;
+        for (let attempt = 0;; attempt++) {
             try {
-                await this.client.writeTuples([write]);
-                return;
+                await this.client.writeTuples(writeSet(tupleFor(expiresAt)), attempt === 0 ? undefined : IGNORE_DUPLICATE_WRITES);
+                return { existed: false, expiresAt };
             }
-            catch {
-                // cae al delete+write de abajo
+            catch (error) {
+                if (!isDuplicateWrite(error))
+                    throw error;
+                if (attempt >= GRANT_WRITE_ATTEMPTS - 1) {
+                    throw new WriteConflictError(`grant: ${GRANT_WRITE_ATTEMPTS} intentos y el store sigue en conflicto sobre ` +
+                        `${key.object}. Reintenta la escritura.`, { cause: error });
+                }
+                const raced = await this.readAssignment(key);
+                if (raced.kind === 'present') {
+                    const target = resolveGrantExpiry(raced.validUntil, options.expiresAt, this.now());
+                    if (!sameInstant(raced.validUntil, target)) {
+                        await this.replaceAssignment(key, tupleFor(target), structure);
+                    }
+                    return { existed: true, previousExpiresAt: raced.validUntil, expiresAt: target };
+                }
+                if (raced.kind === 'unknown') {
+                    // La relectura FALLÓ: sin objetivo explícito no se sabe qué
+                    // preservar, y el error de lectura va como causa.
+                    if (options.expiresAt === undefined)
+                        throw withPreserveRecipe(raced.error);
+                    const existed = await this.writeAssignment(key, tupleFor(options.expiresAt), structure);
+                    return { existed, expiresAt: options.expiresAt };
+                }
+                // `absent` con estructura: el choque fue de las aristas, que las
+                // comparten todos los holders del mismo rol en el mismo scope. Otra
+                // vuelta, esta vez dándolas por buenas.
             }
         }
+    }
+    /**
+     * 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).
+     */
+    async writeAssignment(key, tuple, structure = []) {
+        try {
+            await this.client.writeTuples([...structure, tuple]);
+            return false;
+        }
+        catch (error) {
+            if (!isDuplicateWrite(error))
+                throw error;
+            // Sin estructura el duplicado solo puede ser la asignación; con ella
+            // puede ser una arista compartida, y entonces quién existía lo dice la
+            // relectura y no el error.
+            const existed = structure.length ? (await this.readAssignment(key)).kind !== 'absent' : true;
+            await this.replaceAssignment(key, tuple, structure);
+            return existed;
+        }
+    }
+    /**
+     * 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).
+     */
+    async replaceAssignment(key, tuple, structure = []) {
         await this.client.deleteTuples([key], {
             conflict: { onMissingDeletes: ClientWriteRequestOnMissingDeletes.Ignore },
         });
-        await this.client.writeTuples([write], {
-            conflict: { onDuplicateWrites: ClientWriteRequestOnDuplicateWrites.Ignore },
-        });
+        await this.client.writeTuples([...structure, tuple], IGNORE_DUPLICATE_WRITES);
     }
     /**
      * Estado actual de una asignación, con TRES resultados posibles y no dos.
      *
      * Distinguir `unknown` de `present` sin condición es lo que impide un bug
      * feo: si un fallo de lectura se pareciera a "existe y sin expiración", un
-     * grant sin expiración saldría por el atajo del no-op y se perdería —
-     * mientras el hook onWrite ya habría auditado que se concedió.
+     * grant sin expiración saldría por el atajo del no-op y se perdería. El
+     * error de lectura (ya clasificado como 503) viaja con el resultado para
+     * que quien no pueda seguir sin él lo propague.
      */
     async readAssignment(key) {
         try {
-            const response = await this.client.read(key);
+            const response = await this.client.read(key, { consistency: this.consistency });
             const tuple = response.tuples?.[0];
             if (!tuple)
                 return { kind: 'absent' };
             const validUntil = tuple.key?.condition?.context?.valid_until;
-            return { kind: 'present', validUntil: validUntil ? String(validUntil) : undefined };
+            return { kind: 'present', validUntil: toExpiryDate(validUntil) };
         }
-        catch {
-            // No se pudo leer: se asume lo peor y se toma el camino largo, que
-            // funciona exista o no la tuple.
-            return { kind: 'unknown' };
+        catch (error) {
+            return { kind: 'unknown', error };
         }
     }
     async revoke(subject, role, scope) {
-        await this.client.deleteTuples([
-            {
-                user: this.fgaSubject(subject),
-                relation: 'assignee',
-                object: `role_binding:${scopeKey(scope)}|${encodeSlug(role)}`,
-            },
-        ], { conflict: { onMissingDeletes: ClientWriteRequestOnMissingDeletes.Ignore } });
+        assertIdentity({ subject, role, scope });
+        // Rol fuera del catálogo para ese nivel ⇒ 422, como en `grant` (D10). Se
+        // quitan los bindings de TODOS los roles con ese nombre en el scope
+        // exacto (3B): a lo sumo uno es visible ahí; quitar nunca concede.
+        const named = rolesToRevoke(await this.catalog.view(), role, scope);
+        // Sin cadena, TODAS las ortografías de las que el uuid puede ser alias
+        // (3b-8 · A4): con una sola, el alias hacía del delete un no-op
+        // silencioso (`onMissingDeletes: Ignore`) y el hecho canónico seguía ahí.
+        const targets = await this.canonicalTargets(scope, 'revoke');
+        const user = this.fgaSubject(subject);
+        await this.client.deleteTuples(targets.flatMap((target) => named.map((r) => ({ user, relation: 'assignee', object: `role_binding:${scopeKey(target)}|${r.uuid}` }))), { conflict: { onMissingDeletes: ClientWriteRequestOnMissingDeletes.Ignore } });
     }
     async hasRole(subject, role, scope) {
+        assertIdentity({ subject, role, scope });
         const user = this.fgaSubject(subject);
-        const chain = await this.chain(scope);
-        const results = await this.batchCheckAll(chain.map((s) => ({
+        const chain = await this.chain(scope, 'hasRole');
+        if (!chain)
+            return false;
+        // El id del binding lleva el scope (y con él su tipo) y el UUID del rol
+        // que el catálogo declara con ese slug para el tipo de ESE nivel (3A):
+        // en cada nivel solo casa el rol de ese nivel. Con `{ slug, scopeType }`
+        // se recorta la cadena a los niveles de ese tipo (L0.6). Y solo se
+        // pregunta por los niveles para los que el catálogo declara el rol (D5):
+        // un rol retirado no es membresía aunque su tupla siga en el store.
+        const catalog = await this.catalog.view();
+        const targets = hasRoleTargets(catalog, role, chain);
+        if (targets.length === 0)
+            return false;
+        const context = this.checkContext();
+        const results = await this.batchCheckAll(targets.map(({ scope: s, roleUuid }) => ({
             user,
             relation: 'assignee',
-            object: `role_binding:${scopeKey(s)}|${encodeSlug(role)}`,
-            context: checkContext(),
+            object: `role_binding:${scopeKey(s)}|${roleUuid}`,
+            context,
         })));
-        return results.some((r) => r.allowed && !r.error);
+        return results.some((r) => r.allowed);
     }
     async deny(subject, permission, scope) {
+        assertIdentity({ subject, permission, scope });
         const perm = await this.findPermission(permission);
-        if (!perm) {
-            throw new Exception(`Permiso '${permission}' no existe en el catálogo`, { status: 422 });
-        }
-        await this.client.writeTuples([
-            {
-                user: this.fgaSubject(subject),
-                relation: 'denied',
-                object: `deny_binding:${scopeKey(scope)}|${encodeSlug(permission)}`,
-            },
-        ], { conflict: { onDuplicateWrites: ClientWriteRequestOnDuplicateWrites.Ignore } });
+        if (!perm)
+            throw new UnknownPermissionError(permission);
+        const [target] = await this.knownScope(scope, 'deny');
+        await this.client.writeTuples([this.denyTuple(subject, permission, target)], {
+            conflict: { onDuplicateWrites: ClientWriteRequestOnDuplicateWrites.Ignore },
+        });
     }
     async removeDeny(subject, permission, scope) {
-        await this.client.deleteTuples([
-            {
-                user: this.fgaSubject(subject),
-                relation: 'denied',
-                object: `deny_binding:${scopeKey(scope)}|${encodeSlug(permission)}`,
-            },
-        ], { conflict: { onMissingDeletes: ClientWriteRequestOnMissingDeletes.Ignore } });
+        assertIdentity({ subject, permission, scope });
+        const perm = await this.findPermission(permission);
+        if (!perm)
+            throw new UnknownPermissionError(permission);
+        // Mismo fan-out que `revoke` (3b-8 · A4): quitar un deny de menos por un
+        // alias sería un deny fantasma que nadie puede levantar.
+        const targets = await this.canonicalTargets(scope, 'removeDeny');
+        await this.client.deleteTuples(targets.map((target) => this.denyTuple(subject, permission, target)), { conflict: { onMissingDeletes: ClientWriteRequestOnMissingDeletes.Ignore } });
     }
+    /**
+     * 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.
+     */
+    denyTuple(subject, permission, target) {
+        const user = this.fgaSubject(subject);
+        return factsDenyTuple(scopeKey(target), permission, user);
+    }
+    /**
+     * Holders con asignación vigente del rol en el scope exacto: `Read` por
+     * objeto exacto, paginado, con la caducidad filtrada en cliente. Antes era
+     * `ListUsers`, que trunca al tope del servidor sin señal (L0.7).
+     */
     async listSubjects(role, scope) {
-        // ListUsers exige EXACTAMENTE un user_filter → una consulta por tipo.
-        const results = [];
+        assertIdentity({ role, scope });
+        // Un rol que el catálogo no declara para ese nivel (en ningún owner) no
+        // tiene holders (D5): nada que leer, ni árbol ni store. Un scope que el
+        // árbol no conoce no existe para el motor (D8, K1): nada; uno que conoce
+        // se lee bajo su identidad canónica, y el rol tiene que existir AHÍ (3B ·
+        // B2); el que existe se lee por su uuid (3A).
+        const catalog = await this.catalog.view();
+        const asked = normalizeRoleQuery(role);
+        if (asked.uuid !== undefined ? catalog.roleByUuid(asked.uuid) === null : catalog.rolesNamed(asked.slug, asked.scopeType ?? scope.type).length === 0) {
+            return [];
+        }
+        const chain = await this.chain(scope, 'listSubjects');
+        if (!chain)
+            return [];
+        const declared = visibleRoleFor(catalog, asked, scope, chainKeysFrom(chain)[0]);
+        if (!declared)
+            return [];
         const fgaToMorph = Object.fromEntries(Object.entries(this.holderTypes).map(([morph, fga]) => [fga, morph]));
-        for (const fgaType of [...new Set(Object.values(this.holderTypes))]) {
-            const response = await this.client.listUsers({
-                object: { type: 'role_binding', id: `${scopeKey(scope)}|${encodeSlug(role)}` },
-                relation: 'assignee',
-                user_filters: [{ type: fgaType }],
-                context: checkContext(),
-            });
-            for (const u of response.users ?? []) {
-                if (u.object) {
-                    results.push({ type: fgaToMorph[u.object.type] ?? u.object.type, uuid: u.object.id });
-                }
+        const tuples = await this.readAllTuples({
+            relation: 'assignee',
+            object: `role_binding:${scopeKey(chain[0])}|${declared.uuid}`,
+        });
+        const results = [];
+        for (const tuple of tuples) {
+            // `<tipoFga>:<uuid>`; un userset (`#`) o un tipo que no está en el mapa
+            // no es un holder que este driver haya escrito.
+            const separator = tuple.user.indexOf(':');
+            const fgaType = separator > 0 ? tuple.user.slice(0, separator) : '';
+            const uuid = separator > 0 ? tuple.user.slice(separator + 1) : '';
+            const morph = fgaToMorph[fgaType];
+            if (!morph || !uuid || uuid.includes('#')) {
+                this.diagnostics.unparseableBindings += 1;
+                this.warn(`authz(openfga): el user '${tuple.user}' de '${tuple.object}' no es un holder del motor; se ignora en la enumeración (total: ${this.diagnostics.unparseableBindings})`);
+                continue;
             }
+            results.push({ type: morph, uuid });
         }
         return results;
     }
-    /** role_binding ids del subject (asignaciones directas vigentes). */
-    async listBindings(subject) {
-        const response = await this.client.listObjects({
+    /**
+     * Bindings del subject ya parseados (asignaciones directas vigentes). Los
+     * ids que no se entienden se registran y se cuentan, no se descartan.
+     */
+    async listBindings(subject, at) {
+        const tuples = await this.readAllTuples({
             user: this.fgaSubject(subject),
             relation: 'assignee',
-            type: 'role_binding',
-            context: checkContext(),
-        });
-        return (response.objects ?? []).map((obj) => obj.replace(/^role_binding:/, ''));
+            object: 'role_binding:',
+        }, { at });
+        return this.parseBindings('role_binding', tuples.map((t) => t.object));
+    }
+    /** Scopes (por clave) donde el subject tiene un deny directo del permiso (por su uuid). */
+    async deniedScopeKeys(subject, permissionUuid, at) {
+        // El deny es una relación DEL SCOPE: se pide por esa relación exacta y la
+        // lectura devuelve ya solo los denies de ESTE permiso (una request, sin
+        // filtrar en cliente). Un permiso que el catálogo ya no declara no tiene
+        // relación que leer: sin denies (D5).
+        const slug = (await this.catalog.view()).permissionSlug(permissionUuid);
+        if (!slug)
+            return new Set();
+        const tuples = await this.readAllTuples({
+            user: this.fgaSubject(subject),
+            relation: factsRelationsOf(slug).denied,
+            object: `${FACTS_SCOPE_TYPE}:`,
+        }, { at });
+        return new Set(tuples.map((t) => t.object.slice(FACTS_SCOPE_TYPE.length + 1)));
+    }
+    /**
+     * 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).
+     */
+    async factsDenies(subject, catalog, at) {
+        const permissionByRelation = new Map();
+        for (const slug of catalog.permissionSlugs) {
+            permissionByRelation.set(factsRelationsOf(slug).denied, slug);
+        }
+        const tuples = await this.readAllTuples({ user: this.fgaSubject(subject), object: `${FACTS_SCOPE_TYPE}:` }, { at });
+        const denies = [];
+        for (const tuple of tuples) {
+            if (!tuple.relation.startsWith(FACTS_DENIED_PREFIX))
+                continue;
+            const permission = permissionByRelation.get(tuple.relation);
+            if (!permission)
+                continue;
+            const scope = scopeFromKey(tuple.object.slice(FACTS_SCOPE_TYPE.length + 1));
+            if (!scope) {
+                this.diagnostics.unparseableBindings += 1;
+                this.warn(`authz(openfga): el objeto '${tuple.object}' de un deny no tiene la forma de un scope del motor; se ignora en la enumeración (total: ${this.diagnostics.unparseableBindings})`);
+                continue;
+            }
+            denies.push({ scope, permission });
+        }
+        return denies;
+    }
+    parseBindings(type, objects) {
+        const parsed = [];
+        for (const obj of objects) {
+            const id = obj.replace(new RegExp(`^${type}:`), '');
+            const binding = parseBindingId(id);
+            if (binding) {
+                parsed.push(binding);
+            }
+            else {
+                this.diagnostics.unparseableBindings += 1;
+                this.warn(`authz(openfga): binding '${type}:${id}' no tiene la forma del motor; se ignora en la enumeración (total: ${this.diagnostics.unparseableBindings})`);
+            }
+        }
+        return parsed;
+    }
+    warn(message) {
+        this.logger.warn(message);
     }
     async listRoles(subject, scope) {
-        const prefix = scopeKey(scope);
+        assertIdentity({ subject, scope });
+        // Un scope que el árbol no conoce no existe para el motor (D8): nada.
+        const chain = await this.chain(scope, 'listRoles');
+        if (!chain)
+            return [];
+        const prefix = scopeKey(chain[0]);
+        const keys = chainKeysFrom(chain)[0];
+        const catalog = await this.catalog.view();
         const roles = new Set();
-        for (const id of await this.listBindings(subject)) {
-            const parsed = parseBindingId(id);
-            if (parsed && scopeKey(parsed.scope) === prefix)
-                roles.add(parsed.slug);
+        for (const binding of await this.listBindings(subject)) {
+            if (scopeKey(binding.scope) !== prefix)
+                continue;
+            const declared = this.declaredRole(catalog, binding, keys);
+            if (declared)
+                roles.add(declared.slug);
         }
         return [...roles];
     }
+    /**
+     * Roles directos vigentes del holder en cada scope de la cadena (2D · G5):
+     * UNA lectura (`Read` paginado de sus bindings) agrupada por scope, en vez
+     * de un `listRoles` por nivel. Solo roles que el catálogo declara para ese
+     * nivel (D5). La cadena viene ya resuelta por el manager.
+     */
+    async rolesInChain(subject, chain) {
+        assertIdentity({ subject });
+        for (const scope of chain)
+            assertScope(scope);
+        if (chain.length === 0)
+            return [];
+        const catalog = await this.catalog.view();
+        const keysFrom = chainKeysFrom(chain);
+        const wanted = new Map(chain.map((s, i) => [scopeKey(s), { scope: s, keys: keysFrom[i] }]));
+        const seen = new Set();
+        const result = [];
+        for (const binding of await this.listBindings(subject)) {
+            const id = scopeKey(binding.scope);
+            const level = wanted.get(id);
+            if (!level)
+                continue;
+            const scope = level.scope;
+            const declared = this.declaredRole(catalog, binding, level.keys);
+            if (!declared)
+                continue;
+            // Dedupe por IDENTIDAD (3D · M1: el uuid, no el slug).
+            const dedupe = `${id}\u001f${declared.uuid}`;
+            if (seen.has(dedupe))
+                continue;
+            seen.add(dedupe);
+            result.push({ scope, role: declared });
+        }
+        return result;
+    }
     async listRoleScopes(subject, scopeType) {
-        const seen = new Map();
-        for (const id of await this.listBindings(subject)) {
-            const parsed = parseBindingId(id);
-            if (parsed && parsed.scope.type === scopeType) {
-                seen.set(scopeKey(parsed.scope), parsed.scope);
-            }
+        assertIdentity({ subject, scopeType });
+        const catalog = await this.catalog.view();
+        const byScope = new Map();
+        for (const binding of await this.listBindings(subject)) {
+            if (binding.scope.type !== scopeType)
+                continue;
+            const k = scopeKey(binding.scope);
+            if (!byScope.has(k))
+                byScope.set(k, { scope: binding.scope, bindings: [] });
+            byScope.get(k).bindings.push(binding);
+        }
+        // Los scopes que el árbol ya no conoce no se listan (D8): una consulta
+        // al resolutor por scope, el mismo coste que `listScopes`. Y con la
+        // cadena se decide si alguno de sus roles existe ahí (D5, 3B · B2).
+        const known = [];
+        for (const { scope, bindings } of byScope.values()) {
+            const chain = await this.chain(scope, 'listRoleScopes');
+            if (!chain)
+                continue;
+            const keys = chainKeysFrom(chain)[0];
+            if (bindings.some((b) => this.declaredRole(catalog, b, keys)))
+                known.push(scope);
         }
-        return [...seen.values()];
+        return known;
     }
     async listScopes(subject, permission) {
-        const perm = await this.findPermission(permission);
+        assertIdentity({ subject, permission });
+        const catalog = await this.catalog.view();
+        const perm = catalog.permission(permission);
         if (!perm)
             return [];
-        const granting = await this.rolesGranting(perm.uuid);
-        // Denies del subject para este permiso (una sola consulta).
-        const denyResponse = await this.client.listObjects({
-            user: this.fgaSubject(subject),
-            relation: 'denied',
-            type: 'deny_binding',
-        });
-        const deniedKeys = new Set((denyResponse.objects ?? [])
-            .map((obj) => obj.replace(/^deny_binding:/, ''))
-            .map((id) => parseBindingId(id))
-            .filter((p) => Boolean(p && p.slug === permission))
-            .map((p) => scopeKey(p.scope)));
+        const granting = catalog.rolesGranting(perm.uuid);
+        // Denies directos del subject para este permiso: TODOS, paginando. Con
+        // `ListObjects` el tope del servidor se consumía con los denies de
+        // cualquier permiso y el relevante podía quedar fuera: fail-open (L0.7).
+        // Las dos lecturas filtran la caducidad con el MISMO instante (K9).
+        const at = this.now();
+        const deniedKeys = await this.deniedScopeKeys(subject, perm.uuid, at);
         const result = new Map();
-        for (const id of await this.listBindings(subject)) {
-            const parsed = parseBindingId(id);
-            if (!parsed)
+        for (const binding of await this.listBindings(subject, at)) {
+            const role = (granting.get(binding.scope.type) ?? []).find((r) => r.uuid === binding.uuid);
+            if (!role)
                 continue;
-            if (!(granting.get(parsed.scope.type) ?? []).includes(parsed.slug))
+            // Un scope que el árbol ya no conoce no concede: no se lista. Y el rol
+            // tiene que existir ahí (3B · B2: global u owner en la cadena).
+            const chain = await this.chain(binding.scope, 'listScopes');
+            if (!chain)
+                continue;
+            if (!isRoleVisibleWith(role, chainKeysFrom(chain)[0]))
                 continue;
-            const chain = await this.chain(parsed.scope);
             const blocked = chain.some((s) => deniedKeys.has(scopeKey(s)));
             if (!blocked)
-                result.set(scopeKey(parsed.scope), parsed.scope);
+                result.set(scopeKey(binding.scope), binding.scope);
         }
         return [...result.values()];
     }
+    /**
+     * 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).
+     */
+    async listDenies(subject, scope) {
+        assertIdentity(scope ? { subject, scope } : { subject });
+        const chain = scope ? await this.chain(scope, 'listDenies') : null;
+        if (scope && !chain)
+            return [];
+        const wanted = chain ? scopeKey(chain[0]) : null;
+        const view = await this.catalog.view();
+        const denies = await this.factsDenies(subject, view);
+        const result = [];
+        for (const deny of denies) {
+            if (wanted !== null) {
+                if (scopeKey(deny.scope) !== wanted)
+                    continue;
+            }
+            else if (!(await this.chain(deny.scope, 'listDenies'))) {
+                continue;
+            }
+            result.push({ permission: deny.permission, scope: deny.scope });
+        }
+        return result;
+    }
+    /* ── El ÁRBOL como hechos (3b-2b) ──────────────────────────────────── */
+    /**
+     * 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»).
+     */
+    assertOneParent(object, current) {
+        if (current.length <= 1)
+            return;
+        throw new ScopeTreeDriftError(`El árbol del store tiene ${current.length} padres para ${object} ` +
+            `(${current.map((t) => t.user).join(', ')}); el paquete solo escribe uno. ` +
+            `No se elige por ti: reconstruye el árbol con authz:reconcile.`);
+    }
+    /**
+     * 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).
+     */
+    async onScopeAttached(child, parent) {
+        await this.reparent(child, parent, 'scopes.attached');
+    }
+    /**
+     * 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.
+     */
+    async onScopeMoved(child, newParent) {
+        await this.reparent(child, newParent, 'scopes.moved');
+    }
+    /**
+     * **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.
+     */
+    async assertEdge(child, parent, operation) {
+        assertScope(child);
+        assertScope(parent);
+        if (child.type === APP_SCOPE_TYPE) {
+            throw new InvalidIdentityError(`${operation}: la raíz \`app\` no puede colgar de nada`);
+        }
+        // (ii) 422 E_AUTHZ_UNKNOWN_SCOPE si el padre no existe.
+        const parentChain = await this.knownScope(parent, operation);
+        // El hijo, si el árbol ya lo conoce, con su identidad canónica.
+        const childChain = await this.chain(child, operation);
+        const childKey = scopeKey(childChain ? childChain[0] : child);
+        if (parentChain.some((s) => scopeKey(s) === childKey)) {
+            throw new ScopeCycleError(`${operation}: ${parent.type}:${parent.uuid ?? ''} desciende de ${childKey} (o es él mismo); ` +
+                `colgarlo cerraría un ciclo y FGA lo evaluaría en los dos sentidos: un grant en el ` +
+                `descendiente concedería en el ancestro.`);
+        }
+        return { childKey, parentKey: scopeKey(parentChain[0]) };
+    }
+    /**
+     * 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).
+     */
+    async onScopeDetached(child) {
+        assertScope(child);
+        if (child.type === APP_SCOPE_TYPE) {
+            throw new InvalidIdentityError('scopes.detached: la raíz `app` no se puede borrar ni purgar');
+        }
+        const scope = await this.canonicalOrSelf(child, 'scopes.detached');
+        const object = factsScopeObject(scopeKey(scope));
+        const current = await this.readAllTuples({ object, relation: FACTS_PARENT_RELATION }, { includeExpired: true });
+        // Aquí NO se exige un solo padre: el nodo se va entero y llevarse las dos
+        // aristas de una deriva es lo correcto (a diferencia de `moved`, donde
+        // habría que elegir cuál sobrevive).
+        if (current.length === 0)
+            return;
+        await this.client.write({ writes: [], deletes: current });
+    }
+    /**
+     * 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`).
+     */
+    async reparent(child, parent, operation) {
+        const { childKey, parentKey } = await this.assertEdge(child, parent, operation);
+        const wanted = factsParentTuple(childKey, parentKey);
+        for (let attempt = 0;; attempt++) {
+            const current = await this.readAllTuples({ object: wanted.object, relation: FACTS_PARENT_RELATION }, { includeExpired: true });
+            this.assertOneParent(wanted.object, current);
+            if (current.length === 1 && current[0].user === wanted.user) {
+                // **El atajo idempotente TAMBIÉN barre** (3b-8 · A3). El relay
+                // reintenta: un `moved` cuyo primer intento escribió la arista y
+                // murió ANTES del barrido vuelve a entregarse, cae aquí, y hasta
+                // 3b-8 el `return` a secas se saltaba `sweepLocalRoleBindings` — el
+                // rol local del tenant A seguía concediendo en el subárbol del B
+                // para siempre, con el relay en verde (invariante 18 roto por
+                // COMPOSICIÓN de dos piezas correctas: la idempotencia y el barrido).
+                // Coste: cero requests sin roles locales, como el propio barrido.
+                await this.sweepLocalRoleBindings(childKey);
+                return;
+            }
+            // **El ciclo se mira también en el árbol DEL STORE** (3b-8 · A5).
+            // `assertEdge` valida contra la cadena del CONSUMIDOR, pero quien
+            // decide en `facts` es el store, y una outbox aplicada en desorden (un
+            // `moved` aparcado + el move inverso posterior) lo deja desincronizado:
+            // la arista nueva —legal para el consumidor— puede cerrar un ciclo
+            // REAL, que FGA acepta y evalúa en los dos sentidos (cruce 3:
+            // fail-open mudo). `storeChain` del barrido solo lanzaba DESPUÉS de
+            // escribir y no deshacía nada. Se sube por la cadena del PADRE en el
+            // store antes del `Write`; el coste es O(profundidad) lecturas por
+            // cambio de árbol, fuera del camino caliente.
+            if ((await this.storeChain(parentKey)).includes(childKey)) {
+                throw new ScopeCycleError(`${operation}: en el árbol del STORE ${factsScopeObject(parentKey)} desciende de ${childKey} ` +
+                    `(o es él mismo); escribir la arista cerraría un ciclo real que FGA evalúa en los dos ` +
+                    `sentidos. El árbol del store está desincronizado del consumidor (una outbox aplicada en ` +
+                    `desorden, una entrada aparcada): reconstrúyelo con authz:reconcile.`);
+            }
+            try {
+                await this.client.write({ writes: [wanted], deletes: current });
+            }
+            catch (error) {
+                if (!isTreeWriteRace(error))
+                    throw error;
+                if (attempt >= TREE_WRITE_ATTEMPTS - 1) {
+                    throw new WriteConflictError(`${operation}: ${TREE_WRITE_ATTEMPTS} intentos y el árbol del store sigue en conflicto sobre ` +
+                        `${wanted.object}. El relay es escritor ÚNICO: si hay dos pasadas a la vez, dale un lease a tu outbox.`, { cause: error });
+                }
+                continue;
+            }
+            await this.sweepLocalRoleBindings(childKey);
+            return;
+        }
+    }
+    /**
+     * **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.
+     */
+    async sweepLocalRoleBindings(movedKey) {
+        const catalog = await this.catalog.view();
+        const locals = catalog.localRoles();
+        if (locals.length === 0)
+            return;
+        // La cadena del nodo movido y su subárbol se leen del STORE, no del
+        // consumidor: el árbol que decide en `facts` es el del store, y con la
+        // outbox el relay aplica esto MÁS TARDE, cuando el árbol del consumidor
+        // puede haber seguido moviéndose.
+        const chainOfMoved = await this.storeChain(movedKey);
+        /** `scopeKey` → claves de su cadena (él incluido), con el árbol de AHORA. */
+        const subtree = new Map([[movedKey, chainOfMoved]]);
+        const pending = [movedKey];
+        while (pending.length) {
+            const key = pending.pop();
+            const children = await this.readAllTuples({ user: factsScopeObject(key), relation: FACTS_PARENT_RELATION, object: `${FACTS_SCOPE_TYPE}:` }, { includeExpired: true });
+            for (const edge of children) {
+                const childKey = edge.object.slice(FACTS_SCOPE_TYPE.length + 1);
+                if (subtree.has(childKey))
+                    continue;
+                subtree.set(childKey, [childKey, ...subtree.get(key)]);
+                pending.push(childKey);
+            }
+        }
+        const writes = [];
+        const deletes = [];
+        for (const role of locals) {
+            // Los bindings de ESTE rol, esté donde esté: `role_binding:…#role@role:<uuid>`.
+            // El filtro lleva `user`, que es lo que el servidor real exige cuando el
+            // objeto es solo un tipo (lección del 2c).
+            const bindings = await this.readAllTuples({ user: `${FACTS_ROLE_TYPE}:${role.uuid}`, relation: FACTS_ROLE_RELATION, object: `${FACTS_BINDING_TYPE}:` }, { includeExpired: true });
+            for (const binding of this.parseBindings(FACTS_BINDING_TYPE, bindings.map((t) => t.object))) {
+                const chainKeys = subtree.get(scopeKey(binding.scope));
+                if (!chainKeys)
+                    continue;
+                this.classifyBindingEdge(catalog, binding, chainKeys, writes, deletes);
+            }
+        }
+        await this.applyBindingSweep(writes, deletes);
+    }
+    /**
+     * **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.
+     */
+    async sweepRoleVisibility(roleUuid) {
+        const catalog = await this.catalog.view();
+        // Un rol que el catálogo ya no declara no tiene visibilidad que decidir:
+        // sus hechos son de `purgeRole` (que los borra enteros) y de
+        // `authz:reconcile`, no de este barrido.
+        const role = catalog.roleByUuid(roleUuid);
+        if (!role)
+            return;
+        const bindings = await this.readAllTuples({ user: `${FACTS_ROLE_TYPE}:${roleUuid}`, relation: FACTS_ROLE_RELATION, object: `${FACTS_BINDING_TYPE}:` }, { includeExpired: true });
+        if (bindings.length === 0)
+            return;
+        const writes = [];
+        const deletes = [];
+        /** `scopeKey` → su cadena en el árbol del STORE, una vez por scope. */
+        const chains = new Map();
+        for (const binding of this.parseBindings(FACTS_BINDING_TYPE, bindings.map((t) => t.object))) {
+            const key = scopeKey(binding.scope);
+            let chainKeys = chains.get(key);
+            if (!chainKeys) {
+                // La cadena solo decide para un rol LOCAL: la visibilidad de un
+                // global no depende del árbol, así que no se paga por leerlo.
+                chainKeys = role.owner === GLOBAL_OWNER_KEY ? [key] : await this.storeChain(key);
+                chains.set(key, chainKeys);
+            }
+            this.classifyBindingEdge(catalog, binding, chainKeys, writes, deletes);
+        }
+        await this.applyBindingSweep(writes, deletes);
+    }
+    /**
+     * 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.
+     */
+    classifyBindingEdge(catalog, binding, chainKeys, writes, deletes) {
+        const edge = factsScopeBindingTuple(scopeKey(binding.scope), binding.uuid);
+        if (declaredRoleAt(catalog, binding.uuid, binding.scope.type, chainKeys))
+            writes.push(edge);
+        else
+            deletes.push(edge);
+    }
+    /**
+     * 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).
+     */
+    async applyBindingSweep(writes, deletes) {
+        if (!writes.length && !deletes.length)
+            return;
+        const operations = [
+            ...deletes.map((tuple) => ({ delete: tuple })),
+            ...writes.map((tuple) => ({ write: tuple })),
+        ];
+        for (let i = 0; i < operations.length; i += PURGE_BATCH_SIZE) {
+            const chunk = operations.slice(i, i + PURGE_BATCH_SIZE);
+            await this.client.write({
+                writes: chunk.filter((o) => o.write).map((o) => o.write),
+                deletes: chunk.filter((o) => o.delete).map((o) => o.delete),
+            }, {
+                conflict: {
+                    onDuplicateWrites: ClientWriteRequestOnDuplicateWrites.Ignore,
+                    onMissingDeletes: ClientWriteRequestOnMissingDeletes.Ignore,
+                },
+            });
+        }
+    }
+    /**
+     * `[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.
+     */
+    async storeChain(key) {
+        const chain = [key];
+        const seen = new Set([key]);
+        for (let hop = 0; hop < MAX_SCOPE_CHAIN_HOPS; hop++) {
+            const object = factsScopeObject(chain[chain.length - 1]);
+            const parents = await this.readAllTuples({ object, relation: FACTS_PARENT_RELATION }, { includeExpired: true });
+            this.assertOneParent(object, parents);
+            if (parents.length === 0)
+                return chain;
+            const parentKey = parents[0].user.slice(FACTS_SCOPE_TYPE.length + 1);
+            if (seen.has(parentKey)) {
+                throw new ScopeCycleError(`El árbol del store tiene un ciclo en ${factsScopeObject(parentKey)}: no se puede decidir la ` +
+                    `visibilidad de un rol local. Reconstruye el árbol con authz:reconcile.`);
+            }
+            seen.add(parentKey);
+            chain.push(parentKey);
+        }
+        throw new AuthorizationInternalError(`El árbol del store pasa de ${MAX_SCOPE_CHAIN_HOPS} niveles desde ${factsScopeObject(key)}; ` +
+            `no se puede resolver la cadena para el barrido de roles locales.`);
+    }
+    /**
+     * 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` — 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).
+     */
+    async purgeScope(purged) {
+        assertScope(purged);
+        if (purged.type === APP_SCOPE_TYPE) {
+            throw new InvalidIdentityError('purgeScope: la raíz `app` no se purga');
+        }
+        // La identidad canónica si el árbol aún lo conoce (K1); tal cual si ya no.
+        const scope = await this.canonicalOrSelf(purged, 'purgeScope');
+        const key = scopeKey(scope);
+        const roles = await this.sql('purgeScope.roles', () => db.from('authz_roles').where('scope_type', scope.type).select('uuid'));
+        // **Los denies no son objetos propios** (3b-2c): son relaciones
+        // `denied_<P>` DEL SCOPE, así que se purgan leyendo el objeto
+        // `scope:<key>` —una lectura en vez de O(permisos)—, y con ellos se va el
+        // enlace `#binding` de los bindings que colgaban de aquí. Lo que NO se
+        // toca es la arista `parent`: la borra `scopes.detached` DESPUÉS de que
+        // esta purga demuestre cero (S6, cruce 9). Al revés, una purga que muriera
+        // a medias dejaría el scope sin ancestro y, desde (c2r), sin conceder
+        // nada — pero también sin nadie que volviera a purgarlo.
+        const scopeObject = factsScopeObject(key);
+        const objects = [...roles.map((r) => `role_binding:${key}|${r.uuid}`), scopeObject];
+        /** Lo purgable de un objeto: todo, salvo la arista `parent` del scope. */
+        const purgeable = async (object) => {
+            const keys = await this.readAllTuples({ object }, { includeExpired: true });
+            return object === scopeObject ? keys.filter((k) => k.relation !== FACTS_PARENT_RELATION) : keys;
+        };
+        /** Borra en lotes ≤ 100 (límite del `Write`), sin quejarse de lo que ya no está. */
+        const deleteKeys = async (keys) => {
+            for (let i = 0; i < keys.length; i += PURGE_BATCH_SIZE) {
+                await this.client.deleteTuples(keys.slice(i, i + PURGE_BATCH_SIZE), {
+                    conflict: { onMissingDeletes: ClientWriteRequestOnMissingDeletes.Ignore },
+                });
+            }
+        };
+        /** Las dos aristas de (c2): estructura, no hechos (`#role` y `#binding`). */
+        const isStructure = (k) => k.relation === FACTS_BINDING_RELATION || k.relation === FACTS_ROLE_RELATION;
+        // **El ORDEN de la purga es parte del contrato** (3b-2f · R3).
+        // No hay transacción que abarque los N objetos, así que un `grant`
+        // concurrente aterriza en algún hueco; lo que se elige es que NINGÚN
+        // hueco deje una asignación que `listRoles`/`hasRole` ven y `authorize`
+        // no honra —enumerada y sin conceder, que es peor que perder la
+        // escritura—:
+        //
+        //  1. **la ESTRUCTURA primero** (`role_binding#role` y `scope#binding`).
+        //     Son deterministas —`factsBindingTuples(key, rol)`—, así que se
+        //     borran a ciegas y esta fase no cuesta ni una lectura.
+        //  2. **los HECHOS después** (`assignee`), releyendo cada objeto: lo que
+        //     alguien escribió después de (1) también se borra.
+        //  3. **los `denied_<P>` del scope, los últimos.**
+        //
+        // Con el `grant` escribiendo sus TRES tuplas en un solo `Write`, un
+        // grant que aterriza antes de (2) pierde su asignación ahí (cero,
+        // coherente) y uno que aterriza después se queda ENTERO con las aristas
+        // que él mismo escribió (concede, coherente). Al revés —las aristas al
+        // final, como hasta 3b-2e— el grant que caía en medio se quedaba con el
+        // `assignee` y sin arista.
+        // Los denies van los ÚLTIMOS porque una purga que muere a medias tiene
+        // que dejar denies de MÁS, nunca de menos (invariante 2): entre (1) y
+        // (3) lo que queda del scope es inerte, no permisivo. Y (2) y (3) borran
+        // SOLO lo suyo: una arista que un grant concurrente reescribió no se
+        // toca —sería volver a huerfanar su asignación—; queda como residuo, y
+        // el residuo es justo lo que la demostración de cero reporta. La arista
+        // `parent` sigue sin tocarse: la borra `scopes.detached` DESPUÉS de que
+        // esta purga demuestre cero (S6, cruce 9).
+        await deleteKeys(roles.flatMap((r) => factsBindingTuples(key, r.uuid)));
+        for (const object of objects) {
+            if (object === scopeObject)
+                continue;
+            await deleteKeys((await purgeable(object)).filter((k) => !isStructure(k)));
+        }
+        // **Las aristas `#binding` de roles que el catálogo YA NO declara en este
+        // nivel también se purgan** (3b-8 · C2). El barrido no es atómico con el
+        // catálogo: un rol cuya fila se borró (o cambió de `scope_type`) entre el
+        // commit y esta purga dejaba una arista que el paso 1 no ve —solo mira
+        // `authz_roles WHERE scope_type = <este>`— y que la demostración de cero
+        // SÍ cuenta ⇒ `E_AUTHZ_PURGE_INCOMPLETE` en TODOS los intentos y
+        // `detached` bloqueado para siempre. Borrarla nunca concede (es la arista
+        // de visibilidad, y su rol ya no existe en este nivel), y la arista de un
+        // rol DEL catálogo que un `grant` concurrente reescribió no se toca
+        // (`known` la protege): esa sigue saliendo como residuo, que es lo
+        // correcto — se reintenta.
+        const known = new Set(roles.map((r) => `role_binding:${key}|${r.uuid}`));
+        await deleteKeys((await purgeable(scopeObject)).filter((k) => k.relation === FACTS_BINDING_RELATION && !known.has(k.user)));
+        await deleteKeys((await purgeable(scopeObject)).filter((k) => k.relation.startsWith(FACTS_DENIED_PREFIX)));
+        // Demostrar cero: lo que no se puede demostrar, se reporta.
+        const residue = [];
+        for (const object of objects) {
+            const left = await purgeable(object);
+            if (left.length)
+                residue.push(`${object} (${left.length})`);
+        }
+        if (residue.length) {
+            throw new PurgeIncompleteError(`purgeScope ${key}: quedan tuplas tras el borrado — ${residue.join('; ')}. ` +
+                `No confirmes el borrado del scope; reintenta la purga.`);
+        }
+    }
+    /**
+     * 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() {
+        return {
+            assertPublishable: (permissions) => {
+                assertFactsModelPublishable(this.holderTypes, permissions, (message) => this.warn(message));
+            },
+            project: (snapshot) => this.projectCatalog(snapshot),
+        };
+    }
+    /**
+     * **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.
+     */
+    async ensureFactsRoot() {
+        const wanted = factsRootTuples(this.holderTypes);
+        const current = await this.readAllTuples({ object: factsScopeObject(APP_SCOPE_TYPE), relation: FACTS_ROOTED_RELATION }, { includeExpired: true });
+        const have = new Set(current.map((tuple) => tuple.user));
+        const missing = wanted.filter((tuple) => !have.has(tuple.user));
+        if (missing.length)
+            await this.client.write({ writes: missing, deletes: [] });
+    }
+    /**
+     * 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.
+     */
+    async projectCatalog(snapshot) {
+        await this.ensureFactsRoot();
+        const wanted = new Map();
+        for (const tuple of factsCatalogTuples(snapshot.roles, this.holderTypes)) {
+            wanted.set(factsTupleId(tuple), tuple);
+        }
+        // Lo que la proyección tiene HOY. `Read` por prefijo de tipo, paginado y
+        // acotado como todas las enumeraciones del driver (L0.7) — y UNA lectura
+        // por holder, porque el servidor REAL rechaza con un 400 un `Read` cuyo
+        // objeto es solo el tipo y no trae user («the object type field is
+        // required and both the object id and user cannot be empty»). Con el
+        // comodín de usuario de (c2) eso no cuesta nada: la proyección son
+        // exactamente las tuplas `<holder>:*`, así que preguntando por cada
+        // comodín se ve el espejo ENTERO —incluidas las tuplas de roles que el
+        // catálogo ya no lista, que es lo que hay que borrar—. Lo escrito con
+        // otro user sobre `role:` no es de esta proyección y no se toca.
+        const current = new Map();
+        for (const holderType of Object.values(this.holderTypes)) {
+            for (const key of await this.readAllTuples({ user: `${holderType}:*`, object: `${FACTS_ROLE_TYPE}:` }, { includeExpired: true })) {
+                // Solo la familia del catálogo: si el modelo crece con otras
+                // relaciones sobre `role`, no son de esta proyección.
+                if (!key.relation.startsWith(FACTS_PERMITS_PREFIX))
+                    continue;
+                current.set(factsTupleId(key), key);
+            }
+        }
+        const writes = [...wanted.values()].filter((tuple) => !current.has(factsTupleId(tuple)));
+        const deletes = [...current.values()].filter((tuple) => !wanted.has(factsTupleId(tuple)));
+        // Los deletes van primero dentro del lote: quitar un permiso tiene que
+        // caber en la misma request que lo que lo sustituye.
+        const operations = [
+            ...deletes.map((tuple) => ({ delete: tuple })),
+            ...writes.map((tuple) => ({ write: tuple })),
+        ];
+        for (let i = 0; i < operations.length; i += PURGE_BATCH_SIZE) {
+            const chunk = operations.slice(i, i + PURGE_BATCH_SIZE);
+            await this.client.write({
+                writes: chunk.filter((o) => o.write).map((o) => o.write),
+                deletes: chunk.filter((o) => o.delete).map((o) => o.delete),
+            });
+        }
+        return { written: writes.length, deleted: deletes.length, unchanged: wanted.size - writes.length };
+    }
+    /**
+     * **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.
+     */
+    async purgeRole(roleUuid) {
+        assertCatalogUuid('rol', roleUuid);
+        const existing = await this.sql('purgeRole.role', () => db.from('authz_roles').where('uuid', roleUuid).select('uuid'));
+        if (!existing.length)
+            throw new UnknownRoleError(roleUuid);
+        const roleObject = `${FACTS_ROLE_TYPE}:${roleUuid}`;
+        /** Los objetos `role_binding` de este rol, por su arista `#role`. */
+        const bindingsOf = async () => {
+            const edges = await this.readAllTuples({ user: roleObject, relation: FACTS_ROLE_RELATION, object: `${FACTS_BINDING_TYPE}:` }, { includeExpired: true });
+            return [...new Set(edges.map((edge) => edge.object))];
+        };
+        /** El scope del que cuelga un binding, según su propio id (`<scopeKey>|<roleUuid>`). */
+        const scopeOf = (binding) => {
+            const id = binding.slice(FACTS_BINDING_TYPE.length + 1);
+            const separator = id.lastIndexOf('|');
+            return separator > 0 ? id.slice(0, separator) : null;
+        };
+        /** Todo lo purgable del rol: sus bindings enteros, las aristas del scope y su proyección. */
+        const purgeable = async () => {
+            const keys = [];
+            for (const binding of await bindingsOf()) {
+                keys.push(...(await this.readAllTuples({ object: binding }, { includeExpired: true })));
+                const key = scopeOf(binding);
+                if (!key)
+                    continue;
+                // La arista vive en el objeto `scope`, así que se lee de ahí (y solo
+                // la que apunta a ESTE binding: el scope tiene las de otros roles).
+                const scopeEdges = await this.readAllTuples({ user: binding, relation: FACTS_BINDING_RELATION, object: factsScopeObject(key) }, { includeExpired: true });
+                keys.push(...scopeEdges);
+            }
+            // La proyección del catálogo del rol: `role:<uuid>#permits_<P>@<holder>:*`.
+            for (const holderType of Object.values(this.holderTypes)) {
+                keys.push(...(await this.readAllTuples({ user: `${holderType}:*`, object: roleObject }, { includeExpired: true })));
+            }
+            return keys;
+        };
+        const keys = await purgeable();
+        for (let i = 0; i < keys.length; i += PURGE_BATCH_SIZE) {
+            await this.client.deleteTuples(keys.slice(i, i + PURGE_BATCH_SIZE), {
+                conflict: { onMissingDeletes: ClientWriteRequestOnMissingDeletes.Ignore },
+            });
+        }
+        const residue = await purgeable();
+        if (residue.length) {
+            throw new PurgeIncompleteError(`purgeRole ${roleUuid}: quedan ${residue.length} tuplas tras el borrado ` +
+                `(${residue.slice(0, 3).map((k) => `${k.user}#${k.relation}@${k.object}`).join('; ')}…). ` +
+                `El rol NO se borra del catálogo: reintenta la purga.`);
+        }
+        try {
+            await this.sql('purgeRole', () => withAuthzCatalogWrite(async (trx) => {
+                // `authz_assignments` es del driver `database` y aquí está vacía,
+                // pero se limpia igual: un store que viene de una migración entre
+                // drivers no puede dejar filas apuntando a un rol que ya no existe.
+                await this.sql('purgeRole.assignments', () => trx.from('authz_assignments').where('role_uuid', roleUuid).delete());
+                await this.sql('purgeRole.links', () => trx.from('authz_role_permissions').where('role_uuid', roleUuid).delete());
+                const deleted = await this.sql('purgeRole.role.delete', () => trx.from('authz_roles').where('uuid', roleUuid).delete());
+                if (Number(Array.isArray(deleted) ? deleted[0] : deleted) === 0)
+                    throw new UnknownRoleError(roleUuid);
+            }, { driver: 'openfga', timeoutMs: this.timeoutMs }));
+        }
+        finally {
+            this.catalog.invalidate();
+        }
+    }
+    /**
+     * 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.
+     */
+    async countRoleAssignments(roleUuids) {
+        for (const uuid of roleUuids)
+            assertCatalogUuid('rol', uuid);
+        const counts = [];
+        for (const roleUuid of roleUuids) {
+            const edges = await this.readAllTuples({ user: `${FACTS_ROLE_TYPE}:${roleUuid}`, relation: FACTS_ROLE_RELATION, object: `${FACTS_BINDING_TYPE}:` }, { includeExpired: true });
+            let total = 0;
+            for (const binding of new Set(edges.map((edge) => edge.object))) {
+                total += (await this.readAllTuples({ relation: FACTS_ASSIGNEE_RELATION, object: binding })).length;
+            }
+            counts.push(total);
+        }
+        return counts;
+    }
+    /**
+     * **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.
+     */
+    async projectCatalogRole(roleUuid) {
+        assertCatalogUuid('rol', roleUuid);
+        await this.sweepRoleVisibility(roleUuid);
+        const catalog = await this.catalog.view();
+        const permissions = [...catalog.rolePermissionsOf(roleUuid)].sort();
+        const object = `${FACTS_ROLE_TYPE}:${roleUuid}`;
+        const wanted = new Map();
+        for (const tuple of factsCatalogTuples([{ uuid: roleUuid, permissions }], this.holderTypes)) {
+            wanted.set(factsTupleId(tuple), tuple);
+        }
+        const current = new Map();
+        for (const holderType of Object.values(this.holderTypes)) {
+            for (const key of await this.readAllTuples({ user: `${holderType}:*`, object }, { includeExpired: true })) {
+                if (!key.relation.startsWith(FACTS_PERMITS_PREFIX))
+                    continue;
+                current.set(factsTupleId(key), key);
+            }
+        }
+        const writes = [...wanted.values()].filter((tuple) => !current.has(factsTupleId(tuple)));
+        const deletes = [...current.values()].filter((tuple) => !wanted.has(factsTupleId(tuple)));
+        if (!writes.length && !deletes.length)
+            return;
+        await this.client.write({ writes, deletes });
+    }
+    /* ── `authz:reconcile --to=openfga` (3b-3a) ───────────────────────────── */
+    /**
+     * **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.
+     */
+    async reconcile(source, options = {}) {
+        const dryRun = options.dryRun === true;
+        const prune = options.prune === true;
+        const batchSize = reconcileBatchSize(options.batchSize);
+        const maxTuples = reconcileMaxTuples(options.maxTuples);
+        const catalog = await this.catalog.view();
+        const now = this.now();
+        /** Lo que el destino DEBE tener, por id de tupla. */
+        const wanted = new Map();
+        /** Aristas de visibilidad que NO pueden existir (invariante 18). */
+        const forbidden = new Set();
+        const skipped = {};
+        const details = [];
+        const note = (kind, reason, detail) => {
+            skipped[reason] = (skipped[reason] ?? 0) + 1;
+            if (details.length < RECONCILE_MAX_DETAILS)
+                details.push({ kind, reason, detail });
+        };
+        const want = (tuple, family, validUntil = null) => {
+            wanted.set(factsTupleId(tuple), { tuple, family, validUntil });
+        };
+        // 1. El marcador de raíz. Va el primero porque sin él `can_<P>` es `false`
+        //    en TODO el store (fail-closed total, medido en 3b-2i).
+        for (const tuple of factsRootTuples(this.holderTypes))
+            want(tuple, 'root');
+        // 2. La proyección del catálogo, con la MISMA foto que el sync.
+        const snapshot = await readCatalogProjectionSnapshot(db, (operation, fn) => this.sql(`reconcile.catalog.${operation}`, fn));
+        // Lo que el MODELO publicado declara: un permiso que el catálogo tiene y
+        // el modelo no (el store se quedó en una versión anterior) haría que el
+        // `Write` de su `permits_<P>` fuese un 400 del servidor a mitad de la
+        // migración. Se detecta con una lectura y se cuenta, en vez de reventar.
+        const publishable = await this.modelPermissions();
+        const usable = (permission) => publishable === null || publishable.has(factsRelationsOf(permission).permits);
+        for (const role of snapshot.roles) {
+            const permissions = role.permissions.filter((permission) => {
+                if (usable(permission))
+                    return true;
+                note('tuple', 'permission-not-in-model', `role:${role.uuid} permits_${permission}`);
+                return false;
+            });
+            for (const tuple of factsCatalogTuples([{ uuid: role.uuid, permissions }], this.holderTypes)) {
+                want(tuple, 'catalog');
+            }
+        }
+        // 3. El ÁRBOL, paginado por cursor y con los ciclos DETECTADOS: FGA acepta
+        //    un ciclo de `parent` y lo evalúa —un grant en cualquier nodo concede
+        //    en la raíz (cruce 3, reproducido dos veces)—, así que ninguna arista
+        //    de un ciclo se escribe y el ciclo se reporta.
+        const { parentOf, cycles } = await this.readSourceTree(source, batchSize, note);
+        for (const [child, parent] of parentOf)
+            want(factsParentTuple(child, parent), 'tree');
+        /** `[key, ...ancestros]` según el árbol del ORIGEN, o `null` si no llega a la raíz. */
+        const chains = new Map();
+        const chainOf = (key) => {
+            const memo = chains.get(key);
+            if (memo !== undefined)
+                return memo;
+            const chain = [];
+            let current = key;
+            const seen = new Set();
+            while (current !== undefined && !seen.has(current)) {
+                chain.push(current);
+                if (current === APP_SCOPE_TYPE) {
+                    chains.set(key, chain);
+                    return chain;
+                }
+                seen.add(current);
+                current = parentOf.get(current);
+            }
+            chains.set(key, null);
+            return null;
+        };
+        // 4. Los HECHOS, **de quien sea su fuente de verdad** (3b-5). `authz_*`
+        //    lo es en la MIGRACIÓN `database` → `openfga`, y por eso esa
+        //    dirección es la vía de salida de un store escrito por otra versión.
+        //    Pero cuando el motor ya SIRVE desde este driver los hechos son las
+        //    tuplas del store, no esas tablas: leerlas ahí resucitaba lo revocado
+        //    tras el cutover y dejaba el barrido de visibilidad sin aplicar (los
+        //    dos 🔴 del auditor final). Quién es el origen lo decide el manager y
+        //    llega en `source.factsOrigin`; aquí solo se obedece.
+        const origin = source.factsOrigin ?? {
+            name: AUTHZ_TABLES_ORIGIN,
+            authzTables: true,
+        };
+        const factsCtx = { note, usable, chainOf, want, forbidden };
+        const facts = origin.authzTables
+            ? await this.readSourceFacts(catalog, batchSize, now, factsCtx)
+            : await this.readOriginFacts(source, batchSize, maxTuples, catalog, now, factsCtx);
+        // 5. El destino ENTERO, tal como está. **La cota es DECLARADA** (3b-3b ·
+        //    B5): este volcado entra en memoria —el ORIGEN se lee por lotes con
+        //    cursor, el destino no—, así que pasar de `maxTuples` es un 500 con
+        //    nombre antes de escribir nada, no un OOM a mitad de migración.
+        const current = await this.readEveryTuple(maxTuples);
+        const phases = emptyPhases();
+        const drift = {
+            rootMarker: false,
+            multiParent: [],
+            roleVisibility: 0,
+            pendingRelay: 0,
+            deadRelay: 0,
+        };
+        const deletes = [];
+        const writes = [];
+        const seen = new Set();
+        const parents = new Map();
+        /** Bindings que el store YA conoce (tienen `assignee`): ver `drift.roleVisibility`. */
+        const storeBindings = new Set();
+        for (const tuple of current) {
+            const id = factsTupleId(tuple);
+            if (tuple.relation === FACTS_ASSIGNEE_RELATION)
+                storeBindings.add(tuple.object);
+            const family = familyOfTuple(tuple);
+            if (tuple.relation === FACTS_PARENT_RELATION && tuple.object.startsWith(`${FACTS_SCOPE_TYPE}:`)) {
+                parents.set(tuple.object, (parents.get(tuple.object) ?? 0) + 1);
+            }
+            const target = wanted.get(id);
+            if (target) {
+                seen.add(id);
+                if (sameInstant(tuple.validUntil, target.validUntil)) {
+                    phases[target.family].unchanged += 1;
+                    continue;
+                }
+                // La caducidad NO es parte de la clave en FGA: cambiarla es borrar y
+                // volver a escribir (por eso `Ignore` se queda la vieja — S7).
+                phases[target.family].updated += 1;
+                deletes.push(bareTuple(tuple));
+                writes.push(reconcileWriteForm(target));
+                continue;
+            }
+            phases[family].extra += 1;
+            const visibilityDrift = forbidden.has(id);
+            if (visibilityDrift)
+                drift.roleVisibility += 1;
+            // Lo derivado se rehace entero; los hechos solo con `--prune`.
+            if (family === 'facts' && !prune && !visibilityDrift) {
+                note('tuple', 'extra-fact', id);
+                continue;
+            }
+            phases[family].deleted += 1;
+            deletes.push(bareTuple(tuple));
+        }
+        for (const [id, target] of wanted) {
+            if (seen.has(id))
+                continue;
+            if (target.family === 'root')
+                drift.rootMarker = true;
+            // Una arista de visibilidad que falta con el binding YA en el store es
+            // la escritura del invariante 18 que el relay pudo perder; en una
+            // migración a un store vacío no falta nada, sobra todo.
+            if (target.tuple.relation === FACTS_BINDING_RELATION && storeBindings.has(target.tuple.user)) {
+                drift.roleVisibility += 1;
+            }
+            phases[target.family].written += 1;
+            writes.push(reconcileWriteForm(target));
+        }
+        for (const [object, count] of parents) {
+            if (count > 1)
+                drift.multiParent.push(object);
+        }
+        drift.multiParent.sort();
+        // El seguro contra el origen ciego (AA2 aplicado a la migración): borrar
+        // hechos con `authz_*` VACÍO es casi siempre apuntar a la base equivocada
+        // o estar mirando el driver que NO escribe ahí.
+        const factsDeleted = phases.facts.deleted;
+        // 3b-8 · B1: sobre los hechos UTILIZABLES, no el conteo crudo — un origen
+        // que devuelve N filas y las N se descartan (caducadas, scopes que ya no
+        // resuelven) sigue sin respaldar NADA de lo que --prune va a borrar.
+        const massDelete = prune && factsDeleted > 0 && facts.usable === 0;
+        if (massDelete && !dryRun && options.allowMassDelete !== true) {
+            throw new MassReconcileRefusedError(`authz:reconcile --to=openfga --prune borraría ${factsDeleted} tupla(s) de hechos del store y el ` +
+                `ORIGEN no ha aportado NI UN hecho utilizable (${facts.rows} leídos, todos descartados — mira ` +
+                `'skipped'). Eso es la firma de una base equivocada, de un árbol que ya no resuelve esos scopes, ` +
+                `o de que los hechos los está escribiendo el driver 'openfga' (que los guarda en el store, no en ` +
+                `'authz_assignments'/'authz_denies'): esta pasada dejaría el store sin nada concedido y no hay desde ` +
+                `dónde reconstruirlo. Comprueba la conexión y el driver activo; si de verdad quieres vaciarlo, ` +
+                `--allow-mass-delete.`);
+        }
+        if (!dryRun) {
+            // Los DELETES primero: si la pasada muere entre medias, lo que queda es
+            // de MENOS (fail-closed), nunca una tupla vieja conviviendo con la nueva.
+            await this.applyReconcileWrites(deletes, []);
+            await this.applyReconcileWrites([], writes);
+        }
+        const totals = sumPhases(phases);
+        return {
+            to: 'openfga',
+            factsFrom: origin.name,
+            dryRun,
+            prune,
+            ...totals,
+            phases,
+            skipped,
+            details,
+            cycles,
+            drift,
+            massDelete,
+        };
+    }
+    /**
+     * 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.
+     */
+    async modelPermissions() {
+        const response = await this.client.readLatestAuthorizationModel();
+        const model = response?.authorization_model;
+        if (!model?.type_definitions)
+            return null;
+        const role = model.type_definitions.find((definition) => definition.type === FACTS_ROLE_TYPE);
+        if (!role?.relations)
+            return null;
+        return new Set(Object.keys(role.relations).filter((name) => name.startsWith(FACTS_PERMITS_PREFIX)));
+    }
+    /**
+     * 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)—.
+     */
+    async readSourceTree(source, batchSize, note) {
+        if (typeof source.enumerateEdges !== 'function') {
+            throw new AuthorizationConfigError("authz:reconcile necesita 'scopes.enumerateEdges' en config/authorization.ts: sin el árbol del consumidor " +
+                'no se puede reconstruir el del store (y suponerlo plano sería inventar una jerarquía).');
+        }
+        const parentOf = new Map();
+        const cycles = [];
+        const cycleNodes = new Set();
+        const seenCursors = new Set();
+        let after;
+        for (let page = 0;; page++) {
+            const result = await source.enumerateEdges({ limit: batchSize, after });
+            if (!result || !Array.isArray(result.edges)) {
+                throw new AuthorizationConfigError(`scopes.enumerateEdges devolvió ${typeof result} en vez de { edges, cursor? }`);
+            }
+            if (result.edges.length > batchSize) {
+                throw new AuthorizationConfigError(`scopes.enumerateEdges devolvió ${result.edges.length} aristas con limit=${batchSize}: ` +
+                    `no se puede paginar lo que no cabe en el lote.`);
+            }
+            for (const edge of result.edges) {
+                if (!edge || !isValidScope(edge.child) || !isValidScope(edge.parent)) {
+                    note('edge', 'invalid-scope', JSON.stringify(edge ?? null));
+                    continue;
+                }
+                if (edge.child.type === APP_SCOPE_TYPE) {
+                    note('edge', 'root-child', `la raíz 'app' no cuelga de nada`);
+                    continue;
+                }
+                const child = scopeKey(edge.child);
+                const parent = scopeKey(edge.parent);
+                const previous = parentOf.get(child);
+                if (previous !== undefined) {
+                    note('edge', 'two-parents-in-source', `${child} → ${previous} y ${parent}`);
+                    continue;
+                }
+                const cycle = walkUpTo(parentOf, parent, child);
+                if (cycle) {
+                    // `cycle` ya viene con TODOS los nodos del ciclo (`[padre … hijo]`).
+                    cycles.push(cycle);
+                    for (const node of cycle)
+                        cycleNodes.add(node);
+                    note('edge', 'cycle', `${child} → ${parent} cierra un ciclo`);
+                    continue;
+                }
+                parentOf.set(child, parent);
+            }
+            if (result.cursor === undefined || result.cursor === null)
+                break;
+            if (seenCursors.has(result.cursor)) {
+                throw new AuthorizationConfigError(`scopes.enumerateEdges: el cursor '${result.cursor}' se repite (página ${page + 1}); no avanza.`);
+            }
+            seenCursors.add(result.cursor);
+            after = result.cursor;
+            if (page >= RECONCILE_MAX_PAGES) {
+                throw new AuthorizationInternalError(`scopes.enumerateEdges: más de ${RECONCILE_MAX_PAGES} páginas sin agotar el árbol.`);
+            }
+        }
+        // Un ciclo deja a TODOS sus nodos sin arista, no solo al que la cerró: si
+        // no, cuál se queda fuera dependería del orden de enumeración.
+        for (const node of cycleNodes) {
+            if (parentOf.delete(node))
+                note('edge', 'cycle', `${node} pertenece a un ciclo: su arista no se escribe`);
+        }
+        return { parentOf, cycles };
+    }
+    /**
+     * 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.
+     */
+    async readSourceFacts(catalog, batchSize, now, ctx) {
+        const expiry = sqlExpiryCodec(db.connection());
+        let rows = 0;
+        // Hechos que RESPALDAN algo en el destino (3b-8 · B1): el seguro de
+        // borrado masivo mira esto, no el conteo crudo.
+        let usable = 0;
+        // Los DOS barridos, en UNA sola foto (3b-6). Ver `withSourceSnapshot`.
+        return this.withSourceSnapshot(async (client) => {
+            await this.eachRow(client, 'reconcile.assignments', batchSize, (query) => query
+                .from('authz_assignments')
+                .select('uuid', 'holder_type', 'holder_uuid', 'role_uuid', 'scope_type', 'scope_uuid')
+                .select(expiry.select('expires_at')), (row) => {
+                rows += 1;
+                if (this.wantAssignment(catalog, now, ctx, {
+                    holder: { type: row.holder_type, uuid: String(row.holder_uuid) },
+                    // `scope_uuid` es NOT NULL y la RAÍZ va con el centinela (K1/L0.10):
+                    // un `?? null` nunca es null y `scopeKey` rechazaba `app` con uuid,
+                    // así que un grant en la raíz reventaba la migración entera (3b-3b).
+                    scope: { type: row.scope_type, uuid: fromDbScopeUuid(String(row.scope_uuid)) },
+                    roleUuid: String(row.role_uuid),
+                    expiresAt: expiry.fromDb(row.expires_at),
+                    detail: `${row.holder_type}:${row.holder_uuid} → ${row.role_uuid} @ ${row.scope_type}:${row.scope_uuid ?? ''}`,
+                })) {
+                    usable += 1;
+                }
+            });
+            await this.eachRow(client, 'reconcile.denies', batchSize, (query) => query.from('authz_denies').select('uuid', 'holder_type', 'holder_uuid', 'permission_uuid', 'scope_type', 'scope_uuid'), (row) => {
+                rows += 1;
+                const label = `${row.holder_type}:${row.holder_uuid} ⊘ ${row.permission_uuid} @ ${row.scope_type}:${row.scope_uuid ?? ''}`;
+                // En `authz_denies` el permiso es un uuid; por el puerto es un slug
+                // (`ReconcileFact.permission`), que es lo que el catálogo local sabe
+                // traducir. Aquí se traduce una vez y el resto es común.
+                const permission = catalog.permissionSlug(String(row.permission_uuid));
+                if (!permission) {
+                    ctx.note('deny', 'unknown-permission', label);
+                    return;
+                }
+                if (this.wantDeny(ctx, {
+                    holder: { type: row.holder_type, uuid: String(row.holder_uuid) },
+                    scope: { type: row.scope_type, uuid: fromDbScopeUuid(String(row.scope_uuid)) },
+                    permission,
+                    detail: label,
+                })) {
+                    usable += 1;
+                }
+            });
+            return { rows, usable };
+        });
+    }
+    /**
+     * **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.
+     */
+    async withSourceSnapshot(fn) {
+        const options = isSqliteDialect(db.connection())
+            ? undefined
+            : { isolationLevel: 'repeatable read' };
+        // Lo que lance `fn` ya viene clasificado (cada consulta pasa por
+        // `this.sql`); lo que falle al ABRIR o cerrar la transacción es la base y
+        // se clasifica aquí, que un error crudo de knex no cruza la frontera.
+        let inner = null;
+        try {
+            return await db.transaction(async (trx) => {
+                try {
+                    return await fn(trx);
+                }
+                catch (error) {
+                    inner = { error };
+                    throw error;
+                }
+            }, options);
+        }
+        catch (error) {
+            if (inner !== null && inner.error === error)
+                throw error;
+            if (isAuthzError(error))
+                throw error;
+            if (isTimeoutLike(error)) {
+                throw new AuthorizationBackendTimeoutError('openfga', 'reconcile.snapshot', this.timeoutMs, error);
+            }
+            throw new AuthorizationBackendError('openfga', 'reconcile.snapshot', error);
+        }
+    }
+    /**
+     * **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.
+     */
+    async readOriginFacts(source, batchSize, maxTuples, catalog, now, ctx) {
+        const enumerate = source.facts;
+        if (typeof enumerate !== 'function') {
+            throw new UnsupportedOperationError('enumerateFacts', 'authz:reconcile --to=openfga', 'origen', `El ORIGEN de esta pasada no son 'authz_assignments'/'authz_denies', así que tiene que saber ` +
+                `enumerar sus hechos: sin eso la pasada leería cero hechos y con --prune vaciaría el store.`);
+        }
+        let rows = 0;
+        let usable = 0;
+        let after;
+        const seenCursors = new Set();
+        for (let page = 0;; page++) {
+            const got = await enumerate({ limit: batchSize, after });
+            if (got.facts.length > batchSize) {
+                throw new AuthorizationInternalError(`authz:reconcile: el origen devolvió ${got.facts.length} hechos con limit=${batchSize}`);
+            }
+            for (const skip of got.skipped ?? [])
+                ctx.note(skip.kind, skip.reason, skip.detail);
+            for (const fact of got.facts) {
+                rows += 1;
+                if (rows > maxTuples) {
+                    throw new ReconcileTooLargeError(`authz:reconcile --to=openfga: el ORIGEN pasa de maxTuples (${maxTuples}) hechos y la pasada ` +
+                        `necesita compararlos contra el estado ENTERO del destino, que entra en memoria. Sube ` +
+                        `maxTuples si tu proceso lo aguanta; no hay migración por particiones en esta versión.`);
+                }
+                if (fact.kind === 'assignment') {
+                    if (this.wantAssignment(catalog, now, ctx, {
+                        holder: fact.holder,
+                        scope: fact.scope,
+                        roleUuid: String(fact.roleUuid ?? ''),
+                        expiresAt: fact.expiresAt ?? null,
+                        detail: fact.detail,
+                    })) {
+                        usable += 1;
+                    }
+                    continue;
+                }
+                if (!fact.permission) {
+                    ctx.note('deny', 'unknown-permission', fact.detail);
+                    continue;
+                }
+                if (this.wantDeny(ctx, {
+                    holder: fact.holder,
+                    scope: fact.scope,
+                    permission: fact.permission,
+                    detail: fact.detail,
+                })) {
+                    usable += 1;
+                }
+            }
+            const cursor = got.cursor;
+            if (!cursor)
+                break;
+            if (seenCursors.has(cursor)) {
+                throw new AuthorizationInternalError(`authz:reconcile: el cursor del origen se repite (página ${page + 1}); no avanza`);
+            }
+            seenCursors.add(cursor);
+            after = cursor;
+        }
+        return { rows, usable };
+    }
+    /**
+     * 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.
+     */
+    wantAssignment(catalog, now, ctx, fact) {
+        if (fact.expiresAt !== null && fact.expiresAt <= now) {
+            ctx.note('assignment', 'expired', fact.detail);
+            return false;
+        }
+        const key = scopeKey(fact.scope);
+        const chain = ctx.chainOf(key);
+        if (chain === null) {
+            ctx.note('assignment', 'unknown-scope', fact.detail);
+            return false;
+        }
+        const role = catalog.roleByUuid(fact.roleUuid);
+        if (!role) {
+            ctx.note('assignment', 'unknown-role', fact.detail);
+            return false;
+        }
+        let user;
+        try {
+            user = this.fgaSubject(fact.holder);
+        }
+        catch {
+            ctx.note('assignment', 'unknown-holder-type', fact.detail);
+            return false;
+        }
+        const object = factsBindingObject(key, role.uuid);
+        ctx.want({ user, relation: FACTS_ASSIGNEE_RELATION, object }, 'facts', fact.expiresAt);
+        ctx.want({ user: `${FACTS_ROLE_TYPE}:${role.uuid}`, relation: FACTS_ROLE_RELATION, object }, 'facts');
+        // La arista `scope#binding` significa «el rol es VISIBLE aquí»
+        // (3b-2g · R1), y la regla es la misma que evalúa `database` en cada
+        // pregunta: nivel declarado + owner en la cadena.
+        const edge = factsScopeBindingTuple(key, role.uuid);
+        if (declaredRoleAt(catalog, role.uuid, fact.scope.type, chain)) {
+            ctx.want(edge, 'facts');
+        }
+        else {
+            ctx.forbidden.add(factsTupleId(edge));
+            ctx.note('assignment', 'role-not-visible', fact.detail);
+        }
+        return true;
+    }
+    /** Un DENY del origen (permiso ya como slug) traducido a `scope#denied_<P>`. */
+    wantDeny(ctx, fact) {
+        if (!ctx.usable(fact.permission)) {
+            ctx.note('deny', 'permission-not-in-model', fact.detail);
+            return false;
+        }
+        const key = scopeKey(fact.scope);
+        if (ctx.chainOf(key) === null) {
+            ctx.note('deny', 'unknown-scope', fact.detail);
+            return false;
+        }
+        let user;
+        try {
+            user = this.fgaSubject(fact.holder);
+        }
+        catch {
+            ctx.note('deny', 'unknown-holder-type', fact.detail);
+            return false;
+        }
+        ctx.want(factsDenyTuple(key, fact.permission, user), 'facts');
+        return true;
+    }
+    /**
+     * 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.
+     */
+    async eachRow(client, operation, batchSize, build, handle) {
+        let after;
+        for (;;) {
+            const rows = await this.sql(operation, () => {
+                const query = build(client);
+                if (after !== undefined)
+                    query.where('uuid', '>', after);
+                return query.orderBy('uuid', 'asc').limit(batchSize);
+            });
+            for (const row of rows)
+                handle(row);
+            if (rows.length < batchSize)
+                return;
+            after = String(rows[rows.length - 1].uuid);
+        }
+    }
+    /**
+     * **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.
+     */
+    async enumerateFacts(page) {
+        const limit = Math.trunc(page.limit);
+        if (!Number.isFinite(limit) || limit < 1) {
+            throw new AuthorizationConfigError(`enumerateFacts: limit debe ser un entero >= 1 (llegó ${String(page.limit)})`);
+        }
+        const catalog = await this.catalog.view();
+        const permissionByRelation = new Map();
+        for (const slug of catalog.permissionSlugs) {
+            permissionByRelation.set(factsRelationsOf(slug).denied, slug);
+        }
+        const fgaToMorph = Object.fromEntries(Object.entries(this.holderTypes).map(([morph, fga]) => [fga, morph]));
+        const holderOf = (user) => {
+            const separator = user.indexOf(':');
+            if (separator <= 0)
+                return null;
+            const morph = fgaToMorph[user.slice(0, separator)];
+            const uuid = user.slice(separator + 1);
+            if (!morph || !uuid || uuid.includes('#') || uuid === '*')
+                return null;
+            return { type: morph, uuid };
+        };
+        const facts = [];
+        const skipped = [];
+        // El `pageSize` que se le pide al servidor va acotado por el tope de
+        // página del driver: pedir 1 000 es un 400 del servidor, y el contrato del
+        // puerto es «como mucho `limit`», no «exactamente `limit`».
+        const response = await this.client.read({}, { pageSize: Math.min(limit, READ_PAGE_SIZE), continuationToken: page.after, consistency: this.consistency });
+        for (const tuple of response.tuples ?? []) {
+            const key = tuple?.key;
+            if (!key?.user || !key?.relation || !key?.object) {
+                skipped.push({ kind: 'tuple', reason: 'unparseable-tuple', detail: JSON.stringify(key ?? null) });
+                continue;
+            }
+            const id = `${key.user}#${key.relation}@${key.object}`;
+            if (key.relation === FACTS_ASSIGNEE_RELATION) {
+                const binding = key.object.startsWith(`${FACTS_BINDING_TYPE}:`)
+                    ? parseBindingId(key.object.slice(FACTS_BINDING_TYPE.length + 1))
+                    : null;
+                if (!binding) {
+                    // Un id de binding que este motor no escribiría (los de 1.x/2.1
+                    // llevaban el slug): es un hecho que NADIE puede migrar.
+                    skipped.push({ kind: 'tuple', reason: 'unparseable-binding', detail: id });
+                    continue;
+                }
+                const holder = holderOf(key.user);
+                if (!holder) {
+                    skipped.push({ kind: 'tuple', reason: 'unknown-holder-type', detail: id });
+                    continue;
+                }
+                facts.push({
+                    kind: 'assignment',
+                    holder,
+                    scope: binding.scope,
+                    roleUuid: binding.uuid,
+                    expiresAt: toExpiryDate(key.condition?.context?.valid_until),
+                    detail: id,
+                });
+                continue;
+            }
+            if (key.relation.startsWith(FACTS_DENIED_PREFIX) && key.object.startsWith(`${FACTS_SCOPE_TYPE}:`)) {
+                const permission = permissionByRelation.get(key.relation);
+                if (!permission) {
+                    // La relación existe en el modelo pero el catálogo ya no declara
+                    // ese permiso (D5): no es un deny, y quien lo recoge es `--prune`.
+                    skipped.push({ kind: 'tuple', reason: 'unknown-permission', detail: id });
+                    continue;
+                }
+                const scope = scopeFromKey(key.object.slice(FACTS_SCOPE_TYPE.length + 1));
+                if (!scope) {
+                    skipped.push({ kind: 'tuple', reason: 'invalid-scope', detail: id });
+                    continue;
+                }
+                const holder = holderOf(key.user);
+                if (!holder) {
+                    skipped.push({ kind: 'tuple', reason: 'unknown-holder-type', detail: id });
+                    continue;
+                }
+                facts.push({ kind: 'deny', holder, scope, permission, detail: id });
+                continue;
+            }
+            // **El deny del modo `resolver` de 2.2 ES un hecho y se emite** (3b-8 ·
+            // A2): `deny_binding:<scopeKey>|<permissionUuid>#denied@<holder>`. El
+            // modelo (c2r) ni declara ese tipo, pero un store escrito por la
+            // versión anterior lo tiene, y `reconcile` es el sustituto documentado
+            // del importador borrado en 3b-2k · K2: descartarlo en silencio perdía
+            // los denies explícitos de la migración con el verificador en VERDE
+            // (invariante 2 roto sin una línea en ningún contador). El permiso va
+            // por uuid en el id (así los escribía 2.2); el catálogo local lo
+            // traduce a slug, y lo que no traduce sale contado, jamás mudo.
+            if (key.relation === LEGACY_DENIED_RELATION && key.object.startsWith(`${LEGACY_DENY_BINDING_TYPE}:`)) {
+                const binding = parseBindingId(key.object.slice(LEGACY_DENY_BINDING_TYPE.length + 1));
+                if (!binding) {
+                    skipped.push({ kind: 'tuple', reason: 'unparseable-binding', detail: id });
+                    continue;
+                }
+                const permission = catalog.permissionSlug(binding.uuid);
+                if (!permission) {
+                    skipped.push({ kind: 'tuple', reason: 'unknown-permission', detail: id });
+                    continue;
+                }
+                const holder = holderOf(key.user);
+                if (!holder) {
+                    skipped.push({ kind: 'tuple', reason: 'unknown-holder-type', detail: id });
+                    continue;
+                }
+                facts.push({ kind: 'deny', holder, scope: binding.scope, permission, detail: id });
+                continue;
+            }
+            // Estructura y proyección del catálogo: derivado, no es un hecho.
+        }
+        const cursor = response.continuation_token || undefined;
+        return { facts, ...(skipped.length ? { skipped } : {}), ...(cursor ? { cursor } : {}) };
+    }
+    /**
+     * 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.
+     */
+    async readEveryTuple(maxTuples) {
+        const out = [];
+        let continuationToken;
+        const seenTokens = new Set();
+        let pages = 0;
+        do {
+            const response = await this.client.read({}, { pageSize: READ_PAGE_SIZE, continuationToken, consistency: this.consistency });
+            pages += 1;
+            for (const tuple of response.tuples ?? []) {
+                const key = tuple?.key;
+                if (!key?.user || !key?.relation || !key?.object) {
+                    this.diagnostics.unparseableBindings += 1;
+                    this.warn(`authz(openfga): tupla malformada en el Read de reconcile (${JSON.stringify(key ?? null)}); ` +
+                        `no se puede comparar (total: ${this.diagnostics.unparseableBindings})`);
+                    continue;
+                }
+                out.push({
+                    user: key.user,
+                    relation: key.relation,
+                    object: key.object,
+                    validUntil: toExpiryDate(key.condition?.context?.valid_until),
+                });
+                if (out.length > maxTuples) {
+                    throw new ReconcileTooLargeError(`authz:reconcile --to=openfga: el store pasa de maxTuples (${maxTuples}) tuplas y la pasada ` +
+                        `necesita la foto ENTERA del destino para saber qué sobra (que es la mitad del trabajo: ` +
+                        `las aristas que ya nadie respalda, el nodo con dos padres, la basura de otra versión). ` +
+                        `Sube maxTuples si tu proceso lo aguanta; no hay migración por particiones en esta versión.`);
+                }
+            }
+            continuationToken = response.continuation_token || undefined;
+            if (continuationToken) {
+                if (seenTokens.has(continuationToken)) {
+                    throw new AuthorizationInternalError(`reconcile: el continuation_token se repite (página ${pages}); el servidor no avanza`);
+                }
+                if (pages >= MAX_READ_PAGES) {
+                    throw new AuthorizationInternalError(`reconcile: más de ${MAX_READ_PAGES} páginas sin agotar el store`);
+                }
+                seenTokens.add(continuationToken);
+            }
+        } while (continuationToken);
+        return out;
+    }
+    /**
+     * 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—.
+     */
+    async applyReconcileWrites(deletes, writes) {
+        for (let i = 0; i < deletes.length; i += PURGE_BATCH_SIZE) {
+            await this.client.deleteTuples(deletes.slice(i, i + PURGE_BATCH_SIZE), {
+                conflict: { onMissingDeletes: ClientWriteRequestOnMissingDeletes.Ignore },
+            });
+        }
+        for (let i = 0; i < writes.length; i += PURGE_BATCH_SIZE) {
+            await this.client.writeTuples(writes.slice(i, i + PURGE_BATCH_SIZE), IGNORE_DUPLICATE_WRITES);
+        }
+    }
+    /**
+     * TODAS las tuplas que casan con el filtro, paginando `Read` hasta agotar
+     * el `continuation_token`, sin las caducadas. Es la única primitiva de
+     * enumeración del driver (L0.7): `Read` no tiene tope de resultados —a
+     * diferencia de `ListObjects`/`ListUsers`, que cortan al máximo del
+     * servidor sin ninguna señal— y devuelve la condición de cada tupla, así
+     * que la caducidad se filtra aquí con el mismo reloj que `checkContext`.
+     *
+     * Contrapartida, documentada en el README: `Read` devuelve tuplas
+     * ESCRITAS, no relaciones computadas. Con el modelo que genera este paquete
+     * (`assignee`/`denied` directas) es exactamente lo mismo; un modelo
+     * extendido con relaciones derivadas sobre `role_binding` no se enumeraría
+     * por aquí.
+     */
+    async readAllTuples(filter, options = {}) {
+        // El instante con el que se filtra: el de la operación si lo trae (K9), o
+        // el de esta lectura.
+        const now = options.at ?? this.now();
+        const keys = [];
+        let continuationToken;
+        const seenTokens = new Set();
+        let pages = 0;
+        do {
+            const response = await this.client.read(filter, {
+                pageSize: READ_PAGE_SIZE,
+                continuationToken,
+                consistency: this.consistency,
+            });
+            pages += 1;
+            for (const tuple of response.tuples ?? []) {
+                const k = tuple?.key;
+                if (!k?.user || !k?.relation || !k?.object) {
+                    // Una tupla que el motor no puede leer es un hecho que las
+                    // enumeraciones NO muestran: se cuenta y se registra (L0.16, H16).
+                    this.diagnostics.unparseableBindings += 1;
+                    this.warn(`authz(openfga): tupla malformada en Read ${JSON.stringify(filter)} (${JSON.stringify(k ?? null)}); se ignora en la enumeración (total: ${this.diagnostics.unparseableBindings})`);
+                    continue;
+                }
+                if (!options.includeExpired) {
+                    const validUntil = toExpiryDate(k.condition?.context?.valid_until);
+                    if (validUntil && validUntil <= now)
+                        continue;
+                }
+                keys.push({ user: k.user, relation: k.relation, object: k.object });
+            }
+            continuationToken = response.continuation_token || undefined;
+            if (continuationToken) {
+                if (seenTokens.has(continuationToken)) {
+                    throw new AuthorizationInternalError(`Read ${JSON.stringify(filter)}: el continuation_token se repite (página ${pages}); el servidor no avanza`);
+                }
+                if (pages >= MAX_READ_PAGES) {
+                    throw new AuthorizationInternalError(`Read ${JSON.stringify(filter)}: más de ${MAX_READ_PAGES} páginas sin agotar el continuation_token`);
+                }
+                seenTokens.add(continuationToken);
+            }
+        } while (continuationToken);
+        return keys;
+    }
+}
+/* ── `authz:reconcile` (3b-3a): piezas puras ────────────────────────────── */
+/** Tope de páginas de `scopes.enumerateEdges` (10 000 000 de nodos a 100). */
+const RECONCILE_MAX_PAGES = 100_000;
+/**
+ * A qué FAMILIA pertenece una tupla del store, que es lo que decide si esta
+ * pasada puede borrarla por su cuenta:
+ *  - `root`, `catalog` y `tree` son ESPEJOS de datos locales (el `holderTypes`
+ *    del config, `authz_roles`/`authz_permissions`, `scopes.enumerateEdges`)
+ *    que nadie más escribe: lo que sobra se borra siempre;
+ *  - todo lo demás son HECHOS —`assignee`, las dos aristas de (c2), los
+ *    `denied_<P>` y cualquier tupla de un modelo anterior— y solo los borra
+ *    `--prune`.
+ */
+function familyOfTuple(tuple) {
+    if (tuple.relation === FACTS_ROOTED_RELATION)
+        return 'root';
+    if (tuple.object.startsWith(`${FACTS_ROLE_TYPE}:`) && tuple.relation.startsWith(FACTS_PERMITS_PREFIX))
+        return 'catalog';
+    if (tuple.object.startsWith(`${FACTS_SCOPE_TYPE}:`) && tuple.relation === FACTS_PARENT_RELATION)
+        return 'tree';
+    return 'facts';
+}
+/** La clave sola: un `delete` de FGA no lleva condición. */
+function bareTuple(tuple) {
+    return { user: tuple.user, relation: tuple.relation, object: tuple.object };
+}
+/** La tupla tal como se ESCRIBE: con la condición `not_expired` si caduca. */
+function reconcileWriteForm(target) {
+    if (target.validUntil === null)
+        return target.tuple;
+    return {
+        ...target.tuple,
+        condition: { name: 'not_expired', context: { valid_until: target.validUntil.toISOString() } },
+    };
+}
+/**
+ * ¿Se llega a `target` subiendo desde `from`? Devuelve el camino recorrido
+ * (`[from, ..., target]`) o `null`. Es el anti-ciclos del árbol del ORIGEN: la
+ * arista que cierra el ciclo es la que se está clasificando, así que el mapa
+ * por el que se sube NUNCA tiene uno (el cinturón de `seen` es por si acaso).
+ */
+function walkUpTo(parentOf, from, target) {
+    const path = [];
+    const seen = new Set();
+    let current = from;
+    while (current !== undefined && !seen.has(current)) {
+        path.push(current);
+        if (current === target)
+            return path;
+        seen.add(current);
+        current = parentOf.get(current);
+    }
+    return null;
 }
 //# sourceMappingURL=openfga_driver.js.map