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

package/build/src/relations_config_store.js

@@ -22,14 +22,45 @@
  * sin uso (cleanup futuro).
  */
 import { systemClock } from './clock.js';
-import { RelationConfigError } from './errors.js';
+import { AuthorizationConfigError, DenyReachRefusedError, RelationConfigError } from './errors.js';
 import { guardSql } from './shared/backend_guard.js';
 import db from '@adonisjs/lucid/services/db';
 import { invalidateAuthzCatalog, withAuthzCatalogWrite } from './catalog/catalog_cache.js';
 import { defineRelationsConfig } from './relations/define_relations_config.js';
+import { DENY_REACH_KEY_PATTERN, deniedPublicRelation, denyReachBaselineOf, denyReachCheck, denyReachKey, denyReachLine, judgeDenyReach } from './relations/deny_reach.js';
 const TABLE = 'authz_relations_config';
 const ROW_ID = 1;
 const DEFAULT_TIMEOUT_MS = 5_000;
+/** La lista de la salida forzada acotada, validada (L5): `undefined` ⇒ ninguna; array de `tipo#relación` ⇒ esa; otra cosa ⇒ 500. */
+function namedShrinkExemptions(value) {
+    if (value === undefined)
+        return new Set();
+    const ok = Array.isArray(value) && value.every((key) => typeof key === 'string' && DENY_REACH_KEY_PATTERN.test(key));
+    if (!ok) {
+        throw new AuthorizationConfigError(`saveRelationsConfig: allowDenyReachShrink tiene que ser una lista de 'tipo#relación' (llegó ${JSON.stringify(value) ?? String(value)}). ` +
+            `Desde el sublote (8) la salida forzada exime SOLO los hallazgos que nombras —p. ej. { allowDenyReachShrink: ['note#editor'] }—; ` +
+            `no hay un true global.`);
+    }
+    return new Set(value);
+}
+/** Los nombres de la lista que no eximen ningún hallazgo `shrunk`/`orphan` de este guardado (orden de la lista). */
+function unusedShrinkExemptions(exempt, judged) {
+    const used = new Set(judged.filter((finding) => finding.reason !== 'no-baseline').map(denyReachKey));
+    return [...exempt].filter((key) => !used.has(key));
+}
+function unusedShrinkExemptionsError(unused) {
+    return new AuthorizationConfigError(`saveRelationsConfig: allowDenyReachShrink nombra ${JSON.stringify(unused)}, y en este guardado ningún deny vivo de ` +
+        `esa(s) relación(es) encoge ni queda huérfano: no exime nada. Quita ese nombre de la lista (la salida forzada acotada ` +
+        `se usa en el guardado que la necesita y se retira después; pegada, eximiría en silencio un encogimiento futuro). ` +
+        `No se ha escrito nada (ni la fila ni la versión del catálogo).`);
+}
+/** `establishBaseline` validado (L5): solo `undefined`, `false` o `true`. */
+function establishBaselineOf(value) {
+    if (value === undefined || value === false || value === true)
+        return value === true;
+    throw new AuthorizationConfigError(`saveRelationsConfig: establishBaseline tiene que ser true o false (llegó ${JSON.stringify(value) ?? String(value)}): ` +
+        `solo true adopta la línea base, y una opción mal escrita no puede levantar la guarda.`);
+}
 function connectionOf(options) {
     return options?.connection ? db.connection(options.connection) : db;
 }
@@ -41,21 +72,141 @@ function connectionOf(options) {
  * siguiente pregunta—. Devuelve la config congelada.
  */
 export async function saveRelationsConfig(spec, options = {}) {
-    // Valida ANTES de escribir: una config inválida no ensucia la tabla.
+    // Valida ANTES de escribir: una config inválida no ensucia la tabla. Las dos salidas de la guarda (8), también antes
+    // (L5: una forma rota es 500 sin tomar el cerrojo).
     const config = defineRelationsConfig(spec);
-    const json = JSON.stringify(spec);
+    const json = JSON.stringify(persistableRelationsSpec(spec));
+    const { allowDenyReachShrink, establishBaseline, ...storeOptions } = options;
+    const exempt = namedShrinkExemptions(allowDenyReachShrink);
+    const adopt = establishBaselineOf(establishBaseline);
     await withAuthzCatalogWrite(async (trx) => {
         const existing = await trx.from(TABLE).where('id', ROW_ID).first();
+        // **La guarda (8) de `database`**, DENTRO de la transacción del catálogo (cerrojo de la fila de versión) y ANTES de la
+        // primera escritura: la línea base es la fila que acabamos de leer (TODO O NADA) y los denies vivos se leen por la
+        // MISMA trx. Cada hallazgo se niega salvo su salida con nombre: `no-baseline` ⇐ `establishBaseline: true` (solo existe
+        // sin línea base utilizable: con ella es inerte); `shrunk`/`orphan` ⇐ su `tipo#relación` en `allowDenyReachShrink`.
+        const judged = judgeDenyReach(baselineOf(existing), config, await liveDenyGroups(trx));
+        const refused = judged.filter((finding) => (finding.reason === 'no-baseline' ? !adopt : !exempt.has(denyReachKey(finding))));
+        if (refused.length > 0)
+            throw denyReachRefused(refused);
+        // **Un nombre de la salida acotada que no exime NADA en ESTE guardado ⇒ 500** (firma «(8 · cierre 1 · ronda)», 🟡 1 del
+        // auditor del cierre 1): «casa» = exime un `shrunk`/`orphan` de este guardado (un `no-baseline` no cuenta), calculado
+        // aquí, dentro de la trx. Así la salida se APAGA SOLA: una lista que se queda pegada en el pipeline no exime en silencio
+        // el encogimiento FUTURO de esa relación. Un huérfano heredado sigue siendo hallazgo en cada guardado: su nombre casa.
+        const unused = unusedShrinkExemptions(exempt, judged);
+        if (unused.length > 0)
+            throw unusedShrinkExemptionsError(unused);
         if (existing) {
             await trx.from(TABLE).where('id', ROW_ID).update({ spec: json, updated_at: systemClock() });
         }
         else {
             await trx.table(TABLE).insert({ id: ROW_ID, spec: json, model_id: null, updated_at: systemClock() });
         }
-    }, options);
+    }, storeOptions);
     invalidateAuthzCatalog();
     return config;
 }
