@jantstack/adonis-authz 2.5.0-alpha.2 → 2.5.0-alpha.4

package/build/commands/openfga_provision.js

@@ -105,7 +105,7 @@ export default class OpenFgaProvision extends BaseCommand {
         }
         const { OpenFgaClient } = await import('@openfga/sdk');
         // El subpath `/openfga` es la única puerta al SDK (D9).
-        const { openFgaFactsModel, provisionOpenFgaStore, assertFactsModelPublishable } = await import('../src/openfga.js');
+        const { openFgaFactsModel, provisionOpenFgaStore, assertFactsModelPublishable, factsModelDifferences } = await import('../src/openfga.js');
         // Los holders del consumidor viven en SU config, no en el paquete.
         const holderTypes = config?.holderTypes ?? {};
         // Los PERMISOS del modelo (c2r) salen de los catálogos del config. Se
@@ -130,12 +130,26 @@ export default class OpenFgaProvision extends BaseCommand {
             // esto salía como error crudo del SDK con una request ya hecha (⚪ N1
             // del auditor de alpha.4). Cero requests si no es publicable.
             assertFactsModelPublishable(holderTypes, permissions, undefined, relations);
-            const client = new OpenFgaClient({ apiUrl, storeId: this.storeId });
-            const model = await client.writeAuthorizationModel(openFgaFactsModel(holderTypes, permissions, relations));
+            // Injerto 15 del juez (H12): sin reintentos a escondidas (desde el SDK 0.9.6 un cliente sin `retryParams` reintenta).
+            const client = new OpenFgaClient({ apiUrl, storeId: this.storeId, retryParams: { maxRetry: 0 } });
+            const next = openFgaFactsModel(holderTypes, permissions, relations);
+            // Lote D · D2: la guarda contra la MUTILACIÓN del modelo (R2-4 c / H3) — ANTES de escribir nada. Cierre 1 de D2:
+            // juzga el ESTADO del store (🟡 3) y devuelve las relaciones que hay que RE-CONTAR justo antes de publicar (🟠 2).
+            const guard = await this.guardDroppedDenies(client, next);
+            if (guard === null)
+                return;
+            // Cierre 1 de D2 · 🟠 2 (TOCTOU): el barrido es O(store) y la flota puede seguir escribiendo denies mientras dura.
+            // Se vuelve a contar JUSTO antes de `writeAuthorizationModel`; un deny nuevo ⇒ exit 1 y CERO modelos. Estrecha la
+            // ventana, no la cierra: la garantía es el paso 0 del procedimiento (la flota en deny: 'read' antes de contar).
+            if (guard.recount.length > 0 && !(await this.recountBeforePublish(client, guard.recount)))
+                return;
+            const model = await client.writeAuthorizationModel(next);
             this.logger.success('Nuevo authorization model escrito en el store existente.');
             if (relations)
                 this.logger.info(`Tipos de relación fusionados: ${relations.objectTypes.map((t) => t.type).join(', ')}`);
             this.logger.log(`OPENFGA_STORE_ID=${this.storeId}`);
+            if (!(await this.reread(OpenFgaClient, factsModelDifferences, apiUrl, this.storeId, model.authorization_model_id, holderTypes, relations)))
+                return;
             this.logger.log(`OPENFGA_MODEL_ID=${model.authorization_model_id}`);
             return;
         }
@@ -147,8 +161,140 @@ export default class OpenFgaProvision extends BaseCommand {
         this.logger.log('Añade al .env (junto a AUTHZ_DRIVER=openfga):');
         this.logger.log(`OPENFGA_URL=${apiUrl}`);
         this.logger.log(`OPENFGA_STORE_ID=${storeId}`);
+        if (!(await this.reread(OpenFgaClient, factsModelDifferences, apiUrl, storeId, modelId, holderTypes, relations)))
+            return;
         this.logger.log(`OPENFGA_MODEL_ID=${modelId}`);
     }
