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

package/build/src/drivers/database_driver.js

@@ -3,12 +3,14 @@ import { v7 as uuidv7 } from 'uuid';
 import { APP_SCOPE_TYPE } from '../types.js';
 import { assertCatalogUuid, assertIdentity, assertScope, chainKeysFrom, normalizeRoleQuery } from '../identity.js';
 import { resolveGrantExpiry, sameInstant } from '../expiry.js';
-import { AuthorizationBackendError, AuthorizationConfigError, AuthorizationInternalError, InvalidIdentityError, RoleNotVisibleError, UnknownPermissionError, UnknownRoleError, } from '../errors.js';
-import { assertKnownScope, canonicalScope, guardSql, resolveChain, rootOnlyResolver } from './backend_guard.js';
-import { assertAssignableAt } from '../catalog.js';
-import { CatalogCache, GLOBAL_OWNER_KEY, assertCatalogOptions, isRoleVisibleWith, withAuthzCatalogWrite } from '../catalog_cache.js';
+import { AuthorizationBackendError, AuthorizationConfigError, AuthorizationInternalError, InvalidIdentityError, MassReconcileRefusedError, ReconcileTooLargeError, RoleNotVisibleError, UnknownPermissionError, UnknownRoleError, UnsupportedOperationError, WriteConflictError, } from '../errors.js';
+import { RECONCILE_MAX_DETAILS, emptyReconcilePhases, reconcileBatchSize, reconcileMaxTuples, sumReconcilePhases, } from '../reconcile.js';
+import { assertKnownScope, canonicalScope, canonicalScopeTargets, guardSql, isUniqueViolation, resolveChain, rootOnlyResolver, } from '../shared/backend_guard.js';
+import { assertCallerTransaction } from '../shared/transaction_guard.js';
+import { assertAssignableAt } from '../catalog/catalog.js';
+import { CatalogCache, GLOBAL_OWNER_KEY, assertCatalogOptions, isRoleVisibleWith, withAuthzCatalogWrite } from '../catalog/catalog_cache.js';
 import { isClock, systemClock } from '../clock.js';
