@jantstack/adonis-authz 2.5.0-alpha.2 → 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

@@ -51,6 +51,14 @@ export declare function isUniqueViolation(error: unknown): boolean;
  * crudo del motor ni un 503 disfrazado de indeterminado.
  */
 export declare function isDeadlock(error: unknown): boolean;
+/**
+ * **¿Es el 400 del tope de operaciones por `Write` del servidor OpenFGA?** MEDIDO en v1.19.0 (cierre 2 de D1 · ⚪ N3):
+ * el SDK lanza `FgaApiValidationError` con `statusCode` 400 y `apiErrorCode` `exceeded_entity_limit` («The number of
+ * write operations exceeds the allowed limit of N»). Se mira el error y su `cause` directa (los dos drivers lo envuelven
+ * en un `AuthorizationBackendError`). PUNTO DE PASO ÚNICO de los dos puertos (lote D · D2, el gemelo de roles de N3):
+ * un despliegue con `--max-tuples-per-write` < 100 no es transitorio y no puede salir como 503.
+ */
+export declare function isServerWriteLimit(error: unknown): boolean;
 /**
  * ¿El error viene de un deadline vencido? knex lanza `KnexTimeoutError` (o, si
  * además falló la cancelación, el error de cancelación con `timeout` puesto);
@@ -58,6 +66,58 @@ export declare function isDeadlock(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
@@ -150,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';
 /**
@@ -92,6 +92,21 @@ export function isDeadlock(error) {
     }
     return false;
 }
+/**
+ * **¿Es el 400 del tope de operaciones por `Write` del servidor OpenFGA?** MEDIDO en v1.19.0 (cierre 2 de D1 · ⚪ N3):
+ * el SDK lanza `FgaApiValidationError` con `statusCode` 400 y `apiErrorCode` `exceeded_entity_limit` («The number of
+ * write operations exceeds the allowed limit of N»). Se mira el error y su `cause` directa (los dos drivers lo envuelven
+ * en un `AuthorizationBackendError`). PUNTO DE PASO ÚNICO de los dos puertos (lote D · D2, el gemelo de roles de N3):
+ * un despliegue con `--max-tuples-per-write` < 100 no es transitorio y no puede salir como 503.
+ */
+export function isServerWriteLimit(error) {
+    for (const candidate of [error, error?.cause]) {
+        const e = candidate;
+        if (e && typeof e === 'object' && e.statusCode === 400 && e.apiErrorCode === 'exceeded_entity_limit')
+            return true;
+    }
+    return false;
+}
 /**
  * ¿El error viene de un deadline vencido? knex lanza `KnexTimeoutError` (o, si
  * además falló la cancelación, el error de cancelación con `timeout` puesto);
@@ -105,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
@@ -325,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