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

package/build/src/drivers/database_driver.js

@@ -1,7 +1,7 @@
 import db from '@adonisjs/lucid/services/db';
 import { v7 as uuidv7 } from 'uuid';
 import { APP_SCOPE_TYPE } from '../types.js';
-import { assertCatalogUuid, assertIdentity, assertScope, chainKeysFrom, normalizeRoleQuery } from '../identity.js';
+import { assertCatalogUuid, assertIdentity, assertScope, assertSnapshotReads, chainKeysFrom, normalizeRoleQuery } from '../identity.js';
 import { resolveGrantExpiry, sameInstant } from '../expiry.js';
 import { AuthorizationBackendError, AuthorizationConfigError, AuthorizationInternalError, InvalidIdentityError, MassReconcileRefusedError, ReconcileTooLargeError, RoleNotVisibleError, UnknownPermissionError, UnknownRoleError, UnsupportedOperationError, WriteConflictError, } from '../errors.js';
 import { RECONCILE_MAX_DETAILS, emptyReconcilePhases, reconcileBatchSize, reconcileMaxTuples, sumReconcilePhases, } from '../reconcile.js';
@@ -243,6 +243,12 @@ export function whereScopeIn(query, column, scopes, intent) {
         }
     });
 }
+/**
+ * Las partes posibles de la FOTO de una decisión (rotación 2 · cierre 3, `readFoto`): `grant` = asignaciones que
+ * conceden UN permiso (con el vínculo rol→permiso por `JOIN`), `role` = asignaciones sin filtrar por permiso
+ * (`rolesInChain`) y `deny` = denies. El literal de `foto_kind` sale de esta tabla CERRADA, jamás de un dato.
+ */
+const FOTO_KINDS = { grant: 'grant', deny: 'deny', role: 'role' };
 export const DEFAULT_TIMEOUT_MS = 5_000;
 /**
  * Driver `database`: motor de autorización propio sobre las tablas `authz_*`.
@@ -262,7 +268,7 @@ export class DatabaseAuthorizationDriver {
     /**
      * Lo que este driver declara (3b-2e · E2). El árbol es del consumidor
      * (`resolveChain`), así que no hay hechos de jerarquía ni deriva que
-     * mitigar; `authorize` son varias consultas SQL; la membresía la resuelve
+     * mitigar; `authorize` es UNA consulta SQL de hechos (la foto, rotación 2 · cierre 3) más el catálogo y el árbol, no un `Check`; la membresía la resuelve
      * el propio SQL contra la cadena que le pasan; los `list*` no enumeran
      * herencia (invariante 7); y `purgeRole` está implementado en una
      * transacción.
@@ -330,6 +336,9 @@ export class DatabaseAuthorizationDriver {
             // Estrategia 2.5.0 · firma 4 (D15): `false` EXPLÍCITO — `database` es el driver ESTABLE de 2.5.0 (el experimental
             // es `openfga`). Explícito para que la copia de `authorization.capabilities()` y este objeto digan lo mismo.
             experimental: false,
+            // Rotación 2 · cierre 3 (D15, L12): toda decisión que combina concesión y deny se lee en UNA sentencia
+            // (`readFoto`), y `readSnapshot` da esa foto a las composiciones del manager.
+            snapshotDecisions: true,
         });
         assertCatalogOptions('DatabaseAuthorizationDriver', options);
         this.catalog =
@@ -407,6 +416,54 @@ export class DatabaseAuthorizationDriver {
         const rows = await this.sql(operation, () => fn().limit(1));
         return rows[0] ?? null;
     }
+    /**
+     * **La FOTO de una decisión: el punto de paso ÚNICO** (rotación 2 · cierre 3; 4.ª aparición del linaje L12 «lector
+     * rasgado», la primera en `database`). Propiedad universal: *toda DECISIÓN de `database` que combina concesión y deny
+     * se lee en UNA foto*. Hasta aquí `authorize` leía los denies y las asignaciones en DOS sentencias, y una escritura
+     * que caía entre las dos daba una respuesta que NINGÚN estado real daba (un `deny` y después un `grant` ⇒ `true` una
+     * vez; repro `.claude/reproducciones/database-authorize-rasgado.spec.ts`).
+     *
+     * La foto es **UNA sentencia**: las partes van unidas con `UNION ALL` y cada fila dice de qué parte es
+     * (`foto_kind`). Una sentencia ve UN estado en los tres motores y en cualquier aislamiento —PostgreSQL toma la foto
+     * por SENTENCIA en READ COMMITTED, InnoDB una vista de lectura por sentencia, SQLite una transacción de lectura
+     * implícita—, así que no hace falta abrir una transacción REPEATABLE READ como `withSourceSnapshot` del reconcile:
+     * eso costaría BEGIN/COMMIT por pregunta en el camino caliente y, con un pool de 1 (`:memory:`), retendría la única
+     * conexión mientras el catálogo o un `resolveChain` SQL del consumidor esperan otra. Elegido por eso: una ida y
+     * vuelta (antes dos), sin conexión retenida y sin nivel por motor.
+     *
+     * Lo que va DENTRO de la foto: los HECHOS (asignaciones —con el vínculo rol→permiso por `JOIN` cuando la parte lo
+     * filtra— y denies). Lo que va FUERA, antes o después: el catálogo (memo contrastado con la versión compartida,
+     * invariante 14) y la cadena del consumidor (`resolveChain`). «Cadena frente a hechos» (un `scopes.moved` entre el
+     * `resolveChain` y la foto) depende del resolutor del consumidor y está DECLARADO en README «Limits» (fila «Torn
+     * read»), no se arregla aquí.
+     *
+     * Columnas comunes de cada parte: `foto_kind`, `foto_scope_type`, `foto_scope_uuid`, `foto_role` y
+     * `foto_permission` (`null` en la parte que no la tiene). Solo SQL estándar del query builder (M6). Una sola parte
+     * es una sola `SELECT`, sin `UNION`. La guardia `database.decision.snapshot` cuenta las sentencias que tocan
+     * `authz_assignments`/`authz_denies` por decisión: con dos, rojo.
+     */
+    async readFoto(operation, parts) {
+        const foto = { grant: [], deny: [], role: [] };
+        const live = parts.filter((part) => part !== null);
+        if (live.length === 0)
+            return foto;
+        const selects = live.map((part) => part.query.select(db.raw(`'${FOTO_KINDS[part.kind]}' as foto_kind`), `${part.scope}_type as foto_scope_type`, `${part.scope}_uuid as foto_scope_uuid`, part.role ? `${part.role} as foto_role` : db.raw('null as foto_role'), part.permission ? `${part.permission} as foto_permission` : db.raw('null as foto_permission')));
+        const [head, ...rest] = selects;
+        const rows = await this.sql(operation, () => (rest.length ? head.unionAll(rest) : head));
+        for (const row of rows) {
+            const kind = row.foto_kind;
+            if (!(kind in foto)) {
+                throw new AuthorizationInternalError(`database.${operation}: la foto devolvió una fila de una parte desconocida (${String(kind)})`);
+            }
+            foto[kind].push({
+                scope_type: row.foto_scope_type,
+                scope_uuid: row.foto_scope_uuid,
+                role_uuid: row.foto_role ?? null,
+                permission_uuid: row.foto_permission ?? null,
+            });
+        }
+        return foto;
+    }
     /**
      * Por dónde escribe `operation` (L-3): la transacción ABIERTA del llamante
      * si llegó en `options.transaction` —validada contra la conexión de este
@@ -511,8 +568,6 @@ export class DatabaseAuthorizationDriver {
             .where('permission_uuid', perm.uuid), 'scope', chain, 'read');
         if (!deniedQuery)
             return false;
-        if (await this.first('authorize.denies', () => deniedQuery))
-            return false;
         // Una asignación vigente, en la cadena, cuyo rol concede el permiso Y es
         // visible en su nivel (global u owner ancestro-o-igual del scope de la
         // asignación, 3B · B2). `assignableAt`/`rank` no entran: composición.
@@ -525,8 +580,13 @@ export class DatabaseAuthorizationDriver {
             .where('a.holder_uuid', subject.uuid), chain);
         if (!grantedQuery)
             return false;
-        const granted = await this.first('authorize.assignments', () => this.whereActive(grantedQuery, 'a.expires_at'));
-        return Boolean(granted);
+        // Los denies y las asignaciones en UNA foto (rotación 2 · cierre 3, L12): deny en la cadena ⇒ false; si no, una
+        // asignación vigente que concede ⇒ true. Nunca dos sentencias: ver `readFoto`.
+        const foto = await this.readFoto('authorize', [
+            { kind: 'deny', query: deniedQuery, scope: 'scope', permission: 'permission_uuid' },
+            { kind: 'grant', query: this.whereActive(grantedQuery, 'a.expires_at'), scope: 'a.scope', role: 'a.role_uuid' },
+        ]);
+        return foto.deny.length === 0 && foto.grant.length > 0;
     }
     async grant(subject, role, scope, options = {}) {
         assertIdentity({ subject, role, scope, expiresAt: options.expiresAt });
@@ -784,13 +844,21 @@ export class DatabaseAuthorizationDriver {
         assertIdentity({ subject });
         for (const scope of chain)
             assertScope(scope);
+        const foto = await this.readFoto('rolesInChain', [this.rolesInChainPart(subject, chain)]);
+        return this.rolesInChainFrom(foto.role, chain);
+    }
+    /** La parte de la foto de `rolesInChain`: asignaciones vigentes del holder en los scopes de la cadena (`null` sin cadena). */
+    rolesInChainPart(subject, chain) {
         const query = whereScopeIn(db
             .from('authz_assignments as a')
             .where('a.holder_type', subject.type)
             .where('a.holder_uuid', subject.uuid), 'a.scope', chain, 'read');
         if (!query)
-            return [];
-        const rows = await this.sql('rolesInChain', () => this.whereActive(query, 'a.expires_at').distinct('a.scope_type', 'a.scope_uuid', 'a.role_uuid'));
+            return null;
+        return { kind: 'role', query: this.whereActive(query, 'a.expires_at'), scope: 'a.scope', role: 'a.role_uuid' };
+    }
+    /** De las filas de la foto a la respuesta de `rolesInChain` (catálogo DESPUÉS de la foto: es memo, no hechos). */
+    async rolesInChainFrom(rows, chain) {
         const catalog = await this.catalog.view();
         const keysFrom = chainKeysFrom(chain);
         const levelOf = new Map(chain.map((s, i) => [dbScopeKey(s), i]));
@@ -853,25 +921,38 @@ export class DatabaseAuthorizationDriver {
         const perm = await this.findPermission(permission);
         if (!perm)
             return [];
-        const rows = await this.sql('listScopes.assignments', () => this.whereActive(db
+        // Las asignaciones que conceden y los denies del permiso en UNA foto (rotación 2 · cierre 3, L12): antes eran dos
+        // sentencias y un offboarding (revoke, luego removeDeny) entre ellas listaba un scope que ningún estado concedía.
+        const foto = await this.readFoto('listScopes', [this.grantsOfPart(subject, perm.uuid), this.deniesPart(subject, perm.uuid)]);
+        return this.listScopesFrom(foto.grant, foto.deny);
+    }
+    /** La parte «asignaciones vigentes del holder cuyo rol concede el permiso», en todo scope (la de `listScopes`). */
+    grantsOfPart(subject, permissionUuid) {
+        const query = this.whereActive(db
             .from('authz_assignments as a')
             .join('authz_role_permissions as rp', 'rp.role_uuid', 'a.role_uuid')
-            .where('rp.permission_uuid', perm.uuid)
+            .where('rp.permission_uuid', permissionUuid)
             .where('a.holder_type', subject.type)
-            .where('a.holder_uuid', subject.uuid), 'a.expires_at').distinct('a.scope_type', 'a.scope_uuid', 'a.role_uuid'));
-        const denies = await this.sql('listScopes.denies', () => db
-            .from('authz_denies')
-            .where('holder_type', subject.type)
-            .where('holder_uuid', subject.uuid)
-            .where('permission_uuid', perm.uuid)
-            .select('scope_type', 'scope_uuid'));
+            .where('a.holder_uuid', subject.uuid), 'a.expires_at');
+        return { kind: 'grant', query, scope: 'a.scope', role: 'a.role_uuid', permission: 'rp.permission_uuid' };
+    }
+    /** La parte «denies del holder» (de UN permiso si se da; si no, todos), en todo scope. */
+    deniesPart(subject, permissionUuid) {
+        const query = db.from('authz_denies').where('holder_type', subject.type).where('holder_uuid', subject.uuid);
+        if (permissionUuid !== undefined)
+            query.where('permission_uuid', permissionUuid);
+        return { kind: 'deny', query, scope: 'scope', permission: 'permission_uuid' };
+    }
+    /**
+     * De la foto a la respuesta de `listScopes` (árbol y catálogo DESPUÉS de la foto). `denies` son los del permiso: por
+     * scope, el conjunto de roles que conceden; el scope se lista si el árbol lo conoce, alguno de esos roles existe ahí
+     * (3B · B2) y ningún deny de la cadena lo bloquea — exactamente lo que `authorize` diría.
+     */
+    async listScopesFrom(grants, denies) {
         const deniedKeys = new Set(denies.map((d) => `${d.scope_type}:${fromDbScopeUuid(d.scope_uuid) ?? ''}`));
-        // Por scope: el conjunto de roles que conceden; el scope se lista si el
-        // árbol lo conoce, alguno de esos roles existe ahí (3B · B2) y ningún
-        // deny de la cadena lo bloquea — exactamente lo que `authorize` diría.
         const catalog = await this.catalog.view();
         const byScope = new Map();
-        for (const row of rows) {
+        for (const row of grants) {
             const k = rowScopeKey(row);
             if (!byScope.has(k))
                 byScope.set(k, { scope: { type: row.scope_type, uuid: fromDbScopeUuid(row.scope_uuid) }, roles: [] });
@@ -910,7 +991,11 @@ export class DatabaseAuthorizationDriver {
         const query = chain ? whereScopeIn(base, 'scope', [chain[0]], 'read') : base;
         if (!query)
             return [];
-        const rows = await this.sql('listDenies', () => query.select('permission_uuid', 'scope_type', 'scope_uuid'));
+        const foto = await this.readFoto('listDenies', [{ kind: 'deny', query, scope: 'scope', permission: 'permission_uuid' }]);
+        return this.deniesFrom(foto.deny, scope === undefined);
+    }
+    /** De las filas de denies a `DenyRef[]` (catálogo y, sin `scope` pedido, árbol DESPUÉS de la foto). */
+    async deniesFrom(rows, resolveEach) {
         const view = await this.catalog.view();
         const result = [];
         for (const row of rows) {
@@ -918,12 +1003,42 @@ export class DatabaseAuthorizationDriver {
             if (!permission)
                 continue;
             const denyScope = { type: row.scope_type, uuid: fromDbScopeUuid(row.scope_uuid) };
-            if (!scope && !(await this.chain(denyScope, 'listDenies')))
+            if (resolveEach && !(await this.chain(denyScope, 'listDenies')))
                 continue;
             result.push({ permission, scope: denyScope });
         }
         return result;
     }
+    /**
+     * **Varias lecturas del puerto en UNA foto** (rotación 2 · cierre 3, L12; método OPCIONAL del puerto,
+     * `AuthorizationDriver.readSnapshot`, capacidad `snapshotDecisions`). Es lo que el manager usa para las decisiones
+     * que COMPONE con dos métodos del puerto —`effectivePermissions` y la policy de delegación (`rolesInChain` +
+     * `listDenies`), `authorizedScopes` (`listScopes` + `listDenies`)—: cada respuesta pedida es EXACTAMENTE la del método
+     * homónimo, y todas salen de la MISMA foto de los hechos (`readFoto`: una sentencia). Lo no pedido no viene.
+     * Árbol y catálogo se leen después de la foto, como en cada método suelto.
+     */
+    async readSnapshot(subject, reads) {
+        assertIdentity({ subject });
+        const asked = assertSnapshotReads(reads);
+        const chain = asked.rolesInChain;
+        const perm = asked.listScopes !== undefined ? await this.findPermission(asked.listScopes) : null;
+        // Los denies: todos si se pidió `listDenies`; si solo hace falta para `listScopes`, los de ese permiso.
+        const wantsDenies = asked.listDenies === true || perm !== null;
+        const foto = await this.readFoto('readSnapshot', [
+            chain ? this.rolesInChainPart(subject, chain) : null,
+            perm ? this.grantsOfPart(subject, perm.uuid) : null,
+            wantsDenies ? this.deniesPart(subject, asked.listDenies === true ? undefined : perm.uuid) : null,
+        ]);
+        const answer = {};
+        if (chain)
+            answer.rolesInChain = await this.rolesInChainFrom(foto.role, chain);
+        if (asked.listScopes !== undefined) {
+            answer.listScopes = perm ? await this.listScopesFrom(foto.grant, foto.deny.filter((d) => d.permission_uuid === perm.uuid)) : [];
+        }
+        if (asked.listDenies === true)
+            answer.listDenies = await this.deniesFrom(foto.deny, true);
+        return answer;
+    }
     /**
      * Borra asignaciones y denies del scope exacto, en una transacción. Si el
      * árbol aún lo conoce se purga su identidad canónica (K1); si ya no (el

package/build/src/drivers/database_relations_driver.js

@@ -760,6 +760,11 @@ export class DatabaseRelationsDriver {
         const relPlaceholders = relations.map(() => '?').join(', ');
         const at = this.#expiry.bind(this.#now());
         const active = this.#activeSql(q, 'r');
+        // Rotación 2 · cierre 3b (L12, H1 del auditor): la PUERTA «¿hay algún `denied_*` vigente en el objeto?» va en la
+        // MISMA sentencia que los candidatos (una rama más del `UNION`, `foto_kind = 'd'`). Antes era una segunda sentencia y
+        // un offboarding suelto (unrelate y luego removeDeny) que caía entre las dos devolvía los candidatos de la primera
+        // SIN juzgarlos: listaba a un sujeto que no era miembro en NINGÚN estado real.
+        const deniedRelations = deniableAbove(this.#config, object.type, relation).map(deniedRelationOf);
         // `grp`: los grupos alcanzables por usersets desde (object, RS) —directos y
         // anidados—. Ancla de UN solo SELECT (MySQL no mezcla UNION ALL con la
         // recursión): los usersets directos del objeto para cualquier rel de RS.
@@ -777,16 +782,22 @@ export class DatabaseRelationsDriver {
             `AND r.${q('relation')} = '${GROUP_MEMBER}' AND r.${q('subject_type')} = '${GROUP_TYPE}' ` +
             `AND r.${q('subject_relation')} = '${GROUP_MEMBER}' AND ${active} ` +
             `) ` +
-            // Holders directos del objeto para RS, UNION holders directos de cualquier grupo de `grp`.
-            `SELECT ${meta.hint}${q('subject_type')} AS ${q('subject_type')}, ${q('subject_uuid')} AS ${q('subject_uuid')} ` +
+            // Holders directos del objeto para RS, UNION holders directos de cualquier grupo de `grp` (`foto_kind = 'm'`),
+            // UNION la puerta de denies (`foto_kind = 'd'`, una fila como mucho: el `UNION` funde los `NULL`).
+            `SELECT ${meta.hint}'m' AS ${q('foto_kind')}, ${q('subject_type')} AS ${q('subject_type')}, ${q('subject_uuid')} AS ${q('subject_uuid')} ` +
             `FROM ${q(RELATIONS_TABLE)} r ` +
             `WHERE r.${q('partition_key')} = ? AND r.${q('object_type')} = ? AND r.${q('object_uuid')} = ? ` +
             `AND r.${q('relation')} IN (${relPlaceholders}) AND COALESCE(r.${q('subject_relation')}, '') = '' AND ${active} ` +
             `UNION ` +
-            `SELECT r.${q('subject_type')}, r.${q('subject_uuid')} FROM ${q(RELATIONS_TABLE)} r ` +
+            `SELECT 'm', r.${q('subject_type')}, r.${q('subject_uuid')} FROM ${q(RELATIONS_TABLE)} r ` +
             `JOIN grp ON r.${q('object_uuid')} = grp.g_uuid ` +
             `WHERE r.${q('partition_key')} = ? AND r.${q('object_type')} = '${GROUP_TYPE}' ` +
-            `AND r.${q('relation')} = '${GROUP_MEMBER}' AND COALESCE(r.${q('subject_relation')}, '') = '' AND ${active}`;
+            `AND r.${q('relation')} = '${GROUP_MEMBER}' AND COALESCE(r.${q('subject_relation')}, '') = '' AND ${active}` +
+            (deniedRelations.length
+                ? ` UNION SELECT 'd', NULL, NULL FROM ${q(RELATIONS_TABLE)} r ` +
+                    `WHERE r.${q('partition_key')} = ? AND r.${q('object_type')} = ? AND r.${q('object_uuid')} = ? ` +
+                    `AND r.${q('relation')} IN (${deniedRelations.map(() => '?').join(', ')}) AND ${active}`
+                : '');
         const bindings = [
             // grp ancla
             partitionKey, object.type, object.id, ...relations, at,
@@ -796,22 +807,21 @@ export class DatabaseRelationsDriver {
             partitionKey, object.type, object.id, ...relations, at,
             // holders de los grupos
             partitionKey, at,
+            // la puerta de denies (misma sentencia)
+            ...(deniedRelations.length ? [partitionKey, object.type, object.id, ...deniedRelations, at] : []),
         ];
         const rows = rowsOf(await this.#raw('membersOf', sql, bindings));
-        const candidates = rows.map((row) => ({ type: String(row.subject_type), uuid: String(row.subject_uuid) }));
+        const candidates = rows
+            .filter((row) => String(row.foto_kind) === 'm')
+            .map((row) => ({ type: String(row.subject_type), uuid: String(row.subject_uuid) }));
+        const denied = rows.some((row) => String(row.foto_kind) === 'd');
         // **Lote D · `membersOf` RESTA** (juez ronda 2: «listObjects y membersOf restan»; D8: siempre, con o sin opt-in).
         // Si el objeto tiene alguna fila `denied_*` vigente, cada candidato se juzga con `check` —el MISMO corte de camino
         // que el resto de lecturas, un `check` por candidato—; sin filas deny, cero consultas de más (la respuesta y el coste
-        // de 2.4.0-alpha.10). Coste declarado: O(miembros) consultas cuando el objeto tiene denies.
-        const denied = await this.#sql('membersOf.denies', () => this.#whereActive(this.#connection()
-            .from(RELATIONS_TABLE)
-            .where('partition_key', partitionKey)
-            .where('object_type', object.type)
-            .where('object_uuid', object.id)
-            .whereIn('relation', deniableAbove(this.#config, object.type, relation).map(deniedRelationOf)), this.#now())
-            .select('uuid')
-            .limit(1));
-        if (denied.length === 0)
+        // de 2.4.0-alpha.10). Coste declarado: O(miembros) consultas cuando el objeto tiene denies. La puerta sale de la
+        // MISMA sentencia que los candidatos (L12): sin deny en esa foto, todos los candidatos son miembros en ese estado.
+        // Con deny, cada candidato se juzga con su `check` (una foto por candidato, como cada posición de `authorizeMany`).
+        if (!denied)
             return { subjects: candidates };
         // **Cierre 1 de D1 · 🟡 4 del auditor**: con deny, N `check` en serie sin cota ni deadline total era una
         // amplificación barata para quien puede escribir un deny (disponibilidad, no concesión). Cota DECLARADA

package/build/src/errors.d.ts

@@ -195,6 +195,24 @@ export declare class AuthorizationInternalError extends Exception {
 export declare class UnknownScopeError extends Exception {
     static status: number;
     static code: string;
+    /**
+     * **Para el OPERADOR, no para el tenant** (rotación 2 · cierre 2 · RC2-A): en `updateScopedRole`/`deleteScopedRole` el
+     * scope que no resuelve es el OWNER del rol (dormido), que el llamante no pasó y puede ser de otro tenant: el `message`
+     * nombra el rol y el owner va aquí, NO enumerable (mismo patrón que `NotWithinError.details`). Ausente en el resto de
+     * rutas, donde el scope desconocido es el que pasó el llamante y el `message` lo nombra.
+     */
+    readonly details: {
+        owner: {
+            type: string;
+            uuid: string | null;
+        };
+    } | undefined;
+    constructor(message?: string, details?: {
+        owner: {
+            type: string;
+            uuid: string | null;
+        };
+    });
 }
 /**
  * Se preguntó por un scope que no es la raíz y el driver no tiene resolutor
@@ -458,6 +476,27 @@ export declare class ActorRequiredError extends Exception {
 export declare class NotWithinError extends Exception {
     static status: number;
     static code: string;
+    /**
+     * **Para el OPERADOR, no para el tenant** (rotación 2 de M4 · R2-03, decisión del dueño 2026-10-22 (3)). Hasta
+     * 2.5.0-alpha.4 el `message` imprimía la cadena ENTERA del scope (`unit:<B1x> → unit:<B1> → organization:<org de B>
+     * → app`): el admin de A que conoce un uuid de B aprendía a qué tenant pertenece y su ruta, y un 422 es lo que un
+     * framework devuelve al cliente tal cual (la misma clase de fuga que 3E · Q2 cerró en `ROLE_NOT_VISIBLE`). Ahora el
+     * `message` nombra solo lo que el llamante ya tiene —el scope que pasó y su `within`— y la cadena va aquí, NO
+     * enumerable como `ScopeDepthLimitError.details` (alpha.8): `JSON.stringify(error)` —lo que un handler genérico
+     * manda— no la lleva, y el log del servidor la lee por `error.details.chain`. El CÓDIGO no cambia.
+     */
+    readonly details: {
+        chain: ReadonlyArray<{
+            type: string;
+            uuid: string | null;
+        }>;
+    } | undefined;
+    constructor(message: string, details?: {
+        chain: ReadonlyArray<{
+            type: string;
+            uuid: string | null;
+        }>;
+    });
 }
 /**
  * `config.requireWithin` (`true` o `'non-root'`) y una escritura llegó sin

package/build/src/errors.js

@@ -267,6 +267,10 @@ export class AuthorizationInternalError extends Exception {
 export class UnknownScopeError extends Exception {
     static status = 422;
     static code = 'E_AUTHZ_UNKNOWN_SCOPE';
+    constructor(message, details) {
+        super(message);
+        Object.defineProperty(this, 'details', { value: details, enumerable: false, configurable: true, writable: false });
+    }
 }
 /**
  * Se preguntó por un scope que no es la raíz y el driver no tiene resolutor
@@ -565,6 +569,10 @@ export class ActorRequiredError extends Exception {
 export class NotWithinError extends Exception {
     static status = 422;
     static code = 'E_AUTHZ_NOT_WITHIN';
+    constructor(message, details) {
+        super(message);
+        Object.defineProperty(this, 'details', { value: details, enumerable: false, configurable: true, writable: false });
+    }
 }
 /**
  * `config.requireWithin` (`true` o `'non-root'`) y una escritura llegó sin

package/build/src/identity.d.ts

@@ -1,4 +1,4 @@
-import type { NormalizedRoleQuery, RoleQuery, ScopeRef, SubjectRef } from './types.js';
+import type { NormalizedRoleQuery, RoleQuery, ScopeRef, SnapshotReads, SubjectRef } from './types.js';
 /**
  * Validación de identidad del motor: holder, scope, rol y permiso.
  *
@@ -338,3 +338,9 @@ export interface IdentityParts {
  * cuesta una consulta ni deja rastro.
  */
 export declare function assertIdentity(parts: IdentityParts): void;
+/**
+ * La forma de una pregunta a `readSnapshot` (rotación 2 · cierre 3): al menos una de las tres claves y ninguna más;
+ * `rolesInChain` un array de scopes válidos, `listScopes` un slug de permiso, `listDenies` exactamente `true`. Lo
+ * demás es 422 `E_AUTHZ_INVALID_IDENTITY` antes de tocar el backend. Devuelve la pregunta con las claves presentes.
+ */
+export declare function assertSnapshotReads(reads: unknown): SnapshotReads;

package/build/src/identity.js

@@ -610,3 +610,32 @@ export function assertIdentity(parts) {
     if ('expiresAt' in parts)
         assertExpiresAt(parts.expiresAt);
 }
+/**
+ * La forma de una pregunta a `readSnapshot` (rotación 2 · cierre 3): al menos una de las tres claves y ninguna más;
+ * `rolesInChain` un array de scopes válidos, `listScopes` un slug de permiso, `listDenies` exactamente `true`. Lo
+ * demás es 422 `E_AUTHZ_INVALID_IDENTITY` antes de tocar el backend. Devuelve la pregunta con las claves presentes.
+ */
+export function assertSnapshotReads(reads) {
+    if (reads === null || typeof reads !== 'object' || Array.isArray(reads)) {
+        throw new InvalidIdentityError(`readSnapshot: se esperaba un objeto { rolesInChain?, listScopes?, listDenies? } y llegó ${Array.isArray(reads) ? 'un array' : typeof reads}`);
+    }
+    const known = new Set(['rolesInChain', 'listScopes', 'listDenies']);
+    const present = Object.keys(reads).filter((key) => reads[key] !== undefined);
+    const unknown = present.filter((key) => !known.has(key));
+    if (unknown.length)
+        throw new InvalidIdentityError(`readSnapshot: clave desconocida ${unknown.map((k) => `'${k}'`).join(', ')}`);
+    if (present.length === 0)
+        throw new InvalidIdentityError('readSnapshot: no se pidió ninguna lectura');
+    const { rolesInChain, listScopes, listDenies } = reads;
+    if (rolesInChain !== undefined) {
+        if (!Array.isArray(rolesInChain))
+            throw new InvalidIdentityError('readSnapshot: rolesInChain tiene que ser un array de scopes');
+        for (const scope of rolesInChain)
+            assertScope(scope);
+    }
+    if (listScopes !== undefined)
+        assertIdentity({ permission: listScopes });
+    if (listDenies !== undefined && listDenies !== true)
+        throw new InvalidIdentityError('readSnapshot: listDenies solo admite true');
+    return { rolesInChain, listScopes, listDenies };
+}

package/build/src/manager.d.ts

@@ -71,6 +71,12 @@ export declare const RELAY_LEASE_POLL_MS = 25;
  * reloj de pared: con `config.clock` fijo el sondeo por reloj no terminaba nunca.
  */
 export declare const RELAY_WAIT_LEASE_MAX_MS = 60000;
+/**
+ * Por qué una pasada de `pruneOrphanRoles` tiene la firma de un resolutor ciego (3b-0b · AA2 + rotación 2 · R2-02):
+ * todos los owners huérfanos, más del 50 % de los roles locales, o huérfanos de más de un owner con alguno que todavía
+ * concede (o no se sabe).
+ */
+export type MassPurgeReason = 'all-owners' | 'proportion' | 'granting-across-owners';
 export interface ForRequestOptions {
     /**
      * Milisegundos durante los que la vista puede LEER (default 30 000).
@@ -700,6 +706,21 @@ export declare class AuthorizationManager {
      *    antes de su `purgeRole`; si ha vuelto, el rol se salta y se cuenta en
      *    `skipped` con `reason: 'owner-came-back'`.
      *
+     * **Tercer disparador del seguro** (rotación 2 de M4 · R2-02, decisión del dueño 2026-10-22 (2)): la
+     *    proporción la controla un TENANT —con la API de delegación legítima infla su catálogo local hasta que los
+     *    huérfanos de los demás bajan del 50 %—, y la variante realista del resolutor ciego no es «`null` para todo»
+     *    sino un contexto de tenant COLADO en el job de plataforma, que solo deja vivo a ese tenant. Así que, con
+     *    `force`, si los huérfanos son de MÁS DE UN owner y ALGUNO todavía concede (`stillGranting === true`) o no se
+     *    sabe (`undefined`: el driver no cuenta), también es 500 `E_AUTHZ_MASS_PURGE_REFUSED` antes de borrar nada,
+     *    salvo `allowMassPurge`. Un solo owner huérfano con asignaciones vivas sigue pasando (es el caso normal de un
+     *    tenant que se va, y el listado lo marca aparte). El `--dry-run` no lanza: lo marca en `massPurge` y dice por
+     *    qué en `massPurgeReasons` (`'all-owners' | 'proportion' | 'granting-across-owners'`).
+     *  - **Cota de lectura** (R2-04): `maxLocalRoles` (default `DEFAULT_MAX_LOCAL_ROLES`, `--max-local-roles` en el
+     *    comando) acota la lectura del catálogo local; pasarla es 500 `E_AUTHZ_TOO_MANY_LOCAL_ROLES`, nunca una lista
+     *    parcial. Hasta este cierre la opción no existía y el mensaje pedía «subir la cota» sin mando: un tenant con
+     *    10 001 roles locales dejaba `prune-orphans` muerto para todos. Un valor que no es un entero ≥ 1 es 500
+     *    `E_AUTHZ_CONFIG` antes de leer nada.
+     *
      * Coste: una lectura del catálogo local + un `resolveChain` por OWNER
      * DISTINTO (memoizado) + UNA llamada a `countRoleAssignments` con los
      * uuids de los huérfanos (ninguna si no hay) + un `resolveChain` más por
@@ -710,6 +731,7 @@ export declare class AuthorizationManager {
     pruneOrphanRoles(options?: {
         force?: boolean;
         allowMassPurge?: boolean;
+        maxLocalRoles?: number;
     }): Promise<{
         orphans: Array<{
             role: CatalogRole;
@@ -725,6 +747,8 @@ export declare class AuthorizationManager {
         }>;
         /** ¿La pasada tiene la firma de un resolutor ciego? Con `force` exige `allowMassPurge`. */
         massPurge: boolean;
+        /** Qué disparó `massPurge` (vacío si no saltó): todos los owners, la proporción, o huérfanos de > 1 owner que conceden (R2-02). */
+        massPurgeReasons: MassPurgeReason[];
         dryRun: boolean;
     }>;
     /**