-import { sqlExpiryCodec } from './sql_expiry.js';
+import { sqlExpiryCodec } from '../shared/sql_expiry.js';
 /**
  * UUID centinela para el scope 'app' en las columnas scope_uuid (NOT NULL):
  * permite que el unique de assignments/denies cubra también el nivel app
@@ -23,7 +25,15 @@ function toDbScopeUuid(scope) {
     assertScope(scope);
     return scope.uuid ?? APP_SCOPE_DB_UUID;
 }
-function fromDbScopeUuid(uuid) {
+/**
+ * La vuelta de `toDbScopeUuid`: el centinela de la raíz vuelve a ser `null`.
+ * **Exportada desde 3b-3b**: `authz:reconcile --to=openfga` lee estas mismas
+ * columnas y hacía `row.scope_uuid ?? null`, que con la columna NOT NULL
+ * nunca es null — un grant o un deny en la RAÍZ reventaban la migración con
+ * un 422 a mitad de pasada (`el scope 'app' no admite uuid`). Lo cazó el
+ * contrato de migración, cuya siembra fija sí concede en `app`.
+ */
+export function fromDbScopeUuid(uuid) {
     return uuid === APP_SCOPE_DB_UUID ? null : uuid;
 }
 /**
@@ -38,6 +48,35 @@ function dbScopeKey(scope) {
 function rowScopeKey(row) {
     return `${row.scope_type}\u001f${row.scope_uuid}`;
 }
+/**
+ * Clave de comparación de una asignación. **Es exactamente el unique
+ * `authz_asg_holder_role_scope_uq`** y NO incluye `expires_at`: cambiar la
+ * caducidad es un UPDATE de la misma fila, no una fila nueva (invariante 6).
+ * Que la clave del diff sea la del índice es lo que hace que la migración no
+ * pueda dejar dos filas del mismo hecho ni chocar con el unique al insertar.
+ */
+function assignmentKey(row) {
+    return [row.holder_type, row.holder_uuid, row.role_uuid, row.scope_type, row.scope_uuid].join('\u001f');
+}
+function denyKey(row) {
+    return [row.holder_type, row.holder_uuid, row.permission_uuid, row.scope_type, row.scope_uuid].join('\u001f');
+}
+/**
+ * La caducidad que dura MÁS (`null` = para siempre). Es la regla con la que
+ * se resuelve un colapso de dos hechos del origen en una sola fila: el
+ * origen concedía mientras CUALQUIERA de los dos siguiera vivo, así que la
+ * unión es lo que conserva la respuesta.
+ */
+function longerExpiry(a, b) {
+    if (a === null || b === null)
+        return null;
+    return a >= b ? a : b;
+}
+/** Cómo se NOMBRA una fila del destino en `details`: sin esto un motivo no se arregla. */
+function reconcileRowLabel(row) {
+    const what = row.role_uuid ? `→ ${row.role_uuid}` : `⊘ ${row.permission_uuid}`;
+    return `${row.holder_type}:${row.holder_uuid} ${what} @ ${row.scope_type}:${row.scope_uuid}`;
+}
 /**
  * El rol `(slug, scopeType)` que existe en el scope cuya cadena empieza por
  * `chainKeys`, o 422: `E_AUTHZ_ROLE_NOT_VISIBLE` si hay roles con ese nombre
@@ -220,6 +259,21 @@ export const DEFAULT_TIMEOUT_MS = 5_000;
  * crudo de knex (L0.11).
  */
 export class DatabaseAuthorizationDriver {
+    /**
+     * Lo que este driver declara (3b-2e · E2). El árbol es del consumidor
+     * (`resolveChain`), así que no hay hechos de jerarquía ni deriva que
+     * mitigar; `authorize` son varias consultas SQL; la membresía la resuelve
+     * el propio SQL contra la cadena que le pasan; los `list*` no enumeran
+     * herencia (invariante 7); y `purgeRole` está implementado en una
+     * transacción.
+     */
+    capabilities;
+    /**
+     * Con `transactionalWrites: false` declarado por el despliegue, un
+     * `{ transaction }` que llegara igual (un llamante que se salta el manager)
+     * se rechaza aquí también: no se ignora en silencio.
+     */
+    transactionalWrites;
     /**
      * Resolutor de jerarquía inyectado por el consumidor (el chasis pasa el
      * suyo, que conoce organizations/units, en `config/authorization.ts`).
@@ -250,6 +304,30 @@ export class DatabaseAuthorizationDriver {
             throw new AuthorizationConfigError(`DatabaseAuthorizationDriver: 'now' debe ser una función () => Date (llegó ${typeof options.now})`);
         }
         this.now = options.now ?? systemClock;
+        this.transactionalWrites = options.transactionalWrites ?? true;
+        this.capabilities = Object.freeze({
+            hierarchyFacts: false,
+            singleCheckAuthorize: false,
+            roleInheritanceNative: false,
+            listObjectsInherited: false,
+            purgeRole: true,
+            countRoleAssignments: true,
+            // 3b-2k · K1: `authorize` resuelve la cadena y usa `chain[0]`, así que un
+            // alias del uuid que el árbol funde con la fila real encuentra sus hechos.
+            canonicalScopeReads: true,
+            // 3b-3b: sus hechos son `authz_assignments`/`authz_denies` —el esquema
+            // PUBLICADO del paquete—, así que el destino los lee de ahí y no por el
+            // puerto. No es «no sabe»: es que no hace falta un método para leer una
+            // tabla documentada. Un driver de terceros que quiera ser origen sí lo
+            // necesita, y por eso la capacidad tiene sus dos caras.
+            enumerateFacts: false,
+            // L-3: `grant`/`revoke`/`deny`/`removeDeny` escriben por la transacción
+            // ABIERTA del llamante (`writer()`: `assertCallerTransaction` contra la
+            // conexión primaria de Lucid). Lo que NO viaja por ella: el catálogo,
+            // `resolveChain` y la barrera del freeze (autoridad). Un despliegue con
+            // pool 1 lo declara `false` (ver `DatabaseDriverOptions`).
+            transactionalWrites: this.transactionalWrites,
+        });
         assertCatalogOptions('DatabaseAuthorizationDriver', options);
         this.catalog =
             options.catalog ??
@@ -296,10 +374,14 @@ export class DatabaseAuthorizationDriver {
     knownScope(scope, operation) {
         return assertKnownScope(this.chainResolver, scope, operation);
     }
-    /** El scope canónico para `revoke`/`removeDeny`/`purgeScope` (ver `canonicalScope`). */
+    /** El scope canónico para `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);
+    }
     /**
      * Ejecuta una consulta clasificando su fallo (503 con código propio). `fn`
      * devuelve el BUILDER sin ejecutar: el guard le fija el deadline y luego lo
@@ -313,6 +395,49 @@ export class DatabaseAuthorizationDriver {
         const rows = await this.sql(operation, () => fn().limit(1));
         return rows[0] ?? null;
     }
+    /**
+     * Por dónde escribe `operation` (L-3): la transacción ABIERTA del llamante
+     * si llegó en `options.transaction` —validada contra la conexión de este
+     * driver, la primaria de Lucid, por la que escribe todo lo demás: otra
+     * conexión, un `QueryClient` o el `db` entero son 500 `E_AUTHZ_CONFIG`
+     * ANTES de tocar nada—, o `db`. `external` dice cuál de los dos.
+     *
+     * Solo la ESCRITURA va por ella. La lectura de «¿ya existe?» de
+     * `grant`/`deny` también, porque forma parte de la misma escritura (tiene
+     * que ver lo que TU transacción ya escribió: un `grant` y su re-grant en la
+     * misma transacción); el catálogo y `resolveChain` no (autoridad, L-1).
+     */
+    writer(operation, options) {
+        if (options?.transaction === undefined || options.transaction === null)
+            return { client: db, external: false };
+        if (!this.transactionalWrites) {
+            throw new UnsupportedOperationError('transactionalWrites', operation, 'database', 'Este despliegue declara transactionalWrites: false en las opciones del driver (pool 1): { transaction } ' +
+                'no se admite. Quita la opción (exige pool ≥ 2) o no pases transaction.');
+        }
+        const trx = assertCallerTransaction(`database.${operation}`, options.transaction, { connection: db.primaryConnectionName });
+        return { client: trx, external: true };
+    }
+    /**
+     * Un INSERT que falla DENTRO de la transacción del llamante no se absorbe
+     * (L-3). Fuera de ella `grant`/`deny` releen y se quedan con lo del ganador
+     * (K4); dentro no se puede: en PostgreSQL la transacción ya está ABORTADA
+     * (toda sentencia posterior es `25P02` hasta el rollback) y en REPEATABLE
+     * READ (MySQL por defecto) la relectura no vería al ganador. Así que un
+     * choque del UNIQUE sale como **409 `E_AUTHZ_WRITE_CONFLICT`** —«envenena
+     * tu transacción: haz rollback y reintenta»—, un deadline vencido sigue
+     * siendo el 503 `E_AUTHZ_BACKEND_TIMEOUT` que ya clasificó `sql()` (con
+     * `onWrite` `indeterminate: true` en el manager) y cualquier otro fallo, su
+     * 503. Nunca una segunda sentencia sobre una transacción que puede estar
+     * abortada.
+     */
+    poisoned(operation, error) {
+        if (isUniqueViolation(error)) {
+            throw new WriteConflictError(`database.${operation}: el hecho lo escribió otra transacción mientras la tuya estaba abierta (choque del ` +
+                'UNIQUE dentro de tu transacción). No se puede absorber ahí dentro: la transacción queda envenenada ' +
+                '(en PostgreSQL, abortada). Haz rollback y reintenta.', { cause: error });
+        }
+        throw error;
+    }
     get expiry() {
         // Decidir el dialecto no cuesta ninguna consulta: una vista por
         // prototipo (`withClock`/`withChainResolver`) hereda el codec del driver
@@ -402,7 +527,11 @@ export class DatabaseAuthorizationDriver {
         const declared = resolveRoleQuery(catalog, role, target, chainKeysFrom(chain)[0]);
         assertRoleAssignableAt(catalog, declared);
         const roleUuid = declared.uuid;
-        const findExisting = () => whereScopeIn(db
+        // L-3: la ESCRITURA (y la lectura «¿ya existe?» que forma parte de ella)
+        // va por la transacción del llamante si llegó; todo lo de arriba
+        // (árbol, catálogo) fue por la conexión del motor.
+        const { client, external } = this.writer('grant', options);
+        const findExisting = () => whereScopeIn(client
             .from('authz_assignments')
             .where('holder_type', subject.type)
             .where('holder_uuid', subject.uuid)
@@ -416,7 +545,7 @@ export class DatabaseAuthorizationDriver {
         for (let attempt = 0; attempt < 3; attempt++) {
             const existing = await this.first('grant.find', findExisting);
             if (existing) {
-                const refreshed = await this.refreshAssignment(existing, options.expiresAt);
+                const refreshed = await this.refreshAssignment(existing, options.expiresAt, client);
                 if (refreshed)
                     return refreshed;
                 continue;
@@ -424,7 +553,7 @@ export class DatabaseAuthorizationDriver {
             // No había nada: la caducidad es la pedida, o ninguna.
             const expiresAt = options.expiresAt ?? null;
             try {
-                await this.sql('grant.insert', () => db.table('authz_assignments').insert({
+                await this.sql('grant.insert', () => client.table('authz_assignments').insert({
                     uuid: uuidv7(),
                     holder_type: subject.type,
                     holder_uuid: subject.uuid,
@@ -438,6 +567,10 @@ export class DatabaseAuthorizationDriver {
                 return { existed: false, expiresAt };
             }
             catch (error) {
+                // Dentro de la transacción del llamante no hay relectura que valga
+                // (L-3, `poisoned`): 409 si fue el UNIQUE, si no el error tal cual.
+                if (external)
+                    this.poisoned('grant', error);
                 // Carrera check-then-insert: el unique (que cubre también el nivel app
                 // vía centinela) la detecta — el perdedor degrada a re-grant sobre lo
                 // que escribió el ganador (con la misma semántica de tres estados).
@@ -445,7 +578,7 @@ export class DatabaseAuthorizationDriver {
                 const raced = await this.first('grant.race', findExisting);
                 if (!raced)
                     throw error;
-                const refreshed = await this.refreshAssignment(raced, options.expiresAt);
+                const refreshed = await this.refreshAssignment(raced, options.expiresAt, client);
                 if (refreshed)
                     return refreshed;
             }
@@ -459,17 +592,17 @@ export class DatabaseAuthorizationDriver {
      * UPDATE no toca ninguna fila (otro proceso la borró entre la lectura y la
      * escritura, K4) devuelve `null`: no hay «existed: true» sobre nada.
      */
-    async refreshAssignment(row, requested) {
+    async refreshAssignment(row, requested, client) {
         const previous = this.expiry.fromDb(row.expires_at);
         const expiresAt = resolveGrantExpiry(previous, requested, this.now());
         if (!sameInstant(previous, expiresAt)) {
-            const updated = await this.sql('grant.update', () => db.from('authz_assignments').where('uuid', row.uuid).update({ expires_at: this.expiry.toDb(expiresAt) }));
+            const updated = await this.sql('grant.update', () => client.from('authz_assignments').where('uuid', row.uuid).update({ expires_at: this.expiry.toDb(expiresAt) }));
             if (Number(Array.isArray(updated) ? updated[0] : updated) === 0)
                 return null;
         }
         return { existed: true, previousExpiresAt: previous, expiresAt };
     }
-    async revoke(subject, role, scope) {
+    async revoke(subject, role, scope, options) {
         assertIdentity({ subject, role, scope });
         // Rol fuera del catálogo para ese nivel ⇒ 422, como en `grant` (D10). El
         // no-op es para una asignación inexistente de un rol válido. Se quitan
@@ -478,12 +611,17 @@ export class DatabaseAuthorizationDriver {
         // scope puede no existir ya para el árbol (D8), así que no se filtra por
         // visibilidad — quitar nunca concede.
         const named = rolesToRevoke(await this.catalog.view(), role, scope);
-        const target = await this.canonicalOrSelf(scope, 'revoke');
-        await this.sql('revoke', () => whereScopeIn(db
+        // Sin cadena con la que canonizar, TODAS las ortografías de las que el
+        // uuid puede ser alias (3b-8 · A4, mismo fan-out que `scopes.detached`):
+        // con una sola, un alias hacía del DELETE un no-op silencioso y la fila
+        // canónica seguía concediendo si el scope se restauraba.
+        const targets = await this.canonicalTargets(scope, 'revoke');
+        const { client } = this.writer('revoke', options);
+        await this.sql('revoke', () => whereScopeIn(client
             .from('authz_assignments')
             .where('holder_type', subject.type)
             .where('holder_uuid', subject.uuid)
-            .whereIn('role_uuid', named.map((r) => r.uuid)), 'scope', [target], 'write').delete());
+            .whereIn('role_uuid', named.map((r) => r.uuid)), 'scope', targets, 'write').delete());
     }
     async hasRole(subject, role, scope) {
         assertIdentity({ subject, role, scope });
@@ -514,13 +652,14 @@ export class DatabaseAuthorizationDriver {
         const found = await this.first('hasRole', () => this.whereActive(query, 'a.expires_at'));
         return Boolean(found);
     }
-    async deny(subject, permission, scope) {
+    async deny(subject, permission, scope, options) {
         assertIdentity({ subject, permission, scope });
         const perm = await this.findPermission(permission);
         if (!perm)
             throw new UnknownPermissionError(permission);
         const [target] = await this.knownScope(scope, 'deny');
-        const findExisting = () => whereScopeIn(db
+        const { client, external } = this.writer('deny', options);
+        const findExisting = () => whereScopeIn(client
             .from('authz_denies')
             .where('holder_type', subject.type)
             .where('holder_uuid', subject.uuid)
@@ -529,7 +668,7 @@ export class DatabaseAuthorizationDriver {
         if (existing)
             return;
         try {
-            await this.sql('deny.insert', () => db.table('authz_denies').insert({
+            await this.sql('deny.insert', () => client.table('authz_denies').insert({
                 uuid: uuidv7(),
                 holder_type: subject.type,
                 holder_uuid: subject.uuid,
@@ -540,6 +679,9 @@ export class DatabaseAuthorizationDriver {
             }));
         }
         catch (error) {
+            // Dentro de la transacción del llamante no se relee (L-3, `poisoned`).
+            if (external)
+                this.poisoned('deny', error);
             // Carrera: si otro proceso insertó el mismo deny, el unique lo detecta
             // y el resultado deseado ya existe.
             const raced = await this.first('deny.race', findExisting);
@@ -547,17 +689,20 @@ export class DatabaseAuthorizationDriver {
                 throw error;
         }
     }
-    async removeDeny(subject, permission, scope) {
+    async removeDeny(subject, permission, scope, options) {
         assertIdentity({ subject, permission, scope });
         const perm = await this.findPermission(permission);
         if (!perm)
             throw new UnknownPermissionError(permission);
-        const target = await this.canonicalOrSelf(scope, 'removeDeny');
-        await this.sql('removeDeny', () => whereScopeIn(db
+        // 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');
+        const { client } = this.writer('removeDeny', options);
+        await this.sql('removeDeny', () => whereScopeIn(client
             .from('authz_denies')
             .where('holder_type', subject.type)
             .where('holder_uuid', subject.uuid)
-            .where('permission_uuid', perm.uuid), 'scope', [target], 'write').delete());
+            .where('permission_uuid', perm.uuid), 'scope', targets, 'write').delete());
     }
     async listSubjects(role, scope) {
         assertIdentity({ role, scope });
@@ -821,5 +966,346 @@ export class DatabaseAuthorizationDriver {
             this.catalog.invalidate();
         }
     }
+    /**
+     * Cuántos hechos VIGENTES tiene cada rol, en todos los scopes (3b-2j). Es
+     * lo que `pruneOrphanRoles` necesita para decir si un huérfano todavía
+     * concede, y es una pregunta del PUERTO porque los hechos son del driver:
+     * aquí son filas de `authz_assignments`, en `openfga` son tuplas del store.
+     *
+     * Una consulta agrupada para todos los uuids (no una por rol) y la misma
+     * caducidad ESTRICTA que el resto del driver, con SU reloj (`whereActive`,
+     * J1): la asignación que vence ahora ya no cuenta, como no cuenta en
+     * `authorize`. Un rol sin hechos —o que no está en la tabla— es `0`.
+     */
+    async countRoleAssignments(roleUuids) {
+        for (const uuid of roleUuids)
+            assertCatalogUuid('rol', uuid);
+        if (roleUuids.length === 0)
+            return [];
+        const rows = await this.sql('countRoleAssignments', () => this.whereActive(db.from('authz_assignments').whereIn('role_uuid', roleUuids))
+            .groupBy('role_uuid')
+            .select('role_uuid')
+            .count('* as total'));
+        const totals = new Map();
+        for (const row of rows)
+            totals.set(String(row.role_uuid), Number(row.total ?? row.count ?? 0));
+        return roleUuids.map((uuid) => totals.get(uuid) ?? 0);
+    }
+    /* ── `authz:reconcile --to=database` (3b-3b) ─────────────────────────── */
+    /**
+     * **Rehace `authz_assignments`/`authz_denies` desde los hechos de OTRO
+     * driver** — la vuelta de la migración, y con ella la simetría que el dueño
+     * compró: «todo en un driver o todo en otro».
+     *
+     * Qué se migra y qué NO, y por qué:
+     *  - **los HECHOS, sí**: es lo único que vive en el otro driver. Llegan por
+     *    `source.facts` —el puerto `enumerateFacts`, paginado— y no por SQL:
+     *    aquí el origen es un store, no una tabla de este paquete.
+     *  - **el ÁRBOL, no**. En esta dirección el árbol NO se migra: el driver
+     *    `database` lo lee de las tablas del CONSUMIDOR en cada pregunta
+     *    (`resolveChain`), que son su fuente de verdad. Copiarlo a algún sitio
+     *    sería inventarse una segunda copia y con ella una deriva que hoy no
+     *    existe. Se usa, eso sí, para decidir qué hecho es migrable
+     *    (`unknown-scope`) y bajo qué identidad CANÓNICA se escribe
+     *    (invariante 17).
+     *  - **el CATÁLOGO, tampoco**: es propiedad local SIEMPRE (regla de higiene
+     *    del paquete), ya está en `authz_*` y ningún driver es su fuente. Aquí
+     *    solo se usa para traducir: un `roleUuid` que el catálogo no declara y
+     *    un permiso que no existe no son hechos migrables.
+     *
+     * Por eso `phases.root`, `phases.catalog` y `phases.tree` son CERO en esta
+     * dirección, y todo el movimiento está en `phases.facts`. Es una respuesta,
+     * no un hueco: los ceros dicen «aquí no hay nada derivado que rehacer».
+     *
+     * El resto del contrato es el mismo que en la ida (3b-3a): idempotente (la
+     * segunda pasada escribe cero), `dryRun` es el VERIFICADOR y es read-only
+     * por contrato —**un `--fix` está prohibido** (cruce 4 · S18) y no se
+     * implementa ni se deja preparado—, nunca silenciosa (`skipped{motivo}` +
+     * `details`), los hechos que sobran solo se borran con `prune`, y el
+     * seguro del origen ciego (`E_AUTHZ_MASS_RECONCILE_REFUSED`) se aplica
+     * igual: un origen que devuelve CERO hechos y un `--prune` detrás vacían
+     * la base, y eso es casi siempre apuntar al store equivocado.
+     */
+    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();
+        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 });
+        };
+        /** `[scope canónico, ...]` memoizado: el árbol del consumidor manda. */
+        const chains = new Map();
+        const canonical = async (scope) => {
+            const key = dbScopeKey(scope);
+            if (!chains.has(key)) {
+                chains.set(key, await resolveChain(source.resolveChain, scope, 'reconcile'));
+            }
+            const chain = chains.get(key);
+            return chain === null ? null : chain[0];
+        };
+        /* 1. Los HECHOS del origen, paginados por el puerto. */
+        const wantedAssignments = new Map();
+        const wantedDenies = new Map();
+        let sourceFacts = 0;
+        /**
+         * Hechos del origen que RESPALDAN algo en el destino (3b-8 · B1). El
+         * seguro de borrado masivo miraba `sourceFacts`, el conteo CRUDO — se
+         * incrementa ANTES de cada skip—, así que un origen cuyos hechos se
+         * descartan TODOS (caducados, scopes que ya no resuelven: la firma de un
+         * store equivocado o de un resolutor ciego) lo esquivaba y `--prune`
+         * vaciaba `authz_assignments`/`authz_denies` sin una sola pregunta. Es el
+         * primo del 🔴 del lote 5, un escalón abajo: el seguro miraba si el
+         * origen estaba VACÍO, no si estaba VACÍO DE HECHOS UTILIZABLES.
+         */
+        let usableFacts = 0;
+        const enumerate = source.facts;
+        if (typeof enumerate !== 'function') {
+            throw new UnsupportedOperationError('enumerateFacts', 'authz:reconcile --to=database', 'origen', `El ORIGEN de la migración tiene que saber enumerar sus hechos: sin eso, esta pasada leería ` +
+                `cero hechos y con --prune vaciaría 'authz_assignments'/'authz_denies'. El driver 'database' ` +
+                `no lo implementa a propósito (sus hechos SON esas tablas).`);
+        }
+        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 ?? [])
+                note(skip.kind, skip.reason, skip.detail);
+            for (const fact of got.facts) {
+                sourceFacts += 1;
+                if (sourceFacts > maxTuples) {
+                    throw new ReconcileTooLargeError(`authz:reconcile --to=database: el ORIGEN pasa de maxTuples (${maxTuples}) hechos y la pasada ` +
+                        `necesita comparar 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.`);
+                }
+                const target = await canonical(fact.scope);
+                if (target === null) {
+                    note(fact.kind, 'unknown-scope', fact.detail);
+                    continue;
+                }
+                if (fact.kind === 'assignment') {
+                    if (fact.expiresAt !== null && fact.expiresAt !== undefined && fact.expiresAt <= now) {
+                        note('assignment', 'expired', fact.detail);
+                        continue;
+                    }
+                    const role = fact.roleUuid ? catalog.roleByUuid(fact.roleUuid) : null;
+                    if (!role) {
+                        note('assignment', 'unknown-role', fact.detail);
+                        continue;
+                    }
+                    const row = {
+                        holder_type: fact.holder.type,
+                        holder_uuid: fact.holder.uuid,
+                        role_uuid: role.uuid,
+                        scope_type: target.type,
+                        scope_uuid: toDbScopeUuid(target),
+                    };
+                    // **Dos hechos del origen que colapsan en UNA fila** (S15, medido):
+                    // el store distingue `scope:unit|AAA` de `scope:unit|aaa` y la tabla
+                    // del consumidor no puede tener las dos (columna `uuid` en
+                    // PostgreSQL, collation `*_ci` en MySQL), así que la cadena
+                    // canónica las funde. No se pierde en silencio: se cuenta con su
+                    // motivo, y la fila se queda con la caducidad que MÁS dura —que es
+                    // lo que el origen respondía, donde bastaba con que UNA siguiera
+                    // viva—.
+                    usableFacts += 1;
+                    const key = assignmentKey(row);
+                    const before = wantedAssignments.get(key);
+                    if (before) {
+                        note('assignment', 'folded-scope', `${before.detail} ≡ ${fact.detail}`);
+                    }
+                    const expiresAt = fact.expiresAt ?? null;
+                    if (!before || longerExpiry(before.expiresAt, expiresAt) === expiresAt) {
+                        wantedAssignments.set(key, { row, expiresAt, detail: fact.detail });
+                    }
+                    continue;
+                }
+                const permission = fact.permission ? catalog.permission(fact.permission) : null;
+                if (!permission) {
+                    note('deny', 'unknown-permission', fact.detail);
+                    continue;
+                }
+                const row = {
+                    holder_type: fact.holder.type,
+                    holder_uuid: fact.holder.uuid,
+                    permission_uuid: permission.uuid,
+                    scope_type: target.type,
+                    scope_uuid: toDbScopeUuid(target),
+                };
+                usableFacts += 1;
+                const denyId = denyKey(row);
+                if (wantedDenies.has(denyId))
+                    note('deny', 'folded-scope', fact.detail);
+                wantedDenies.set(denyId, row);
+            }
+            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;
+        }
+        /* 2. El DESTINO entero, tal como está. */
+        const phases = emptyReconcilePhases();
+        const inserts = [];
+        const updates = [];
+        const deletes = { assignments: [], denies: [] };
+        const seenAssignments = new Set();
+        const seenDenies = new Set();
+        let destinationRows = 0;
+        const countDestination = () => {
+            destinationRows += 1;
+            if (destinationRows > maxTuples) {
+                throw new ReconcileTooLargeError(`authz:reconcile --to=database: el DESTINO pasa de maxTuples (${maxTuples}) filas y la pasada ` +
+                    `necesita la foto entera para saber qué sobra. Sube maxTuples si tu proceso lo aguanta; ` +
+                    `no hay migración por particiones en esta versión.`);
+            }
+        };
+        await this.eachReconcileRow('reconcile.assignments', batchSize, (query) => query
+            .from('authz_assignments')
+            .select('uuid', 'holder_type', 'holder_uuid', 'role_uuid', 'scope_type', 'scope_uuid')
+            .select(this.expiry.select('expires_at')), (row) => {
+            countDestination();
+            const key = assignmentKey(row);
+            const target = wantedAssignments.get(key);
+            if (target) {
+                seenAssignments.add(key);
+                if (sameInstant(this.expiry.fromDb(row.expires_at), target.expiresAt)) {
+                    phases.facts.unchanged += 1;
+                    return;
+                }
+                phases.facts.updated += 1;
+                updates.push({ uuid: String(row.uuid), expiresAt: target.expiresAt });
+                return;
+            }
+            phases.facts.extra += 1;
+            if (!prune) {
+                note('assignment', 'extra-fact', reconcileRowLabel(row));
+                return;
+            }
+            phases.facts.deleted += 1;
+            deletes.assignments.push(String(row.uuid));
+        });
+        await this.eachReconcileRow('reconcile.denies', batchSize, (query) => query
+            .from('authz_denies')
+            .select('uuid', 'holder_type', 'holder_uuid', 'permission_uuid', 'scope_type', 'scope_uuid'), (row) => {
+            countDestination();
+            const key = denyKey(row);
+            if (wantedDenies.has(key)) {
+                seenDenies.add(key);
+                phases.facts.unchanged += 1;
+                return;
+            }
+            phases.facts.extra += 1;
+            if (!prune) {
+                note('deny', 'extra-fact', reconcileRowLabel(row));
+                return;
+            }
+            phases.facts.deleted += 1;
+            deletes.denies.push(String(row.uuid));
+        });
+        for (const [key, target] of wantedAssignments) {
+            if (seenAssignments.has(key))
+                continue;
+            phases.facts.written += 1;
+            inserts.push({
+                table: 'authz_assignments',
+                row: {
+                    uuid: uuidv7(),
+                    ...target.row,
+                    expires_at: this.expiry.toDb(target.expiresAt),
+                    created_at: systemClock(),
+                },
+            });
+        }
+        for (const [key, row] of wantedDenies) {
+            if (seenDenies.has(key))
+                continue;
+            phases.facts.written += 1;
+            inserts.push({ table: 'authz_denies', row: { uuid: uuidv7(), ...row, created_at: systemClock() } });
+        }
+        /* 3. El seguro del origen ciego (AA2 aplicado a la migración; 3b-8 · B1:
+         *    sobre los hechos UTILIZABLES, no el conteo crudo — un origen que
+         *    devuelve N hechos y los N se descartan sigue siendo un origen que
+         *    no respalda NADA de lo que `--prune` va a borrar). */
+        const massDelete = prune && phases.facts.deleted > 0 && usableFacts === 0;
+        if (massDelete && !dryRun && options.allowMassDelete !== true) {
+            throw new MassReconcileRefusedError(`authz:reconcile --to=database --prune borraría ${phases.facts.deleted} fila(s) de hechos y el ORIGEN ` +
+                `no ha devuelto NI UN hecho utilizable (${sourceFacts} leídos, todos descartados — mira 'skipped'). ` +
+                `Eso es la firma de un store equivocado (o vacío, o de un árbol que ya no resuelve ninguno de sus ` +
+                `scopes), no de una base que sobra: esta pasada dejaría 'authz_assignments'/'authz_denies' sin nada ` +
+                `concedido. Comprueba el --from y el store; si de verdad quieres vaciarlas, --allow-mass-delete.`);
+        }
+        /* 4. Aplicar. Deletes primero: si muere a medias, el destino queda de
+         *    MENOS (fail-closed), nunca con dos filas del mismo hecho. */
+        if (!dryRun) {
+            for (let i = 0; i < deletes.assignments.length; i += batchSize) {
+                const slice = deletes.assignments.slice(i, i + batchSize);
+                await this.sql('reconcile.delete.assignments', () => db.from('authz_assignments').whereIn('uuid', slice).delete());
+            }
+            for (let i = 0; i < deletes.denies.length; i += batchSize) {
+                const slice = deletes.denies.slice(i, i + batchSize);
+                await this.sql('reconcile.delete.denies', () => db.from('authz_denies').whereIn('uuid', slice).delete());
+            }
+            for (const update of updates) {
+                await this.sql('reconcile.update', () => db.from('authz_assignments').where('uuid', update.uuid).update({ expires_at: this.expiry.toDb(update.expiresAt) }));
+            }
+            for (const table of ['authz_assignments', 'authz_denies']) {
+                const rows = inserts.filter((i) => i.table === table).map((i) => i.row);
+                for (let i = 0; i < rows.length; i += batchSize) {
+                    const slice = rows.slice(i, i + batchSize);
+                    await this.sql('reconcile.insert', () => db.table(table).insert(slice));
+                }
+            }
+        }
+        const totals = sumReconcilePhases(phases);
+        return {
+            to: 'database',
+            dryRun,
+            prune,
+            ...totals,
+            phases,
+            skipped,
+            details,
+            // El árbol NO se migra en esta dirección, así que no hay ciclos que
+            // reportar ni aristas de más: los ciclos del árbol del consumidor los
+            // ve `--to=openfga`, que es quien lo copia.
+            cycles: [],
+            drift: { rootMarker: false, multiParent: [], roleVisibility: 0, pendingRelay: 0, deadRelay: 0 },
+            massDelete,
+        };
+    }
+    /**
+     * Pasea una tabla `authz_*` por lotes con cursor sobre `uuid` (PK: orden
+     * total y estable). Lo mismo que hace `openfga.reconcile` con el origen,
+     * por el mismo motivo: una base grande no entra entera de golpe.
+     */
+    async eachReconcileRow(operation, batchSize, build, handle) {
+        let after;
+        for (;;) {
+            const rows = await this.sql(operation, () => {
+                const query = build(db);
+                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);
+        }
+    }
 }
 //# sourceMappingURL=database_driver.js.map