+/**
+ * La LÍNEA BASE de la guarda (8) y del detector de un driver: la config persistida, leída TODO O NADA
+ * (`denyReachBaselineOf`), o `null` = NO UTILIZABLE (sin fila, JSON roto, o una forma que la lectura no puede tipar). Una
+ * fila que no valida en 2.5 pero cuyos campos de alcance se tipan (p. ej. una clave que 2.5 no conoce) SÍ es línea base:
+ * re-guardarla con la spec corregida (la receta de B5) entra sin forzar.
+ */
+function baselineOf(row) {
+    if (!row)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(String(row.spec));
+    }
+    catch {
+        return null;
+    }
+    return denyReachBaselineOf(parsed);
+}
+/**
+ * Los denies VIVOS de `authz_relations` agrupados por tipo y relación (las filas del driver `database`), por la conexión o
+ * la trx que se le pase. Todas las filas `denied_*`: el deny no caduca (D3) y una fila con `expires_at` escrita a mano cuenta
+ * igual (contar de más rechaza de más: lo conservador). El filtro del deny es UNO, aquí (`deniedPublicRelation`): una fila
+ * que no es un deny no pide línea base (S-A0).
+ */
+async function liveDenyGroups(connection) {
+    return denyGroupsOf(await liveDenyQuery(connection));
+}
+/** La consulta (un `GROUP BY` de `authz_relations`): aparte para que el detector de un driver le ponga su deadline. */
+function liveDenyQuery(connection) {
+    return connection.from('authz_relations').select('object_type', 'relation').count('* as n').groupBy('object_type', 'relation');
+}
+function denyGroupsOf(rows) {
+    const groups = [];
+    for (const row of rows) {
+        const relation = deniedPublicRelation(String(row.relation));
+        if (relation !== null)
+            groups.push({ objectType: String(row.object_type), relation, count: Number(row.n) });
+    }
+    return groups;
+}
+function denyReachRefused(findings) {
+    const shrink = findings.filter((f) => f.reason !== 'no-baseline').map(denyReachKey);
+    const exits = [
+        ...(findings.some((f) => f.reason === 'no-baseline')
+            ? ['sin línea base utilizable, la adopción es saveRelationsConfig(spec, { establishBaseline: true }) con la spec que la flota sirve HOY, sin cambios']
+            : []),
+        ...(shrink.length > 0
+            ? [`si de verdad quieres que esos denies dejen de cortar, la salida forzada ACOTADA es saveRelationsConfig(spec, { allowDenyReachShrink: ${JSON.stringify(shrink)} })`]
+            : []),
+    ];
+    const error = new DenyReachRefusedError(`saveRelationsConfig NEGADO (E_AUTHZ_DENY_REACH_REFUSED): ${findings.length} hallazgo(s) sobre denies vivos de authz_relations — ` +
+        `una config que encoge su alcance haría conceder, de forma persistente, lo que negaban (decisión (8): para todo deny ` +
+        `vivo, alcance nuevo ⊇ alcance viejo). ${findings.map(denyReachLine).join(' ')} No se ha escrito nada (ni la fila ni la ` +
+        `versión del catálogo). ${exits.join('; ')}.`);
+    error.findings = findings.map(({ objectType, relation, reason, count, lost, recipe }) => ({ objectType, relation, reason, count, lost, recipe }));
+    return error;
+}
+/**
+ * **El detector de UN solo driver** (firma (8 · detector de un driver), R4 del analista del panel): en un despliegue
+ * solo-`database` el detector de `authz:relations:reconcile --dry-run` no corre (necesita DOS drivers de relaciones:
+ * origen = destino es 500). Esta función compara la config que SIRVE el proceso (`served`) con la línea base persistida
+ * sobre los denies vivos de `authz_relations`, en las DOS direcciones:
+ *  - persistida → servida: lo que la guarda negaría (`shrunk`, `orphan`, `no-baseline`);
+ *  - servida → persistida: la línea base RANCIA (`stale`), que la guarda no puede ver.
+ *
+ * Solo LEE (la fila y un `GROUP BY` de `authz_relations`, por `options.connection` o la primaria), sin transacción y sin el
+ * cerrojo del catálogo, con el MISMO punto de paso que la guarda (`baselineOf` + `liveDenyGroups` + `denyReachCheck`).
+ * **Receta**: en CI, DESPUÉS del paso que guarda la config y ANTES de servir, y en un cron; falla el job si `ok` es `false`.
+ * **Nunca** como fallo duro en `ready`: durante un despliegue un pod viejo que se reinicia sirve la config estrecha contra la
+ * fila nueva y entraría en un bucle de reinicios.
+ */
+export async function checkRelationsConfigDenyReach(served, options = {}) {
+    if (!served || !Array.isArray(served.objectTypes)) {
+        throw new AuthorizationConfigError('checkRelationsConfigDenyReach: pasa la config de relaciones que SIRVE este proceso (relations.config de config/authorization.ts, la de defineRelationsConfig).');
+    }
+    const connection = connectionOf(options);
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const row = await guardSql('relations-config', 'read', timeoutMs, () => connection.from(TABLE).where('id', ROW_ID).first());
+    const groups = denyGroupsOf(await guardSql('relations-config', 'read', timeoutMs, () => liveDenyQuery(connection)));
+    const check = denyReachCheck(baselineOf(row), served, groups);
+    return {
+        ...check,
+        ok: check.findings.length === 0 && check.staleBaseline.length === 0,
+        lines: [...check.findings, ...check.staleBaseline].map(denyReachLine),
+    };
+}
+/**
+ * **Lo que se persiste de la spec** (cierre-2 de R1 · P1, decisión del dueño 2026-10-20): `maxGroupDepth` y
+ * `database.enforceGroupDepth` son claves de DESPLIEGUE, no de modelo. Se VALIDAN (`defineRelationsConfig`, arriba: un
+ * valor malo es el mismo 500) pero NO se guardan. Nadie las lee de la base (el plan del reconcile toma el techo de
+ * `to.groupDepthLimit()`, no de la config persistida), y guardarlas rompía un despliegue mezclado: un proceso alpha.2/
+ * alpha.3 relee la fila con su lista blanca (B2, sin esas claves) y su `authz:relations:reconcile` sale con 1. No es el
+ * «descartar en silencio» de B2: se conocen y se validan; solo no se escriben. El resto de la spec va TAL CUAL.
+ */
+function persistableRelationsSpec(spec) {
+    const { maxGroupDepth: _deployment, ...rest } = spec;
+    if (rest.database === undefined || rest.database === null || typeof rest.database !== 'object')
+        return rest;
+    const { enforceGroupDepth: _enforce, ...database } = rest.database;
+    return { ...rest, database };
+}
 /** Lee el spec persistido (o `null` si no hay relaciones declaradas — opt-in). */
 export async function readRelationsConfigSpec(options = {}) {
     const row = await guardSql('relations-config', 'read', options.timeoutMs ?? DEFAULT_TIMEOUT_MS, () => connectionOf(options).from(TABLE).where('id', ROW_ID).first());
@@ -93,4 +244,3 @@ export async function readRelationsConfig(options = {}) {
     const spec = await readRelationsConfigSpec(options);
     return spec ? defineRelationsConfig(spec) : null;
 }
-//# sourceMappingURL=relations_config_store.js.map

package/build/src/relations_reconcile.d.ts

@@ -76,4 +76,3 @@ export type RunRelationsReconcileOptions = Omit<RelationsReconcileOptions, 'from
  *    Pásale el manager del servicio, nunca uno construido o envuelto a mano.
  */
 export declare function runRelationsReconcile(authorization: Pick<AuthorizationManager, 'withFrozenWrites' | 'relationsDriverKey' | 'relationsDriverFactory'>, options: RunRelationsReconcileOptions): Promise<RelationsReconcileReport>;
-//# sourceMappingURL=relations_reconcile.d.ts.map

package/build/src/relations_reconcile.js

@@ -82,4 +82,3 @@ export async function runRelationsReconcile(authorization, options) {
         return report;
     }, { kind: 'reconcile', operatorAsContext: true });
 }
