@jantstack/adonis-authz 2.5.0-alpha.3 → 2.5.0-rc.1

package/build/src/drivers/database_relations_driver.js

@@ -29,13 +29,15 @@ import { AuthorizationBackendTimeoutError, AuthorizationConfigError, InvalidIden
 import { assertPartition, assertSubject, assertExpiresAt, partitionKey } from '../identity.js';
 import { relationPartitionTrigger, relationPartitionTriggerDrops } from '../relation_partition_trigger.js';
 import { isClock, systemClock } from '../clock.js';
-import { resolveGrantExpiry, sameInstant } from '../expiry.js';
+import { isActiveExpiry, resolveGrantExpiry, sameInstant } from '../expiry.js';
+import { assertGroupDepthSettings, groupDepthLimitError, groupNestingVerdict, isGroupNesting, plannedByReconcile } from '../relations/group_depth.js';
 import { sqlExpiryCodec } from '../shared/sql_expiry.js';
 import { guardSql, isDeadlock, isUniqueViolation, withDeadline } from '../shared/backend_guard.js';
 import { assertCallerTransaction } from '../shared/transaction_guard.js';
 import { isRelUserset } from '../types.js';
 import { assertRelationDeclared, assertObjectTypeDeclared, assertUsersetSubject, assertRelationDenyable, assertDenySubject, assertDenyNoExpiry, cutPathAllows, decideFrom, deniableAbove, deniedRelationOf, storedRelationKind, denyPhaseOf, relationsDown, RELATION_DENY_PREFIX, } from '../relations/define_relations_config.js';
 import { assertCheckManyObjects, distinctObjects, expandByPosition } from '../relations/check_many.js';
+import { assertEnumeratePage, assertNoListPage, enumerateLimit } from '../relations/page.js';
 const DEFAULT_TIMEOUT_MS = 5_000;
 /**
  * **Cota de candidatos de `membersOf` cuando el objeto tiene un deny vigente** (lote D · cierre 1 de D1, 🟡 4): con deny
@@ -58,9 +60,6 @@ const GROUP_MEMBER = 'member';
  * userset puede colisionar con ella.
  */
 const HOLDER_RELATION = '';
-/** Tamaño de página por defecto y tope de `enumerateRelations` (origen de reconcile). */
-const DEFAULT_ENUMERATE_LIMIT = 100;
-const MAX_ENUMERATE_LIMIT = 1_000;
 /** Formato de id de relación: minúsculas, dígitos y `._-`; sin separadores del store. */
 const RELATION_ID_FORMAT = /^[a-z0-9_.-]+$/;
 const DIALECTS = {
@@ -116,6 +115,9 @@ export class DatabaseRelationsDriver {
     #database;
     #expiryCodec;
     constructor(config, options = {}, database = db) {
+        // Cierre de R1 · 🟡 4 del auditor: el driver RE-VALIDA el techo de la config (una config extendida con spread no pasó
+        // por `defineRelationsConfig`; `NaN` o `enforceGroupDepth: true` sin número apagaban el gate en silencio). 500.
+        assertGroupDepthSettings(config.maxGroupDepth, config.enforceGroupDepth, 'DatabaseRelationsDriver');
         this.#config = config;
         this.#connectionName = options.connection;
         this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
@@ -137,6 +139,8 @@ export class DatabaseRelationsDriver {
             // Cierre 2 de D2 · 🟠 N1: renovar (otra caducidad) es delete + insert en UNA transacción (`#upsert`): ningún
             // instante sin la tupla, así que una membresía que transporta un deny se renueva sin ventana.
             atomicRenewal: true,
+            // Estrategia 2.5.0 · firma 4 (D15): `false` EXPLÍCITO — `database` es el driver ESTABLE de 2.5.0.
+            experimental: false,
         });
     }
     /**
@@ -367,6 +371,54 @@ export class DatabaseRelationsDriver {
         this.#assertObject(object);
         await this.#deleteTuple('removeDeny', subject, deniedRelationOf(relation), object, partition, options);
     }
+    /**
+     * **El techo de anidación de grupos de ESTE driver** (lote «antes de RC» · R1, decisión del dueño 2026-10-17 (5)):
+     * `database` no tiene techo técnico (la CTE deduplica y termina con ciclos), así que es `null` SALVO el opt-in
+     * explícito `database.enforceGroupDepth: true`, que aplica el `maxGroupDepth` de la config (obligatorio y numérico
+     * con el opt-in: lo valida `defineRelationsConfig` al arrancar).
+     */
+    async groupDepthLimit() {
+        return this.#groupDepthLimit();
+    }
+    #groupDepthLimit() {
+        const { maxGroupDepth, enforceGroupDepth } = assertGroupDepthSettings(this.#config.maxGroupDepth, this.#config.enforceGroupDepth, 'DatabaseRelationsDriver');
+        return enforceGroupDepth && typeof maxGroupDepth === 'number' ? maxGroupDepth : null;
+    }
+    /**
+     * **El gate de R1 en `database`** (opt-in): la arista `group:<parent>#member@group:<child>#member` que se va a escribir
+     * VIVA no puede cerrar un ciclo ni dejar un camino de grupos anidados más largo que el techo. El grafo se LEE POR EL
+     * MISMO CLIENTE QUE ESCRIBE (`trx`: la transacción del llamante con `{ transaction }`, o la interna de la escritura) —
+     * T-6 del tester: leído por la conexión del motor, un llamante que en UNA transacción escribe `A⊂B` y luego `B⊂C`
+     * pasaría las dos (la segunda no ve la primera, sin confirmar). Lo que esto NO cierra, declarado: dos transacciones
+     * CONCURRENTES que escriben cada una media cadena (cada una ve su foto, sin cerrojo) — la carrera entre procesos.
+     * Una sentencia por nivel del BFS (y por cada 500 grupos del nivel), con la caducidad ESTRICTA de la lectura.
+     */
+    async #assertGroupNesting(trx, operation, partitionKey, edge, now, limit) {
+        const neighbours = async (groups, column) => {
+            const out = [];
+            for (let i = 0; i < groups.length; i += 500) {
+                const chunk = groups.slice(i, i + 500);
+                const rows = await this.#sql(`${operation}.groupDepth`, () => this.#whereActive(trx
+                    .from(RELATIONS_TABLE)
+                    .where('partition_key', partitionKey)
+                    .where('object_type', GROUP_TYPE)
+                    .where('relation', GROUP_MEMBER)
+                    .where('subject_type', GROUP_TYPE)
+                    .where('subject_relation', GROUP_MEMBER)
+                    .whereIn(column, chunk), now).select({ child: 'subject_uuid', parent: 'object_uuid' }));
+                for (const row of rows)
+                    out.push({ child: row.child, parent: row.parent });
+            }
+            return out;
+        };
+        const verdict = await groupNestingVerdict(edge, limit, {
+            parentsOf: (groups) => neighbours(groups, 'subject_uuid'),
+            childrenOf: (groups) => neighbours(groups, 'object_uuid'),
+        });
+        if (verdict.kind !== 'ok') {
+            throw groupDepthLimitError(verdict, `group:${edge.parent}#member@group:${edge.child}#member`, limit);
+        }
+    }
     /** El check-then-delete-insert idempotente de `relate`/`deny` sobre la relación ALMACENADA. */
     async #upsert(operation, subject, relation, object, partition, requested, options) {
         const partitionKey = this.#keyOf(partition);
