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

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

@@ -1,3 +1,4 @@
+import { AuthorizationConfigError } from '../errors.js';
 import type { CatalogProjectionRole, HolderTypeMap } from '../types.js';
 /**
  * `holderTypes` tiene que ser INYECTIVO. Si dos morph names caen en el mismo
@@ -333,6 +334,12 @@ export interface RelationObjectType {
     type: string;
     /** Sus relaciones, en orden de declaración. */
     relations: readonly RelationObjectRelation[];
+    /**
+     * Opt-in del deny (plan 2.5 · lote D, D10): con `'read'` o `'write'` el generador emite, por cada relación `X`,
+     * `X = <la de hoy> but not denied_X` y `denied_X = this ∨ denied_P` (por cada `P` que incluye a `X`). Ausente ⇒
+     * el literal de 2.4.0-alpha.10, byte a byte (D-29).
+     */
+    deny?: 'read' | 'write';
 }
 /**
  * La config de relaciones que el generador FUSIONA en el modelo `facts`
@@ -381,4 +388,108 @@ export declare function assertRelationsConfigPublishable(permissionRelations: re
  * `(holders + 1) × (tipo + 'not_expired')` bytes por relación declarada.
  */
 export declare function factsRelationTypeDefinitions(permissionRelations: readonly FactsRelations[], config: FactsRelationsConfig, holderTypes: readonly string[]): any[];