+    /**
+     * **La RELECTURA de lo publicado** (lote «antes de RC» · L11, diseño 1.3 D del analista; condición de aceptación C12 del
+     * tester): tras `writeAuthorizationModel` se LEE el modelo por su id y se compara ENTERO (`slice: 'all'`) con el que
+     * genera la config. Ancla el canonicalizador de L11 contra el servidor REAL en cada publicación: un servidor que
+     * serialice distinto (otra versión, un campo nuevo) se descubre en el despliegue, no con un 500 en la primera petición
+     * de producción. Si la relectura falla o difiere: exit 1, prefijo ESTABLE «provision RELECTURA FALLIDA:» (punto 7) y la
+     * letra que no miente (H11 c): el modelo YA está publicado en el store, y NO hay que fijarlo — por eso la línea
+     * `OPENFGA_MODEL_ID=` NO se imprime. Devuelve si se puede fijar.
+     */
+    async reread(OpenFgaClient, factsModelDifferences, apiUrl, storeId, modelId, holderTypes, relations) {
+        let differences;
+        try {
+            const client = new OpenFgaClient({ apiUrl, storeId, authorizationModelId: modelId, retryParams: { maxRetry: 0 } });
+            const response = await client.readAuthorizationModel();
+            differences = factsModelDifferences(response?.authorization_model, { holderTypes, relations, slice: 'all' }).differences.map((d) => d.path);
+        }
+        catch (error) {
+            this.logger.error(`provision RELECTURA FALLIDA: el modelo ${modelId} SE PUBLICÓ en el store ${storeId}, pero no se pudo releer y ` +
+                `comparar con el que genera la config (${String(error?.message ?? error)}). NO lo fijes (OPENFGA_MODEL_ID): los ` +
+                'drivers lo comparan al arrancar y, sin esta comprobación, podrían negarse a servir. Repite el comando cuando el ' +
+                'servidor responda.');
+            this.exitCode = 1;
+            return false;
+        }
+        if (differences.length === 0) {
+            // Punto 7 de CLAUDE.md (cierre de L11, 🟡-1 del tester): la rama de éxito también dice que corrió, con prefijo ESTABLE.
+            this.logger.success(`provision RELECTURA OK: el modelo ${modelId} releído del store ${storeId} es IGUAL (entero) al que genera la config; ya se puede fijar.`);
+            return true;
+        }
+        this.logger.error(`provision RELECTURA FALLIDA: el modelo ${modelId} SE PUBLICÓ en el store ${storeId}, pero lo que el servidor devuelve ` +
+            `NO es igual al que genera la config (L11): ${differences.slice(0, 20).join('; ')}${differences.length > 20 ? ' …' : ''}. ` +
+            'NO lo fijes (OPENFGA_MODEL_ID): los drivers openfga lo compararían igual al arrancar y responderían 500 E_AUTHZ_CONFIG. ' +
+            'Suele ser un servidor de otra versión que serializa el modelo distinto: compruébalo (CI prueba OpenFGA v1.19.0) y repórtalo.');
+        this.exitCode = 1;
+        return false;
+    }
+    /**
+     * **La guarda contra la MUTILACIÓN del modelo** (plan 2.5 · lote D · D2; analista §4.6, juez ronda 2 · R2-4 c y H3;
+     * cierre 1 de D2 · 🟡 3 y 🟠 2). `openfga:provision --store-id` publica desde la config del PROCESO: si ese proceso ya
+     * no declara el opt-in de un tipo (un refactor, otra rama del config, un binario viejo), el modelo nuevo no trae
+     * `denied_<rel>` y TODOS los denies de ese tipo dejan de bloquear en cuanto un pod lo resuelve — fail-open en silencio.
+     *
+     *  - **El ESTADO del store manda** (🟡 3): se leen TODOS los modelos del store (`readAuthorizationModels`, paginado y
+     *    acotado por `PROVISION_MODEL_HISTORY_MAX`) y se barre por las `<tipo>#denied_<rel>` que ALGÚN modelo declaró y el
+     *    nuevo no (una tupla `denied_*` solo puede existir si un modelo la declaró al escribirla). Un deny VIVO de esas
+     *    relaciones ⇒ exit 1 con o sin la bandera. Hasta el cierre se comparaba solo con el ÚLTIMO modelo: un modelo
+     *    intermedio sin `denied_*` (un ensayo de rollback con alpha.10) desactivaba la guarda.
+     *  - **La INTENCIÓN la dice la bandera**: si el nuevo quita respecto del ÚLTIMO modelo, sin `--allow-drop-deny` es exit
+     *    1 aunque no quede ningún deny (retirar un opt-in se pide en voz alta).
+     *  - Devuelve las relaciones a RE-CONTAR antes de publicar (🟠 2), o `null` si negó. Todas las ramas fallidas empiezan
+     *    por el prefijo ESTABLE «provision NEGADO:» (punto 7), también un barrido que falla a medias (⚪ 10 c).
+     */
+    async guardDroppedDenies(client, next) {
+        let models;
+        try {
+            models = await readModelHistory(client);
+        }
+        catch (error) {
+            this.logger.error(`provision NEGADO: no se pudo leer el modelo ACTUAL del store ${this.storeId} ni su historia de modelos ` +
+                `(${String(error?.message ?? error)}). Sin ella no se puede comprobar si el modelo nuevo apaga denies vivos; no ` +
+                'se publica a ciegas. No se ha escrito nada.');
+            this.exitCode = 1;
+            return null;
+        }
+        const droppedLatest = droppedDenyRelations(models[0], next);
+        const droppedEver = droppedDenyRelations({ type_definitions: models.flatMap((m) => m?.type_definitions ?? []) }, next);
+        if (droppedLatest.length > 0 && this.allowDropDeny !== true) {
+            this.logger.error(`provision NEGADO: el modelo nuevo QUITA ${droppedLatest.join(', ')}, que el modelo actual del store declara. Publicarlo apagaría ` +
+                'todos los denies de esas relaciones en cuanto un pod lo resuelva (fail-open en silencio). Suele ser un proceso ' +
+                "con la config sin el opt-in (deny: 'read'/'write') o con un paquete < 2.5.0-alpha.3: publica desde la versión y " +
+                "la config actuales. Si de verdad quieres retirar el opt-in: pasa ANTES la flota entera a deny: 'read', retira esos " +
+                'denies (removeDeny) y repite con --allow-drop-deny (solo publica si el store no tiene NI UN deny vivo de ellas). ' +
+                'No se ha escrito nada.');
+            this.exitCode = 1;
+            return null;
+        }
+        if (droppedEver.length === 0)
+            return { recount: [] };
+        const list = droppedEver.join(', ');
+        const sweep = await this.sweep(client, droppedEver);
+        if (sweep === null)
+            return null;
+        if (sweep.count > 0) {
+            this.logger.error((droppedLatest.length > 0
+                ? `provision NEGADO: --allow-drop-deny no apaga denies VIVOS: el store tiene ${sweep.count} deny(s) de ${list} `
+                : `provision NEGADO: el store tiene ${sweep.count} deny(s) VIVOS de ${list} (declaradas por un modelo ` +
+                    `ANTERIOR del store) que el modelo nuevo no declara `) +
+                `(p. ej. ${sweep.live.slice(0, 3).join(', ')}). Publicarlo los apagaría. Retíralos con removeDeny (o purga) y ` +
+                'repite. No se ha escrito nada.');
+            this.exitCode = 1;
+            return null;
+        }
+        this.logger.warning(`${droppedLatest.length > 0 ? '--allow-drop-deny: el modelo nuevo quita' : 'el modelo nuevo no declara (algún modelo anterior sí)'} ${list}; ` +
+            `barrido del store: 0 denies vivos de esas relaciones (${sweep.read} tuplas leídas). Se publica.`);
+        return { recount: droppedEver };
+    }
+    /**
+     * El barrido; `null` (y exit 1 con el prefijo estable) si falla a medias (⚪ 10 c). Cierre 2 de D2 · 🟡 N4: en STREAMING
+     * —página a página, sin cargar el store en memoria y SIN cota de tuplas—: hasta el cierre 2, un store de más de 1 M
+     * tuplas dejaba `provision --store-id` en exit 1 PARA SIEMPRE tras retirar un opt-in (la historia de modelos no se
+     * borra en FGA), sin bandera que lo salvara. Lo que sigue siendo ruidoso: un servidor que no avanza (token repetido).
+     */
+    async sweep(client, dropped) {
+        try {
+            return await countLiveDenies(client, dropped);
+        }
+        catch (error) {
+            this.logger.error(`provision NEGADO: el barrido del store falló a medias (${String(error?.message ?? error)}): no se puede demostrar ` +
+                `que no queda ningún deny vivo de ${dropped.join(', ')}. No se ha escrito nada.`);
+            this.exitCode = 1;
+            return null;
+        }
+    }
+    /**
+     * **El RECUENTO justo antes de publicar** (cierre 1 de D2 · 🟠 2, TOCTOU): otro barrido de las mismas relaciones; un
+     * deny que llegó DURANTE o DESPUÉS del primero ⇒ exit 1 y CERO modelos. Es la señal de que la flota sigue en
+     * `deny: 'write'` (el paso 0 del procedimiento no se hizo).
+     */
+    async recountBeforePublish(client, dropped) {
+        const sweep = await this.sweep(client, dropped);
+        if (sweep === null)
+            return false;
+        if (sweep.count === 0)
+            return true;
+        this.logger.error(`provision NEGADO: el RECUENTO justo antes de publicar encontró ${sweep.count} deny(s) de ${dropped.join(', ')} ` +
+            `que llegaron DURANTE el barrido (p. ej. ${sweep.live.slice(0, 3).join(', ')}): la flota sigue escribiendo denies. ` +
+            "Pasa ANTES toda la flota a deny: 'read' (deny ⇒ 422 en todos los pods), retíralos y repite. No se ha escrito nada.");
+        this.exitCode = 1;
+        return false;
+    }
     /**
      * Los permisos del modelo, o `null` (y exit 1) si no hay ninguno: un modelo
      * `facts` sin permisos no puede responder a nada, y descubrirlo aquí es
@@ -178,6 +324,10 @@ __decorate([
     flags.string({ description: 'Store name when creating one (default: APP_NAME del entorno)' }),
     __metadata("design:type", Object)
 ], OpenFgaProvision.prototype, "name", void 0);
+__decorate([
+    flags.boolean({ description: 'Allow a new model that drops denied_<rel> relations (only if the store has no live deny of them)' }),
+    __metadata("design:type", Object)
+], OpenFgaProvision.prototype, "allowDropDeny", void 0);
 /**
  * Los slugs de permiso de TODOS los catálogos del config, sin duplicados y en
  * orden estable (3b-2k · K2). Se exporta —y no es un método— para que se
@@ -219,4 +369,86 @@ export function relationsConfigOf(config) {
         return undefined;
     return { objectTypes };
 }
-//# sourceMappingURL=openfga_provision.js.map
+/**
+ * Cierre 1 de D2 · 🟡 3: tope de la HISTORIA de modelos que `provision --store-id` lee para juzgar el estado del store
+ * (cada modelo publicado es una versión): pasarse es exit 1 (`provision NEGADO:`), nunca juzgar con una historia cortada.
+ */
+export const PROVISION_MODEL_HISTORY_MAX = 10_000;
+/** Todos los modelos del store, del más RECIENTE al más antiguo (`readAuthorizationModels` paginado, acotado). */
+async function readModelHistory(client) {
+    const models = [];
+    let continuationToken;
+    do {
+        const page = await client.readAuthorizationModels({ pageSize: 50, continuationToken });
+        models.push(...(page?.authorization_models ?? []));
+        if (models.length > PROVISION_MODEL_HISTORY_MAX) {
+            throw new Error(`el store tiene más de ${PROVISION_MODEL_HISTORY_MAX} modelos (PROVISION_MODEL_HISTORY_MAX)`);
+        }
+        continuationToken = page?.continuation_token || undefined;
+    } while (continuationToken);
+    return models;
+}
+/** Los tipos que gobierna el modelo de ROLES (`facts`): sus `denied_<P>` son de permisos, no del deny de relaciones. */
+const ROLE_MODEL_TYPES = new Set(['scope', 'role', 'role_binding', 'deny_binding']);
+/**
+ * **Las `<tipo>#denied_<rel>` de TIPOS DE RELACIÓN que el modelo actual declara y el nuevo no** (plan 2.5 · lote D ·
+ * D2): la mutilación que la guarda de `openfga:provision` niega. Función PURA (dos modelos JSON en la forma de
+ * `readLatestAuthorizationModel` / `openFgaFactsModel`). Los `denied_<P>` de `scope` (roles) quedan fuera: retirar un
+ * permiso del catálogo no es retirar el opt-in de un tipo.
+ */
+export function droppedDenyRelations(current, next) {
+    const nextRelations = new Set();
+    for (const t of next?.type_definitions ?? []) {
+        for (const relation of Object.keys(t?.relations ?? {}))
+            nextRelations.add(`${t.type}#${relation}`);
+    }
+    const dropped = [];
+    for (const t of current?.type_definitions ?? []) {
+        if (ROLE_MODEL_TYPES.has(t?.type))
+            continue;
+        for (const relation of Object.keys(t?.relations ?? {})) {
+            if (relation.startsWith('denied_') && !nextRelations.has(`${t.type}#${relation}`))
+                dropped.push(`${t.type}#${relation}`);
+        }
+    }
+    return dropped.sort();
+}
+/**
+ * **El barrido de `--allow-drop-deny`, en STREAMING** (cierre 2 de D2 · 🟡 N4): cuenta las tuplas vivas cuyo
+ * `<tipo>#<relación>` está en `dropped` leyendo el store ENTERO por páginas (`Read({})`: un `Read` por prefijo de objeto
+ * es 200 con cero tuplas) sin acumularlo — guarda el recuento y TRES ejemplos para la letra, nada más — y SIN cota de
+ * tuplas (hasta el cierre 2, 1 M ⇒ exit 1 para siempre). Exhaustivo o ruidoso: una página sin `tuples` o un
+ * `continuation_token` que se repite (el servidor no avanza) LANZA (el comando lo dice como «el barrido falló a medias»).
+ * Exportada para el caso que la juzga sin servidor.
+ */
+export async function countLiveDenies(client, dropped) {
+    const wanted = new Set(dropped);
+    const live = [];
+    let count = 0;
+    let read = 0;
+    let continuationToken;
+    const seen = new Set();
+    do {
+        const page = await client.read({}, { pageSize: 100, continuationToken });
+        if (!Array.isArray(page?.tuples))
+            throw new Error("una página del Read no trae 'tuples': no se toma por vacía");
+        for (const tuple of page.tuples) {
+            read++;
+            const type = String(tuple?.key?.object ?? '').split(':')[0];
+            if (!wanted.has(`${type}#${tuple?.key?.relation}`))
+                continue;
+            count++;
+            if (live.length < 3)
+                live.push(`${tuple.key.object}#${tuple.key.relation}@${tuple.key.user}`);
+        }
+        const next = page?.continuation_token || undefined;
+        // Un token YA visto (no solo el inmediato: un ciclo a → b → a tampoco avanza) lanza; sin la cota de tuplas, esta
+        // guarda es lo único que impide un barrido infinito. Coste: un token por página en memoria.
+        if (next !== undefined && seen.has(next))
+            throw new Error(`el continuation_token se repite tras ${read} tuplas: el servidor no avanza`);
+        if (next !== undefined)
+            seen.add(next);
+        continuationToken = next;
+    } while (continuationToken);
+    return { live, count, read };
+}