-//# sourceMappingURL=relations_reconcile.js.map

package/build/src/scope_outbox.d.ts

@@ -124,4 +124,3 @@ export declare function scopeOutboxLockNames(connection: string | undefined, tab
 };
 export declare function sqlScopeOutbox(options?: SqlScopeOutboxOptions, database?: DatabaseLike): ScopeOutbox;
 export {};
-//# sourceMappingURL=scope_outbox.d.ts.map

package/build/src/scope_outbox.js

@@ -532,4 +532,3 @@ export function sqlScopeOutbox(options = {}, database = db) {
         },
     };
 }
-//# sourceMappingURL=scope_outbox.js.map

package/build/src/shared/backend_guard.d.ts

@@ -66,6 +66,58 @@ export declare function isServerWriteLimit(error: unknown): boolean;
  * `cause`. Se mira la cadena entera de causas.
  */
 export declare function isTimeoutLike(error: unknown): boolean;
+/**
+ * Las clases de la decisión del dueño 2026-10-17 (3) y (4) (lote «antes de RC» · R3), separadas SIN leer el mensaje
+ * (F0 · M-d: 41 formas literales del SDK 0.9.6 contra OpenFGA v1.19, en `tests/fixtures/fga_errors/`):
+ *
+ * | clase | al llamante | en el relay |
+ * |---|---|---|
+ * | `timeout` (deadline propio, `ECONNABORTED`/`ETIMEDOUT`, el `FgaError` sin respuesta) | 503 `E_AUTHZ_BACKEND_TIMEOUT` | transitorio |
+ * | `transient` (5xx —501 incluido—, 408, 429, `deadline_exceeded`, sin respuesta, ítem `internal_error`; en una ESCRITURA el 504 y `deadline_exceeded` son `timeout`) | 503 `E_AUTHZ_BACKEND_UNAVAILABLE` | transitorio |
+ * | `resolution-limit` (`authorization_model_resolution_too_complex`, excepción o ítem) | 503 `E_AUTHZ_RESOLUTION_LIMIT` | transitorio |
+ * | `deployment` (401/403/404, 400 con código de la LISTA BLANCA, validación del cliente) | 500 `E_AUTHZ_CONFIG` «no es transitorio» | transitorio (marca) |
+ * | `race` (409, 400 `write_failed_due_to_invalid_input`) | 409 `E_AUTHZ_WRITE_CONFLICT` si escapa | transitorio (`isTransientRelayFailure`, cierre de R3) |
+ * | `unknown-4xx` (cualquier otro 4xx) | 500 `E_AUTHZ_CONFIG` con `cause` | transitorio (marca) |
+ */
+export type FgaFailureKind = 'timeout' | 'transient' | 'resolution-limit' | 'deployment' | 'race' | 'unknown-4xx';
+export interface FgaFailure {
+    kind: FgaFailureKind;
+    /** El `statusCode` HTTP de la respuesta (ausente sin respuesta y en el error por ítem de `batchCheck`). */
+    status?: number;
+    /** `apiErrorCode` del SDK, o el valor de la clave del error por ítem (`input_error`/`internal_error`). */
+    apiErrorCode?: string;
+}
+/** El código de OpenFGA que dice «el grafo excede lo que resuelvo» (decisión 4: 503 con código propio). */
+export declare const FGA_RESOLUTION_TOO_COMPLEX = "authorization_model_resolution_too_complex";
+/**
+ * **La LISTA BLANCA de códigos de despliegue** (F0 · M-d): solo códigos MEDIDOS. Un 400 con un código fuera de ella (y todo 422)
+ * es `unknown-4xx` (la clase `FgaApiValidationError` no basta: el 400 de código desconocido es la misma clase). Dentro de
+ * la clase no se separan sin el mensaje —y no hace falta, la decisión 3 los junta—: relación/tipo ausente del modelo
+ * fijado ↔ contexto ausente en la tupla ↔ `current_time` ausente (los tres `validation_error`), y store ↔ modelo ausente
+ * con pin (los dos `authorization_model_not_found`).
+ */
+export declare const FGA_DEPLOYMENT_CODES: ReadonlySet<string>;
+/**
+ * **`classifyFgaFailure(error)`**: la clase de un fallo de OpenFGA, por `statusCode` + `apiErrorCode` (lista blanca) o,
+ * en el error POR ÍTEM de un `batchCheck` 200, por la CLAVE del objeto `error` (`input_error`/`internal_error`). **Jamás
+ * lee `message` ni `apiErrorMessage`** (lo vigila la propiedad `fga.errors.classify` de la guardia; las ÚNICAS exenciones,
+ * por nombre y firmadas —decisión del dueño 2026-10-18 (5-bis)—, son `isDuplicateWrite`/`isTreeWriteRace`, que leen el
+ * SUB-tipo de la carrera «already exists» / «does not exist» y viven ENCIMA de esta clase). PUNTO DE PASO ÚNICO de los
+ * TRES sitios: `#guard` del driver de relaciones, `guardBackendErrors` y `alignBatchResults` (los dos drivers).
+ */
+export declare function classifyFgaFailure(error: unknown, context?: {
+    write?: boolean;
+}): FgaFailure;
+/**
+ * **El error PÚBLICO de un fallo de OpenFGA** (R3): `classifyFgaFailure` ⇒ la clase de la tabla de arriba. La causa
+ * original viaja SIEMPRE en `cause` (la carrera la leen `isDuplicateWrite`/`isTreeWriteRace` por la cadena). `timeoutMs`
+ * solo da la letra del timeout. `failure` deja pasar una clasificación ya hecha (el llamante que necesita mirarla antes).
+ */
+export declare function fgaFailureError(driver: string, operation: string, error: unknown, options?: {
+    timeoutMs?: number;
+    failure?: FgaFailure;
+    write?: boolean;
+}): Error;
 /**
  * Ejecuta una consulta SQL con deadline y traduce su fallo. El builder de
  * Lucid es perezoso (se ejecuta al hacer `await`), así que el `timeout` se
@@ -158,4 +210,3 @@ export declare function canonicalScope(resolver: ScopeChainResolver, scope: Scop
 export declare function canonicalScopeTargets(resolver: ScopeChainResolver, scope: ScopeRef, operation: string): Promise<ScopeRef[]>;
 /** La cadena canónica, o 422 `E_AUTHZ_UNKNOWN_SCOPE` si el scope no existe (para escrituras). */
 export declare function assertKnownScope(resolver: ScopeChainResolver, scope: ScopeRef, operation: string): Promise<ScopeRef[]>;