-//# sourceMappingURL=openfga_facts.d.ts.map
+/**
+ * **Las reglas de reescritura (`relations`) de UN tipo de objeto, tal como las genera el paquete** — la fuente ÚNICA
+ * del generador (`factsRelationTypeDefinitions`) y de la guarda D-31 del driver (cierre 2 de D1, ⚪ N4: la guarda
+ * compara el modelo FIJADO con ESTO, por igualdad estructural, no solo la forma). Pura y sin holders: el `metadata`
+ * (qué sujetos admite cada relación) no decide qué concede.
+ */
+export declare function factsRelationRewrites(objectType: RelationObjectType): Record<string, unknown>;
+/**
+ * **Forma canónica de una regla de reescritura** para compararla con la que devuelve el servidor (cierre 2 de D1,
+ * ⚪ N4). MEDIDO en v1.19.0: `ReadAuthorizationModel` devuelve las relaciones en otro orden de claves y cada
+ * `computedUserset` con `object: ""`; ninguna de las dos cosas cambia qué concede. Se ordenan las claves, se quita el
+ * `object` vacío y se ordenan los hijos de `union`/`intersection` (conmutativos; `difference` tiene `base`/`subtract`
+ * con nombre y no se toca). Cualquier otra diferencia es una regla DISTINTA.
+ */
+export declare function canonicalRewrite(node: unknown): unknown;
+/**
+ * Qué tipos compara cada puerta (L11): `roles` (los holders, `role`, `role_binding`, `scope`), `relations` (los holders,
+ * `group` y los tipos de la config) y `all` (el modelo ENTERO que generaría la config, más todo tipo que el servido
+ * traiga de más: la relectura de `openfga:provision`). Las condiciones y `schema_version` se comparan SIEMPRE.
+ */
+export type FactsModelSlice = 'roles' | 'relations' | 'all';
+/** Una diferencia del modelo servido respecto del generado, por RUTA legible. `type: null` = global (condiciones…). */
+export interface FactsModelDifference {
+    type: string | null;
+    path: string;
+}
+export interface FactsModelComparison {
+    equal: boolean;
+    differences: FactsModelDifference[];
+    /**
+     * La forma con la que el modelo servido trae cada tipo de relaciones de la config: `deny` (con `denied_<rel>`) o
+     * `plain`. Con opt-in siempre `deny`; sin él, **D8 por TIPO ENTERO** (cierra P2: un modelo MEZCLADO, unas relaciones
+     * con la forma con deny y otras sin ella, no lo genera ninguna config y es diferencia). Lo usa `decideMany`.
+     */
+    denyForm: ReadonlyMap<string, 'plain' | 'deny'>;
+    /** P_M: los permisos que declara el propio modelo servido (las bases de `role#permits_*`), ordenados. */
+    permissions: string[];
+}
+/**
+ * **Forma canónica de un modelo (o de cualquier trozo) de OpenFGA** para compararlo con el que genera el paquete
+ * (L11; extiende `canonicalRewrite`). MEDIDO contra v1.19.0 (`:8090`): el servidor devuelve el ruido de proto3
+ * —`module: ""`, `source_info: null`, `condition: ""` en cada restricción, `metadata: null`, `generic_types: []`,
+ * `object: ""` en cada `computedUserset`— y otro orden de claves. Se quitan los valores por defecto de proto3 (`""`,
+ * `null`, `[]`), **NUNCA un `{}`** (`this: {}` y `wildcard: {}` significan algo), se ordenan las claves y los hijos
+ * CONMUTATIVOS (`child` de `union`/`intersection` y `directly_related_user_types`; `difference` tiene `base`/
+ * `subtract` con nombre y no se toca). Una restricción DUPLICADA no se funde: es una diferencia.
+ */
+export declare function canonicalModel(node: unknown): unknown;
+/**
+ * **El punto de paso ÚNICO de L11** (lote «antes de RC», decisión del dueño 2026-10-17 (1); linaje L11): compara el
+ * modelo que SIRVE el servidor con el que genera la config de este proceso, POR TIPO, en reglas, restricciones de
+ * tipo (con su condición) y condiciones. Pura y sin SDK. Determinista: no busca entre combinaciones.
+ *
+ *  1. `P_M` = los permisos que declara el propio servido (`role#permits_*`): la igualdad es «módulo el catálogo», que
+ *     cambia en runtime (el desfase catálogo ↔ modelo lo cuenta el reconcile, `permission-not-in-model`).
+ *  2. `D8_M` = los tipos de la config SIN opt-in que el servido trae con la forma con deny (algún `denied_*`): se
+ *     generan con `deny` para comparar — por TIPO ENTERO —.
+ *  3. Se genera `openFgaFactsModel(holderTypes, P_M, config con D8_M)`; si el generador lanza (un `permits_*` del
+ *     servido que no es un nombre publicable), es 500 `E_AUTHZ_CONFIG`, nunca «igual» (H11 d).
+ *  4. Diferencias por ruta: `<tipo> (tipo ausente)`, `<tipo>#<rel> (falta)`, `(relación de más)` —una relación EXTRA
+ *     es deriva, D-L11-3—, `(regla)`, `(restricciones de tipo)`, `<tipo>.<campo>`, `conditions.<nombre> (…)`,
+ *     `schema_version`. Un tipo AJENO al `slice` no se mira (límite declarado y razonado, caso C7); con `all`, sí.
+ */
+export declare function factsModelDifferences(served: unknown, inputs: {
+    holderTypes: HolderTypeMap;
+    relations?: FactsRelationsConfig;
+    slice: FactsModelSlice;
+}): FactsModelComparison;
+/** Cuántas rutas nombra como mucho la letra del 500 de L11 (el resto se cuenta). */
+export declare const FACTS_MODEL_DRIFT_LISTED = 20;
+/**
+ * **La LETRA del 500 de la puerta L11**, la MISMA en los dos drivers `openfga`: qué driver, qué operación, qué
+ * `modelId`, las diferencias por ruta y la receta. Cero llamadas que evalúen o escriban.
+ */
+export declare function factsModelDriftError(driver: string, operation: string, modelId: string | undefined, differences: readonly FactsModelDifference[]): AuthorizationConfigError & {
+    modelDifferences: string[];
+};
+/**
+ * **El token del opt-in de `openfga` EXPERIMENTAL en 2.5.x** (estrategia 2.5.0, firma 4 del dueño 2026-10-21, «(b) con
+ * candado»). Lleva la VERSIÓN a propósito (auditor B1/B7, tester E1): con `true` nada obligaría a releer los límites NUEVOS
+ * cuando cambien; con `'openfga@2.5'` la 2.6 cambiará el token y un `^2.5.0` que se actualice hace ruido (500) en vez de
+ * colarse. NO se exporta por `/openfga`: el consumidor escribe el LITERAL, que es lo que demuestra que leyó «Limits».
+ */
+export declare const OPENFGA_EXPERIMENTAL_TOKEN = "openfga@2.5";
+/**
+ * **La puerta del opt-in experimental, en los DOS constructores `openfga`** (firma 4; mismo patrón que
+ * `E_AUTHZ_SCOPE_DRIFT_UNGUARDED`: «una recomendación no es un mecanismo»). En 2.5.x `openfga` tiene límites declarados
+ * en README «Limits» (carreras entre escritores, árbol con outbox sin medir, el gemelo `permits_*`…) que se cierran en
+ * 2.6, así que construirlo exige escribir `experimental: 'openfga@2.5'`. Cualquier otra cosa —ausente, `true`,
+ * `'acknowledged'`, otra versión, el token con espacios— es 500 `E_AUTHZ_CONFIG` al CONSTRUIR, como PRIMERA línea del
+ * constructor: ni se valida lo demás ni se crea el cliente, así que hay CERO llamadas al servidor. Va en el constructor
+ * y no en el stub ni en el registro de la factory: `manager.driver()` (y con él `authz:catalog:sync`),
+ * `authz:reconcile --to=openfga`, `authz:relations:reconcile`, el provider y la construcción directa pasan todos por
+ * aquí, y un config solo-`database` que REGISTRA la factory `openfga` sin usarla arranca (las factories son perezosas).
+ * `openfga:provision` NO construye un driver (crea el store y publica el modelo con el SDK): corre sin la marca, y el
+ * primer driver que sirva con ese store, no.
+ */
+export declare function assertExperimentalOptIn(driver: string, value: unknown): void;
+/**
+ * **`modelId` OBLIGATORIO en los dos drivers `openfga`** (lote «antes de RC» · L11, decisión del dueño 2026-10-17 (2);
+ * D14 ampliado: siempre, con o sin deny). Sin el pin la puerta L11 compara el modelo que el driver lee al arrancar y el
+ * servidor evalúa cada petición con el ÚLTIMO del store: un `openfga:provision` desde otro proceso cambiaría lo que se
+ * concede sin que ninguna comparación lo vea. 500 al CONSTRUIR, con la receta.
+ */
+export declare function assertPinnedModel(driver: string, modelId: unknown): void;