package/build/configure.d.ts

@@ -18,4 +18,3 @@ import type Configure from '@adonisjs/core/commands/configure';
  * nada distinto.
  */
 export declare function configure(command: Configure): Promise<void>;
-//# sourceMappingURL=configure.d.ts.map

package/build/configure.js

@@ -76,4 +76,3 @@ export async function configure(command) {
     }
     command.logger.info('Siguiente paso: node ace migration:run');
 }
-//# sourceMappingURL=configure.js.map

package/build/index.d.ts

@@ -50,7 +50,7 @@ export type { SqlScopeOutboxOptions } from './src/scope_outbox.js';
  * obligaría a importar ese SDK — acoplando el call-site al backend que este
  * paquete existe para abstraer.
  */
-export { AuthorizationBackendError, AuthorizationBackendTimeoutError, ScopeResolverError, InvalidIdentityError, InvalidSlugError, AuthorizationConfigError, AuthorizationInternalError, UnknownScopeError, NoScopeResolverError, UnknownRoleError, UnknownPermissionError, CatalogConflictError, RoleIsNotAccessError, ScopeCycleError, PurgeIncompleteError, WriteConflictError, ActorRequiredError, CheckManyBatchError, NotWithinError, WithinRequiredError, WithinRootForbiddenError, TooManyScopesError, TooManyLocalRolesError, MassPurgeRefusedError, PruneInterruptedError, UnsupportedDialectError, ScopeTooDeepError, ScopeDepthLimitError, ScopeRequeueRefusedError, UnsupportedOperationError, NoDescendantsResolverError, ViewExpiredError, RoleNotVisibleError, AmbiguousRoleError, RoleImmutableError, RoleLevelAboveOwnerError, RoleNotAssignableAtError, PermissionNotDelegableError, RankExceededError, ModelTooLargeError, RelationConfigError, RelationConfigUnknownKeyError, RelationTypeUnknownError, RelationUnknownError, RelationUsersetUnsupportedError, ScopeTreeDriftError, ScopeDriftUnguardedError, AuthorizationFrozenError, FreezeHeldError, MassReconcileRefusedError, StaleSourceRefusedError, OperatorWindowExpiredError, ReconcileTooLargeError, markPartialWrite, isPartialWrite, } from './src/errors.js';
+export { AuthorizationBackendError, AuthorizationBackendTimeoutError, ResolutionLimitError, ScopeResolverError, InvalidIdentityError, InvalidSlugError, AuthorizationConfigError, AuthorizationInternalError, UnknownScopeError, NoScopeResolverError, UnknownRoleError, UnknownPermissionError, CatalogConflictError, RoleIsNotAccessError, ScopeCycleError, PurgeIncompleteError, WriteConflictError, RenewalUnsafeError, RenewalRacedError, ActorRequiredError, CheckManyBatchError, NotWithinError, WithinRequiredError, WithinRootForbiddenError, TooManyScopesError, TooManyLocalRolesError, MassPurgeRefusedError, PruneInterruptedError, UnsupportedDialectError, ScopeTooDeepError, ScopeDepthLimitError, GroupDepthLimitError, ScopeRequeueRefusedError, UnsupportedOperationError, NoDescendantsResolverError, ViewExpiredError, RoleNotVisibleError, AmbiguousRoleError, RoleImmutableError, RoleLevelAboveOwnerError, RoleNotAssignableAtError, PermissionNotDelegableError, RankExceededError, ModelTooLargeError, RelationConfigError, RelationConfigUnknownKeyError, RelationTypeUnknownError, RelationUnknownError, RelationUsersetUnsupportedError, RelationNotDenyableError, RelationDenyExpiryError, MembersOfDenyLimitError, InvalidRelationPageError, ScopeTreeDriftError, ScopeDriftUnguardedError, AuthorizationFrozenError, FreezeHeldError, MassReconcileRefusedError, DenyMigrationRefusedError, DenyReachRefusedError, StaleSourceRefusedError, OperatorWindowExpiredError, ReconcileTooLargeError, markPartialWrite, isPartialWrite, } from './src/errors.js';
 /**
  * Validación de identidad y de slugs (422). La aplica el manager en cada
  * llamada y los drivers por defensa en profundidad; se exporta para que un
@@ -65,17 +65,20 @@ export type { IdentityParts, SlugKind } from './src/identity.js';
  * `defineRelationsConfig`, la fachada `RelationsManager` (F-05 + `assertWrite`
  * + `actor`) y los tipos de la config.
  */
