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

package/build/src/errors.d.ts

@@ -41,6 +41,18 @@ export declare class AuthorizationBackendTimeoutError extends AuthorizationBacke
     static code: string;
     constructor(driver: string, operation: string, timeoutMs: number, cause?: unknown);
 }
+/**
+ * **El grafo excede lo que el motor resuelve** (lote «antes de RC» · R3, decisión del dueño 2026-10-17 (4)): OpenFGA
+ * respondió `authorization_model_resolution_too_complex` —una cadena de scopes o una anidación de grupos más profunda que
+ * su `--resolve-node-limit`—. Es un `AuthorizationBackendError` (503, se maneja igual y el relay lo trata como
+ * transitorio) con código propio, porque NO es una caída: en el BORDE es probabilístico (a 23 saltos falla entre un 4 % y
+ * un 26 % según la carga, medido en 3b-2e) y un reintento puede acertar, pero por ENCIMA de la cota falla siempre. Las
+ * cotas están en la tabla «Limits» del README (`FACTS_MAX_RESOLVE_DEPTH`). Nunca un `false`: deniega, pero ruidoso.
+ */
+export declare class ResolutionLimitError extends AuthorizationBackendError {
+    static code: string;
+    constructor(driver: string, operation: string, cause?: unknown);
+}
 /**
  * El resolutor de ancestros del consumidor lanzó. Es una dependencia más de
  * cada pregunta (el árbol de scopes), así que su caída se clasifica como la
@@ -78,6 +90,17 @@ export declare class InvalidSlugError extends Exception {
 export declare class AuthorizationConfigError extends Exception {
     static status: number;
     static code: string;
+    /**
+     * **Un deny CONDICIONAL ya en el store que `openfga` no puede reemplazar** (plan 2.5 · lote D · cierre 1 de D2, 🟡 4).
+     * El deny del paquete no caduca (D3): una tupla `denied_<rel>` CON condición solo puede venir de fuera (escrita a
+     * mano). Re-escribirla sin condición es 409 «already exists with a different condition» (medido en v1.19.0; M5: FGA
+     * no reemplaza la misma clave en un `Write`), que hasta el cierre salía como 503 «transitorio» y se repetía para
+     * siempre — y el deny CADUCABA. Ahora es 500 con la receta; `denyConditional: true` deja que el reconcile lo
+     * clasifique como residuo `deny-conditional` del destino (nunca 503 repetido).
+     */
+    static conditionalDeny(operation: string, tuple: string): AuthorizationConfigError & {
+        denyConditional: true;
+    };
     /**
      * **`assertWrite` devolvió una promesa** (2.4.0-alpha.3 · D3, hallazgo H2).
      * `assertWrite(ref): void` es SÍNCRONO y puro a propósito (R-13), pero
@@ -124,6 +147,33 @@ export declare function isThenable(value: unknown): boolean;
 export declare function markPartialWrite<E extends object>(error: E): E & {
     partialWrite: true;
 };
+/**
+ * **Marca de fallo de DESPLIEGUE** (lote «antes de RC» · cierre de L11, 🟠 A1 del auditor = H1; adelanta SOLO esta pieza
+ * de la decisión del dueño 2026-10-17 (3), que R3 generaliza con `classifyFgaFailure`): el error dice algo del
+ * DESPLIEGUE —el modelo fijado no es el que genera la config (la puerta L11), o el generador no puede generar con él—,
+ * no de la entrada que se estaba aplicando. Para el relay es TRANSITORIO (`markFailed(…, { transient: true })`: no
+ * consume intento ni aparca): aparcar un `moved`/`detached` por un despliegue a medias era fail-open PERSISTENTE (los
+ * admins de la org vieja conservaban el acceso hasta un `requeue` manual). Para el llamante sigue siendo lo que es
+ * (500 `E_AUTHZ_CONFIG`, «no es transitorio»): la marca es una propiedad, no una clase, y no cambia ni `status` ni
+ * `code`. Interna: no se exporta por `index.ts` (R3 decide la forma pública).
+ */
+export declare function markDeploymentFailure<E extends object>(error: E): E & {
+    deploymentFailure: true;
+};
+/** ¿El error viene marcado como fallo de despliegue (`markDeploymentFailure`)? */
+export declare function isDeploymentFailure(error: unknown): boolean;
+/**
+ * **¿Es un fallo TRANSITORIO para el relay?** (no consume intento ni aparca; `markFailed(…, { transient: true })`).
+ * PUNTO DE PASO ÚNICO de la regla (el manager la llama en cada fallo de la pasada; la guardia `fga.errors.classify` la
+ * juzga sobre las formas medidas). Transitorio: un 503 del backend (`AuthorizationBackendError` y subclases —timeout,
+ * `E_AUTHZ_RESOLUTION_LIMIT`—, o cualquier `status` 503), un fallo marcado de DESPLIEGUE (`markDeploymentFailure`) y
+ * **una CARRERA que escapa** (409 `E_AUTHZ_WRITE_CONFLICT`: otro escritor —un `grant` concurrente sobre la misma
+ * arista `scope#binding` del barrido, o la contención del árbol de `reparent`— llegó antes). Cierre de R3 (🟠 R3-A1 del
+ * auditor, decisión (3) firmada «carrera ⇒ como hoy»: antes de R3 la carrera que escapaba del guard era un 503
+ * transitorio): para el LLAMANTE sigue siendo 409; para el relay, aparcar por contención era H1 (un `moved` aparcado
+ * deja el padre viejo concediendo y tapona su clave). Lo demás —422, 500 sin marca, error sin `status`— cuenta intento.
+ */
+export declare function isTransientRelayFailure(error: unknown): boolean;
 /** ¿El error viene marcado como escritura parcial (`markPartialWrite`)? */
 export declare function isPartialWrite(error: unknown): boolean;
 /**
@@ -331,6 +381,54 @@ export declare class WriteConflictError extends Exception {
     static status: number;
     static code: string;
 }
+/**
+ * **Renovar esta membresía abriría un hueco en un deny** (plan 2.5 · lote D · cierre 2 de D2, 🟠 N1; decisión del dueño
+ * 2026-10-15 (9)): `relate` sobre una membresía `group:*#member` EXISTENTE con otra caducidad, en un driver que renueva
+ * con delete + write (`atomicRenewal: false`, `openfga`: FGA no reemplaza la misma clave en un `Write`, M5), cuando ese
+ * grupo —o uno por encima de él— es sujeto de un deny vivo de la partición. Entre los dos `Write` el sujeto no tendría el
+ * deny y CONCEDERÍA; si el 2.º fallara, para siempre. 409 y CERO escrituras: el estado del store no admite esta
+ * escritura tal cual. **Siempre cero escrituras** (cierre 4 · ⚪ C3-3): la renovación que SÍ se aplicó y en cuya
+ * ventana cayó un deny concurrente es `RenewalRacedError` (`E_AUTHZ_RENEWAL_RACED`), con otra receta.
+ *
+ * **La receta, honesta** (cierre 5 de D2, decisión del dueño §2026-10-16 (10), opción A): en `openfga` NO hay forma sin
+ * ventana de cambiar esa caducidad —FGA no tiene upsert, openfga/openfga#2151—. (1) Patrón recomendado: membresías SIN
+ * caducidad en los grupos con deny, que se terminan con `unrelate`. (2) Si hay que cambiarla: `unrelate` + `relate`
+ * ACEPTANDO la ventana, dicho como tal. Hasta el cierre 5 el mensaje ofrecía además «retira antes el deny, renueva y
+ * vuelve a escribirlo» como si fuera la salida segura: también abre la ventana (sin el deny, el sujeto concede). Cuando
+ * OpenFGA ofrezca upsert, la renovación será UNA escritura y `atomicRenewal` pasará a `true`.
+ */
+export declare class RenewalUnsafeError extends Exception {
+    static status: number;
+    static code: string;
+    static carrier(membership: string, denied: string): RenewalUnsafeError;
+    /**
+     * **La clave YA existe con una condición que el paquete no escribe** (lote «antes de RC» · L11, injerto 3 del juez —H8
+     * del auditor—): `relate` (relaciones) o `grant` (roles) de `openfga` sobre una tupla cuya condición es `foreign`
+     * (otra condición, o `not_expired` con un contexto que no es exactamente `{ valid_until }`) o `unparseable`
+     * (`fgaTupleExpiry`). Tratarla como «sin caducidad» era un no-op mudo sobre una tupla que el servidor ignora o evalúa
+     * con otra semántica; como «vencida», una reescritura en dos `Write` sin mirar nada. 409 y CERO escrituras.
+     */
+    static foreignCondition(operation: string, tuple: string, detail: string): RenewalUnsafeError;
+}
+/**
+ * **La renovación SE APLICÓ y un deny concurrente cayó en su ventana** (cierre 3 de D2 · 🟡 C2-3; código PROPIO desde el
+ * cierre 4 · ⚪ C3-3): la renovación (dos `Write`) de una membresía cuyo grupo NO transportaba ningún deny al
+ * comprobarlo, y la RE-COMPROBACIÓN tras los dos `Write` encuentra uno —un `deny` concurrente entró entre la comprobación
+ * y la renovación—. Estado final correcto (la membresía está y el deny vuelve a alcanzar al sujeto), pero durante la
+ * ventana entre los dos `Write` el deny ya confirmado NO alcanzó al sujeto. Va marcado parcial (`markPartialWrite`: el
+ * manager notifica `indeterminate: true`) y lleva `carriedDeny` y `renewalApplied: true`.
+ *
+ * Hasta el cierre 4 era el MISMO 409 `E_AUTHZ_RENEWAL_UNSAFE` («cero escrituras, aplica la receta»): un consumidor que
+ * automatizara esa receta (`unrelate` + `relate`) ante este caso reabría la ventana con el deny YA dentro del grupo. Por
+ * eso tiene su código y su receta, que NO es esa.
+ */
+export declare class RenewalRacedError extends Exception {
+    static status: number;
+    static code: string;
+    carriedDeny: string;
+    renewalApplied: true;
+    static raced(membership: string, denied: string): RenewalRacedError;
+}
 /**
  * **El lote de `checkMany` no tiene la forma admitida** (plan 2.5 · lote A,
  * P4): vacío, o por encima de `RELATIONS_CHECK_MANY_MAX` (50). Es 422 con
@@ -444,6 +542,31 @@ export declare class ScopeDepthLimitError extends Exception {
         server: string;
     });
 }
+/**
+ * **La arista de anidación de grupos que el techo del driver no admite** (lote «antes de RC» · R1, decisiones del dueño
+ * 2026-10-17 (5) y (5-bis)): `relate(group:Gc#member, 'member', group:Gp)` dejaría una cadena de grupos anidados MÁS
+ * LARGA que el techo del driver —el camino más largo que atraviesa la arista nueva, hacia arriba y hacia abajo—, cerraría
+ * un CICLO, o el grafo a recorrer pasa de `GROUP_DEPTH_MAX_NODES`. 422 y CERO escrituras: la pregunta está bien formada,
+ * es el grafo el que no cabe. Gemelo de `E_AUTHZ_SCOPE_DEPTH_LIMIT` y con su misma regla de letra (alpha.8, 7.2): el
+ * `message` es para el TENANT (la cadena, el techo, `maxGroupDepth`, «no se ha escrito nada») y no nombra el
+ * backend; el porqué del techo —OpenFGA no resuelve más allá, el mando del servidor es `OPENFGA_RESOLVE_NODE_LIMIT`— va
+ * en `details`, NO enumerable (un handler genérico que serializa el error no se lo enseña al tenant).
+ */
+export declare class GroupDepthLimitError extends Exception {
+    static status: number;
+    static code: string;
+    readonly details: {
+        reason: 'too-deep' | 'cycle' | 'too-many-groups';
+        edge: string;
+        depth: number | null;
+        maxGroupDepth: number;
+        /** Solo con `too-many-groups`: qué cota se pasó (grupos, requests, tuplas leídas o el deadline total). */
+        budget?: 'nodes' | 'reads' | 'tuples' | 'deadline';
+        why: string;
+        server: string;
+    };
+    constructor(message: string, details: GroupDepthLimitError['details']);
+}
 /**
  * Una primitiva de 2.1 necesita un método OPCIONAL del puerto que el driver
  * activo no implementa (2.1, B5): se nombra el método y se lanza. 500 porque
@@ -480,6 +603,33 @@ export declare class UnsupportedOperationError extends Exception {
      * entre procesos (invariante 14); moverla al commit del consumidor lo anula.
      */
     static transactionalCatalog(operation: string): UnsupportedOperationError;