-//# sourceMappingURL=backend_guard.d.ts.map

package/build/src/shared/backend_guard.js

@@ -1,4 +1,4 @@
-import { AuthorizationBackendError, AuthorizationBackendTimeoutError, NoScopeResolverError, ScopeResolverError, UnknownScopeError, } from '../errors.js';
+import { AuthorizationBackendError, AuthorizationBackendTimeoutError, AuthorizationConfigError, markDeploymentFailure, NoScopeResolverError, ResolutionLimitError, ScopeResolverError, UnknownScopeError, WriteConflictError, } from '../errors.js';
 import { APP_SCOPE, APP_SCOPE_TYPE } from '../types.js';
 import { assertScope, scopeSpellings } from '../identity.js';
 /**
@@ -120,10 +120,173 @@ export function isTimeoutLike(error) {
             return true;
         if (current.code === 'ECONNABORTED' || current.code === 'ETIMEDOUT')
             return true;
+        if (isBareFgaError(current))
+            return true;
         current = current.cause;
     }
     return false;
 }
+/**
+ * **El `FgaError` SIN respuesta** (lote «antes de RC» · R3; F0 · M-d, nota 1 al auditor): el SDK 0.9.6 envuelve el
+ * timeout de axios —y también la conexión rechazada— en un `FgaError` genérico que NO conserva `code`, `cause` ni
+ * `statusCode` (fixtures `real-client-timeout`, `fake-client-timeout-slow-server`, `net-connection-refused`): solo
+ * `name` y `message`. Sin leer el mensaje (prohibido, decisión 2026-10-17 (3)) los dos NO se separan, así que se toma la
+ * clase CONSERVADORA: timeout —indeterminado—. Para el relay los dos son transitorios; para la auditoría
+ * (invariante 13) decir «quizá se escribió» de una conexión rechazada sobra, y callarlo de un timeout faltaría. Hasta R3
+ * solo lo salvaba que `withDeadline` arranca antes que el reloj del SDK. El nombre EXACTO `FgaError` (las subclases del
+ * SDK tienen el suyo) y SIN `statusCode`: con respuesta, lo decide `classifyFgaFailure`.
+ */
+function isBareFgaError(candidate) {
+    return candidate?.name === 'FgaError' && (candidate.statusCode === undefined || candidate.statusCode === null);
+}
+/** El código de OpenFGA que dice «el grafo excede lo que resuelvo» (decisión 4: 503 con código propio). */
+export const FGA_RESOLUTION_TOO_COMPLEX = 'authorization_model_resolution_too_complex';
+/**
+ * **La LISTA BLANCA de códigos de despliegue** (F0 · M-d): solo códigos MEDIDOS. Un 400 con un código fuera de ella (y todo 422)
+ * es `unknown-4xx` (la clase `FgaApiValidationError` no basta: el 400 de código desconocido es la misma clase). Dentro de
+ * la clase no se separan sin el mensaje —y no hace falta, la decisión 3 los junta—: relación/tipo ausente del modelo
+ * fijado ↔ contexto ausente en la tupla ↔ `current_time` ausente (los tres `validation_error`), y store ↔ modelo ausente
+ * con pin (los dos `authorization_model_not_found`).
+ */
+export const FGA_DEPLOYMENT_CODES = new Set([
+    'validation_error',
+    'authorization_model_not_found',
+    'latest_authorization_model_not_found',
+    'exceeded_entity_limit',
+    // `store_id_not_found` NO está (cierre de R3, ⚪-6 del tester): se midió solo como 404, que ya decide el status.
+]);
+/** El código con el que OpenFGA dice que venció SU deadline (504 por el grpc-gateway; F0 · M-d `fake-504-deadline-exceeded`). */
+const FGA_DEADLINE_EXCEEDED = 'deadline_exceeded';
+/** El 400 de la carrera (`isDuplicateWrite`/`isTreeWriteRace` leen su sub-tipo; aquí basta el código). */
+const FGA_RACE_CODE = 'write_failed_due_to_invalid_input';
+/**
+ * Los errores del SDK que se lanzan SIN red (el cliente valida antes de llamar: un `authorizationModelId` que no es un
+ * ULID, un parámetro obligatorio ausente). Deterministas: despliegue. Es lo ÚNICO que se decide por `name`, porque sin
+ * respuesta no hay `statusCode` que mirar (la regla general es «por `statusCode` + `apiErrorCode`, nunca por la clase JS»:
+ * 408/409/418/501 son los cuatro `FgaApiError`).
+ */
+const FGA_CLIENT_VALIDATION_NAMES = new Set(['FgaValidationError', 'FgaRequiredParamError']);
+/**
+ * **`classifyFgaFailure(error)`**: la clase de un fallo de OpenFGA, por `statusCode` + `apiErrorCode` (lista blanca) o,
+ * en el error POR ÍTEM de un `batchCheck` 200, por la CLAVE del objeto `error` (`input_error`/`internal_error`). **Jamás
+ * lee `message` ni `apiErrorMessage`** (lo vigila la propiedad `fga.errors.classify` de la guardia; las ÚNICAS exenciones,
+ * por nombre y firmadas —decisión del dueño 2026-10-18 (5-bis)—, son `isDuplicateWrite`/`isTreeWriteRace`, que leen el
+ * SUB-tipo de la carrera «already exists» / «does not exist» y viven ENCIMA de esta clase). PUNTO DE PASO ÚNICO de los
+ * TRES sitios: `#guard` del driver de relaciones, `guardBackendErrors` y `alignBatchResults` (los dos drivers).
+ */
+export function classifyFgaFailure(error, context = {}) {
+    const item = error;
+    if (item && typeof item === 'object' && item.statusCode === undefined && ('input_error' in item || 'internal_error' in item)) {
+        // El error POR ÍTEM de `batchCheck` (respuesta 200): no es una excepción del SDK, es un objeto de la respuesta.
+        if (typeof item.internal_error === 'string')
+            return { kind: 'transient', apiErrorCode: item.internal_error };
+        if (typeof item.input_error === 'string') {
+            const code = item.input_error;
+            if (code === FGA_RESOLUTION_TOO_COMPLEX)
+                return { kind: 'resolution-limit', apiErrorCode: code };
+            if (FGA_DEPLOYMENT_CODES.has(code))
+                return { kind: 'deployment', apiErrorCode: code };
+            return { kind: 'unknown-4xx', apiErrorCode: code };
+        }
+        return { kind: 'transient' };
+    }
+    if (isTimeoutLike(error))
+        return { kind: 'timeout' };
+    const responded = respondedFgaError(error);
+    if (responded === null) {
+        let current = error;
+        for (let depth = 0; current && depth < 6; depth++) {
+            if (typeof current.name === 'string' && FGA_CLIENT_VALIDATION_NAMES.has(current.name))
+                return { kind: 'deployment' };
+            current = current.cause;
+        }
+        return { kind: 'transient' };
+    }
+    const { status, apiErrorCode } = responded;
+    const failure = (kind) => ({ kind, status, ...(apiErrorCode !== undefined ? { apiErrorCode } : {}) });
+    // Cierre de R3 (🟡 R3-A2 del auditor; invariante 13: «una escritura que vence el deadline es indeterminada»): en una
+    // ESCRITURA, el deadline del SERVIDOR (`deadline_exceeded`) y el 504 de un proxy/gateway son de la familia TIMEOUT —el
+    // `Write` puede haberse confirmado aguas arriba después de que se cortara la respuesta—, así que salen 503
+    // `E_AUTHZ_BACKEND_TIMEOUT` y el manager notifica `indeterminate: true`. El resto de 5xx en una escritura conserva
+    // «no ocurrió» (el servidor contestó que falló); en una LECTURA el 504 sigue siendo transitorio (no hay nada que auditar).
+    if (context.write === true && (status === 504 || apiErrorCode === FGA_DEADLINE_EXCEEDED))
+        return failure('timeout');
+    if (status >= 500 || status === 408 || status === 429)
+        return failure('transient');
+    if (status === 409)
+        return failure('race');
+    if (status === 401 || status === 403 || status === 404)
+        return failure('deployment');
+    // Solo el 400 lleva códigos medidos (cierre de R3, ⚪-6 del tester: un 422 se midió solo con código desconocido, así
+    // que cualquier 422 es `unknown-4xx` —mismo error público que el despliegue: 500 marcado—).
+    if (status === 400) {
+        if (apiErrorCode === FGA_RACE_CODE)
+            return failure('race');
+        if (apiErrorCode === FGA_RESOLUTION_TOO_COMPLEX)
+            return failure('resolution-limit');
+        if (apiErrorCode !== undefined && FGA_DEPLOYMENT_CODES.has(apiErrorCode))
+            return failure('deployment');
+        return failure('unknown-4xx');
+    }
+    if (status >= 400)
+        return failure('unknown-4xx');
+    return failure('transient');
+}
+/** El primer error de la cadena de `cause` que trae una respuesta HTTP (`statusCode` numérico). */
+function respondedFgaError(error) {
+    let current = error;
+    for (let depth = 0; current && depth < 6; depth++) {
+        if (typeof current.statusCode === 'number') {
+            return {
+                status: current.statusCode,
+                ...(typeof current.apiErrorCode === 'string' ? { apiErrorCode: current.apiErrorCode } : {}),
+            };
+        }
+        current = current.cause;
+    }
+    return null;
+}
+/**
+ * **El error PÚBLICO de un fallo de OpenFGA** (R3): `classifyFgaFailure` ⇒ la clase de la tabla de arriba. La causa
+ * original viaja SIEMPRE en `cause` (la carrera la leen `isDuplicateWrite`/`isTreeWriteRace` por la cadena). `timeoutMs`
+ * solo da la letra del timeout. `failure` deja pasar una clasificación ya hecha (el llamante que necesita mirarla antes).
+ */
+export function fgaFailureError(driver, operation, error, options = {}) {
+    const failure = options.failure ?? classifyFgaFailure(error, { write: options.write });
+    const what = [failure.status !== undefined ? `HTTP ${failure.status}` : null, failure.apiErrorCode ?? null]
+        .filter((x) => x !== null)
+        .join(' ');
+    switch (failure.kind) {
+        case 'timeout': {
+            const timeout = new AuthorizationBackendTimeoutError(driver, operation, options.timeoutMs ?? 0, error);
+            if (failure.status !== undefined) {
+                // Con respuesta (504 / `deadline_exceeded` en una escritura): no es NUESTRO deadline, es el del servidor o el
+                // de un proxy intermedio. La escritura es INDETERMINADA (invariante 13), no «no ocurrió».
+                timeout.message =
+                    `El backend de autorización '${driver}' venció un deadline aguas arriba en ${operation} (${what}): la ` +
+                        'escritura es INDETERMINADA —el servidor puede haberla confirmado después de cortarse la respuesta—.';
+            }
+            return timeout;
+        }
+        case 'transient':
+            return new AuthorizationBackendError(driver, operation, error);
+        case 'resolution-limit':
+            return new ResolutionLimitError(driver, operation, error);
+        case 'race':
+            return new WriteConflictError(`El backend de autorización '${driver}' rechazó ${operation} por una CARRERA con otro escritor (${what}): el ` +
+                'estado del store no es el que esta escritura esperaba. Relee y reintenta la escritura.', { cause: error });
+        case 'deployment':
+            return markDeploymentFailure(new AuthorizationConfigError(`El backend de autorización '${driver}' rechazó ${operation} (${what || 'validación del cliente, sin red'}): el ` +
+                'DESPLIEGUE no es el que espera la config —store o modelo inexistente (OPENFGA_STORE_ID/OPENFGA_MODEL_ID), ' +
+                'credenciales, o un tipo, relación o contexto que el modelo fijado no admite—. No es transitorio: repetida, la ' +
+                'operación vuelve a fallar igual hasta que se corrija el despliegue (openfga:provision publica el modelo de la ' +
+                'config). Para el relay no consume intento.', { cause: error }));
+        case 'unknown-4xx':
+            return markDeploymentFailure(new AuthorizationConfigError(`El backend de autorización '${driver}' rechazó ${operation} con un 4xx que este paquete no conoce (${what}). ` +
+                'No es transitorio (un 4xx dice «no reintentes»): mira la causa (cause) y la versión del servidor OpenFGA. ' +
+                'Para el relay no consume intento.', { cause: error }));
+    }
+}
 /**
  * Ejecuta una consulta SQL con deadline y traduce su fallo. El builder de
  * Lucid es perezoso (se ejecuta al hacer `await`), así que el `timeout` se
@@ -340,4 +503,3 @@ export async function assertKnownScope(resolver, scope, operation) {
     }
     return chain;
 }
-//# sourceMappingURL=backend_guard.js.map

package/build/src/shared/sql_expiry.d.ts

@@ -52,4 +52,3 @@ export declare function parseUtcDatetime(value: string): Date | null;
  * de la identidad.
  */
 export declare function sqlExpiryCodec(connection?: any): ExpiryCodec;