-export { defineRelationsConfig } from './src/relations/define_relations_config.js';
-export type { RelationsConfig, RelationsConfigSpec, RelationsDatabaseOptions, RelationObjectTypeSpec, RelationObjectRelationSpec, } from './src/relations/define_relations_config.js';
+export { defineRelationsConfig, DENIABLE_RELATION_NAME_MAX, RELATION_DENY_PREFIX, } from './src/relations/define_relations_config.js';
+export type { RelationDenyPhase, RelationsConfig, RelationsConfigSpec, RelationsDatabaseOptions, RelationObjectTypeSpec, RelationObjectRelationSpec, } from './src/relations/define_relations_config.js';
 export { RelationsManager } from './src/relations/manager.js';
 export type { RelationsManagerOptions } from './src/relations/manager.js';
 export { relationTupleKey, relationSubjectKey } from './src/relations/tuple_key.js';
 export type { RelationTupleKind, RelationTupleIdentity } from './src/relations/tuple_key.js';
 export { RELATIONS_CHECK_MANY_MAX } from './src/relations/check_many.js';
-export type { RelationsReconcileReport, RelationsReconcileDetail } from './src/relations/reconcile.js';
-export { saveRelationsConfig, readRelationsConfig, readRelationsConfigSpec, } from './src/relations_config_store.js';
-export type { RelationsConfigStoreOptions } from './src/relations_config_store.js';
-export { DatabaseRelationsDriver } from './src/drivers/database_relations_driver.js';
+export { RELATIONS_ENUMERATE_DEFAULT_LIMIT, RELATIONS_ENUMERATE_MAX_LIMIT } from './src/relations/page.js';
+export { RELATIONS_GROUP_DEPTH_MEASURED, GROUP_DEPTH_CONFIG_MAX, GROUP_DEPTH_MAX_NODES, GROUP_DEPTH_MAX_READS, GROUP_DEPTH_MAX_TUPLES, GROUP_DEPTH_DEADLINE_MS, GROUP_DEPTH_CALIBRATION_BACKOFF_MS, GROUP_DEPTH_RECALIBRATION_MIN_INTERVAL_MS, } from './src/relations/group_depth.js';
+export type { RelationsReconcileReport, RelationsReconcileDetail, RelationsPartitionRefusal, RelationsPartitionRefusalReason } from './src/relations/reconcile.js';
+export { saveRelationsConfig, readRelationsConfig, readRelationsConfigSpec, checkRelationsConfigDenyReach, } from './src/relations_config_store.js';
+export type { RelationsConfigStoreOptions, SaveRelationsConfigOptions, RelationsConfigDenyReachCheck } from './src/relations_config_store.js';
+export type { DenyReachFinding, DenyReachReason } from './src/relations/deny_reach.js';
+export { DatabaseRelationsDriver, RELATIONS_MEMBERS_DENY_CHECK_MAX } from './src/drivers/database_relations_driver.js';
 export type { DatabaseRelationsDriverOptions } from './src/drivers/database_relations_driver.js';
 export { resolveGrantExpiry, isActiveExpiry, sameInstant } from './src/expiry.js';
 export { DatabaseAuthorizationDriver, APP_SCOPE_DB_UUID } from './src/drivers/database_driver.js';