@@ -399,10 +451,21 @@ export class DatabaseRelationsDriver {
             // Los tres estados (invariante 10): omitido preserva la VIGENTE (una
             // caducada revive sin caducidad), null la quita, Date la fija.
             const expiresAt = resolveGrantExpiry(previous, requested, now);
+            // Idempotente (invariante 6): la misma caducidad no reescribe nada — y va ANTES del gate de R1: un `relate`
+            // repetido de una arista preexistente (sembrada antes de alpha.4 o con el gate apagado) sigue siendo un no-op.
+            if (current && sameInstant(previous, expiresAt))
+                return;
+            // R1 (opt-in en `database`): una arista de anidación que queda VIVA —nueva, renovada o revivida— pasa el gate,
+            // leyendo el grafo por ESTE `trx` (T-6). Una vencida no conecta nada (la misma regla que la lectura). Antes del
+            // DELETE: un 422 no deja la arista vieja borrada.
+            const limit = this.#groupDepthLimit();
+            if (limit !== null &&
+                isGroupNesting(subject, relation, object) &&
+                isActiveExpiry(expiresAt, now) &&
+                !plannedByReconcile(options, partition, { child: subject.object.id, parent: object.id })) {
+                await this.#assertGroupNesting(trx, operation, partitionKey, { child: subject.object.id, parent: object.id }, now, limit);
+            }
             if (current) {
-                // Idempotente (invariante 6): la misma caducidad no reescribe nada.
-                if (sameInstant(previous, expiresAt))
-                    return;
                 // **INSERT/DELETE-ONLY (decisión (c))**: cambiar la caducidad es
                 // BORRAR la fila e INSERTAR otra —nunca un UPDATE—; la fila nueva
                 // tiene otro `uuid`, que es lo que lo hace observable. Dentro de la
@@ -592,10 +655,12 @@ export class DatabaseRelationsDriver {
         }
         return { distinct, index, facts };
     }
-    async listObjects(subject, relation, objectType, partition, _page) {
+    async listObjects(subject, relation, objectType, partition) {
         assertRelationDeclared(this.#config, { type: objectType }, relation);
         assertPartition(partition);
         this.#assertId('el tipo de objeto', objectType, RELATION_ID_MAX);
+        // 7.4: sin página (un quinto argumento ≠ undefined ⇒ 500 con cero sentencias), después de F-05 y la partición.
+        assertNoListPage('listObjects', arguments[4], 'database');
         const partitionKey = this.#keyOf(partition);
         const s = this.#subjectColumns(subject, partitionKey);
         // Lote D · D-15: `listObjects` RESTA (la misma regla de corte que `check`, objeto a objeto).
@@ -630,14 +695,15 @@ export class DatabaseRelationsDriver {
             .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
         return { objects };
     }
-    async listSubjects(relation, object, partition, _page) {
+    async listSubjects(relation, object, partition) {
         assertRelationDeclared(this.#config, object, relation);
         assertPartition(partition);
         this.#assertObject(object);
-        return this.#directSubjects('listSubjects', relation, object, partition, _page);
+        assertNoListPage('listSubjects', arguments[3], 'database');
+        return this.#directSubjects('listSubjects', relation, object, partition);
     }
     /** Los sujetos DIRECTOS vigentes de UNA relación almacenada (`listSubjects`; `listDenies` con `denied_<rel>`). */
-    async #directSubjects(operation, relation, object, partition, _page) {
+    async #directSubjects(operation, relation, object, partition) {
         const partitionKey = this.#keyOf(partition);
         // DIRECTOS del relation EXACTO (invariante 7): ni transitivo (eso es
         // `membersOf`) ni derivado por includes. `usersetSubjects: true` ⇒ los
@@ -657,11 +723,12 @@ export class DatabaseRelationsDriver {
      * `listSubjects` sobre la relación almacenada `denied_<rel>`; no resta ni deriva—. Sobre CUALQUIER tipo declarado
      * (D8/R2-4 b: con el opt-in retirado, los denies vivos se siguen pudiendo listar y borrar).
      */
-    async listDenies(relation, object, partition, page) {
+    async listDenies(relation, object, partition) {
         assertRelationDeclared(this.#config, object, relation);
         assertPartition(partition);
         this.#assertObject(object);
-        return this.#directSubjects('listDenies', deniedRelationOf(relation), object, partition, page);
+        assertNoListPage('listDenies', arguments[3], 'database');
+        return this.#directSubjects('listDenies', deniedRelationOf(relation), object, partition);
     }
     /**
      * **`denyPhase` — ¿admite este driver escrituras de deny en el tipo?** (lote D · D2, R2-5): la fase del opt-in EN
@@ -679,12 +746,13 @@ export class DatabaseRelationsDriver {
      * directos): en un grupo con `member(g1#member, g2)`, `membersOf(g2)` trae a
      * los holders de g1 y `listSubjects(member, g2)` solo el userset `g1#member`.
      */
-    async membersOf(object, relation, partition, _page) {
+    async membersOf(object, relation, partition) {
         // Cierre-2 · 🟡 3: F-05 (par, ESTRICTA) también en `membersOf`, la octava
         // operación del puerto; antes solo `#assertObject` (gramática).
         assertRelationDeclared(this.#config, object, relation);
         assertPartition(partition);
         this.#assertObject(object);
+        assertNoListPage('membersOf', arguments[3], 'database');
         const partitionKey = this.#keyOf(partition);
         const relations = this.#expandDown(object.type, relation);
         const meta = this.#dialectMeta();
@@ -692,6 +760,11 @@ export class DatabaseRelationsDriver {
         const relPlaceholders = relations.map(() => '?').join(', ');
         const at = this.#expiry.bind(this.#now());
         const active = this.#activeSql(q, 'r');
+        // Rotación 2 · cierre 3b (L12, H1 del auditor): la PUERTA «¿hay algún `denied_*` vigente en el objeto?» va en la
+        // MISMA sentencia que los candidatos (una rama más del `UNION`, `foto_kind = 'd'`). Antes era una segunda sentencia y
+        // un offboarding suelto (unrelate y luego removeDeny) que caía entre las dos devolvía los candidatos de la primera
+        // SIN juzgarlos: listaba a un sujeto que no era miembro en NINGÚN estado real.
+        const deniedRelations = deniableAbove(this.#config, object.type, relation).map(deniedRelationOf);
         // `grp`: los grupos alcanzables por usersets desde (object, RS) —directos y
         // anidados—. Ancla de UN solo SELECT (MySQL no mezcla UNION ALL con la
         // recursión): los usersets directos del objeto para cualquier rel de RS.
@@ -709,16 +782,22 @@ export class DatabaseRelationsDriver {
             `AND r.${q('relation')} = '${GROUP_MEMBER}' AND r.${q('subject_type')} = '${GROUP_TYPE}' ` +
             `AND r.${q('subject_relation')} = '${GROUP_MEMBER}' AND ${active} ` +
             `) ` +
-            // Holders directos del objeto para RS, UNION holders directos de cualquier grupo de `grp`.
-            `SELECT ${meta.hint}${q('subject_type')} AS ${q('subject_type')}, ${q('subject_uuid')} AS ${q('subject_uuid')} ` +
+            // Holders directos del objeto para RS, UNION holders directos de cualquier grupo de `grp` (`foto_kind = 'm'`),
+            // UNION la puerta de denies (`foto_kind = 'd'`, una fila como mucho: el `UNION` funde los `NULL`).
+            `SELECT ${meta.hint}'m' AS ${q('foto_kind')}, ${q('subject_type')} AS ${q('subject_type')}, ${q('subject_uuid')} AS ${q('subject_uuid')} ` +
             `FROM ${q(RELATIONS_TABLE)} r ` +
             `WHERE r.${q('partition_key')} = ? AND r.${q('object_type')} = ? AND r.${q('object_uuid')} = ? ` +
             `AND r.${q('relation')} IN (${relPlaceholders}) AND COALESCE(r.${q('subject_relation')}, '') = '' AND ${active} ` +
             `UNION ` +
-            `SELECT r.${q('subject_type')}, r.${q('subject_uuid')} FROM ${q(RELATIONS_TABLE)} r ` +
+            `SELECT 'm', r.${q('subject_type')}, r.${q('subject_uuid')} FROM ${q(RELATIONS_TABLE)} r ` +
             `JOIN grp ON r.${q('object_uuid')} = grp.g_uuid ` +
             `WHERE r.${q('partition_key')} = ? AND r.${q('object_type')} = '${GROUP_TYPE}' ` +
-            `AND r.${q('relation')} = '${GROUP_MEMBER}' AND COALESCE(r.${q('subject_relation')}, '') = '' AND ${active}`;
+            `AND r.${q('relation')} = '${GROUP_MEMBER}' AND COALESCE(r.${q('subject_relation')}, '') = '' AND ${active}` +
+            (deniedRelations.length
+                ? ` UNION SELECT 'd', NULL, NULL FROM ${q(RELATIONS_TABLE)} r ` +
+                    `WHERE r.${q('partition_key')} = ? AND r.${q('object_type')} = ? AND r.${q('object_uuid')} = ? ` +
+                    `AND r.${q('relation')} IN (${deniedRelations.map(() => '?').join(', ')}) AND ${active}`
+                : '');
         const bindings = [
             // grp ancla
             partitionKey, object.type, object.id, ...relations, at,
@@ -728,22 +807,21 @@ export class DatabaseRelationsDriver {
             partitionKey, object.type, object.id, ...relations, at,
             // holders de los grupos
             partitionKey, at,
+            // la puerta de denies (misma sentencia)
+            ...(deniedRelations.length ? [partitionKey, object.type, object.id, ...deniedRelations, at] : []),
         ];
         const rows = rowsOf(await this.#raw('membersOf', sql, bindings));
-        const candidates = rows.map((row) => ({ type: String(row.subject_type), uuid: String(row.subject_uuid) }));
+        const candidates = rows
+            .filter((row) => String(row.foto_kind) === 'm')
+            .map((row) => ({ type: String(row.subject_type), uuid: String(row.subject_uuid) }));
+        const denied = rows.some((row) => String(row.foto_kind) === 'd');
         // **Lote D · `membersOf` RESTA** (juez ronda 2: «listObjects y membersOf restan»; D8: siempre, con o sin opt-in).
         // Si el objeto tiene alguna fila `denied_*` vigente, cada candidato se juzga con `check` —el MISMO corte de camino
         // que el resto de lecturas, un `check` por candidato—; sin filas deny, cero consultas de más (la respuesta y el coste
-        // de 2.4.0-alpha.10). Coste declarado: O(miembros) consultas cuando el objeto tiene denies.
-        const denied = await this.#sql('membersOf.denies', () => this.#whereActive(this.#connection()
-            .from(RELATIONS_TABLE)
-            .where('partition_key', partitionKey)
-            .where('object_type', object.type)
-            .where('object_uuid', object.id)
-            .whereIn('relation', deniableAbove(this.#config, object.type, relation).map(deniedRelationOf)), this.#now())
-            .select('uuid')
-            .limit(1));
-        if (denied.length === 0)
+        // de 2.4.0-alpha.10). Coste declarado: O(miembros) consultas cuando el objeto tiene denies. La puerta sale de la
+        // MISMA sentencia que los candidatos (L12): sin deny en esa foto, todos los candidatos son miembros en ese estado.
+        // Con deny, cada candidato se juzga con su `check` (una foto por candidato, como cada posición de `authorizeMany`).
+        if (!denied)
             return { subjects: candidates };
         // **Cierre 1 de D1 · 🟡 4 del auditor**: con deny, N `check` en serie sin cota ni deadline total era una
         // amplificación barata para quien puede escribir un deny (disponibilidad, no concesión). Cota DECLARADA
@@ -844,9 +922,12 @@ export class DatabaseRelationsDriver {
      */
     async enumerateRelations(partition, page) {
         assertPartition(partition);
+        // 7.4 (injerto 4, H2/H3): limit entero ≥ 1 y after = un uuid canónico (el cursor que ESTE driver emite) o 422,
+        // con cero sentencias; un limit por encima del techo se recorta en #enumerateRows.
+        const checked = assertEnumeratePage('enumerateRelations', page, 'uuid', 'database');
         const wanted = new Map();
         wanted.set(partitionKey(partition), partition);
-        return this.#enumerateRows('enumerateRelations', wanted, page);
+        return this.#enumerateRows('enumerateRelations', wanted, checked);
     }
     /**
      * **`enumerateRelationsMany` — K particiones en UNA consulta** (2.4.0-alpha.8
@@ -875,7 +956,8 @@ export class DatabaseRelationsDriver {
             if (!wanted.has(key))
                 wanted.set(key, partition);
         }
-        return this.#enumerateRows('enumerateRelationsMany', wanted, page);
+        const checked = assertEnumeratePage('enumerateRelationsMany', page, 'uuid', 'database');
+        return this.#enumerateRows('enumerateRelationsMany', wanted, checked);
     }
     /**
      * La consulta de `enumerateRelations`/`enumerateRelationsMany`: los hechos
@@ -887,7 +969,8 @@ export class DatabaseRelationsDriver {
     async #enumerateRows(operation, wanted, page) {
         const partitionKeys = [...wanted.keys()];
         const declaredTypes = [GROUP_TYPE, ...this.#config.objectTypes.map((t) => t.type)];
-        const limit = Math.max(1, Math.min(page?.limit ?? DEFAULT_ENUMERATE_LIMIT, MAX_ENUMERATE_LIMIT));
+        // La COPIA validada en la entrada (assertEnumeratePage), no la página del llamante: aquí solo el default y el RECORTE al techo, declarado en «Limits».
+        const limit = enumerateLimit(page);
         const after = page?.after;
         const rows = await this.#sql(operation, () => {
             let q = this.#connection()
@@ -959,4 +1042,3 @@ function rowsOf(result) {
     }
     return result?.rows ?? [];
 }
-//# sourceMappingURL=database_relations_driver.js.map

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

@@ -142,8 +142,12 @@ export declare function isDuplicateWrite(error: unknown): boolean;
 export interface OpenFgaDriverOptions {
     apiUrl: string;
     storeId: string;
-    /** Pin del model; si se omite, FGA usa el último. */
-    modelId?: string;
+    /**
+     * **Pin del model — OBLIGATORIO** (lote «antes de RC» · L11, decisión del dueño 2026-10-17 (2)): el driver comprueba
+     * UNA vez por proceso que ese modelo es el que genera su config (la puerta L11) y el servidor evalúa con ÉL. Sin él,
+     * 500 `E_AUTHZ_CONFIG` al construir con la receta (`openfga:provision` imprime `OPENFGA_MODEL_ID`).
+     */
+    modelId: string;
     /** Jerarquía del consumidor (ver ScopeChainResolver). */
     resolveChain?: ScopeChainResolver;
     /**
@@ -225,6 +229,14 @@ export interface OpenFgaDriverOptions {
      * valor «truthy» no es una aceptación.
      */
     acceptScopeDriftRisk?: boolean;
+    /**
+     * **`openfga` es EXPERIMENTAL en 2.5.x** (estrategia 2.5.0, firma 4 del dueño 2026-10-21): no apto para producción,
+     * con límites declarados en README «Limits» que se cierran en 2.6. Construirlo exige este LITERAL, versionado; sin él
+     * (o con `true`, `'acknowledged'`, otra versión…) el constructor lanza 500 `E_AUTHZ_CONFIG` como primera línea, sin
+     * crear el cliente. Opcional en el TIPO —como `acceptScopeDriftRisk`— para que un config que solo REGISTRA la factory
+     * `openfga` (el stub publicado) siga compilando; obligatorio al construir.
+     */
+    experimental?: 'openfga@2.5';
 }
 /**
  * **El gate de construcción de `facts`** (3b-2d, panel 2 cruce 4 · S5).
@@ -247,6 +259,13 @@ export declare function assertScopeDriftGuarded(options: {
     acceptScopeDriftRisk?: boolean;
 }): void;
 export declare const DEFAULT_TIMEOUT_MS = 5000;
+/**
+ * **Vueltas del settle** (lote C · carreras, resolución 7 del juez; linaje L13): aplicaciones que
+ * `settleRoleVisibility` intenta antes de rendirse. Al agotarlas BORRA las aristas `scope#binding` de los pares (fail-CLOSED,
+ * intra-tenant: el churn exige `within` en los dos padres) y lanza 409 `E_AUTHZ_WRITE_CONFLICT` marcado PARCIAL
+ * (invariante 13: `indeterminate: true` en `onWrite`).
+ */
+export declare const SETTLE_MAX_ROUNDS = 5;
 /**
  * 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
@@ -284,6 +303,7 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
         canonicalScopeReads: false;
         enumerateFacts: true;
         transactionalWrites: false;
+        experimental: true;
     }>;
     private client;
     private chainResolver;
@@ -306,6 +326,12 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      * con el que este driver escribe y responde, no el último del store.
      */
     private readonly modelId;
+    /**
+     * **La comparación modelo ↔ config de L11, UNA por proceso** (`modelGate`). Es un OBJETO que se MUTA y nunca se
+     * reasigna (H11 b): las vistas `withChainResolver`/`withClock` son `Object.create(this)` y lo heredan por prototipo,
+     * así que `forRequest()` no relee el modelo por petición.
+     */
+    private readonly modelMemo;
     private consistency;
     /** Reloj de pared del driver (J1): el ÚNICO `now` de checks, filtros y re-grant. */
     private now;
@@ -355,6 +381,22 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      * `authorize` evaluaba el deny en un instante y el rol en otro.
      */
     private checkContext;
+    /**
+     * **La lectura del modelo, UNA por proceso** (L11): `readAuthorizationModel` del `modelId` FIJADO y
+     * `factsModelDifferences` con `slice: 'roles'` (los holders, `role`, `role_binding`, `scope` y las condiciones; la
+     * igualdad es «módulo el catálogo»: `P_M` sale del propio modelo). Se memoriza el ÉXITO —también con diferencias— y un
+     * generador que no puede generar (500); **un fallo al LEER el modelo NO se memoriza, sea 503 o 500** (cierre de L11).
+     */
+    private modelGate;
+    /**
+     * **La puerta L11 del driver de ROLES** (lote «antes de RC», decisión del dueño 2026-10-17 (1); hasta L11 este driver
+     * no comparaba NINGUNA regla —P7: solo el conjunto de `permits_*`, «no es una barrera de seguridad»—: un `can_<P>` sin
+     * `but not denied_<P>`, un `rooted` cambiado o un `assignee` sin `not_expired` concedían o negaban sin error). Toda
+     * operación que llega al store la pasa ENTERA, justo después de validar su entrada y antes de la primera llamada
+     * (catálogo, resolutor y cliente incluidos); `enumerateFacts` —el ORIGEN de una migración— solo la parte
+     * `conditions`. Distinta ⇒ 500 `E_AUTHZ_CONFIG` con las rutas y CERO llamadas que evalúen o escriban.
+     */
+    private assertModel;
     /**
      * 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
@@ -368,6 +410,58 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      * alineada por ese id: un resultado por check, ni uno más ni uno menos.
      */
     private batchCheckAll;
+    /**
+     * **El catálogo de una ESCRITURA** (K4, resolución 2 del juez): con la versión contrastada en fresco SIEMPRE
+     * (`CatalogCache.freshView`), ignore o no la ventana `{ everyMs }`. Un `catalog` inyectado que no lo traiga cae en
+     * `view()` (el contrato del memo es suyo).
+     */
+    private writeCatalog;
+    /**
+     * K4 (segunda mitad): un uuid de rol que el STORE tiene y el catálogo de la escritura no conoce fuerza UNA recarga del
+     * memo (`invalidate` + foto en fresco). Si tras ella sigue ausente, el rol se borró: quien llama BORRA su arista.
+     */
+    private writeCatalogKnowing;
+    /**
+     * Un `batchCheck` con `HIGHER_CONSISTENCY` para el settle, SIN colapsar los errores por ítem: el llamante decide qué
+     * hacer con un `E_AUTHZ_RESOLUTION_LIMIT` de `ancestor` (caer a `storeChain`, condición 2 de la resolución 9) y propaga
+     * el resto (clasificados por el MISMO `fgaFailureError` que `alignBatchResults`).
+     */
+    private checkForWrite;
+    /**
+     * **La decisión del settle**, con el STORE (todas las lecturas con HIGHER, en UN `batchCheck`): para cada par, si la
+     * arista TIENE que estar (`want`) y si ESTÁ (`has`). `want` exige, por este orden:
+     *  - el rol en el catálogo de la escritura (K4: en fresco y, si falta, tras una recarga; si sigue faltando, `known: false`
+     *    y la arista se borra — «rol ausente ⇒ borra»);
+     *  - declarado para el NIVEL del scope (3b-2g · R1);
+     *  - `role_binding#role` VIVO (auditor ⚪ 8: tras un `revoke`/`purgeScope`/`purgeRole` concurrente el settle no resucita
+     *    la arista; `liveness: false` solo en la decisión PREVIA del `grant`, que escribe esa arista en el mismo `Write`);
+     *  - y, si el rol es LOCAL, su owner ancestro-o-igual del scope EN EL STORE: atajo `scope == owner` (`ancestor` no es
+     *    reflexivo, K6), `Check(scope:<owner> ancestor scope:<S>)` y, si ese `Check` excede la cota del servidor (medido en M2:
+     *    solo cuando el owner SÍ es ancestro a > 26 saltos), la cadena del store salto a salto (`storeChain`) — nunca «borrar
+     *    por si acaso» (fail-closed aleatorio cerca de la cota). La laxitud de `ancestor` ante DOS padres es deriva que ya
+     *    denuncian `moved` y reconcile (riesgo declarado del juez).
+     */
+    private decideRoleVisibility;
+    /**
+     * **El ÚNICO sitio que da de ALTA una arista `scope#binding` de rol local** (y borra las que se le pidan), en lotes ≤ 100
+     * (`Write` con `Ignore` en las dos direcciones: dice el estado que DEBE quedar, no el delta — invariante 6).
+     */
+    private writeBindingEdges;
+    /**
+     * **`settleRoleVisibility`** — el punto de paso de L13. Decide con el store (`decideRoleVisibility`), y si alguna
+     * arista no está como tiene que estar, aplica la diferencia y VUELVE A LEER; termina cuando una lectura POSTERIOR a su
+     * última escritura ve el store coherente (punto fijo: «borro una vez» deja CLOSED persistente al entrar, R1-entrar).
+     *
+     * **Cota** (resolución 7): tras `SETTLE_MAX_ROUNDS` aplicaciones sin converger (un churn que mueve el árbol en cada
+     * relectura) se RINDE: borra las aristas de los pares que NO convergieron —y, en el mismo `Write`, `giveUpDeletes` (el `assignee` de un
+     * `grant` que CREÓ la asignación: vuelta a «no ocurrió»)— y lanza 409 `E_AUTHZ_WRITE_CONFLICT` marcado PARCIAL
+     * (`indeterminate: true`). Fail-CLOSED declarado e intra-tenant; en un re-grant el 409 NO significa «no asignado».
+     *
+     * Devuelve los pares cuyo rol el catálogo ya no conoce (`known: false`): el `grant` que los CREÓ deshace su asignación.
+     */
+    private settleRoleVisibility;
+    /** Las vueltas del settle (lo que hasta el cierre 1 era el cuerpo de `settleRoleVisibility`). */
+    private settleRounds;
     private findPermission;
     /**
      * Filtro por catálogo de las lecturas de membresía (`listRoles`,
@@ -438,6 +532,13 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      */
     private rejectTransaction;
     grant(subject: SubjectRef, role: RoleQuery, scope: ScopeRef, options?: GrantOptions): Promise<GrantOutcome>;
+    /**
+     * El cuerpo de ESCRITURA del `grant` (sin la decisión de visibilidad): lee la asignación, decide entre no-op, write o
+     * delete+write, y re-aplica ante una carrera. `structure` son las aristas que van con el `assignee` en el MISMO `Write`
+     * (las tres para un rol global; sin la `scope#binding` si el store dice que el rol local no es visible ahí). `progress`
+     * cuenta los `Write` INTENTADOS (el settle del `grant` local corre si hubo alguno, también si falló: invariante 13).
+     */
+    private writeGrant;
     /**
      * 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
@@ -550,8 +651,12 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      * 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.
+     * write del nuevo, que es atómico PARA EL ESCRITOR (el store nunca guarda
+     * los dos padres ni ninguno) pero NO para un lector concurrente: un `Check`
+     * que dura lo que el `Write` puede leer la arista vieja por una rama del
+     * modelo y la nueva por otra (lector rasgado, fila «torn read» de Limits del
+     * README; medido 1,2–7,1 %, decisión del dueño 6b). O(profundidad) requests;
+     * con roles locales, además el barrido F4 (ver `reparent`).
      */
     onScopeMoved(child: ScopeRef, newParent: ScopeRef): Promise<void>;
     /**
@@ -623,8 +728,8 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      */
     private reparent;
     /**
-     * **El barrido del rol local** (3b-2e · E1; decisión del dueño del
-     * 2026-08-30, opción 1).
+     * **El barrido PREVIO del rol local** (3b-2e · E1; decisión del dueño del
+     * 2026-08-30, opción 1; F4: solo borra).
      *
      * 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
@@ -634,11 +739,12 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      * 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.
+     * ALCANZABLE la asignación: el barrido previo la BORRA donde el owner del
+     * rol no estará en la cadena NUEVA; las ALTAS (volver a su sitio restaura)
+     * son del settle de después (`settleSubtree`), el punto de paso único de
+     * L13. 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.
@@ -647,9 +753,22 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      * 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.
+     * `Write` por lote (el coste O(roles locales) por `moved` es el 🟡 6, declarado hasta 2.6).
      */
     private sweepLocalRoleBindings;
+    /**
+     * Los bindings de roles LOCALES que cuelgan del subárbol de `movedKey` en el STORE (HIGHER), con la cadena de cada
+     * scope del subárbol. El catálogo es el de una ESCRITURA (K4: en fresco), y un uuid que el store tiene y el catálogo no
+     * conoce fuerza una recarga (`writeCatalogKnowing`); los roles se enumeran por el catálogo (el amarillo 6 —enumerar
+     * desde el store— es de 2.6). `chain` es la cadena que el nodo TENDRÁ (barrido previo) o, sin ella, la del store.
+     */
+    private localBindingsBelow;
+    /**
+     * **El settle del subárbol de un cambio de árbol** (lote C · L13): los bindings de roles locales del subárbol de
+     * `movedKey` (en el store, HIGHER, catálogo en fresco) pasan por `settleRoleVisibility`. Lo llaman `reparent` tras la
+     * arista, su atajo idempotente y su `finally`.
+     */
+    private settleSubtree;
     /**
      * **El barrido por NIVEL** (3b-2g · R1; decisión del dueño del 2026-08-30
      * (2), mismo mecanismo que E1).
@@ -660,18 +779,22 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      * —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
+     * Se cierra igual que el owner: dejando la arista `scope#binding` de los
+     * bindings de ESE rol como dice 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.
+     * **Desde el lote C pasa ENTERO por el settle** (L13; 🟠 1 de F4-carreras: este barrido leía `storeChain` y escribía
+     * DESPUÉS, y un `moved` que barriera entre medias quedaba pisado — fail-OPEN persistente entre tenants). El catálogo es
+     * el de una escritura (K4, hallazgo 4 del panel TREE): con un memo rancio un rol recién definido en otro proceso se
+     * ignoraba. Un rol que el catálogo ya no declara —tras la recarga— no tiene visibilidad que decidir: sus aristas se BORRAN
+     * («rol ausente ⇒ borra», K4); el resto de sus hechos son de `purgeRole`/`authz:reconcile`.
+     *
+     * Coste: una lectura (los bindings del rol) y un `batchCheck` (HIGHER) por vuelta del settle; un `Write` por lote solo
+     * si hay algo que corregir. Un rol sin bindings —todo `defineScopedRole`— son 0 escrituras.
      */
     private sweepRoleVisibility;
     /**
@@ -681,15 +804,12 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      * 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.
+     * cambia es dónde se la ve. (Desde el lote C solo lo usa el barrido PREVIO, que solo borra.)
      */
     private classifyBindingEdge;
     /**
-     * Aplica el barrido en lotes ≤ 100 (el límite del `Write`).
-     *
-     * `Ignore` en las dos direcciones: el barrido dice el estado que DEBE
-     * quedar, no el delta — borrar lo que ya no está y reescribir lo que ya
-     * estaba son no-ops, no errores (invariante 6).
+     * Aplica los BORRADOS de un barrido (lote C · L13: `applyBindingSweep` ya no da ALTAS; las altas de `scope#binding` de
+     * rol local solo salen del settle). Borrar nunca concede, así que va directo, en lotes ≤ 100 con `Ignore`.
      */
     private applyBindingSweep;
     /**
@@ -698,7 +818,8 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      * 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.
+     * enumeraciones: un ciclo escrito a mano no cuelga el proceso. Alimenta
+     * escrituras (anti-ciclos de `reparent`, barrido, caída del settle) ⇒ HIGHER (hallazgo 3 TREE).
      */
     private storeChain;
     /**
@@ -826,6 +947,13 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      * divergencia R1 del lote 2e.
      */
     projectCatalogRole(roleUuid: string): Promise<void>;
+    /**
+     * La proyección `permits_<P>` de UN rol (la otra mitad de `projectCatalogRole`). **Hallazgo 4 del panel TREE (K4)**: el
+     * catálogo es el de una ESCRITURA (`writeCatalog`, versión en fresco) — con un memo `{ everyMs }` que todavía no conoce
+     * un rol recién definido en otro proceso, `rolePermissionsOf` devolvía `[]` y esto BORRABA sus `permits_*` (fail-closed
+     * medido: `dave@C`). Mutante `project.memo-catalog`.
+     */
+    private projectRolePermits;
     /**
      * **Reconstruye el store desde `authz_*` + el árbol del consumidor.**
      *
@@ -1085,6 +1213,12 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
      * default `?? []` sobre `tuples` vuelva a este fichero.
      */
     private tuplesOrThrow;
+    /**
+     * **`readAllTuples` para una lectura que ALIMENTA UNA ESCRITURA** (lote C · carreras, resolución 8; hallazgo 3 TREE):
+     * con `HIGHER_CONSISTENCY` siempre (`WRITE_CONSISTENCY`). Es el helper ÚNICO: la guardia de fuente de
+     * `tests/visibility_settle.spec.ts` exige que los métodos que escriben lean por aquí (o por `checkForWrite`).
+     */
+    private readForWrite;
     private readAllTuples;
 }
 /**
@@ -1120,4 +1254,3 @@ export declare class OpenFgaAuthorizationDriver implements AuthorizationDriver {
  * en silencio los datos de quien ya usaba ese nombre).
  */
 export declare const OWN_FACTS_OBJECT_TYPES: ReadonlySet<string>;
-//# sourceMappingURL=openfga_driver.d.ts.map