-//# sourceMappingURL=sql_expiry.d.ts.map

package/build/src/shared/sql_expiry.js

@@ -67,4 +67,3 @@ function mysqlCodec(connection) {
 export function sqlExpiryCodec(connection = db.connection()) {
     return MYSQL_DIALECTS.has(dialectOf(connection)) ? mysqlCodec(connection) : identityCodec;
 }
-//# sourceMappingURL=sql_expiry.js.map

package/build/src/shared/transaction_guard.d.ts

@@ -50,4 +50,3 @@ export interface CallerTransactionOwner {
  * (no llegó ninguna; el llamante decide qué hacer).
  */
 export declare function assertCallerTransaction(operation: string, transaction: unknown, owner: CallerTransactionOwner): CallerTransaction | undefined;
-//# sourceMappingURL=transaction_guard.d.ts.map

package/build/src/shared/transaction_guard.js

@@ -71,4 +71,3 @@ export function assertCallerTransaction(operation, transaction, owner) {
     }
     return trx;
 }
-//# sourceMappingURL=transaction_guard.js.map

package/build/src/sql_descendants.d.ts

@@ -102,4 +102,3 @@ export interface SqlScopeEdgesOptions {
 }
 export declare function sqlScopeEdges(options: SqlScopeEdgesOptions, database?: DatabaseLike): ScopeEdgesEnumerator;
 export {};
-//# sourceMappingURL=sql_descendants.d.ts.map

package/build/src/sql_descendants.js

@@ -200,4 +200,3 @@ export function sqlScopeEdges(options, database = db) {
             : { edges, cursor: String(last.child_uuid) };
     };
 }