+    /**
+     * **Los `list*` de relaciones no paginan en 2.5** (lote «antes de RC» · 7.4, opción 4 del juez, decisión del dueño
+     * 2026-10-17 (7.4)): `listObjects`/`listSubjects`/`listDenies`/`membersOf` ya no tienen `page` en la firma (nunca
+     * hizo nada: se diseñó en la Fase 4 y no llegó a programarse). Un valor DISTINTO de `undefined` —`null`, `{}`,
+     * `{ limit: 0 }`…— que llegue por JS o `as any` es 500 con cero llamadas al backend, en el manager y en los drivers:
+     * una lista entera que PARECE una página es la ruptura muda que el linaje L8 prohíbe. La paginación de verdad llegará
+     * como métodos aparte (`*Page`, 2.6) con capacidad propia.
+     */
+    static listPage(operation: string, driver: string): UnsupportedOperationError;
+    /**
+     * **Un cursor que este driver nunca emitió** (7.4, injerto 4 del juez; `openfga` y el doble): sus `enumerate*`
+     * devuelven todo en una página y JAMÁS un cursor, así que un `after` no puede haber salido de ellos. 500 con cero
+     * llamadas: aceptarlo en silencio sería empezar «desde algún sitio» o ignorarlo, las dos cosas mudas.
+     */
+    static enumerateCursor(operation: string, driver: string): UnsupportedOperationError;
+}
+/**
+ * **Una página de `enumerate*` mal formada** (lote «antes de RC» · 7.4, injerto 4 del juez; tester H2/H3, auditor T-1):
+ * `limit` que no es un entero ≥ 1 (`NaN`, `0`, negativo, decimal, cadena) o `after` que no es una cadena no vacía (en
+ * `database`, además, con forma de uuid canónico en minúsculas: el cursor que ESE driver emite). 422 porque es la
+ * pregunta la que está mal formada (invariante 5); hasta 7.4 `limit: NaN` generaba una consulta sin `LIMIT` y un
+ * `after` ajeno era un 503 en PostgreSQL (la columna es `uuid`) y un fin silencioso en MySQL/SQLite. Un `limit` por
+ * encima de `RELATIONS_ENUMERATE_MAX_LIMIT` NO es este error: se recorta (con cursor, sin pérdida).
+ */
+export declare class InvalidRelationPageError extends Exception {
+    static status: number;
+    static code: string;
 }
 /**
  * Una vista de `forRequest()` se usó para LEER después de `maxAgeMs` (2D ·
@@ -832,4 +982,86 @@ export declare class RelationUsersetUnsupportedError extends Exception {
     static status: number;
     static code: string;
 }
-//# sourceMappingURL=errors.d.ts.map
+/**
+ * **Deny sobre algo que no se puede denegar** (plan 2.5 · lote D · D1; panel
+ * tenencia ronda 2, D10/D-17). `deny(…)` sobre un tipo cuya spec no declara
+ * `deny: 'write'` (fase 2 del opt-in: sin opt-in, o en `deny: 'read'`, la fase
+ * en la que el modelo y las lecturas ya honran el deny pero aún no se aceptan
+ * escrituras), sobre el tipo built-in `group`, o con el comodín `*` como
+ * sujeto. 422 ANTES de tocar el driver (cero llamadas, cero eventos): una
+ * pregunta inválida, no una caída.
+ */
+export declare class RelationNotDenyableError extends Exception {
+    static status: number;
+    static code: string;
+}
+/**
+ * **`expiresAt` en un deny** (plan 2.5 · lote D · D3, decisión del dueño
+ * 2026-10-14): el deny de relaciones NO caduca en v1. Medido (M5, OpenFGA
+ * v1.19.0): FGA rechaza delete+write de la misma clave en un `Write` (400
+ * `cannot_allow_duplicate_tuples_in_one_request`) y `on_duplicate: ignore` con
+ * otra condición es 409, así que cambiar la caducidad de un deny VIVO exige dos
+ * `Write` con una ventana en la que deja de bloquear — y si el segundo cae, el
+ * deny DESAPARECE. 422 ANTES de tocar el driver, con la razón medida.
+ */
+export declare class RelationDenyExpiryError extends Exception {
+    static status: number;
+    static code: string;
+}
+/**
+ * **`membersOf` de `database` sobre un objeto con deny y más candidatos que la cota** (lote D · cierre 1 de D1, 🟡 4 del
+ * auditor). Con una fila `denied_*` vigente en el objeto, cada candidato se juzga con un `check` (el corte de camino);
+ * sin cota eran N consultas en serie —una amplificación barata para quien puede escribir un deny—. Pasada
+ * `RELATIONS_MEMBERS_DENY_CHECK_MAX` (1 000) ⇒ 500, NUNCA una lista parcial; el deadline TOTAL del bucle es 503
+ * `E_AUTHZ_BACKEND_TIMEOUT`. **500 y no 422** (decisión 1 del cierre 1, ratificada en el cierre 2): no es una pregunta
+ * inválida del llamante —la misma pregunta es válida con menos candidatos— sino una cota del DESPLIEGUE (precedente
+ * `E_AUTHZ_TOO_MANY_LOCAL_ROLES`); y no 503 porque no es reintentable. `authorizedScopes` (`E_AUTHZ_TOO_MANY_SCOPES`,
+ * 422) acota una enumeración que el llamante pide con su `maxScopes`; aquí no hay cota del llamante.
+ */
+export declare class MembersOfDenyLimitError extends Exception {
+    static status: number;
+    static code: string;
+}
+/**
+ * **`authz:relations:reconcile` se NIEGA a migrar denies** (plan 2.5 · lote D · D2; auditor R2-5, tester S6, juez ronda 2
+ * fila D). El origen trae al menos un deny vivo y el destino no puede escribirlo: no declara `relationDenies` (o no trae
+ * `deny`/`removeDeny`/`denyPhase`), el tipo no está en la fase `'write'` del opt-in EN EL DESTINO (su config, no la spec
+ * persistida), el par tipo/relación no está declarado allí, su modelo fijado no declara `denied_<rel>` (D-31), o el
+ * origen enumera un deny SIN marcar `kind` (`unmarked`). Se decide en la FASE DE PLAN, antes de la primera escritura en
+ * cualquier partición: **CERO escrituras**, y **jamás `skipped`** — perder un deny no es una pérdida que se pueda declarar
+ * (escribir los allows sin él concede lo que el origen niega). `--dry-run` no lanza: lo marca en `report.denyRefused` y es
+ * deriva. Lleva `refusals` (una entrada por tipo/relación y motivo). 500 y no 422: no es una pregunta del llamante sino
+ * el estado del despliegue (precedente `E_AUTHZ_MASS_RECONCILE_REFUSED`).
+ */
+export declare class DenyMigrationRefusedError extends Exception {
+    static status: number;
+    static code: string;
+    refusals: ReadonlyArray<{
+        objectType: string;
+        relation: string;
+        reason: string;
+        message: string;
+    }>;
+}
+/**
+ * **`saveRelationsConfig` se NIEGA a guardar una config que encoge el alcance de un deny vivo** (lote RC · sublote (8);
+ * decisión §2026-10-15 (8) y firmas «(8 · panel)» 2026-10-22): la guarda de `database` con la propiedad «para todo deny
+ * vivo de `authz_relations`, alcance nuevo ⊇ alcance viejo» (`src/relations/deny_reach.ts`). Cero escrituras (ni la fila
+ * ni la versión del catálogo). Lleva `findings` (un hallazgo por tipo/relación: `shrunk`, `orphan` o `no-baseline` —sin
+ * línea base utilizable no se puede juzgar—, con su receta). Salidas con nombre, separadas: `{ establishBaseline: true }`
+ * levanta solo `no-baseline`; `{ allowDenyReachShrink: ['tipo#relación'] }` exime solo esos hallazgos. 500 y no 422 por
+ * precedente (`E_AUTHZ_DENY_MIGRATION_REFUSED`, `E_AUTHZ_MASS_RECONCILE_REFUSED`): no es una pregunta mal formada, es el
+ * estado del despliegue.
+ */
+export declare class DenyReachRefusedError extends Exception {
+    static status: number;
+    static code: string;
+    findings: ReadonlyArray<{
+        objectType: string;
+        relation: string;
+        reason: string;
+        count: number;
+        lost: string[];
+        recipe: string;
+    }>;
+}