@@ -86,7 +89,7 @@ export type { DatabaseDriverOptions } from './src/drivers/database_driver.js';
  * opcional `@openfga/sdk`. Un consumidor solo-database arranca sin él (D9).
  */
 export { APP_SCOPE, APP_SCOPE_TYPE, DEFAULT_RECONCILE_MAX_TUPLES } from './src/types.js';
-export type { AuthorizationDriver, AuthorizationDriverFactory, AuthorizedScopes, AuthzWriteEvent, AuthzCatalogWriteEvent, CatalogPermissionSpec, CatalogRole, CatalogRoleSpec, CatalogSpec, ScopedRoleChanges, ScopedRoleSpec, DenyOptions, DenyRef, ExcludedSubtree, GrantOptions, GrantOutcome, HolderTypeMap, ReconcileCounts, ReconcileFact, ReconcileFactPage, ReconcileFactsEnumerator, ReconcileOptions, ReconcileReport, ReconcileSkip, ReconcileSource, RoleQuery, ScopeChainResolver, ScopeDescendantsResolver, ScopeEdge, ScopeEdgePage, ScopeEdgesEnumerator, ScopedWriteOptions, ScopeRef, ScopeType, SubjectRef, WriteOptions, AuthorizationDriverCapabilities, RelationsDriver, RelationsDriverCapabilities, RelObject, RelSubject, RelUserset, RelationRef, RelationWriteEvent, RelationWriteOptions, RelationTransactionOptions, RelationPurgeOptions, RelationPage, RelationObjectsPage, RelationSubjectsPage, RelationTuple, RelationTuplePage, ScopeOutbox, ScopeOutboxContext, ScopeOutboxLease, ScopeOutboxPendingFilter, ScopeOutboxFailure, ScopeRequeueConflict, ScopeRequeueReport, ScopeTreeChange, PendingScopeTreeChange, RelayedScopeChange, ScopeRelayReport, ScopeRelayFailure, ScopeRelayEntry, ScopeRelayEntryStatus, ScopeEnqueueReceipt, } from './src/types.js';
+export type { AuthorizationDriver, AuthorizationDriverFactory, AuthorizedScopes, AuthzWriteEvent, AuthzCatalogWriteEvent, CatalogPermissionSpec, CatalogRole, CatalogRoleSpec, CatalogSpec, ScopedRoleChanges, ScopedRoleSpec, DenyOptions, DenyRef, ExcludedSubtree, GrantOptions, GrantOutcome, HolderTypeMap, ReconcileCounts, ReconcileFact, ReconcileFactPage, ReconcileFactsEnumerator, ReconcileOptions, ReconcileReport, ReconcileSkip, ReconcileSource, RoleQuery, ScopeChainResolver, ScopeDescendantsResolver, ScopeEdge, ScopeEdgePage, ScopeEdgesEnumerator, ScopedWriteOptions, ScopeRef, ScopeType, SubjectRef, WriteOptions, AuthorizationDriverCapabilities, RelationsDriver, RelationsDriverCapabilities, RelObject, RelSubject, RelUserset, RelationRef, RelationWriteEvent, RelationWriteOptions, RelationDenyOptions, RelationDecision, RelationTransactionOptions, RelationPurgeOptions, RelationPage, RelationObjectsPage, RelationSubjectsPage, RelationTuple, RelationTuplePage, ScopeOutbox, ScopeOutboxContext, ScopeOutboxLease, ScopeOutboxPendingFilter, ScopeOutboxFailure, ScopeRequeueConflict, ScopeRequeueReport, ScopeTreeChange, PendingScopeTreeChange, RelayedScopeChange, ScopeRelayReport, ScopeRelayFailure, ScopeRelayEntry, ScopeRelayEntryStatus, ScopeEnqueueReceipt, } from './src/types.js';
 export { isRelUserset } from './src/types.js';
 /**
  * **¿De quién es esta transacción?** (L-1 · 🟠 9, regla del puerto `{trx}`):
@@ -106,4 +109,3 @@ export { default as AuthzAssignment } from './src/models/authz_assignment.js';
 export { default as AuthzDeny } from './src/models/authz_deny.js';
 export { withAuthzScopes } from './src/traits/authz_scopes.js';
 export { hasUuid } from './src/traits/has_uuid.js';
-//# sourceMappingURL=index.d.ts.map

package/build/index.js

@@ -43,7 +43,7 @@ export { sqlScopeOutbox } from './src/scope_outbox.js';
  * obligaría a importar ese SDK — acoplando el call-site al backend que este
  * paquete existe para abstraer.
  */
