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

package/build/src/scope_outbox.js

@@ -85,7 +85,9 @@ const MYSQL_LOCK_NAME_MAX = 64;
  * coincidieran en los primeros 64 COMPARTÍAN lease y se excluían para siempre
  * — y el modo de fallo era `busy: true`, que no lanza: el relay de uno de los
  * dos no corría nunca, en silencio. Desde alpha.5 el nombre es un hash
- * ESTABLE del nombre completo (`current`, 59 caracteres), que no colisiona.
+ * ESTABLE del nombre completo (`current`, 59 caracteres), que no colisiona entre
+ * TABLAS — entre BASES del mismo servidor sí: el «nombre completo» no llevaba la
+ * base (rotación 2 · R2-01, abajo).
  *
  * **Transición**: `sqlScopeOutbox.acquire()` toma el lock viejo (`legacy`, el
  * recortado) Y el nuevo durante alpha.5, porque en un rolling deploy un
@@ -114,13 +116,47 @@ export const SCOPE_OUTBOX_LEGACY_LOCK_UNTIL = '2.4.0-alpha.6';
  * desde ≤ alpha.4 en MySQL exige parada completa del relay, no despliegue rodante.
  */
 export const SCOPE_OUTBOX_TAKES_LEGACY_LOCK = false;
-export function scopeOutboxLockNames(connection, table) {
+/**
+ * **La identidad de la BASE en el nombre del lease** (rotación 2 de M4 · R2-01, decisión del dueño 2026-10-22 (1)).
+ * `GET_LOCK` es un cerrojo de SERVIDOR, y hasta 2.5.0-alpha.4 el nombre era `<conexión>:<tabla>`: dos despliegues en
+ * BASES distintas del mismo MySQL con la conexión por defecto de Adonis y la tabla del stub calculaban el MISMO nombre y
+ * se excluían (`busy`, exit 0) — el síntoma que R6 de alpha.5 daba por cerrado nunca lo estuvo, porque el «nombre
+ * completo» no llevaba la base. Desde este cierre `current` lleva la base que la PROPIA conexión que sostiene el lease
+ * lee con `DATABASE()` (no la del config: es la base contra la que esa sesión resuelve la tabla sin cualificar, o sea la
+ * identidad real de la cola; un alias de host o una URL distinta que apunte a la misma base dan el mismo nombre).
+ *
+ * En MINÚSCULAS a propósito: los dos errores posibles no cuestan lo mismo. Fundir `App` y `app` (dos bases distintas en
+ * un servidor sensible a mayúsculas) solo hace que esos dos despliegues compartan lease —vivacidad, `busy`—; separar la
+ * misma base escrita de dos formas por dos procesos del MISMO despliegue serían dos escritores —seguridad—. Se elige el
+ * error barato. `DATABASE()` `NULL` (sesión sin base por defecto: la tabla tiene que ir cualificada) entra como cadena
+ * vacía: los procesos de ese despliegue siguen calculando el mismo nombre.
+ *
+ * Los tres nombres: `legacy` (el recortado a 64 de ≤ alpha.4, retirado en alpha.7, se conserva para el caso que lo
+ * fija), `unscoped` (el sha1 sin base de 2.4.0-alpha.5..2.5.0-alpha.4) y `current` (el sha1 con base). Sin `database`
+ * —quien no ha abierto conexión: los casos de identidad pura— `current` es `unscoped`.
+ */
+export function scopeOutboxLockNames(connection, table, database) {
     const full = `authz_scope_outbox:${connection ?? 'default'}:${table}`;
+    const sha = (value) => `authz_scope_outbox:${createHash('sha1').update(value).digest('hex')}`;
+    const unscoped = sha(full);
     return {
         legacy: full.slice(0, MYSQL_LOCK_NAME_MAX),
-        current: `authz_scope_outbox:${createHash('sha1').update(full).digest('hex')}`,
+        unscoped,
+        current: database === undefined ? unscoped : sha(`${full}@db:${String(database ?? '').toLowerCase()}`),
     };
 }
+/**
+ * **La transición del nombre sin base** (rotación 2 · R2-01, firmada: «como alpha.5»). En 2.5.x `acquire()` toma el
+ * nombre VIEJO (`unscoped`, el de 2.4.0-alpha.5..2.5.0-alpha.4) y DESPUÉS el nuevo (`current`, con la base), y suelta
+ * los dos: en un despliegue rodante un proceso de alpha.4 solo conoce el viejo, y los dos tienen que seguir
+ * excluyéndose. **El precio, declarado**: mientras se tome el viejo, dos despliegues en bases distintas del mismo
+ * servidor SIGUEN compartiéndolo — R2-01 queda abierto en 2.5.x y se cierra al retirarlo en 2.6 (README «Limits»,
+ * `relay.mysql-unscoped-lease`; backlog 2.6). Atado a la versión como en alpha.6: `tests/rotacion2_cierre.spec.ts` exige
+ * que valga exactamente «`package.json` < `SCOPE_OUTBOX_UNSCOPED_LOCK_RETIRED_IN`» (`2.6.0-alpha.0`: toda 2.6, sus
+ * prereleases incluidas), así que el bump a 2.6 pone la suite en rojo hasta retirarlo.
+ */
+export const SCOPE_OUTBOX_UNSCOPED_LOCK_RETIRED_IN = '2.6.0-alpha.0';
+export const SCOPE_OUTBOX_TAKES_UNSCOPED_LOCK = true;
 /** Hash de 32 bits con signo (lo que acepta `pg_try_advisory_xact_lock`). */
 function hash32(value) {
     let hash = 0;
@@ -374,7 +410,6 @@ export function sqlScopeOutbox(options = {}, database = db) {
          * pasada, que es el precio de que dos pasadas no se pisen.
          */
         async acquire() {
-            const names = scopeOutboxLockNames(connection, table);
             /** El nombre del cerrojo de PROCESO y del advisory de PG: el completo (allí no hay recorte). */
             const name = `authz_scope_outbox:${connection ?? 'default'}:${table}`;
             const client = lockClientOf(database, connection);
@@ -397,11 +432,17 @@ export function sqlScopeOutbox(options = {}, database = db) {
                     return { release: async () => void (await trx.rollback()) };
                 }
                 if (dialect.startsWith('mysql')) {
-                    // **Los DOS locks** (alpha.5 · R6, transición): el nuevo —hash
-                    // estable, sin colisión— y el viejo —el recortado a 64 de alpha.4—,
-                    // para que un rolling deploy con las dos versiones siga siendo
-                    // escritor único. Si cualquiera de los dos falla, se sueltan los que
-                    // se tomaron y es `busy`. El viejo se retira en 2.5.
+                    // **La base en el nombre** (rotación 2 · R2-01): la lee la MISMA sesión que va a sostener el cerrojo.
+                    const database = firstValue(await query('acquire', () => trx.rawQuery('select database() as db')), 'db');
+                    const names = scopeOutboxLockNames(connection, table, database === null || database === undefined ? null : String(database));
+                    // **Transición** (2.5.x): el VIEJO (sin base) primero y el NUEVO después; si cualquiera falla se sueltan los
+                    // ya tomados y es `busy`. Un proceso de alpha.4 solo toma el viejo: los dos siguen excluyéndose.
+                    // (El recortado de ≤ alpha.4 sigue retirado: `SCOPE_OUTBOX_TAKES_LEGACY_LOCK` es `false` desde alpha.7.)
+                    const order = [
+                        ...(SCOPE_OUTBOX_TAKES_UNSCOPED_LOCK ? [names.unscoped] : []),
+                        names.current,
+                        ...(SCOPE_OUTBOX_TAKES_LEGACY_LOCK ? [names.legacy] : []),
+                    ];
                     const taken = [];
                     const take = async (lockName) => {
                         const result = await query('acquire', () => trx.rawQuery('select get_lock(?, 0) as taken', [lockName]));
@@ -410,18 +451,38 @@ export function sqlScopeOutbox(options = {}, database = db) {
                             taken.push(lockName);
                         return ok;
                     };
+                    // `GET_LOCK` es de SESIÓN, no de la transacción: revertir no lo suelta, y una conexión que vuelve al pool
+                    // con el cerrojo puesto deja la cola `busy` para siempre. Se sueltan TODOS los tomados (en orden inverso)
+                    // aunque uno falle, y la transacción se revierte al final pase lo que pase.
+                    let released = false;
                     const releaseAll = async () => {
-                        try {
-                            for (const lockName of taken.reverse())
+                        if (released)
+                            return;
+                        released = true;
+                        let failure;
+                        for (const lockName of [...taken].reverse()) {
+                            try {
                                 await trx.rawQuery('select release_lock(?)', [lockName]);
+                            }
+                            catch (error) {
+                                failure ??= error;
+                            }
                         }
-                        finally {
-                            await trx.rollback();
-                        }
+                        await trx.rollback();
+                        if (failure !== undefined)
+                            throw failure;
                     };
-                    if (!(await take(names.current)) || (SCOPE_OUTBOX_TAKES_LEGACY_LOCK && !(await take(names.legacy)))) {
-                        await releaseAll();
-                        return null;
+                    try {
+                        for (const lockName of order) {
+                            if (!(await take(lockName))) {
+                                await releaseAll();
+                                return null;
+                            }
+                        }
+                    }
+                    catch (error) {
+                        await releaseAll().catch(() => { });
+                        throw error;
                     }
                     return { release: releaseAll };
                 }

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'`.
@@ -207,6 +209,21 @@ export interface DriverCapabilities {
      * 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 {

package/build/src/testing/contract.js

@@ -3017,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
@@ -3060,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;
@@ -3161,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),
@@ -3815,6 +3821,162 @@ export function registerAuthorizationDriverContract(harness, api) {
                 });
             },
         });
+        // ── 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: () => {

package/build/src/types.d.ts

@@ -343,6 +343,38 @@ export interface AuthorizationDriverCapabilities {
      * apaga casos. Par de caras en `runAuthorizationDriverContract`.
      */
     experimental?: boolean;
+    /**
+     * **Toda DECISIÓN del driver que combina concesión y deny se lee en UNA foto de sus hechos** (rotación 2 · cierre 3;
+     * linaje L12 «lector rasgado»). **Opcional y normalizada a `false`** (regla D15). Con `true` el driver promete:
+     * `authorize` (y cada posición de `authorizeMany`) y `listScopes` leen sus concesiones y sus denies de UN mismo estado
+     * —una escritura que cae «entre» no puede dar una respuesta que ningún estado real daba—, y trae `readSnapshot` para
+     * que el manager lea en una foto lo que compone con dos métodos del puerto (`effectivePermissions`, `authorizedScopes`,
+     * la policy de `defineScopedRole`/`updateScopedRole`). Lo que NO promete: la cadena del consumidor (`resolveChain`) y
+     * el catálogo se leen fuera de la foto (README «Limits», fila «Torn read»: «cadena frente a hechos»). `database` =
+     * `true` (UNA sentencia, `readFoto`); el manager usa `readSnapshot` solo con esta capacidad en `true`; `openfga` no la declara (`false`: su `Check` lee ramas del modelo por separado,
+     * la excepción declarada del invariante 2) y el manager compone como antes. Par de caras en
+     * `runAuthorizationDriverContract`.
+     */
+    snapshotDecisions?: boolean;
+}
+/**
+ * Lo que `readSnapshot` lee en UNA foto (rotación 2 · cierre 3). Cada clave pedida es la pregunta del método homónimo
+ * del puerto para el mismo holder: `rolesInChain` con esa cadena (ya resuelta), `listScopes` con ese permiso y
+ * `listDenies: true` = `listDenies(subject)` sin scope. Al menos una.
+ */
+export interface SnapshotReads {
+    rolesInChain?: ScopeRef[];
+    listScopes?: string;
+    listDenies?: boolean;
+}
+/** La respuesta de `readSnapshot`: EXACTAMENTE la del método homónimo para cada clave pedida, todas del mismo estado; lo no pedido no viene. */
+export interface SnapshotAnswer {
+    rolesInChain?: Array<{
+        scope: ScopeRef;
+        role: CatalogRoleRef;
+    }>;
+    listScopes?: ScopeRef[];
+    listDenies?: DenyRef[];
 }
 /**
  * Las claves de `AuthorizationDriverCapabilities`, LITERALES (2.4.0-alpha.4):
@@ -619,6 +651,23 @@ export interface AuthorizationDriver {
         scope: ScopeRef;
         role: CatalogRoleRef;
     }>>;
+    /**
+     * **Varias lecturas del puerto en UNA foto de los hechos** (rotación 2 · cierre 3, L12). Opcional (con su capacidad
+     * `snapshotDecisions`, regla D15): cada clave pedida de `reads` se responde EXACTAMENTE como el método homónimo
+     * (`rolesInChain(subject, chain)`, `listScopes(subject, permission)`, `listDenies(subject)`), y todas desde el MISMO
+     * estado de concesiones y denies. Lo usa el manager para las decisiones que compone con dos métodos del puerto:
+     * `effectivePermissions` y la policy de delegación (`rolesInChain` + `listDenies`) y `authorizedScopes`
+     * (`listScopes` + `listDenies`). El manager lo llama SOLO si el driver declara `snapshotDecisions: true` (decide la
+     * capacidad, no la presencia del método; rotación 2 · cierre 3b): declarar `true` sin traerlo es 500 `E_AUTHZ_CONFIG`
+     * —en la PRIMERA decisión compuesta, no al resolver el driver (cierre 3c, J3), nombrando la clave y la clase del
+     * driver—, y sin la capacidad el manager compone como antes —dos lecturas sin foto común, el hueco DECLARADO de un driver sin
+     * la capacidad— aunque exista un método con este nombre.
+     *
+     * `reads` mal formado (vacío, una clave desconocida, una cadena que no es array, un permiso que no es string,
+     * `listDenies` que no es `true`) es 422 `E_AUTHZ_INVALID_IDENTITY`; un permiso fuera del catálogo responde
+     * `listScopes: []`, como el método suelto.
+     */
+    readSnapshot?(subject: SubjectRef, reads: SnapshotReads): Promise<SnapshotAnswer>;
 }
 /**
  * Un subárbol excluido de un `all` (2.1, B3; tipo nominal desde 2D · F10):

package/build/src/types.js

@@ -59,6 +59,8 @@ export const AUTHORIZATION_DRIVER_CAPABILITY_KEYS = Object.freeze([
     'transactionalWrites',
     // Estrategia 2.5.0 · firma 4 (D15): opcional, normalizada a `false`.
     'experimental',
+    // Rotación 2 · cierre 3 (D15, L12): opcional, normalizada a `false`; `database` declara `true`.
+    'snapshotDecisions',
 ]);
 /**
  * **La copia CONGELADA y NORMALIZADA que publica `authorization.capabilities()`**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jantstack/adonis-authz",
-  "version": "2.5.0-alpha.4",
+  "version": "2.5.0-rc.1",
   "description": "Driver-based authorization engine for AdonisJS + Lucid: hierarchical scopes with downward inheritance, explicit denies, expiring assignments and polymorphic holders. Ships a self-contained database driver and an OpenFGA driver, both judged by the same executable contract suite.",
   "type": "module",
   "license": "MIT",