package/build/src/errors.js

@@ -45,6 +45,27 @@ export class AuthorizationBackendTimeoutError extends AuthorizationBackendError
         this.message = `El backend de autorización '${driver}' no respondió en ${timeoutMs} ms (${operation})`;
     }
 }
+/**
+ * **El grafo excede lo que el motor resuelve** (lote «antes de RC» · R3, decisión del dueño 2026-10-17 (4)): OpenFGA
+ * respondió `authorization_model_resolution_too_complex` —una cadena de scopes o una anidación de grupos más profunda que
+ * su `--resolve-node-limit`—. Es un `AuthorizationBackendError` (503, se maneja igual y el relay lo trata como
+ * transitorio) con código propio, porque NO es una caída: en el BORDE es probabilístico (a 23 saltos falla entre un 4 % y
+ * un 26 % según la carga, medido en 3b-2e) y un reintento puede acertar, pero por ENCIMA de la cota falla siempre. Las
+ * cotas están en la tabla «Limits» del README (`FACTS_MAX_RESOLVE_DEPTH`). Nunca un `false`: deniega, pero ruidoso.
+ */
+export class ResolutionLimitError extends AuthorizationBackendError {
+    static code = 'E_AUTHZ_RESOLUTION_LIMIT';
+    constructor(driver, operation, cause) {
+        super(driver, operation, cause);
+        this.message =
+            `El backend de autorización '${driver}' no pudo resolver ${operation}: el grafo (la cadena de scopes o la ` +
+                'anidación de grupos) excede lo que OpenFGA resuelve (resolution_too_complex). En el borde es probabilístico y un ' +
+                'reintento puede acertar; por encima de la cota falla siempre: ver «Limits» en el README (FACTS_MAX_RESOLVE_DEPTH ' +
+                'para la cadena de scopes; maxGroupDepth (defineRelationsConfig) para la anidación de grupos —el driver ' +
+                'openfga lo calibra contra el servidor, 22 en v1.19 por defecto—; el mando del servidor es OPENFGA_RESOLVE_NODE_LIMIT / --resolve-node-limit). ' +
+                'Nunca es un «sin permiso».';
+    }
+}
 /**
  * El resolutor de ancestros del consumidor lanzó. Es una dependencia más de
  * cada pregunta (el árbol de scopes), así que su caída se clasifica como la
@@ -84,6 +105,24 @@ export class InvalidSlugError extends Exception {
 export class AuthorizationConfigError extends Exception {
     static status = 500;
     static code = 'E_AUTHZ_CONFIG';
+    /**
+     * **Un deny CONDICIONAL ya en el store que `openfga` no puede reemplazar** (plan 2.5 · lote D · cierre 1 de D2, 🟡 4).
+     * El deny del paquete no caduca (D3): una tupla `denied_<rel>` CON condición solo puede venir de fuera (escrita a
+     * mano). Re-escribirla sin condición es 409 «already exists with a different condition» (medido en v1.19.0; M5: FGA
+     * no reemplaza la misma clave en un `Write`), que hasta el cierre salía como 503 «transitorio» y se repetía para
+     * siempre — y el deny CADUCABA. Ahora es 500 con la receta; `denyConditional: true` deja que el reconcile lo
+     * clasifique como residuo `deny-conditional` del destino (nunca 503 repetido).
+     */
+    static conditionalDeny(operation, tuple) {
+        const error = new AuthorizationConfigError(`${operation}: en el store ya hay un deny CONDICIONAL (con caducidad) sobre ${tuple}. El deny del paquete no caduca ` +
+            '(D3), así que esa tupla se escribió desde fuera del paquete; OpenFGA no puede REEMPLAZAR la misma clave en un ' +
+            'Write (409 «already exists with a different condition», M5), así que este driver no puede rehacerlo permanente ' +
+            'y repetir no sirve: no es una caída. Mientras viva niega; cuando caduque concederá lo que cortaba. Receta: ' +
+            'removeDeny + deny (entre los dos hay una VENTANA en la que el deny no está y lo que cortaba se concede: hazlo ' +
+            'con la flota sin tráfico sobre ese objeto o asúmela). No se ha escrito nada.');
+        error.denyConditional = true;
+        return error;
+    }
     /**
      * **`assertWrite` devolvió una promesa** (2.4.0-alpha.3 · D3, hallazgo H2).
      * `assertWrite(ref): void` es SÍNCRONO y puro a propósito (R-13), pero
@@ -159,6 +198,52 @@ export function markPartialWrite(error) {
     }
     return error;
 }
+/**
+ * **Marca de fallo de DESPLIEGUE** (lote «antes de RC» · cierre de L11, 🟠 A1 del auditor = H1; adelanta SOLO esta pieza
+ * de la decisión del dueño 2026-10-17 (3), que R3 generaliza con `classifyFgaFailure`): el error dice algo del
+ * DESPLIEGUE —el modelo fijado no es el que genera la config (la puerta L11), o el generador no puede generar con él—,
+ * no de la entrada que se estaba aplicando. Para el relay es TRANSITORIO (`markFailed(…, { transient: true })`: no
+ * consume intento ni aparca): aparcar un `moved`/`detached` por un despliegue a medias era fail-open PERSISTENTE (los
+ * admins de la org vieja conservaban el acceso hasta un `requeue` manual). Para el llamante sigue siendo lo que es
+ * (500 `E_AUTHZ_CONFIG`, «no es transitorio»): la marca es una propiedad, no una clase, y no cambia ni `status` ni
+ * `code`. Interna: no se exporta por `index.ts` (R3 decide la forma pública).
+ */
+export function markDeploymentFailure(error) {
+    try {
+        Object.defineProperty(error, 'deploymentFailure', { value: true, enumerable: false, configurable: true });
+    }
+    catch {
+        // Un error congelado no admite la marca: se propaga sin ella (cuenta intento, como antes de la marca).
+    }
+    return error;
+}
+/** ¿El error viene marcado como fallo de despliegue (`markDeploymentFailure`)? */
+export function isDeploymentFailure(error) {
+    return error !== null && typeof error === 'object' && error.deploymentFailure === true;
+}
+/**
+ * **¿Es un fallo TRANSITORIO para el relay?** (no consume intento ni aparca; `markFailed(…, { transient: true })`).
+ * PUNTO DE PASO ÚNICO de la regla (el manager la llama en cada fallo de la pasada; la guardia `fga.errors.classify` la
+ * juzga sobre las formas medidas). Transitorio: un 503 del backend (`AuthorizationBackendError` y subclases —timeout,
+ * `E_AUTHZ_RESOLUTION_LIMIT`—, o cualquier `status` 503), un fallo marcado de DESPLIEGUE (`markDeploymentFailure`) y
+ * **una CARRERA que escapa** (409 `E_AUTHZ_WRITE_CONFLICT`: otro escritor —un `grant` concurrente sobre la misma
+ * arista `scope#binding` del barrido, o la contención del árbol de `reparent`— llegó antes). Cierre de R3 (🟠 R3-A1 del
+ * auditor, decisión (3) firmada «carrera ⇒ como hoy»: antes de R3 la carrera que escapaba del guard era un 503
+ * transitorio): para el LLAMANTE sigue siendo 409; para el relay, aparcar por contención era H1 (un `moved` aparcado
+ * deja el padre viejo concediendo y tapona su clave). Lo demás —422, 500 sin marca, error sin `status`— cuenta intento.
+ */
+export function isTransientRelayFailure(error) {
+    if (error instanceof AuthorizationBackendError)
+        return true;
+    if (isDeploymentFailure(error))
+        return true;
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const { status, code } = error;
+    if (code === WriteConflictError.code)
+        return true;
+    return status === 503;
+}
 /** ¿El error viene marcado como escritura parcial (`markPartialWrite`)? */
 export function isPartialWrite(error) {
     return error !== null && typeof error === 'object' && error.partialWrite === true;
@@ -382,6 +467,75 @@ export class WriteConflictError extends Exception {
     static status = 409;
     static code = 'E_AUTHZ_WRITE_CONFLICT';
 }
+/**
+ * **Renovar esta membresía abriría un hueco en un deny** (plan 2.5 · lote D · cierre 2 de D2, 🟠 N1; decisión del dueño
+ * 2026-10-15 (9)): `relate` sobre una membresía `group:*#member` EXISTENTE con otra caducidad, en un driver que renueva
+ * con delete + write (`atomicRenewal: false`, `openfga`: FGA no reemplaza la misma clave en un `Write`, M5), cuando ese
+ * grupo —o uno por encima de él— es sujeto de un deny vivo de la partición. Entre los dos `Write` el sujeto no tendría el
+ * deny y CONCEDERÍA; si el 2.º fallara, para siempre. 409 y CERO escrituras: el estado del store no admite esta
+ * escritura tal cual. **Siempre cero escrituras** (cierre 4 · ⚪ C3-3): la renovación que SÍ se aplicó y en cuya
+ * ventana cayó un deny concurrente es `RenewalRacedError` (`E_AUTHZ_RENEWAL_RACED`), con otra receta.
+ *
+ * **La receta, honesta** (cierre 5 de D2, decisión del dueño §2026-10-16 (10), opción A): en `openfga` NO hay forma sin
+ * ventana de cambiar esa caducidad —FGA no tiene upsert, openfga/openfga#2151—. (1) Patrón recomendado: membresías SIN
+ * caducidad en los grupos con deny, que se terminan con `unrelate`. (2) Si hay que cambiarla: `unrelate` + `relate`
+ * ACEPTANDO la ventana, dicho como tal. Hasta el cierre 5 el mensaje ofrecía además «retira antes el deny, renueva y
+ * vuelve a escribirlo» como si fuera la salida segura: también abre la ventana (sin el deny, el sujeto concede). Cuando
+ * OpenFGA ofrezca upsert, la renovación será UNA escritura y `atomicRenewal` pasará a `true`.
+ */
+export class RenewalUnsafeError extends Exception {
+    static status = 409;
+    static code = 'E_AUTHZ_RENEWAL_UNSAFE';
+    static carrier(membership, denied) {
+        return new RenewalUnsafeError(`relate: no se renueva ${membership}: el grupo TRANSPORTA un deny vivo (${denied}) y este driver renueva con DOS ` +
+            'Write —delete y write: OpenFGA no reemplaza la misma clave en un Write (M5; sin upsert, openfga/openfga#2151)—; ' +
+            'entre los dos el deny no alcanzaría al sujeto y concedería (y si el segundo fallara, para siempre). No se ha escrito ' +
+            'nada. En este driver NO hay forma sin ventana de cambiar esta caducidad. (1) Patrón recomendado: membresías SIN ' +
+            'caducidad en los grupos con deny, que se terminan con unrelate. (2) Si hay que cambiarla: unrelate + relate de esa ' +
+            'membresía ACEPTANDO la ventana — mientras dura, el sujeto no recibe el deny del grupo y concede lo que otro camino le ' +
+            'dé y ese deny corte.');
+    }
+    /**
+     * **La clave YA existe con una condición que el paquete no escribe** (lote «antes de RC» · L11, injerto 3 del juez —H8
+     * del auditor—): `relate` (relaciones) o `grant` (roles) de `openfga` sobre una tupla cuya condición es `foreign`
+     * (otra condición, o `not_expired` con un contexto que no es exactamente `{ valid_until }`) o `unparseable`
+     * (`fgaTupleExpiry`). Tratarla como «sin caducidad» era un no-op mudo sobre una tupla que el servidor ignora o evalúa
+     * con otra semántica; como «vencida», una reescritura en dos `Write` sin mirar nada. 409 y CERO escrituras.
+     */
+    static foreignCondition(operation, tuple, detail) {
+        return new RenewalUnsafeError(`${operation}: la tupla ${tuple} ya existe en el store con una condición que este paquete no escribe ni sabe leer ` +
+            `(${detail}). No se reescribe a ciegas: el paquete no sabe qué concede (la puede haber escrito otra herramienta, o ` +
+            'un modelo anterior). No se ha escrito nada. Receta: revísala y bórrala a mano (SDK/CLI de OpenFGA, o unrelate/' +
+            'revoke por el paquete) y repite.');
+    }
+}
+/**
+ * **La renovación SE APLICÓ y un deny concurrente cayó en su ventana** (cierre 3 de D2 · 🟡 C2-3; código PROPIO desde el
+ * cierre 4 · ⚪ C3-3): la renovación (dos `Write`) de una membresía cuyo grupo NO transportaba ningún deny al
+ * comprobarlo, y la RE-COMPROBACIÓN tras los dos `Write` encuentra uno —un `deny` concurrente entró entre la comprobación
+ * y la renovación—. Estado final correcto (la membresía está y el deny vuelve a alcanzar al sujeto), pero durante la
+ * ventana entre los dos `Write` el deny ya confirmado NO alcanzó al sujeto. Va marcado parcial (`markPartialWrite`: el
+ * manager notifica `indeterminate: true`) y lleva `carriedDeny` y `renewalApplied: true`.
+ *
+ * Hasta el cierre 4 era el MISMO 409 `E_AUTHZ_RENEWAL_UNSAFE` («cero escrituras, aplica la receta»): un consumidor que
+ * automatizara esa receta (`unrelate` + `relate`) ante este caso reabría la ventana con el deny YA dentro del grupo. Por
+ * eso tiene su código y su receta, que NO es esa.
+ */
+export class RenewalRacedError extends Exception {
+    static status = 409;
+    static code = 'E_AUTHZ_RENEWAL_RACED';
+    static raced(membership, denied) {
+        const error = new RenewalRacedError(`relate: la renovación de ${membership} SE APLICÓ, pero un deny concurrente (${denied}) entró entre la comprobación ` +
+            'de portadora y los dos Write: durante la ventana entre el delete y el write ese deny, ya confirmado, NO alcanzó al ' +
+            'sujeto. El estado final es correcto (la membresía está y el deny la alcanza): NO hay nada que reescribir, y la receta ' +
+            'de E_AUTHZ_RENEWAL_UNSAFE (unrelate + relate) reabriría la ventana con el deny ya dentro. Receta: revisa las ' +
+            'decisiones de acceso de ese sujeto en esa ventana; para no repetirla, serializa los deny y las renovaciones de ese ' +
+            'grupo, o renueva con removeDeny antes y deny después.');
+        error.carriedDeny = denied;
+        error.renewalApplied = true;
+        return error;
+    }
+}
 /**
  * **El lote de `checkMany` no tiene la forma admitida** (plan 2.5 · lote A,
  * P4): vacío, o por encima de `RELATIONS_CHECK_MANY_MAX` (50). Es 422 con
@@ -481,6 +635,24 @@ export class ScopeDepthLimitError extends Exception {
         Object.defineProperty(this, 'details', { value: details, enumerable: false, configurable: true, writable: false });
     }
 }
+/**
+ * **La arista de anidación de grupos que el techo del driver no admite** (lote «antes de RC» · R1, decisiones del dueño
+ * 2026-10-17 (5) y (5-bis)): `relate(group:Gc#member, 'member', group:Gp)` dejaría una cadena de grupos anidados MÁS
+ * LARGA que el techo del driver —el camino más largo que atraviesa la arista nueva, hacia arriba y hacia abajo—, cerraría
+ * un CICLO, o el grafo a recorrer pasa de `GROUP_DEPTH_MAX_NODES`. 422 y CERO escrituras: la pregunta está bien formada,
+ * es el grafo el que no cabe. Gemelo de `E_AUTHZ_SCOPE_DEPTH_LIMIT` y con su misma regla de letra (alpha.8, 7.2): el
+ * `message` es para el TENANT (la cadena, el techo, `maxGroupDepth`, «no se ha escrito nada») y no nombra el
+ * backend; el porqué del techo —OpenFGA no resuelve más allá, el mando del servidor es `OPENFGA_RESOLVE_NODE_LIMIT`— va
+ * en `details`, NO enumerable (un handler genérico que serializa el error no se lo enseña al tenant).
+ */
+export class GroupDepthLimitError extends Exception {
+    static status = 422;
+    static code = 'E_AUTHZ_GROUP_DEPTH_LIMIT';
+    constructor(message, details) {
+        super(message);
+        Object.defineProperty(this, 'details', { value: details, enumerable: false, configurable: true, writable: false });
+    }
+}
 /**
  * Una primitiva de 2.1 necesita un método OPCIONAL del puerto que el driver
  * activo no implementa (2.1, B5): se nombra el método y se lanza. 500 porque
@@ -546,6 +718,46 @@ export class UnsupportedOperationError extends Exception {
                 `removeDeny (hechos) y relate/unrelate/purge* (relaciones) admiten { transaction }.`;
         return error;
     }
+    /**
+     * **Los `list*` de relaciones no paginan en 2.5** (lote «antes de RC» · 7.4, opción 4 del juez, decisión del dueño
+     * 2026-10-17 (7.4)): `listObjects`/`listSubjects`/`listDenies`/`membersOf` ya no tienen `page` en la firma (nunca
+     * hizo nada: se diseñó en la Fase 4 y no llegó a programarse). Un valor DISTINTO de `undefined` —`null`, `{}`,
+     * `{ limit: 0 }`…— que llegue por JS o `as any` es 500 con cero llamadas al backend, en el manager y en los drivers:
+     * una lista entera que PARECE una página es la ruptura muda que el linaje L8 prohíbe. La paginación de verdad llegará
+     * como métodos aparte (`*Page`, 2.6) con capacidad propia.
+     */
+    static listPage(operation, driver) {
+        const error = new UnsupportedOperationError('page', operation, driver);
+        error.message =
+            `${operation}: se pasó una página (page) y ${operation} no pagina en 2.5 — devuelve el conjunto COMPLETO (o ` +
+                `señala truncated), nunca un cursor. No se ha llamado al backend ('${driver}'). Quita el argumento page; la ` +
+                `paginación de los listados llegará como métodos aparte (*Page) con capacidad propia.`;
+        return error;
+    }
+    /**
+     * **Un cursor que este driver nunca emitió** (7.4, injerto 4 del juez; `openfga` y el doble): sus `enumerate*`
+     * devuelven todo en una página y JAMÁS un cursor, así que un `after` no puede haber salido de ellos. 500 con cero
+     * llamadas: aceptarlo en silencio sería empezar «desde algún sitio» o ignorarlo, las dos cosas mudas.
+     */
+    static enumerateCursor(operation, driver) {
+        const error = new UnsupportedOperationError('page.after', operation, driver);
+        error.message =
+            `${operation}: el driver '${driver}' no emite cursor (devuelve todas las tuplas en una página), así que un ` +
+                `page.after no salió de él y no se acepta. No se ha llamado al backend. Llama sin after.`;
+        return error;
+    }
+}
+/**
+ * **Una página de `enumerate*` mal formada** (lote «antes de RC» · 7.4, injerto 4 del juez; tester H2/H3, auditor T-1):
+ * `limit` que no es un entero ≥ 1 (`NaN`, `0`, negativo, decimal, cadena) o `after` que no es una cadena no vacía (en
+ * `database`, además, con forma de uuid canónico en minúsculas: el cursor que ESE driver emite). 422 porque es la
+ * pregunta la que está mal formada (invariante 5); hasta 7.4 `limit: NaN` generaba una consulta sin `LIMIT` y un
+ * `after` ajeno era un 503 en PostgreSQL (la columna es `uuid`) y un fin silencioso en MySQL/SQLite. Un `limit` por
+ * encima de `RELATIONS_ENUMERATE_MAX_LIMIT` NO es este error: se recorta (con cursor, sin pérdida).
+ */
+export class InvalidRelationPageError extends Exception {
+    static status = 422;
+    static code = 'E_AUTHZ_INVALID_PAGE';
 }
 /**
  * Una vista de `forRequest()` se usó para LEER después de `maxAgeMs` (2D ·
@@ -876,4 +1088,74 @@ export class RelationUsersetUnsupportedError extends Exception {
     static status = 422;
     static code = 'E_AUTHZ_RELATION_USERSET_UNSUPPORTED';
 }
-//# sourceMappingURL=errors.js.map
+/**
+ * **Deny sobre algo que no se puede denegar** (plan 2.5 · lote D · D1; panel
+ * tenencia ronda 2, D10/D-17). `deny(…)` sobre un tipo cuya spec no declara
+ * `deny: 'write'` (fase 2 del opt-in: sin opt-in, o en `deny: 'read'`, la fase
+ * en la que el modelo y las lecturas ya honran el deny pero aún no se aceptan
+ * escrituras), sobre el tipo built-in `group`, o con el comodín `*` como
+ * sujeto. 422 ANTES de tocar el driver (cero llamadas, cero eventos): una
+ * pregunta inválida, no una caída.
+ */
+export class RelationNotDenyableError extends Exception {
+    static status = 422;
+    static code = 'E_AUTHZ_RELATION_NOT_DENYABLE';
+}
+/**
+ * **`expiresAt` en un deny** (plan 2.5 · lote D · D3, decisión del dueño
+ * 2026-10-14): el deny de relaciones NO caduca en v1. Medido (M5, OpenFGA
+ * v1.19.0): FGA rechaza delete+write de la misma clave en un `Write` (400
+ * `cannot_allow_duplicate_tuples_in_one_request`) y `on_duplicate: ignore` con
+ * otra condición es 409, así que cambiar la caducidad de un deny VIVO exige dos
+ * `Write` con una ventana en la que deja de bloquear — y si el segundo cae, el
+ * deny DESAPARECE. 422 ANTES de tocar el driver, con la razón medida.
+ */
+export class RelationDenyExpiryError extends Exception {
+    static status = 422;
+    static code = 'E_AUTHZ_DENY_EXPIRY_UNSUPPORTED';
+}
+/**
+ * **`membersOf` de `database` sobre un objeto con deny y más candidatos que la cota** (lote D · cierre 1 de D1, 🟡 4 del
+ * auditor). Con una fila `denied_*` vigente en el objeto, cada candidato se juzga con un `check` (el corte de camino);
+ * sin cota eran N consultas en serie —una amplificación barata para quien puede escribir un deny—. Pasada
+ * `RELATIONS_MEMBERS_DENY_CHECK_MAX` (1 000) ⇒ 500, NUNCA una lista parcial; el deadline TOTAL del bucle es 503
+ * `E_AUTHZ_BACKEND_TIMEOUT`. **500 y no 422** (decisión 1 del cierre 1, ratificada en el cierre 2): no es una pregunta
+ * inválida del llamante —la misma pregunta es válida con menos candidatos— sino una cota del DESPLIEGUE (precedente
+ * `E_AUTHZ_TOO_MANY_LOCAL_ROLES`); y no 503 porque no es reintentable. `authorizedScopes` (`E_AUTHZ_TOO_MANY_SCOPES`,
+ * 422) acota una enumeración que el llamante pide con su `maxScopes`; aquí no hay cota del llamante.
+ */
+export class MembersOfDenyLimitError extends Exception {
+    static status = 500;
+    static code = 'E_AUTHZ_MEMBERS_DENY_LIMIT';
+}
+/**
+ * **`authz:relations:reconcile` se NIEGA a migrar denies** (plan 2.5 · lote D · D2; auditor R2-5, tester S6, juez ronda 2
+ * fila D). El origen trae al menos un deny vivo y el destino no puede escribirlo: no declara `relationDenies` (o no trae
+ * `deny`/`removeDeny`/`denyPhase`), el tipo no está en la fase `'write'` del opt-in EN EL DESTINO (su config, no la spec
+ * persistida), el par tipo/relación no está declarado allí, su modelo fijado no declara `denied_<rel>` (D-31), o el
+ * origen enumera un deny SIN marcar `kind` (`unmarked`). Se decide en la FASE DE PLAN, antes de la primera escritura en
+ * cualquier partición: **CERO escrituras**, y **jamás `skipped`** — perder un deny no es una pérdida que se pueda declarar
+ * (escribir los allows sin él concede lo que el origen niega). `--dry-run` no lanza: lo marca en `report.denyRefused` y es
+ * deriva. Lleva `refusals` (una entrada por tipo/relación y motivo). 500 y no 422: no es una pregunta del llamante sino
+ * el estado del despliegue (precedente `E_AUTHZ_MASS_RECONCILE_REFUSED`).
+ */
+export class DenyMigrationRefusedError extends Exception {
+    static status = 500;
+    static code = 'E_AUTHZ_DENY_MIGRATION_REFUSED';
+    refusals = [];
+}
+/**
+ * **`saveRelationsConfig` se NIEGA a guardar una config que encoge el alcance de un deny vivo** (lote RC · sublote (8);
+ * decisión §2026-10-15 (8) y firmas «(8 · panel)» 2026-10-22): la guarda de `database` con la propiedad «para todo deny
+ * vivo de `authz_relations`, alcance nuevo ⊇ alcance viejo» (`src/relations/deny_reach.ts`). Cero escrituras (ni la fila
+ * ni la versión del catálogo). Lleva `findings` (un hallazgo por tipo/relación: `shrunk`, `orphan` o `no-baseline` —sin
+ * línea base utilizable no se puede juzgar—, con su receta). Salidas con nombre, separadas: `{ establishBaseline: true }`
+ * levanta solo `no-baseline`; `{ allowDenyReachShrink: ['tipo#relación'] }` exime solo esos hallazgos. 500 y no 422 por
+ * precedente (`E_AUTHZ_DENY_MIGRATION_REFUSED`, `E_AUTHZ_MASS_RECONCILE_REFUSED`): no es una pregunta mal formada, es el
+ * estado del despliegue.
+ */
+export class DenyReachRefusedError extends Exception {
+    static status = 500;
+    static code = 'E_AUTHZ_DENY_REACH_REFUSED';
+    findings = [];
+}