-export { AuthorizationBackendError, AuthorizationBackendTimeoutError, ScopeResolverError, InvalidIdentityError, InvalidSlugError, AuthorizationConfigError, AuthorizationInternalError, UnknownScopeError, NoScopeResolverError, UnknownRoleError, UnknownPermissionError, CatalogConflictError, RoleIsNotAccessError, ScopeCycleError, PurgeIncompleteError, WriteConflictError, ActorRequiredError, CheckManyBatchError, NotWithinError, WithinRequiredError, WithinRootForbiddenError, TooManyScopesError, TooManyLocalRolesError, MassPurgeRefusedError, PruneInterruptedError, UnsupportedDialectError, ScopeTooDeepError, ScopeDepthLimitError, ScopeRequeueRefusedError, UnsupportedOperationError, NoDescendantsResolverError, ViewExpiredError, RoleNotVisibleError, AmbiguousRoleError, RoleImmutableError, RoleLevelAboveOwnerError, RoleNotAssignableAtError, PermissionNotDelegableError, RankExceededError, ModelTooLargeError, RelationConfigError, RelationConfigUnknownKeyError, RelationTypeUnknownError, RelationUnknownError, RelationUsersetUnsupportedError, ScopeTreeDriftError, ScopeDriftUnguardedError, AuthorizationFrozenError, FreezeHeldError, MassReconcileRefusedError, StaleSourceRefusedError, OperatorWindowExpiredError, ReconcileTooLargeError, 
+export { AuthorizationBackendError, AuthorizationBackendTimeoutError, ResolutionLimitError, ScopeResolverError, InvalidIdentityError, InvalidSlugError, AuthorizationConfigError, AuthorizationInternalError, UnknownScopeError, NoScopeResolverError, UnknownRoleError, UnknownPermissionError, CatalogConflictError, RoleIsNotAccessError, ScopeCycleError, PurgeIncompleteError, WriteConflictError, RenewalUnsafeError, RenewalRacedError, ActorRequiredError, CheckManyBatchError, NotWithinError, WithinRequiredError, WithinRootForbiddenError, TooManyScopesError, TooManyLocalRolesError, MassPurgeRefusedError, PruneInterruptedError, UnsupportedDialectError, ScopeTooDeepError, ScopeDepthLimitError, GroupDepthLimitError, ScopeRequeueRefusedError, UnsupportedOperationError, NoDescendantsResolverError, ViewExpiredError, RoleNotVisibleError, AmbiguousRoleError, RoleImmutableError, RoleLevelAboveOwnerError, RoleNotAssignableAtError, PermissionNotDelegableError, RankExceededError, ModelTooLargeError, RelationConfigError, RelationConfigUnknownKeyError, RelationTypeUnknownError, RelationUnknownError, RelationUsersetUnsupportedError, RelationNotDenyableError, RelationDenyExpiryError, MembersOfDenyLimitError, InvalidRelationPageError, ScopeTreeDriftError, ScopeDriftUnguardedError, AuthorizationFrozenError, FreezeHeldError, MassReconcileRefusedError, DenyMigrationRefusedError, DenyReachRefusedError, StaleSourceRefusedError, OperatorWindowExpiredError, ReconcileTooLargeError, 
 // Cierre de alpha.3 (invariante 13 en purgas multi-request): un driver de
 // relaciones de terceros marca con `markPartialWrite` el fallo que llega
 // DESPUÉS de haber borrado parte; el manager notifica `indeterminate: true`.
@@ -61,19 +61,27 @@ export { assertIdentity, assertSubject, assertScope, assertPartition, assertVali
  * `defineRelationsConfig`, la fachada `RelationsManager` (F-05 + `assertWrite`
  * + `actor`) y los tipos de la config.
  */
-export { defineRelationsConfig } from './src/relations/define_relations_config.js';
+export { defineRelationsConfig, DENIABLE_RELATION_NAME_MAX, RELATION_DENY_PREFIX, } from './src/relations/define_relations_config.js';
 export { RelationsManager } from './src/relations/manager.js';
 // Plan 2.5 · lote A: la clave PURA de una tupla (P3, con `kind` desde el primer día) y el tope de `checkMany` (P4).
 export { relationTupleKey, relationSubjectKey } from './src/relations/tuple_key.js';
 export { RELATIONS_CHECK_MANY_MAX } from './src/relations/check_many.js';
+// Lote «antes de RC» · 7.4: la página de `enumerate*` (default y techo; por encima se recorta con cursor).
+export { RELATIONS_ENUMERATE_DEFAULT_LIMIT, RELATIONS_ENUMERATE_MAX_LIMIT } from './src/relations/page.js';
+// Lote «antes de RC» · R1: las cotas de la anidación de grupos (la fila de «Limits»); la regla vive en los drivers.
+export { RELATIONS_GROUP_DEPTH_MEASURED, GROUP_DEPTH_CONFIG_MAX, GROUP_DEPTH_MAX_NODES, 
+// Cierre de R1 (🟠 1 del auditor): el presupuesto de la comprobación de una arista en openfga.
+GROUP_DEPTH_MAX_READS, GROUP_DEPTH_MAX_TUPLES, GROUP_DEPTH_DEADLINE_MS, 
+// Cierre-2 de R1 (D5): la espera tras una calibración fallida y la cota de la re-calibración tras un 503 de profundidad.
+GROUP_DEPTH_CALIBRATION_BACKOFF_MS, GROUP_DEPTH_RECALIBRATION_MIN_INTERVAL_MS, } from './src/relations/group_depth.js';
 // La config de relaciones PERSISTIDA (🟡3): API de PLATAFORMA (bajo el gate de
 // versión, invariante 14). La CONSUME `authz:relations:reconcile` (config del
 // destino, para la deriva del modelo fusionado en --dry-run).
-export { saveRelationsConfig, readRelationsConfig, readRelationsConfigSpec, } from './src/relations_config_store.js';
+export { saveRelationsConfig, readRelationsConfig, readRelationsConfigSpec, checkRelationsConfigDenyReach, } from './src/relations_config_store.js';
 // El driver `database` de relaciones (el consumidor lo cablea en
 // `relations.drivers` de config/authorization.ts). El driver `openfga` de
 // relaciones NO sale de aquí: vive en el subpath `/openfga` (peer opcional).
-export { DatabaseRelationsDriver } from './src/drivers/database_relations_driver.js';
+export { DatabaseRelationsDriver, RELATIONS_MEMBERS_DENY_CHECK_MAX } from './src/drivers/database_relations_driver.js';
 export { resolveGrantExpiry, isActiveExpiry, sameInstant } from './src/expiry.js';
 export { DatabaseAuthorizationDriver, APP_SCOPE_DB_UUID } from './src/drivers/database_driver.js';
 /**
@@ -100,4 +108,3 @@ export { default as AuthzAssignment } from './src/models/authz_assignment.js';
 export { default as AuthzDeny } from './src/models/authz_deny.js';
 export { withAuthzScopes } from './src/traits/authz_scopes.js';
 export { hasUuid } from './src/traits/has_uuid.js';
-//# sourceMappingURL=index.js.map

package/build/providers/authz_provider.d.ts

@@ -43,4 +43,3 @@ export default class AuthzProvider {
     constructor(app: ApplicationService);
     register(): void;
 }
-//# sourceMappingURL=authz_provider.d.ts.map

package/build/providers/authz_provider.js

@@ -84,4 +84,3 @@ export default class AuthzProvider {
         });
     }
 }
-//# sourceMappingURL=authz_provider.js.map

package/build/services/main.d.ts

@@ -7,4 +7,3 @@ import type { AuthorizationManager } from '../src/manager.js';
  */
 declare let authorization: AuthorizationManager;
 export { authorization as default };
-//# sourceMappingURL=main.d.ts.map

package/build/services/main.js

@@ -10,4 +10,3 @@ await app.booted(async () => {
     authorization = await app.container.make('authz.manager');
 });
 export { authorization as default };
-//# sourceMappingURL=main.js.map

package/build/services/relations.d.ts

@@ -11,4 +11,3 @@ import type { RelationsManager } from '../src/relations/manager.js';
  */
 declare let relations: RelationsManager;
 export { relations as default };
-//# sourceMappingURL=relations.d.ts.map

package/build/services/relations.js

@@ -14,4 +14,3 @@ await app.booted(async () => {
     relations = await app.container.make('authz.relations');
 });
 export { relations as default };
-//# sourceMappingURL=relations.js.map

package/build/src/catalog/catalog.d.ts

@@ -286,4 +286,3 @@ export declare function runCatalogDiff(catalogs: CatalogSource[], options?: {
 export declare function syncCatalogs(catalogs: CatalogSource[], options?: SyncCatalogOptions): Promise<{
     count: number;
 } & CatalogSyncReport>;
-//# sourceMappingURL=catalog.d.ts.map

package/build/src/catalog/catalog.js

@@ -856,4 +856,3 @@ export async function syncCatalogs(catalogs, options = {}) {
     }
     return { count, shadowedByGlobal, assignableAtViolations };
 }
-//# sourceMappingURL=catalog.js.map

package/build/src/catalog/catalog_cache.d.ts

@@ -304,6 +304,19 @@ export declare class CatalogCache {
      * vuelve a intentarlo.
      */
     view(): Promise<CatalogView>;
+    /**
+     * **La foto para una ESCRITURA** (lote C · carreras, resolución 2 del juez = K4): contrasta la versión con la fila
+     * SIEMPRE, ignore o no la ventana `{ everyMs }`. Con `'always'` es exactamente `view()`. La ventana es para DECIDIR
+     * (invariante 14: una pregunta puede responder con un catálogo de hasta `everyMs` de antigüedad); una escritura del driver
+     * deja ESTADO en el store que no caduca —el barrido de `moved`, el settle, la proyección—, y con un memo rancio un rol
+     * recién definido en otro proceso no se barre (fail-open persistente medido, K4). Coste: el SELECT por PK de `'always'`.
+     *
+     * **Nunca se suma a una comprobación ni a una carga EN VUELO** (asentar · cierre 2, ⚪ 6 / O-6 del auditor): la que ya
+     * estaba en marcha pudo leer la fila ANTES de la escritura que precede a esta llamada (la propia, o la de otro proceso
+     * que la escritura acaba de observar) y serviría esa foto. Se espera la carga en vuelo y se lee la versión otra vez;
+     * una carga que arranca DESPUÉS de esta llamada sí se comparte (ya es posterior).
+     */
+    freshView(): Promise<CatalogView>;
     /**
      * Olvida la foto de ESTE memo. La siguiente pregunta recarga. Es un bump
      * de generación, no un `#view = null`: una carga en vuelo capturó la
@@ -321,4 +334,3 @@ export declare class CatalogCache {
  * disfrazado de dato.
  */
 export declare function parseAssignableAt(slug: string, raw: unknown): readonly ScopeType[] | null;
-//# sourceMappingURL=catalog_cache.d.ts.map

package/build/src/catalog/catalog_cache.js

@@ -420,6 +420,31 @@ export class CatalogCache {
         }
         return this.#reload();
     }
+    /**
+     * **La foto para una ESCRITURA** (lote C · carreras, resolución 2 del juez = K4): contrasta la versión con la fila
+     * SIEMPRE, ignore o no la ventana `{ everyMs }`. Con `'always'` es exactamente `view()`. La ventana es para DECIDIR
+     * (invariante 14: una pregunta puede responder con un catálogo de hasta `everyMs` de antigüedad); una escritura del driver
+     * deja ESTADO en el store que no caduca —el barrido de `moved`, el settle, la proyección—, y con un memo rancio un rol
+     * recién definido en otro proceso no se barre (fail-open persistente medido, K4). Coste: el SELECT por PK de `'always'`.
+     *
+     * **Nunca se suma a una comprobación ni a una carga EN VUELO** (asentar · cierre 2, ⚪ 6 / O-6 del auditor): la que ya
+     * estaba en marcha pudo leer la fila ANTES de la escritura que precede a esta llamada (la propia, o la de otro proceso
+     * que la escritura acaba de observar) y serviría esa foto. Se espera la carga en vuelo y se lee la versión otra vez;
+     * una carga que arranca DESPUÉS de esta llamada sí se comparte (ya es posterior).
+     */
+    async freshView() {
+        if (this.#loading)
+            await this.#loading.catch(() => undefined);
+        const current = this.#view;
+        if (!current || !this.#isFresh())
+            return this.#reload();
+        const dbVersion = await this.#readVersion();
+        if (this.#view === current && this.#isFresh() && dbVersion === current.version) {
+            this.#checkedAt = this.#now();
+            return current;
+        }
+        return this.#reload(dbVersion);
+    }
     /** Una carga compartida; `knownVersion` es la fila recién leída por una revalidación (se ahorra releerla). */
     #reload(knownVersion) {
         if (!this.#loading) {
@@ -663,4 +688,3 @@ function buildCatalogView(permissions, roles, links, loadedAt, version) {
         version,
     };
 }
-//# sourceMappingURL=catalog_cache.js.map

package/build/src/clock.d.ts

@@ -21,4 +21,3 @@ export type Clock = () => Date;
 export declare const systemClock: Clock;
 /** `now` tiene que ser una función; se valida al construir (500 `E_AUTHZ_CONFIG` es del llamante). */
 export declare function isClock(value: unknown): value is Clock;
-//# sourceMappingURL=clock.d.ts.map

package/build/src/clock.js

@@ -4,4 +4,3 @@ export const systemClock = () => new Date();
 export function isClock(value) {
     return typeof value === 'function';
 }
-//# sourceMappingURL=clock.js.map

package/build/src/define_config.d.ts

@@ -381,4 +381,3 @@ export declare function defineConfig<T extends AuthorizationConfig>(config: T):
  * barata (claves, no valores).
  */
 export declare function assertAuthorizationConfigShape(config: unknown): void;
-//# sourceMappingURL=define_config.d.ts.map

package/build/src/define_config.js

@@ -77,12 +77,36 @@ function assertConfigBlock(value, path) {
             `una clave conocida no es «nada»: se ignoraría en silencio (plan 2.5 · B2).`);
     }
 }
+/**
+ * **Lápidas: claves que NO existen aquí pero que la letra de una decisión firmada nombra así** (cierre-2 de R1 · D1 (a),
+ * decisión del dueño 2026-10-20: «`relations.maxGroupDepth` ⇒ 500 con mensaje que apunta a `defineRelationsConfig`»).
+ * La decisión (5) escribió `relations.maxGroupDepth`; el mando vive en `defineRelationsConfig` (la config que capturan
+ * las factories de los drivers, `manager.driver()` y `runRelationsReconcile`) y se lee como `relations.config.maxGroupDepth`.
+ * Sin alias (una clave hermana se validaría y no gobernaría tres de las cuatro rutas): la ruta literal es el MISMO 500
+ * de clave desconocida, con la receta del sitio bueno en vez de la lista de claves.
+ */
+const MISPLACED_CONFIG_KEYS = Object.freeze({
+    'relations.maxGroupDepth': "defineConfig: la clave 'relations.maxGroupDepth' no existe. El techo de anidación de grupos va en la config de " +
+        'RELACIONES: defineRelationsConfig({ objectTypes, maxGroupDepth, database: { enforceGroupDepth } }), y ese objeto en ' +
+        'relations.config. Es la config que capturan los drivers (las factories de relations.drivers), manager.driver() y ' +
+        'runRelationsReconcile (authz:relations:reconcile): una clave hermana de relations no llegaría a ninguno y el límite ' +
+        'no se aplicaría.',
+    'relations.enforceGroupDepth': "defineConfig: la clave 'relations.enforceGroupDepth' no existe. El opt-in del techo de anidación de grupos en " +
+        'database va en la config de RELACIONES: defineRelationsConfig({ objectTypes, maxGroupDepth, database: { ' +
+        'enforceGroupDepth: true } }), y ese objeto en relations.config (la que capturan los drivers).',
+});
 function assertKnownConfigKeys(value, known, path) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         return;
     for (const key of Object.keys(value)) {
         if (known.includes(key))
             continue;
+        // Cierre-3 · R-6: `Object.hasOwn` — una clave `constructor`/`toString` (o un `__proto__` propio de un JSON) leía el
+        // prototipo de la tabla y el 500 llevaba de mensaje `function Object() { [native code] }`.
+        const dotted = path === '' ? key : `${path}.${key}`;
+        const tombstone = Object.hasOwn(MISPLACED_CONFIG_KEYS, dotted) ? MISPLACED_CONFIG_KEYS[dotted] : undefined;
+        if (tombstone !== undefined)
+            throw new AuthorizationConfigError(tombstone);
         const where = path === '' ? `'${key}' en la raíz` : `'${path}.${key}'`;
         throw new AuthorizationConfigError(`defineConfig: la clave ${where} no existe (claves válidas en ${path === '' ? 'la raíz' : path}: ${known.join(', ')}). ` +
             `Ninguna clave del config se descarta en silencio (plan 2.5 · B2): un typo ('requireWithing') sería una ` +
@@ -121,4 +145,3 @@ export function assertAuthorizationConfigShape(config) {
         assertKnownConfigKeys(c[block], AUTHORIZATION_CONFIG_KEYS[block], block);
     }
 }
-//# sourceMappingURL=define_config.js.map

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

@@ -204,6 +204,12 @@ export declare class DatabaseAuthorizationDriver implements AuthorizationDriver
      */
     readonly catalog: CatalogCache;
     constructor(options?: DatabaseDriverOptions);
+    /**
+     * **El catálogo de una ESCRITURA** (K4; asentar · cierre 2, D-1): 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). Gemelo de `OpenFgaAuthorizationDriver.writeCatalog`.
+     */
+    private writeCatalog;
     /**
      * Vista de este driver con OTRO resolutor de la cadena y el mismo estado
      * (conexión, memo del catálogo, deadline). Es lo que usa
@@ -393,4 +399,3 @@ export declare class DatabaseAuthorizationDriver implements AuthorizationDriver
      */
     private eachReconcileRow;
 }
-//# sourceMappingURL=database_driver.d.ts.map