-//# sourceMappingURL=sql_descendants.js.map

package/build/src/testing/contract.d.ts

@@ -200,6 +200,13 @@ export interface DriverCapabilities {
      * el destino los lee de ahí. Solo tiene casos en `level: '2.2'`.
      */
     enumerateFacts: boolean;
+    /**
+     * **El driver es EXPERIMENTAL** (estrategia 2.5.0, firma 4; `AuthorizationDriverCapabilities.experimental`). Opcional
+     * (regla D15: un harness publicado de 2.4/2.5 sin la clave sigue valiendo y cuenta como `false`). Con `true` el juez fija
+     * que el driver lo declara y que `authorization.capabilities()` lo publica; con `false` (o ausente), que el driver NO lo
+     * declara y la copia normalizada dice `false`. No apaga ningún caso. `openfga` = `true` en 2.5.x; `database` = `false`.
+     */
+    experimental?: boolean;
 }
 export type ContractLevel = 'core' | '2.0' | '2.1' | '2.2';
 export interface DriverContractHarness {
@@ -280,4 +287,3 @@ export declare function registerAuthorizationDriverContract(harness: DriverContr
  * y una de `BOTH_FACES_REQUIRED` queda sin cubrir con CUALQUIER valor.
  */
 export declare function uncoveredCapabilities(capabilities: DriverCapabilities, covered: ReadonlySet<keyof DriverCapabilities>): (keyof DriverCapabilities)[];
-//# sourceMappingURL=contract.d.ts.map

package/build/src/testing/contract.js

@@ -1922,6 +1922,33 @@ export function registerAuthorizationDriverContract(harness, api) {
             await driver.revoke(alice, 'lead', unitA1);
             assert.isFalse(await driver.authorize(alice, 'docs:write', unitA1));
         });
+        since('2.2', 'un deny en el OWNER sigue ganando sobre su rol local mientras el scope sale del owner y vuelve: authorize false antes, fuera y de vuelta (invariantes 2 y 18; lote «antes de RC» · F4, F-1); sin el deny: true, false, true', async ({ assert, }) => {
+            // F-1 del tester (`loteRC-6b-estudio-tester.md` §6): PARIDAD entre drivers del `moved` con un rol LOCAL y un deny
+            // en su owner. En `database` no hay estado intermedio (la regla se evalúa en cada pregunta); en `openfga` el
+            // barrido F4 borra el binding ANTES de escribir la arista, así que tampoco lo hay (el prefijo lo juzga la
+            // propiedad `openfga.roles.moved.order` de la guardia). Aquí se observa el estado de reposo en los tres puntos.
+            const denied = subject();
+            const plain = subject();
+            const orgA = await orgUnder(tree, APP_SCOPE);
+            const orgB = await orgUnder(tree, APP_SCOPE);
+            const unit = await unitUnder(tree, orgA);
+            const leaf = await unitUnder(tree, unit);
+            await localRole(orgA, { slug: 'lead', scopeType: 'unit', permissions: ['docs:write'] });
+            await driver.grant(denied, 'lead', unit);
+            await driver.grant(plain, 'lead', unit);
+            await driver.deny(denied, 'docs:write', orgA);
+            const both = async () => [
+                await driver.authorize(denied, 'docs:write', unit),
+                await driver.authorize(denied, 'docs:write', leaf),
+                await driver.authorize(plain, 'docs:write', unit),
+                await driver.authorize(plain, 'docs:write', leaf),
+            ];
+            assert.deepEqual(await both(), [false, false, true, true], 'dentro del owner: el deny gana, sin él concede (también abajo)');
+            await tree.move(unit, orgB);
+            assert.deepEqual(await both(), [false, false, false, false], 'fuera del owner: el rol local no existe (y el deny ya no hace falta)');
+            await tree.move(unit, orgA);
+            assert.deepEqual(await both(), [false, false, true, true], 'de vuelta: restaura lo concedido y el deny sigue ganando');
+        });
         since('2.2', 'la visibilidad se decide POR NIVEL, no por el conjunto de la cadena: si el árbol se recuelga y el owner queda POR DEBAJO del scope de la asignación, esa asignación deja de contar aunque el owner siga en la cadena de la pregunta', async ({ assert, }) => {
             // 3B · B2 (desviación 2 del lote, sin caso hasta aquí). La regla es
             // «una asignación en el scope S cuenta si su rol EXISTE EN S»: el owner
@@ -2072,6 +2099,35 @@ export function registerAuthorizationDriverContract(harness, api) {
             assert.isFalse(await driver.authorize(victima, 'docs:write', unitU1), 'el rol de A ya no existe aquí');
             assert.isTrue(await driver.hasRole(victima, 'lead', unitU1));
         });
+        since('2.2', 'K4 · revoke por SLUG decide con el catálogo EN FRESCO aunque el memo sirva con ventana { everyMs }: un rol local recién definido en OTRO proceso con el slug de uno global también se revoca (nunca un «revocado» mudo)', async ({ assert, }) => {
+            // Asentar · cierre 2 (D-1 del re-ataque del cierre 1; gemelo del 🟡 5 de `openfga`). `{ everyMs }` es una ventana
+            // de DECISIÓN (invariante 14); una ESCRITURA decide con la versión en fresco (K4). Con el memo de la ventana,
+            // `revoke(alice, 'unit-editor', unit)` solo veía el global y el DELETE no tocaba la asignación del local homónimo:
+            // seguía concediendo, en silencio y para siempre (al caducar la ventana, también en este proceso). La ventana solo se
+            // construye si `driver.catalog` es un `CatalogCache` (los dos drivers del paquete): un driver con memo PROPIO corre
+            // el caso SIN ventana y el K4 de `revoke` NO queda juzgado para él (cierre 3 · 🟡 B del tester: es su deber escrito,
+            // no juzgado; un hook de harness para su memo sería contrato nuevo).
+            const alice = subject();
+            const orgA = await orgUnder(tree, APP_SCOPE);
+            const unit = await unitUnder(tree, orgA);
+            const memo = new CatalogCache({ revalidate: { everyMs: 3_600_000 } });
+            let windowed = driver;
+            if (driver.catalog instanceof CatalogCache) {
+                windowed = Object.create(driver);
+                Object.defineProperty(windowed, 'catalog', { value: memo, enumerable: true });
+                await memo.view();
+            }
+            // «Otro proceso» define el local con el slug del global `unit-editor` (fila + versión, sin señal en memoria).
+            const local = await localRole(orgA, { slug: 'unit-editor', scopeType: 'unit', permissions: ['docs:write'] });
+            await driver.grant(alice, { uuid: local }, unit);
+            assert.isTrue(await driver.authorize(alice, 'docs:write', unit));
+            if (windowed !== driver) {
+                assert.isNull((await memo.view()).roleByUuid(local), 'la ventana del memo sigue sirviendo la foto SIN el local (si no, el caso no juzga nada)');
+            }
+            await windowed.revoke(alice, 'unit-editor', unit);
+            assert.isFalse(await driver.authorize(alice, 'docs:write', unit), 'la asignación del local homónimo también se revoca');
+            assert.isFalse(await driver.hasRole(alice, { uuid: local }, unit));
+        });
         since('2.2', 'paridad entre drivers (3D · N1): una asignación cuyo rol está declarado para OTRO nivel no cuenta en ninguno de los dos — ni concede, ni es membresía, ni se enumera — y vuelve a contar en cuanto el nivel del rol coincide otra vez', async ({ assert, }) => {
             // Desviación 3 del lote 3B («`database.authorize` exige además
             // `r.scope_type = a.scope_type`, como ya hacía `openfga`») era una
@@ -3738,6 +3794,27 @@ export function registerAuthorizationDriverContract(harness, api) {
                 tree.chainOf = original;
             }
         }
+        // ── Estrategia 2.5.0 · firma 4 · `experimental` (regla D15) ─────────
+        // La capacidad DICE algo que el consumidor tiene que saber —«este driver está fuera de la garantía de la versión»— y
+        // no apaga ningún caso: el juez corre ENTERO contra un driver experimental. Lo que se observa es la declaración: la
+        // del driver y la copia normalizada que publica `authorization.capabilities()`, en las DOS caras.
+        caseFor('experimental', {
+            whenTrue: () => {
+                test('experimental:true · el driver se declara EXPERIMENTAL (capabilities.experimental === true) y `authorization.capabilities()` lo publica tal cual; el juez corre igual contra él', async ({ assert, }) => {
+                    assert.strictEqual(driver.capabilities?.experimental, true, 'el harness declara experimental: true y el driver no: declara lo observable');
+                    const published = await managerOver().capabilities();
+                    assert.strictEqual(published.experimental, true);
+                    assert.isTrue(Object.isFrozen(published));
+                });
+            },
+            whenFalse: () => {
+                test('experimental:false · el driver NO se declara experimental (ausente o false) y `authorization.capabilities().experimental` es false, nunca undefined (D15)', async ({ assert, }) => {
+                    assert.notStrictEqual(driver.capabilities?.experimental, true, 'el harness declara experimental: false y el driver declara true: declara lo observable');
+                    const published = await managerOver().capabilities();
+                    assert.strictEqual(published.experimental, false);
+                });
+            },
+        });
         // ── 3b-2e · E2 · `roleInheritanceNative` ─────────────────────────────
         caseFor('roleInheritanceNative', {
             whenFalse: () => {
@@ -3868,4 +3945,3 @@ export function uncoveredCapabilities(capabilities, covered) {
  * un skip disfrazado — «rechazo activo» sería una etiqueta.
  */
 const BOTH_FACES_REQUIRED = new Set(['transactionalWrites']);
-//# sourceMappingURL=contract.js.map

package/build/src/testing/main.d.ts

@@ -20,4 +20,3 @@ export { runRelationsReconcileContract, registerRelationsReconcileContract, } fr
 export type { RelationsReconcileHarness } from './relations_reconcile_contract.js';
 export { runScopeOutboxContract, registerScopeOutboxContract, makeScopeOutbox, SCOPE_OUTBOX_CAPABILITY_KEYS, } from './scope_outbox_contract.js';
 export type { ScopeOutboxCapabilities, ScopeOutboxContractHarness, ScopeOutboxContractTransactions, MakeScopeOutboxOptions, } from './scope_outbox_contract.js';
-//# sourceMappingURL=main.d.ts.map