package/build/src/drivers/openfga_facts.js

@@ -1,6 +1,7 @@
-import { InvalidIdentityError, InvalidSlugError, ModelTooLargeError, AuthorizationConfigError, RelationConfigError, } from '../errors.js';
+import { InvalidIdentityError, InvalidSlugError, ModelTooLargeError, AuthorizationConfigError, RelationConfigError, markDeploymentFailure, } from '../errors.js';
 import { slugAsRelation, RESERVED_SLUG_PREFIXES, RESERVED_FACTS_TYPES } from '../identity.js';
 import { APP_SCOPE_TYPE } from '../types.js';
+import { FGA_EXPIRY_CONDITION } from '../expiry.js';
 /**
  * Modo `facts` — el MODELO (c2) y la proyección del catálogo, sin `@openfga/sdk`.
  *
@@ -202,7 +203,7 @@ export const FACTS_ROOTED_RELATION = 'rooted';
  * `role_binding#assignee` desde el modo `facts`, y desde R-15 también la de
  * cada sujeto de una relación ReBAC (`document#viewer`, `group#member`…).
  */
-export const FACTS_EXPIRY_CONDITION = 'not_expired';
+export const FACTS_EXPIRY_CONDITION = FGA_EXPIRY_CONDITION;
 /* ── Relaciones derivadas de un permiso ─────────────────────────────────── */
 /**
  * Relaciones propias del modelo (no derivadas de ningún permiso). Un permiso
@@ -751,6 +752,16 @@ export function assertRelationsConfigPublishable(permissionRelations, config, ho
             own.add(name);
             relationNames.add(name);
         }
+        // D1 (lote D): en un tipo con deny, `denied_<X>` tiene que caber en los 50 de FGA (defensa en profundidad de la
+        // cota de 43 que ya aplica `defineRelationsConfig`).
+        if (objectType.deny !== undefined) {
+            for (const name of own) {
+                if (FACTS_DENIED_PREFIX.length + name.length > FGA_MAX_RELATION_NAME) {
+                    throw new RelationConfigError(`La relación '${type}#${name}' tiene ${name.length} caracteres y el tipo declara deny: '${FACTS_DENIED_PREFIX}${name}' ` +
+                        `no cabe en los ${FGA_MAX_RELATION_NAME} de FGA (una relación denegable mide como mucho ${FGA_MAX_RELATION_NAME - FACTS_DENIED_PREFIX.length}).`);
+                }
+            }
+        }
         // Los `includes` refieren relaciones del MISMO tipo (un nivel, sin `from`).
         for (const relation of objectType.relations ?? []) {
             for (const included of relation.includes ?? []) {
@@ -820,17 +831,346 @@ export function factsRelationTypeDefinitions(permissionRelations, config, holder
         },
     ];
     for (const objectType of config.objectTypes) {
-        const relations = {};
+        const relations = factsRelationRewrites(objectType);
+        // `<rel>` y `denied_<rel>` admiten los MISMOS sujetos (holders y `group#member`, con y sin `not_expired`).
         const metadata = {};
-        for (const relation of objectType.relations) {
-            const includes = relation.includes ?? [];
-            relations[relation.name] = includes.length
-                ? { union: { child: [{ this: {} }, ...includes.map((name) => computed(name))] } }
-                : { this: {} };
-            metadata[relation.name] = { directly_related_user_types: holdersOrGroup };
-        }
+        for (const name of Object.keys(relations))
+            metadata[name] = { directly_related_user_types: holdersOrGroup };
         definitions.push({ type: objectType.type, relations, metadata: { relations: metadata } });
     }
     return definitions;
 }
-//# sourceMappingURL=openfga_facts.js.map
+/**
+ * **Las reglas de reescritura (`relations`) de UN tipo de objeto, tal como las genera el paquete** — la fuente ÚNICA
+ * del generador (`factsRelationTypeDefinitions`) y de la guarda D-31 del driver (cierre 2 de D1, ⚪ N4: la guarda
+ * compara el modelo FIJADO con ESTO, por igualdad estructural, no solo la forma). Pura y sin holders: el `metadata`
+ * (qué sujetos admite cada relación) no decide qué concede.
+ */
+export function factsRelationRewrites(objectType) {
+    const relations = {};
+    for (const relation of objectType.relations) {
+        const includes = relation.includes ?? [];
+        const base = includes.length
+            ? { union: { child: [{ this: {} }, ...includes.map((name) => computed(name))] } }
+            : { this: {} };
+        if (objectType.deny === undefined) {
+            // D-29: sin opt-in, el literal de 2.4.0-alpha.10 byte a byte.
+            relations[relation.name] = base;
+            continue;
+        }
+        // **D5 · corte de camino en el MODELO** (lote D, medido en ronda 1 y 2 contra v1.19.0): `X = base but not
+        // denied_X` y `denied_X = this ∨ denied_P` por cada `P` que INCLUYE a `X` (el cierre ASCENDENTE): un deny en
+        // `editor` alcanza a `denied_owner`, así que el grant de `owner` deja de valer entero —y con él lo que deriva—.
+        // `denied_X` admite los MISMOS sujetos que `X` (holders y `group#member`, con y sin `not_expired`): el deny de
+        // relaciones no caduca (D3), pero un deny puede viajar por una membresía de grupo que sí caduca (M6, caso C).
+        const denied = `${FACTS_DENIED_PREFIX}${relation.name}`;
+        const includers = objectType.relations.filter((other) => (other.includes ?? []).includes(relation.name));
+        relations[relation.name] = { difference: { base, subtract: computed(denied) } };
+        relations[denied] = includers.length
+            ? { union: { child: [{ this: {} }, ...includers.map((other) => computed(`${FACTS_DENIED_PREFIX}${other.name}`))] } }
+            : { this: {} };
+    }
+    return relations;
+}
+/**
+ * **Forma canónica de una regla de reescritura** para compararla con la que devuelve el servidor (cierre 2 de D1,
+ * ⚪ N4). MEDIDO en v1.19.0: `ReadAuthorizationModel` devuelve las relaciones en otro orden de claves y cada
+ * `computedUserset` con `object: ""`; ninguna de las dos cosas cambia qué concede. Se ordenan las claves, se quita el
+ * `object` vacío y se ordenan los hijos de `union`/`intersection` (conmutativos; `difference` tiene `base`/`subtract`
+ * con nombre y no se toca). Cualquier otra diferencia es una regla DISTINTA.
+ */
+export function canonicalRewrite(node) {
+    if (Array.isArray(node))
+        return node.map(canonicalRewrite);
+    if (node === null || typeof node !== 'object')
+        return node;
+    const out = {};
+    for (const key of Object.keys(node).sort()) {
+        const value = node[key];
+        if (value === undefined || (key === 'object' && value === ''))
+            continue;
+        out[key] = canonicalRewrite(value);
+    }
+    if (Array.isArray(out.child)) {
+        out.child = [...out.child].sort((a, b) => {
+            const x = JSON.stringify(a);
+            const y = JSON.stringify(b);
+            return x < y ? -1 : x > y ? 1 : 0;
+        });
+    }
+    return out;
+}
+/**
+ * **Forma canónica de un modelo (o de cualquier trozo) de OpenFGA** para compararlo con el que genera el paquete
+ * (L11; extiende `canonicalRewrite`). MEDIDO contra v1.19.0 (`:8090`): el servidor devuelve el ruido de proto3
+ * —`module: ""`, `source_info: null`, `condition: ""` en cada restricción, `metadata: null`, `generic_types: []`,
+ * `object: ""` en cada `computedUserset`— y otro orden de claves. Se quitan los valores por defecto de proto3 (`""`,
+ * `null`, `[]`), **NUNCA un `{}`** (`this: {}` y `wildcard: {}` significan algo), se ordenan las claves y los hijos
+ * CONMUTATIVOS (`child` de `union`/`intersection` y `directly_related_user_types`; `difference` tiene `base`/
+ * `subtract` con nombre y no se toca). Una restricción DUPLICADA no se funde: es una diferencia.
+ */
+export function canonicalModel(node) {
+    if (Array.isArray(node))
+        return node.map(canonicalModel);
+    if (node === null || typeof node !== 'object')
+        return node;
+    // Cierre de L11 (⚪ A3.2 del auditor): SIN prototipo — una relación o condición de más llamada `__proto__` (el servidor
+    // v1.19 la acepta, medido) cambiaba el prototipo de un objeto literal en vez de ser una clave, y el comparador decía
+    // «igual» (D-L11-3: relación de más = deriva). Con `Object.create(null)` es una clave propia más y se ve.
+    const out = Object.create(null);
+    for (const key of Object.keys(node).sort()) {
+        const value = node[key];
+        if (value === undefined || value === null || value === '')
+            continue;
+        if (Array.isArray(value) && value.length === 0)
+            continue;
+        out[key] = canonicalModel(value);
+    }
+    for (const key of ['child', 'directly_related_user_types']) {
+        if (Array.isArray(out[key]))
+            out[key] = sortByJson(out[key]);
+    }
+    return out;
+}
+function sortByJson(items) {
+    return [...items].sort((a, b) => {
+        const x = JSON.stringify(a);
+        const y = JSON.stringify(b);
+        return x < y ? -1 : x > y ? 1 : 0;
+    });
+}
+const sameCanon = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+/**
+ * **El punto de paso ÚNICO de L11** (lote «antes de RC», decisión del dueño 2026-10-17 (1); linaje L11): compara el
+ * modelo que SIRVE el servidor con el que genera la config de este proceso, POR TIPO, en reglas, restricciones de
+ * tipo (con su condición) y condiciones. Pura y sin SDK. Determinista: no busca entre combinaciones.
+ *
+ *  1. `P_M` = los permisos que declara el propio servido (`role#permits_*`): la igualdad es «módulo el catálogo», que
+ *     cambia en runtime (el desfase catálogo ↔ modelo lo cuenta el reconcile, `permission-not-in-model`).
+ *  2. `D8_M` = los tipos de la config SIN opt-in que el servido trae con la forma con deny (algún `denied_*`): se
+ *     generan con `deny` para comparar — por TIPO ENTERO —.
+ *  3. Se genera `openFgaFactsModel(holderTypes, P_M, config con D8_M)`; si el generador lanza (un `permits_*` del
+ *     servido que no es un nombre publicable), es 500 `E_AUTHZ_CONFIG`, nunca «igual» (H11 d).
+ *  4. Diferencias por ruta: `<tipo> (tipo ausente)`, `<tipo>#<rel> (falta)`, `(relación de más)` —una relación EXTRA
+ *     es deriva, D-L11-3—, `(regla)`, `(restricciones de tipo)`, `<tipo>.<campo>`, `conditions.<nombre> (…)`,
+ *     `schema_version`. Un tipo AJENO al `slice` no se mira (límite declarado y razonado, caso C7); con `all`, sí.
+ */
+export function factsModelDifferences(served, inputs) {
+    const model = served;
+    if (!model || typeof model !== 'object' || !Array.isArray(model.type_definitions)) {
+        throw new AuthorizationConfigError('L11: el modelo servido no trae type_definitions; no se puede comparar con el que genera la config (no se toma por igual).');
+    }
+    const differences = [];
+    const servedTypes = new Map();
+    for (const definition of model.type_definitions) {
+        const type = definition?.type;
+        if (typeof type !== 'string' || type === '') {
+            differences.push({ type: null, path: 'type_definitions (un tipo sin nombre)' });
+            continue;
+        }
+        if (servedTypes.has(type))
+            differences.push({ type, path: `${type} (tipo duplicado)` });
+        servedTypes.set(type, definition);
+    }
+    const permissions = inputs.slice === 'relations'
+        ? []
+        : Object.keys(servedTypes.get(FACTS_ROLE_TYPE)?.relations ?? {})
+            .filter((name) => name.startsWith(FACTS_PERMITS_PREFIX))
+            .map((name) => name.slice(FACTS_PERMITS_PREFIX.length))
+            .sort();
+    const denyForm = new Map();
+    let relationsConfig;
+    if (inputs.relations && inputs.slice !== 'roles') {
+        relationsConfig = {
+            objectTypes: inputs.relations.objectTypes.map((spec) => {
+                if (spec.deny !== undefined) {
+                    denyForm.set(spec.type, 'deny');
+                    return spec;
+                }
+                const d8 = Object.keys(servedTypes.get(spec.type)?.relations ?? {}).some((name) => name.startsWith(FACTS_DENIED_PREFIX));
+                denyForm.set(spec.type, d8 ? 'deny' : 'plain');
+                return d8 ? { ...spec, deny: 'read' } : spec;
+            }),
+        };
+    }
+    let generated;
+    try {
+        generated = openFgaFactsModel(inputs.holderTypes, permissions, relationsConfig);
+    }
+    catch (error) {
+        throw markDeploymentFailure(new AuthorizationConfigError(`L11: no se puede generar el modelo de la config con los permisos que declara el modelo servido ` +
+            `(${error?.message ?? String(error)}); no se toma por igual.`, { cause: error }));
+    }
+    const generatedTypes = new Map(generated.type_definitions.map((definition) => [definition.type, definition]));
+    const holders = Object.values(inputs.holderTypes);
+    const sliceTypes = inputs.slice === 'all'
+        ? [...generatedTypes.keys()]
+        : inputs.slice === 'roles'
+            ? [...holders, FACTS_ROLE_TYPE, FACTS_BINDING_TYPE, FACTS_SCOPE_TYPE]
+            : [...holders, FACTS_GROUP_TYPE, ...(inputs.relations?.objectTypes ?? []).map((t) => t.type)];
+    for (const type of sliceTypes)
+        compareTypeDefinition(type, servedTypes.get(type), generatedTypes.get(type), differences);
+    if (inputs.slice === 'all') {
+        for (const type of servedTypes.keys()) {
+            if (!generatedTypes.has(type))
+                differences.push({ type, path: `${type} (tipo de más)` });
+        }
+    }
+    const servedConditions = (canonicalModel(model.conditions ?? {}) ?? {});
+    const generatedConditions = canonicalModel(generated.conditions);
+    for (const name of [...new Set([...Object.keys(servedConditions), ...Object.keys(generatedConditions)])].sort()) {
+        if (!(name in servedConditions))
+            differences.push({ type: null, path: `conditions.${name} (falta)` });
+        else if (!(name in generatedConditions))
+            differences.push({ type: null, path: `conditions.${name} (condición de más)` });
+        else if (!sameCanon(servedConditions[name], generatedConditions[name]))
+            differences.push({ type: null, path: `conditions.${name} (distinta)` });
+    }
+    if (!sameCanon(canonicalModel(model.schema_version), generated.schema_version)) {
+        differences.push({ type: null, path: `schema_version (${JSON.stringify(model.schema_version ?? null)})` });
+    }
+    for (const key of Object.keys(model).sort()) {
+        if (['id', 'schema_version', 'type_definitions', 'conditions'].includes(key))
+            continue;
+        const value = model[key];
+        if (value === undefined || value === null || value === '' || (Array.isArray(value) && value.length === 0))
+            continue;
+        differences.push({ type: null, path: `modelo.${key}` });
+    }
+    return { equal: differences.length === 0, differences, denyForm, permissions };
+}
+function compareTypeDefinition(type, served, generated, out) {
+    if (generated === undefined)
+        return;
+    if (served === undefined) {
+        out.push({ type, path: `${type} (tipo ausente del modelo)` });
+        return;
+    }
+    const s = canonicalModel(served);
+    const g = canonicalModel(generated);
+    const sRelations = s.relations ?? {};
+    const gRelations = g.relations ?? {};
+    const reported = new Set();
+    for (const name of [...new Set([...Object.keys(sRelations), ...Object.keys(gRelations)])].sort()) {
+        if (!(name in sRelations))
+            out.push({ type, path: `${type}#${name} (falta)` });
+        else if (!(name in gRelations))
+            out.push({ type, path: `${type}#${name} (relación de más)` });
+        else if (!sameCanon(sRelations[name], gRelations[name]))
+            out.push({ type, path: `${type}#${name} (regla)` });
+        else
+            continue;
+        reported.add(name);
+    }
+    const sMeta = s.metadata?.relations ?? {};
+    const gMeta = g.metadata?.relations ?? {};
+    for (const name of [...new Set([...Object.keys(sMeta), ...Object.keys(gMeta)])].sort()) {
+        if (reported.has(name))
+            continue;
+        if (!sameCanon(sMeta[name], gMeta[name]))
+            out.push({ type, path: `${type}#${name} (restricciones de tipo)` });
+    }
+    const rest = (definition) => {
+        const { type: _t, relations: _r, metadata, ...others } = definition;
+        const { relations: _mr, ...metaOthers } = (metadata ?? {});
+        return { others, metaOthers };
+    };
+    const sr = rest(s);
+    const gr = rest(g);
+    for (const key of [...new Set([...Object.keys(sr.others), ...Object.keys(gr.others)])].sort()) {
+        if (!sameCanon(sr.others[key], gr.others[key]))
+            out.push({ type, path: `${type}.${key}` });
+    }
+    for (const key of [...new Set([...Object.keys(sr.metaOthers), ...Object.keys(gr.metaOthers)])].sort()) {
+        if (!sameCanon(sr.metaOthers[key], gr.metaOthers[key]))
+            out.push({ type, path: `${type}.metadata.${key}` });
+    }
+}
+/** Cuántas rutas nombra como mucho la letra del 500 de L11 (el resto se cuenta). */
+export const FACTS_MODEL_DRIFT_LISTED = 20;
+/**
+ * **La LETRA del 500 de la puerta L11**, la MISMA en los dos drivers `openfga`: qué driver, qué operación, qué
+ * `modelId`, las diferencias por ruta y la receta. Cero llamadas que evalúen o escriban.
+ */
+export function factsModelDriftError(driver, operation, modelId, differences) {
+    const paths = differences.map((d) => d.path);
+    const listed = paths.slice(0, FACTS_MODEL_DRIFT_LISTED).join('; ');
+    const more = paths.length > FACTS_MODEL_DRIFT_LISTED ? ` … y ${paths.length - FACTS_MODEL_DRIFT_LISTED} más` : '';
+    const error = new AuthorizationConfigError(`${driver}.${operation}: el modelo que sirve este driver (modelId ${modelId ?? '(ninguno)'}) NO es el que genera la ` +
+        `config de este proceso (L11: reglas, restricciones de tipo y condiciones, por tipo) — ${listed}${more}. Con ese ` +
+        'modelo el servidor decide con reglas o condiciones que la config no declara: puede conceder lo que la config —y ' +
+        'database con la misma config— niega, o leer caducidades con otra condición. Republica el modelo desde la config ' +
+        'actual (node ace openfga:provision --store-id=…) y fija el modelId nuevo (OPENFGA_MODEL_ID) en TODA la flota antes ' +
+        'de desplegar. No se ha llamado al servidor para evaluar ni escribir nada.');
+    error.modelDifferences = paths;
+    // Cierre de L11 (🟠 A1): fallo del DESPLIEGUE ⇒ transitorio para el relay (no consume intento ni aparca).
+    return markDeploymentFailure(error);
+}
+/**
+ * **El token del opt-in de `openfga` EXPERIMENTAL en 2.5.x** (estrategia 2.5.0, firma 4 del dueño 2026-10-21, «(b) con
+ * candado»). Lleva la VERSIÓN a propósito (auditor B1/B7, tester E1): con `true` nada obligaría a releer los límites NUEVOS
+ * cuando cambien; con `'openfga@2.5'` la 2.6 cambiará el token y un `^2.5.0` que se actualice hace ruido (500) en vez de
+ * colarse. NO se exporta por `/openfga`: el consumidor escribe el LITERAL, que es lo que demuestra que leyó «Limits».
+ */
+export const OPENFGA_EXPERIMENTAL_TOKEN = 'openfga@2.5';
+/**
+ * **La puerta del opt-in experimental, en los DOS constructores `openfga`** (firma 4; mismo patrón que
+ * `E_AUTHZ_SCOPE_DRIFT_UNGUARDED`: «una recomendación no es un mecanismo»). En 2.5.x `openfga` tiene límites declarados
+ * en README «Limits» (carreras entre escritores, árbol con outbox sin medir, el gemelo `permits_*`…) que se cierran en
+ * 2.6, así que construirlo exige escribir `experimental: 'openfga@2.5'`. Cualquier otra cosa —ausente, `true`,
+ * `'acknowledged'`, otra versión, el token con espacios— es 500 `E_AUTHZ_CONFIG` al CONSTRUIR, como PRIMERA línea del
+ * constructor: ni se valida lo demás ni se crea el cliente, así que hay CERO llamadas al servidor. Va en el constructor
+ * y no en el stub ni en el registro de la factory: `manager.driver()` (y con él `authz:catalog:sync`),
+ * `authz:reconcile --to=openfga`, `authz:relations:reconcile`, el provider y la construcción directa pasan todos por
+ * aquí, y un config solo-`database` que REGISTRA la factory `openfga` sin usarla arranca (las factories son perezosas).
+ * `openfga:provision` NO construye un driver (crea el store y publica el modelo con el SDK): corre sin la marca, y el
+ * primer driver que sirva con ese store, no.
+ */
+export function assertExperimentalOptIn(driver, value) {
+    if (typeof value === 'string' && value === OPENFGA_EXPERIMENTAL_TOKEN)
+        return;
+    throw new AuthorizationConfigError(experimentalOptInMessage(driver, describeOptInValue(value)));
+}
+/**
+ * Qué llegó, SIN tocar el valor (cierre 1 del candado, ⚪ 5 del auditor): `String(value)` de un `Object.create(null)` o de
+ * un objeto cuyo `toString` lanza sustituía el 500 por un `TypeError` o por el error del consumidor. Solo `typeof` y, para
+ * un string, `JSON.stringify` (que no invoca nada del valor).
+ */
+function describeOptInValue(value) {
+    if (value === undefined)
+        return 'nada';
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (typeof value === 'boolean' || typeof value === 'number' || typeof value === 'bigint')
+        return `${typeof value} ${value}`;
+    return `un ${Array.isArray(value) ? 'array' : typeof value}`;
+}
+function experimentalOptInMessage(driver, got) {
+    return (`${driver}: el driver openfga es EXPERIMENTAL en 2.5.x y NO es apto para producción: tiene límites declarados ` +
+        '(README «Limits»: carreras entre escritores del driver de roles, el árbol con outbox sin medir, el gemelo ' +
+        'permits_*…) que se cierran en 2.6. Para usarlo igualmente (CI, ensayo, desarrollo) opta de forma EXPLÍCITA con ' +
+        `experimental: '${OPENFGA_EXPERIMENTAL_TOKEN}' en las opciones del driver (llegó ${got}). El token lleva la versión ` +
+        'a propósito: true u otra versión no valen; el token y el comportamiento experimental de openfga pueden cambiar en ' +
+        '2.6 (una minor) sin major. ' +
+        'En producción usa database; para MIGRAR a database desde openfga (authz:reconcile --to=database, con openfga como ' +
+        'ORIGEN) la factory openfga también necesita la marca: leer el store para salir de él es construir este driver. ' +
+        'No se ha creado el cliente ni se ha llamado al servidor.');
+}
+/**
+ * **`modelId` OBLIGATORIO en los dos drivers `openfga`** (lote «antes de RC» · L11, decisión del dueño 2026-10-17 (2);
+ * D14 ampliado: siempre, con o sin deny). Sin el pin la puerta L11 compara el modelo que el driver lee al arrancar y el
+ * servidor evalúa cada petición con el ÚLTIMO del store: un `openfga:provision` desde otro proceso cambiaría lo que se
+ * concede sin que ninguna comparación lo vea. 500 al CONSTRUIR, con la receta.
+ */
+export function assertPinnedModel(driver, modelId) {
+    if (typeof modelId === 'string' && modelId.trim() !== '')
+        return;
+    throw new AuthorizationConfigError(`${driver}: falta modelId (llegó ${JSON.stringify(modelId ?? null)}). Desde 2.5.0-alpha.4 el modelo FIJADO es ` +
+        'obligatorio en los dos drivers openfga, con o sin deny (L11): el driver comprueba UNA vez que ese modelo es el que ' +
+        'genera tu config y el servidor evalúa con ESE modelo; sin el pin evaluaría con el último del store. Receta: ' +
+        '`node ace openfga:provision` (o `--store-id=$OPENFGA_STORE_ID` sobre un store existente) imprime OPENFGA_MODEL_ID; ' +
+        'ponlo en el .env de TODA la flota y pásalo como modelId (el stub de config/authorization.ts lo hace con ' +
+        "env.get('OPENFGA_MODEL_ID')).");
+}