@jantstack/adonis-authz 2.5.0-alpha.3 → 2.5.0-rc.1

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

@@ -132,8 +132,10 @@ export interface DriverCapabilities {
      * y MySQL, y es la promesa que el README hace.
      *
      * Con `false` (SQLite, que serializa bloqueando la BASE ENTERA) el juez
-     * solo puede exigir lo innegociable: nunca dos ganadores y el perdedor no
-     * escribe — su transacción puede morir con `SQLITE_BUSY`, que es un 503
+     * solo puede exigir lo innegociable: nunca dos ganadores con el MISMO owner
+     * (el del ancestro puede ensombrecer al del descendiente: los dos finales
+     * legales de 3G · Y1, también en esta cara desde la rotación 2) y el
+     * perdedor no escribe — su transacción puede morir con `SQLITE_BUSY`, que es un 503
      * legítimo. Declararlo `true` en un motor así convierte un flake en un
      * fallo; declararlo `false` en PG/MySQL deja pasar un mutante que
      * convierte la colisión en 503. Solo tiene casos en `level: '2.2'`.
@@ -200,6 +202,28 @@ 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;
+    /**
+     * **Toda decisión que combina concesión y deny se lee en UNA foto** (rotación 2 · cierre 3, L12;
+     * `AuthorizationDriverCapabilities.snapshotDecisions`). Opcional (regla D15: un harness publicado sin la clave sigue
+     * valiendo y cuenta como `false`). Solo tiene casos en `level: '2.1'` o superior (necesita `listDenies`). Con `true`
+     * el juez fija que el driver trae `readSnapshot`, que cada lectura pedida es EXACTAMENTE la del método homónimo (y lo
+     * no pedido no viene), que una pregunta mal formada es 422, y que el manager compone `effectivePermissions`,
+     * `authorizedScopes` y la policy de `defineScopedRole` con UNA llamada a `readSnapshot` y ninguna a
+     * `rolesInChain`/`listScopes`/`listDenies` (el espía cuenta solo las llamadas del MANAGER: lo que `readSnapshot` llame
+     * por dentro no cuenta). Con `false`, que el manager NO llama a `readSnapshot` —aunque el driver traiga un método con
+     * ese nombre: decide la capacidad— y compone como antes restando los denies (el hueco declarado de un driver sin la
+     * capacidad); sin `listDenies` la cara se queda en la declaración y su título lo dice. Que la foto sea de verdad UNA no lo puede
+     * observar un juez genérico sin meterse en el backend: en `database` lo fijan los casos de entrelazado forzado y la
+     * guardia `database.decision.snapshot` del paquete.
+     */
+    snapshotDecisions?: boolean;
 }
 export type ContractLevel = 'core' | '2.0' | '2.1' | '2.2';
 export interface DriverContractHarness {
@@ -280,4 +304,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
@@ -2961,7 +3017,7 @@ export function registerAuthorizationDriverContract(harness, api) {
                         // dejaba vivo un mutante que convertía la colisión en un 503.
                         const raceOfDefines = (serialized) => since('2.2', serialized
                             ? 'dos defineScopedRole del MISMO (slug, nivel) con owners de la misma cadena, en paralelo y con memos distintos: EXACTAMENTE uno gana y el perdedor es 422 E_AUTHZ_CATALOG_CONFLICT — la unicidad no es una carrera'
-                            : 'dos defineScopedRole del MISMO (slug, nivel) con owners de la misma cadena, en paralelo y con memos distintos: nunca dos ganadores y el perdedor no escribe (sin escrituras de catálogo serializadas su transacción puede morir con 503)', async ({ assert }) => {
+                            : 'dos defineScopedRole del MISMO (slug, nivel) con owners de la misma cadena, en paralelo y con memos distintos: nunca dos ganadores con el MISMO owner (el del ancestro puede ensombrecer al del descendiente) y el perdedor no escribe (sin escrituras de catálogo serializadas su transacción puede morir con 503)', async ({ assert }) => {
                             // 3D · M2 (auditor V2 🔴 A, reproducido en PG: los dos se insertaban
                             // porque el unique de la base es (slug, scope_type, owner_scope_key)
                             // y cada uno comprobaba la colisión contra SU foto del memo). Ahora
@@ -3004,11 +3060,21 @@ export function registerAuthorizationDriverContract(harness, api) {
                                 assert.oneOf(ok.length, [1, 2], `un ganador, o el del ancestro ensombreciendo al del descendiente (${estado})`);
                             }
                             else {
-                                // Sin serialización garantizada: nunca dos. Cuántos confirman
-                                // depende del motor — SQLite bloquea la base entera y el segundo
-                                // escritor puede recibir `SQLITE_BUSY`, un fallo de backend
-                                // legítimo (503) porque su transacción NO se aplicó.
-                                assert.isAtMost(ok.length, 1, `nunca dos ganadores (${estado})`);
+                                // Sin serialización garantizada cuántos confirman depende del
+                                // motor — SQLite bloquea la base entera y el segundo escritor
+                                // puede recibir `SQLITE_BUSY`, un fallo de backend legítimo (503)
+                                // porque su transacción NO se aplicó—, así que cero también vale.
+                                // Y los mismos DOS finales legales que la cara `true` (rotación 2 ·
+                                // cierre 2 · T-07): desde R2-05 el re-chequeo en la transacción
+                                // decide por AUTORIDAD, así que si el del descendiente confirma
+                                // mientras el del ancestro valida, el del ancestro ENTRA y lo
+                                // ensombrece (final 2 de 3G · Y1). Hasta alpha.4 aquí se afirmaba
+                                // «como mucho uno», que un backend sin el bloqueo de SQLite podía
+                                // poner rojo sin defecto (aserción flaky en el artefacto
+                                // publicado). Lo innegociable se afirma abajo igual que en la
+                                // cara `true`: nunca dos con el MISMO owner y, si son dos, el
+                                // extra es el del ANCESTRO.
+                                assert.isAtMost(ok.length, 2, `nunca dos ganadores con el MISMO owner (${estado})`);
                             }
                             for (const rejected of results.filter((r) => r.status === 'rejected')) {
                                 const error = rejected.reason;
@@ -3105,22 +3171,18 @@ export function registerAuthorizationDriverContract(harness, api) {
                             await insertRoleUnseen({ slug: 'sigiloso', scopeType: 'unit', owner: scopeKey(orgA) });
                             await rejectsWith(assert, () => here.defineScopedRole(admin, unitA1, { ...spec, slug: 'sigiloso' }), conflicto);
                             assert.lengthOf(await rowsNamed('sigiloso', 'unit'), 1, 'no se escribe a ciegas sobre lo que el memo no vio');
-                            // Y la rama del re-chequeo que NO se puede juzgar ahí dentro (3F ·
-                            // U3, tester 3E · §4.2): un homónimo cuyo owner no es global ni
-                            // ancestro-o-igual del owner pedido —una unit HERMANA— no se
-                            // clasifica sin resolver su cadena, y resolverla con el cerrojo del
-                            // catálogo sostenido sería un abrazo mortal con un pool de 1. Se
-                            // rechaza igual, con el 422 que pide REINTENTAR, y no escribe.
-                            // Hasta 3F esa rama solo la observaba la carrera de arriba, y solo
-                            // en el harness cuyo árbol SQL ensancha la ventana: aquí va EN
-                            // SERIE (el memo se recalienta primero, así que la fila nueva le es
-                            // invisible y solo la relectura de la BASE la ve).
+                            // Y la rama del re-chequeo de un owner que NO es global ni ancestro-o-igual del owner pedido —una unit
+                            // HERMANA— (3F · U3, tester 3E · §4.2; volteada en la rotación 2 de M4 · R2-05). Hasta 2.5.0-alpha.4 se
+                            // rechazaba con un 422 «reintenta» que NOMBRABA el owner del hermano (otro tenant) y la colisión era falsa:
+                            // dos hermanos pueden compartir slug. Ahora se juzga con la MISMA regla de autoridad que la comprobación
+                            // previa y entra. EN SERIE: el memo se recalienta primero, así que la fila nueva le es invisible y solo la
+                            // relectura de la BASE la ve.
                             const unitA2 = await unitUnder(tree, orgA);
                             assert.deepEqual(await here.listRoles(admin, orgA), ['org-admin'], 'memo recalentado tras el fallo anterior');
                             await insertRoleUnseen({ slug: 'lateral', scopeType: 'unit', owner: scopeKey(unitA2) });
-                            const cambio = await rejectsWith(assert, () => here.defineScopedRole(admin, unitA1, { ...spec, slug: 'lateral' }), conflicto);
-                            assert.include(String(cambio?.message), 'El catálogo cambió mientras se validaba');
-                            assert.lengthOf(await rowsNamed('lateral', 'unit'), 1, 'el 422 genérico tampoco escribe a ciegas');
+                            const lateral = await here.defineScopedRole(admin, unitA1, { ...spec, slug: 'lateral' });
+                            assert.equal(lateral.owner, scopeKey(unitA1), 'el homónimo de un HERMANO no es colisión: entra');
+                            assert.lengthOf(await rowsNamed('lateral', 'unit'), 2, 'los dos hermanos tienen su lateral@unit');
                         });
                         caseFor('serializedCatalogWrites', {
                             whenTrue: () => raceOfDefines(true),
@@ -3738,6 +3800,183 @@ 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);
+                });
+            },
+        });
+        // ── Rotación 2 · cierre 3 · `snapshotDecisions` (regla D15, linaje L12) ─────────
+        // Una decisión que combina lo que el holder TIENE con lo que tiene DENEGADO, leída en dos métodos del puerto sin
+        // foto común, puede responder lo que ningún estado real responde (un offboarding entre las dos lecturas). La
+        // capacidad dice que el driver lee las dos mitades de una vez; lo que el juez observa es el MÉTODO (`readSnapshot`):
+        // su respuesta es la de los métodos homónimos, y el manager lo usa en vez de componer.
+        const snapshotSeed = async () => {
+            const alice = subject();
+            const orgA = await orgUnder(tree, APP_SCOPE);
+            const unitA1 = await unitUnder(tree, orgA);
+            await driver.grant(alice, 'org-editor', orgA);
+            await driver.grant(alice, 'unit-editor', unitA1);
+            await driver.grant(alice, 'viewer', APP_SCOPE);
+            await driver.deny(alice, 'docs:read', unitA1);
+            await driver.deny(alice, 'billing:read', orgA);
+            return { alice, orgA, unitA1 };
+        };
+        const canonical = (items) => items.map((item) => JSON.stringify(item)).sort();
+        /**
+         * El espía del par (rotación 2 · cierre 3b, tester 🟡 6): cuenta SOLO las llamadas que hace el MANAGER al driver. Cada
+         * método se reenvía con `this` = el driver de verdad (no el proxy), así que lo que un `readSnapshot` llame por dentro
+         * (`this.rolesInChain()` dentro de una transacción REPEATABLE READ, p. ej.) no se cuenta: el juez fija el contrato
+         * (UNA llamada del manager), no la implementación.
+         */
+        const watchManagerCalls = (target) => {
+            const touched = [];
+            // El proxy va sobre un objeto VACÍO (no sobre el driver): un driver congelado o con métodos no configurables no
+            // choca con las invariantes de `Proxy`, y todo se lee del driver de verdad. Una VISTA que devuelve el driver
+            // (`withChainResolver`, `withClock`: el manager las pide por request) se vigila igual, con la misma cuenta.
+            const watch = (real) => new Proxy({}, {
+                get: (_shell, prop) => {
+                    const value = Reflect.get(real, prop, real);
+                    if (typeof value === 'function' && typeof prop === 'string') {
+                        return (...args) => {
+                            touched.push(prop);
+                            const out = value.apply(real, args);
+                            const isView = out !== null && typeof out === 'object' && typeof out.then !== 'function' && typeof out.authorize === 'function';
+                            return isView ? watch(out) : out;
+                        };
+                    }
+                    return value;
+                },
+                has: (_shell, prop) => prop in real,
+            });
+            const watched = watch(target);
+            const reads = () => touched.filter((name) => ['readSnapshot', 'rolesInChain', 'listScopes', 'listDenies', 'listRoles'].includes(name));
+            return { watched, touched, reads };
+        };
+        /**
+         * La parte de DELEGACIÓN de las dos caras (rotación 2 · cierre 3c, A/J1 del auditor y del tester): la policy de
+         * `defineScopedRole` solo se juzga si el harness declara `purgeRole: true`. Sin `purgeRole` el manager no delega
+         * (`defineScopedRole` es 500 `E_AUTHZ_UNSUPPORTED` ANTES de la policy, 3E · P4), y `purgeRole` es un par de `'2.2'`:
+         * un tercero `'2.1'` con `listDenies` y sin `purgeRole` —legítimo, D15— salía ROJO con un caso nuevo. Decide la
+         * DECLARACIÓN del harness, no la presencia del método, por el patrón del juez (como `listDenies` aquí mismo): una
+         * declaración `true` solo es posible en `'2.2'` (en `'2.1'` el juez lanza al registrar un `true` sin caso) y ahí la
+         * juzga su propio par —método presente y purga total, o ausente y 500—, mientras que un método presente en un
+         * harness `'2.1'` no lo juzga nadie. El título de cada cara dice cuál de las dos se registró.
+         */
+        const snapshotDelegation = harness.capabilities.purgeRole === true;
+        caseFor('snapshotDecisions', {
+            whenTrue: () => {
+                since('2.1', 'snapshotDecisions:true · readSnapshot responde cada lectura pedida EXACTAMENTE como el método homónimo (rolesInChain, listScopes, listDenies), lo no pedido no viene, un permiso fuera del catálogo da listScopes [] y una pregunta mal formada es 422', async ({ assert, }) => {
+                    assert.typeOf(driver.readSnapshot, 'function', 'snapshotDecisions: true exige readSnapshot en el puerto');
+                    assert.strictEqual(driver.capabilities?.snapshotDecisions, true, 'el harness declara snapshotDecisions: true y el driver no');
+                    assert.strictEqual((await managerOver().capabilities()).snapshotDecisions, true);
+                    const { alice, unitA1 } = await snapshotSeed();
+                    const chain = (await tree.chainOf(unitA1));
+                    const all = await driver.readSnapshot(alice, { rolesInChain: chain, listScopes: 'docs:write', listDenies: true });
+                    assert.sameMembers(Object.keys(all), ['rolesInChain', 'listScopes', 'listDenies']);
+                    assert.deepEqual(canonical(all.rolesInChain), canonical(await driver.rolesInChain(alice, chain)));
+                    assert.deepEqual(canonical(all.listScopes), canonical(await driver.listScopes(alice, 'docs:write')));
+                    assert.deepEqual(canonical(all.listDenies), canonical(await driver.listDenies(alice)));
+                    assert.lengthOf(all.listDenies, 2);
+                    assert.isAbove(all.rolesInChain.length, 0);
+                    // Con el deny de docs:read en la unit, listScopes de docs:read no lista la unit (ni lo que bloquea).
+                    const reads = await driver.readSnapshot(alice, { listScopes: 'docs:read' });
+                    assert.deepEqual(Object.keys(reads), ['listScopes'], 'lo no pedido no viene');
+                    assert.deepEqual(canonical(reads.listScopes), canonical(await driver.listScopes(alice, 'docs:read')));
+                    assert.deepEqual(await driver.readSnapshot(alice, { listScopes: 'no:existe' }), { listScopes: [] });
+                    for (const bad of [{}, { foo: true }, { listDenies: false }, { rolesInChain: 'x' }, null]) {
+                        await rejectsWith(assert, () => driver.readSnapshot(alice, bad), { status: 422, code: 'E_AUTHZ_INVALID_IDENTITY' });
+                    }
+                });
+                since('2.1', snapshotDelegation
+                    ? 'snapshotDecisions:true · el manager compone effectivePermissions, authorizedScopes y la policy de defineScopedRole con UNA llamada a readSnapshot y CERO a rolesInChain/listScopes/listDenies, con el mismo resultado'
+                    : 'snapshotDecisions:true · el manager compone effectivePermissions y authorizedScopes con UNA llamada a readSnapshot y CERO a rolesInChain/listScopes/listDenies, con el mismo resultado (sin purgeRole: el manager no delega y la policy de defineScopedRole no se juzga aquí)', async ({ assert, }) => {
+                    const { alice, orgA, unitA1 } = await snapshotSeed();
+                    const { watched: spied, touched, reads } = watchManagerCalls(driver);
+                    const watched = managerOver({ delegablePermissions: ['docs:read', 'docs:write'] }, spied);
+                    assert.sameMembers(await watched.effectivePermissions(alice, unitA1), ['docs:write']);
+                    assert.deepEqual(reads(), ['readSnapshot']);
+                    touched.length = 0;
+                    // docs:write: org-editor en la org y unit-editor en la unit (viewer en app solo da docs:read) ⇒ la unit.
+                    assert.deepEqual(await watched.authorizedScopes(alice, 'docs:write', 'unit'), { kind: 'some', scopes: [unitA1] });
+                    assert.deepEqual(reads(), ['readSnapshot']);
+                    touched.length = 0;
+                    assert.deepEqual(await watched.authorizedScopes(alice, 'docs:read', 'unit'), { kind: 'all', excludedSubtrees: [{ scope: unitA1, includesDescendants: true }] });
+                    assert.deepEqual(reads(), ['readSnapshot']);
+                    if (!snapshotDelegation)
+                        return;
+                    assert.typeOf(driver.purgeRole, 'function', 'el harness declara purgeRole: true y el puerto no lo trae');
+                    // La policy de delegación: el actor tiene docs:read DENEGADO en la unit (owner) ⇒ 422 con UNA foto.
+                    const admin = subject();
+                    await driver.grant(admin, 'org-admin', orgA);
+                    await driver.deny(admin, 'docs:read', orgA);
+                    touched.length = 0;
+                    await rejectsWith(assert, () => watched.defineScopedRole(admin, orgA, { slug: 'lead', scopeType: 'unit', rank: 10, permissions: ['docs:read'] }), {
+                        status: 422,
+                        code: 'E_AUTHZ_PERMISSION_NOT_DELEGABLE',
+                    });
+                    assert.deepEqual(reads(), ['readSnapshot']);
+                });
+            },
+            whenFalse: () => {
+                // Rotación 2 · cierre 3b (H3 del auditor): el manager decide por la CAPACIDAD, no por la presencia del método, así
+                // que esta cara NO exige que el puerto no traiga `readSnapshot` (un tercero puede tener un método con ese nombre
+                // para otra cosa): exige que el manager NO lo llame. Sin `listDenies` no hay composición que juzgar y la cara
+                // se queda en la declaración —lo dice su título (tester 🟡 6)—.
+                if (!harness.capabilities.listDenies) {
+                    since('2.1', 'snapshotDecisions:false · (sin listDenies: solo la declaración) authorization.capabilities().snapshotDecisions es false y el driver no declara true; sin listDenies el manager no compone ninguna decisión con deny que juzgar', async ({ assert, }) => {
+                        assert.notStrictEqual(driver.capabilities?.snapshotDecisions, true, 'el harness declara snapshotDecisions: false y el driver declara true');
+                        assert.strictEqual((await managerOver().capabilities()).snapshotDecisions, false);
+                    });
+                    return;
+                }
+                since('2.1', snapshotDelegation
+                    ? 'snapshotDecisions:false · authorization.capabilities().snapshotDecisions es false y el manager compone effectivePermissions, authorizedScopes y la policy de defineScopedRole con rolesInChain/listScopes + listDenies SIN llamar a readSnapshot (aunque el driver traiga un método con ese nombre: decide la capacidad), restando los denies (el hueco DECLARADO de un driver sin la capacidad)'
+                    : 'snapshotDecisions:false · authorization.capabilities().snapshotDecisions es false y el manager compone effectivePermissions y authorizedScopes con rolesInChain/listScopes + listDenies SIN llamar a readSnapshot (aunque el driver traiga un método con ese nombre: decide la capacidad), restando los denies (el hueco DECLARADO de un driver sin la capacidad; sin purgeRole: el manager no delega y la policy de defineScopedRole no se juzga aquí)', async ({ assert, }) => {
+                    assert.notStrictEqual(driver.capabilities?.snapshotDecisions, true, 'el harness declara snapshotDecisions: false y el driver declara true');
+                    assert.strictEqual((await managerOver().capabilities()).snapshotDecisions, false);
+                    const { alice, orgA, unitA1 } = await snapshotSeed();
+                    const { watched: spied, touched, reads } = watchManagerCalls(driver);
+                    const watched = managerOver({ delegablePermissions: ['docs:read', 'docs:write'] }, spied);
+                    assert.sameMembers(await watched.effectivePermissions(alice, unitA1), ['docs:write'], 'el deny de docs:read en la unit se resta');
+                    assert.include(reads(), 'listDenies');
+                    assert.notInclude(reads(), 'readSnapshot');
+                    touched.length = 0;
+                    assert.deepEqual(await watched.authorizedScopes(alice, 'docs:read', 'unit'), { kind: 'all', excludedSubtrees: [{ scope: unitA1, includesDescendants: true }] });
+                    assert.deepEqual(await watched.authorizedScopes(alice, 'docs:write', 'unit'), { kind: 'some', scopes: [unitA1] });
+                    assert.include(reads(), 'listDenies');
+                    assert.notInclude(reads(), 'readSnapshot');
+                    if (!snapshotDelegation)
+                        return;
+                    assert.typeOf(driver.purgeRole, 'function', 'el harness declara purgeRole: true y el puerto no lo trae');
+                    const admin = subject();
+                    await driver.grant(admin, 'org-admin', orgA);
+                    await driver.deny(admin, 'docs:read', orgA);
+                    touched.length = 0;
+                    await rejectsWith(assert, () => watched.defineScopedRole(admin, orgA, { slug: 'lead', scopeType: 'unit', rank: 10, permissions: ['docs:read'] }), {
+                        status: 422,
+                        code: 'E_AUTHZ_PERMISSION_NOT_DELEGABLE',
+                    });
+                    assert.include(reads(), 'listDenies');
+                    assert.notInclude(reads(), 'readSnapshot');
+                });
+            },
+        });
         // ── 3b-2e · E2 · `roleInheritanceNative` ─────────────────────────────
         caseFor('roleInheritanceNative', {
             whenFalse: () => {
@@ -3868,4 +4107,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

package/build/src/testing/main.js

@@ -13,4 +13,3 @@ export { runRelationsDriverContract, registerRelationsDriverContract, makeRelati
 export { createTestClock } from './test_clock.js';
 export { runRelationsReconcileContract, registerRelationsReconcileContract, } from './relations_reconcile_contract.js';
 export { runScopeOutboxContract, registerScopeOutboxContract, makeScopeOutbox, SCOPE_OUTBOX_CAPABILITY_KEYS, } from './scope_outbox_contract.js';
-//# sourceMappingURL=main.js.map

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

@@ -290,4 +290,3 @@ export declare function runMigrationDirection(harness: MigrationContractHarness,
  */
 export declare function runMigrationContract(harness: MigrationContractHarness): void;
 export declare function registerMigrationContract(harness: MigrationContractHarness, api: ContractTestApi): void;
-//# sourceMappingURL=migration_contract.d.ts.map