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

package/build/src/manager.js

@@ -775,11 +775,15 @@ export class AuthorizationManager {
         // se contrasta es la de origen, resuelta en fresco.
         attached: async (child, parent, options) => {
             const actor = await this.#writeOptions(options, 'scopes.attached');
-            const edge = await this.#assertEdge(child, parent, 'scopes.attached');
+            // RC2-B (rotación 2 · cierre 2, firmado: REORDENAR): `within` —destino Y origen, en fresco— se decide ANTES que el
+            // anti-ciclos y el techo de profundidad. Al revés, `SCOPE_CYCLE`/`SCOPE_DEPTH_LIMIT` sobre un scope AJENO decían
+            // DÓNDE está (de qué otro scope ajeno desciende, a cuántos saltos de la raíz) antes del `NOT_WITHIN`.
+            const edge = await this.#resolveEdge(child, parent, 'scopes.attached');
             this.#assertWithinChain(parent, edge.chain, options, 'scopes.attached');
             // Un hijo que el árbol ya conoce se está MOVIENDO (el `attach` de un
             // nodo existente es un `move`): su origen también tiene que estar dentro.
             await this.#assertWithinOrigin(child, options, 'scopes.attached', 'if-known');
+            this.#judgeEdge(edge, parent, 'scopes.attached');
             const outbox = this.#outbox();
             if (outbox) {
                 const receipt = await outbox.enqueue({ op: 'attached', child: edge.child, parent: edge.chain[0] }, { transaction: options?.transaction, ...actor });
@@ -803,9 +807,11 @@ export class AuthorizationManager {
          */
         moved: async (child, newParent, options) => {
             const actor = await this.#writeOptions(options, 'scopes.moved');
-            const edge = await this.#assertEdge(child, newParent, 'scopes.moved');
+            // RC2-B: `within` (destino y origen) antes que el anti-ciclos y el techo (ver `attached`).
+            const edge = await this.#resolveEdge(child, newParent, 'scopes.moved');
             this.#assertWithinChain(newParent, edge.chain, options, 'scopes.moved');
             await this.#assertWithinOrigin(child, options, 'scopes.moved', 'required');
+            this.#judgeEdge(edge, newParent, 'scopes.moved');
             const outbox = this.#outbox();
             if (outbox) {
                 const receipt = await outbox.enqueue({ op: 'moved', child: edge.child, parent: edge.chain[0] }, { transaction: options?.transaction, ...actor });
@@ -2075,7 +2081,7 @@ export class AuthorizationManager {
      *
      * **La raíz `app` NO es clave** (2.4.0-alpha.8; panel relay 2, cuestión 1;
      * decisión del dueño 2026-09-10 (4)). La raíz no se mueve, no se purga y
-     * nunca es hijo (los tres 422 de `#assertEdge`/`scopes.detached`), así que
+     * nunca es hijo (los tres 422 de `#resolveEdge`/`#judgeEdge`/`scopes.detached`), así que
      * dos cambios cuyo ÚNICO cruce sea `app` conmutan: ningún orden que
      * conservar (el auditor lo buscó y no lo encontró; `m2-orden.ts`). Con
      * `[hijo, app]` toda alta de tenant compartía clave con todas las demás:
@@ -2398,16 +2404,35 @@ export class AuthorizationManager {
             return;
         this.#assertWithinChain(child, chain, options, operation);
     }
-    /** Lo mismo con una cadena ya resuelta (en fresco) por el llamante. */
-    #assertWithinChain(scope, chain, options, operation) {
+    /**
+     * Lo mismo con una cadena ya resuelta (en fresco) por el llamante. `asked` es cómo nombra el `message` lo que el
+     * llamante PASÓ cuando el scope contrastado NO lo pasó él (RC2-A, rotación 2 · cierre 2: en `updateScopedRole`/
+     * `deleteScopedRole` se contrasta el OWNER del rol, que sale del catálogo — el llamante solo pasó el uuid del rol).
+     */
+    #assertWithinChain(scope, chain, options, operation, asked) {
         const within = this.#requiredWithin(scope, options, operation);
         if (!within)
             return;
         if (!chain.some((s) => _a.#sameScope(s, within))) {
-            throw new NotWithinError(`${operation}: ${scope.type}:${scope.uuid ?? ''} no está dentro de ` +
-                `${within.type}:${within.uuid ?? ''} (la cadena es ${chain.map((s) => `${s.type}:${s.uuid ?? ''}`).join(' → ')}); ` +
-                `no se escribe fuera del scope declarado.`);
+            // R2-03: el `message` llega al tenant tal cual — solo nombra lo que el llamante PASÓ (el scope, o el rol, y su
+            // `within`); la cadena (identificadores de OTRO tenant) va a `error.details`, no enumerable, para el log del servidor.
+            throw new NotWithinError(`${operation}: ${asked ?? `${scope.type}:${scope.uuid ?? ''}`} no está dentro de ${within.type}:${within.uuid ?? ''}; ` +
+                `no se escribe fuera del scope declarado.`, { chain: chain.map((s) => ({ type: s.type, uuid: s.uuid ?? null })) });
+        }
+    }
+    /**
+     * La cadena (fresca) del OWNER de un rol local para `updateScopedRole`/`deleteScopedRole`, o 422
+     * `E_AUTHZ_UNKNOWN_SCOPE` si el owner ya no resuelve (rol DORMIDO). El `message` nombra el ROL tal como lo pasó el
+     * llamante, nunca el owner: el owner es un identificador que el llamante no aportó y puede ser de otro tenant (RC2-A).
+     * El owner va a `error.details.owner`, no enumerable. El CÓDIGO no cambia.
+     */
+    async #ownerChainOf(owner, roleUuid, operation) {
+        const chain = await resolveChain(this.#freshResolver(), owner, operation);
+        if (!chain) {
+            throw new UnknownScopeError(`El owner del rol ${roleUuid} no existe para el resolutor de la cadena (${operation}): el rol está dormido. ` +
+                `No se escribe sobre un scope que el árbol no reconoce; lo retira la plataforma (authz:catalog:prune-orphans).`, { owner: { type: owner.type, uuid: owner.uuid ?? null } });
         }
+        return chain;
     }
     /** El `within` a contrastar, validado y exigido según `requireWithin`; `null` si no hay que contrastar nada. */
     #requiredWithin(scope, options, operation) {
@@ -2456,13 +2481,13 @@ export class AuthorizationManager {
         return resolver;
     }
     /**
-     * Valida la arista y devuelve la cadena (fresca) del padre y el HIJO
-     * CANÓNICO (invariante 17). El hijo canónico se devuelve desde 3b-2d
+     * Resuelve la arista —identidad, padre conocido— y devuelve la cadena (fresca) del padre y el HIJO
+     * CANÓNICO (invariante 17); el anti-ciclos y el techo los juzga `#judgeEdge`, DESPUÉS de `within` (RC2-B). El hijo canónico se devuelve desde 3b-2d
      * porque la outbox lo encola: lo que se guarda en la cola es la fila del
      * árbol, no lo que escribió el llamante — si no, el relay abriría días
      * después una rama nueva en el store por un alias del uuid.
      */
-    async #assertEdge(child, parent, operation) {
+    async #resolveEdge(child, parent, operation) {
         const resolver = this.#resolver(operation);
         assertScope(child);
         assertScope(parent);
@@ -2474,14 +2499,22 @@ export class AuthorizationManager {
         // El hijo, si el árbol ya lo conoce, con su identidad canónica (K1): un
         // alias del uuid no puede colarse por debajo de la comprobación de ciclo.
         const known = await resolveChain(resolver, child, operation);
-        const canonicalChild = known ? known[0] : child;
-        const childKey = _a.#scopeKey(canonicalChild);
-        if (chain.some((s) => _a.#scopeKey(s) === childKey)) {
+        return { chain, child: known ? known[0] : child };
+    }
+    /**
+     * La otra mitad de la arista: anti-ciclos y techo de profundidad sobre lo que `#resolveEdge` resolvió. **Va DESPUÉS de
+     * `within`** (rotación 2 · cierre 2 · RC2-B, firmado: REORDENAR): los dos errores hablan de la cadena del PADRE —«desciende
+     * de …», «lo dejaría a N saltos»— y con un padre de otro tenant eran un oráculo de ESTRUCTURA ajena (de qué org cuelga
+     * una unit ajena, a qué profundidad está) que salía antes del `NOT_WITHIN`. Sin `within`, o con uno que pasa, el orden
+     * de los demás errores no cambia (identidad → padre desconocido → ciclo → profundidad).
+     */
+    #judgeEdge(edge, parent, operation) {
+        const childKey = _a.#scopeKey(edge.child);
+        if (edge.chain.some((s) => _a.#scopeKey(s) === childKey)) {
             throw new ScopeCycleError(`${operation}: ${parent.type}:${parent.uuid} desciende de ${childKey.replace('\u001f', ':')} (o es él mismo); ` +
                 `colgarlo cerraría un ciclo y la herencia dejaría de ser solo hacia abajo.`);
         }
-        this.#assertDepth(chain, canonicalChild, parent, operation);
-        return { chain, child: canonicalChild };
+        this.#assertDepth(edge.chain, edge.child, parent, operation);
     }
     /**
      * **El gate de profundidad, opt-in** (2.4.0-alpha.5 · R0; `scopes.maxDepth`).
@@ -2596,8 +2629,10 @@ export class AuthorizationManager {
         if (!chain)
             return [];
         const catalog = await this.#catalogFor(driver).view();
-        const { granted } = await this.#rolesAlong(driver, subject, chain, catalog);
-        const denied = await this.#deniedAlong(driver, subject, chain, 'effectivePermissions');
+        // Roles y denies en UNA foto (rotación 2 · cierre 3, L12): ver `#decisionFacts`.
+        const facts = await this.#decisionFacts(driver, subject, { chain, catalog }, 'effectivePermissions');
+        const { granted } = this.#grantedFrom(facts.roles, chain, catalog);
+        const denied = this.#deniedIn(facts.denies, chain);
         return [...granted].filter((permission) => !denied.has(permission));
     }
     /**
@@ -2621,11 +2656,18 @@ export class AuthorizationManager {
      * `E_AUTHZ_AMBIGUOUS_ROLE`) si hay homónimos visibles. Nunca elige uno.
      */
     async #rolesAlong(driver, subject, chain, catalog) {
+        return this.#grantedFrom(await this.#readRoles(driver, subject, chain, catalog), chain, catalog);
+    }
+    /** Los roles del holder en la cadena por el PUERTO: `rolesInChain` si el driver lo trae; si no, la composición por slug. */
+    async #readRoles(driver, subject, chain, catalog) {
+        return typeof driver.rolesInChain === 'function'
+            ? await driver.rolesInChain(subject, chain)
+            : await this.#rolesFromSlugs(driver, subject, chain, chainKeysFrom(chain), catalog);
+    }
+    /** Lo que conceden unos roles YA LEÍDOS a lo largo de la cadena, y el rank más alto (puro: el catálogo es el memo). */
+    #grantedFrom(roles, chain, catalog) {
         const keysFrom = chainKeysFrom(chain);
         const levelIndex = new Map(chain.map((s, i) => [scopeKey(s), i]));
-        const roles = typeof driver.rolesInChain === 'function'
-            ? await driver.rolesInChain(subject, chain)
-            : await this.#rolesFromSlugs(driver, subject, chain, keysFrom, catalog);
         const granted = new Set();
         let rank = 0;
         for (const { scope: level, role } of roles) {
@@ -2724,18 +2766,91 @@ export class AuthorizationManager {
             return undefined;
         }
     }
-    /** Permisos DENEGADOS al holder en algún scope de la cadena: `listDenies` en UNA lectura (500 `E_AUTHZ_UNSUPPORTED` sin él). */
-    async #deniedAlong(driver, subject, chain, primitive) {
-        const listDenies = this.#optional(driver, 'listDenies', primitive);
+    /** Permisos DENEGADOS al holder en algún scope de la cadena, sobre denies YA LEÍDOS (los de `listDenies(subject)`). */
+    #deniedIn(denies, chain) {
         const key = _a.#scopeKey;
         const chainKeys = new Set(chain.map(key));
         const denied = new Set();
-        for (const deny of await listDenies(subject)) {
+        for (const deny of denies) {
             if (chainKeys.has(key(deny.scope)))
                 denied.add(deny.permission);
         }
         return denied;
     }
+    /**
+     * **El punto de paso ÚNICO de las decisiones que el manager COMPONE con concesión y deny** (rotación 2 · cierre 3;
+     * 4.ª aparición del linaje L12 «lector rasgado»). `effectivePermissions`, la policy de delegación de
+     * `defineScopedRole`/`updateScopedRole` (`#assertDelegable`) y `authorizedScopes` combinan lo que el holder TIENE
+     * (`rolesInChain`, o `listScopes` de un permiso) con lo que tiene DENEGADO (`listDenies`). Hasta aquí eran dos métodos
+     * del puerto, dos lecturas sin foto común: un offboarding suelto (revoke y luego removeDeny) entre las dos hacía que
+     * `effectivePermissions` listara un permiso, `authorizedScopes` una unit y `defineScopedRole` delegara algo que el
+     * holder no tenía en NINGÚN estado real (repro `.claude/reproducciones/database-authorize-rasgado.spec.ts`, caso 5).
+     *
+     * Regla: con un driver que DECLARA la capacidad `snapshotDecisions: true` (opcional por D15) las DOS mitades salen de
+     * UNA llamada a `readSnapshot`, que el driver responde desde una sola foto de sus hechos; la respuesta se contrasta
+     * con lo pedido (una clave que falta o que no es un array es un bug del driver: 500 nombrándolo, como
+     * `authorizeMany`). Decide la CAPACIDAD, no la presencia del método (rotación 2 · cierre 3b, H3 del auditor; el
+     * patrón de `membersOfNative`): declarar `true` sin traer `readSnapshot` es 500 `E_AUTHZ_CONFIG` antes de leer nada,
+     * y un driver que declara `false` (o nada) compone como siempre aunque tenga un método con ese nombre —el hueco
+     * DECLARADO de un driver sin la capacidad (`openfga`, terceros)—. En los dos caminos, sin `listDenies` es 500
+     * `E_AUTHZ_UNSUPPORTED` antes de leer nada: nunca un «sin denies».
+     *
+     * `catalog` va con `chain` porque la composición por slug lo necesita; el catálogo y la cadena se leen FUERA de la
+     * foto (el memo contrasta la versión compartida; la cadena es del consumidor: «cadena frente a hechos», declarado).
+     *
+     * **Cuándo sale el 500 de «`true` sin `readSnapshot`»** (rotación 2 · cierre 3c, J3 del auditor): en la PRIMERA
+     * decisión compuesta (`effectivePermissions`, `authorizedScopes`, la policy de `defineScopedRole`/`updateScopedRole`),
+     * no al resolver el driver — `authorize` y los `list*` no lo necesitan y siguen respondiendo. Fail-closed y ruidoso,
+     * pero tarde; el patrón es el de `#optional` (una operación que falta se dice cuando se pide). El mensaje nombra el
+     * driver que lo EMITIÓ —la clave de `config.drivers` y la clase del objeto que la factory devolvió—, no solo
+     * `config.default`.
+     */
+    async #decisionFacts(driver, subject, request, primitive) {
+        const listDenies = this.#optional(driver, 'listDenies', primitive);
+        if (driver.capabilities?.snapshotDecisions === true) {
+            if (typeof driver.readSnapshot !== 'function') {
+                throw new AuthorizationConfigError(`${primitive}: el driver ${this.#emitter(driver)} declara snapshotDecisions: true y no trae readSnapshot. ` +
+                    'La capacidad promete leer en UNA foto lo que el manager compone; sin el método no hay foto que leer. ' +
+                    'Implementa readSnapshot o declara snapshotDecisions: false (el manager compone con dos lecturas, el hueco declarado).');
+            }
+            const answer = await driver.readSnapshot(subject, {
+                ...(request.chain ? { rolesInChain: request.chain } : {}),
+                ...(request.permission !== undefined ? { listScopes: request.permission } : {}),
+                listDenies: true,
+            });
+            const got = (answer ?? {});
+            const missing = [
+                ...(request.chain ? ['rolesInChain'] : []),
+                ...(request.permission !== undefined ? ['listScopes'] : []),
+                'listDenies',
+            ].filter((key) => !Array.isArray(got[key]));
+            if (answer === null || typeof answer !== 'object' || missing.length) {
+                throw new AuthorizationInternalError(`${primitive}: el driver ${this.#emitter(driver)} respondió a readSnapshot sin ${missing.join(', ') || 'un objeto'}; ` +
+                    'el puerto exige un array por cada lectura pedida, todas de la misma foto.');
+            }
+            return {
+                roles: got.rolesInChain,
+                scopes: got.listScopes,
+                denies: got.listDenies,
+            };
+        }
+        // Fallback DECLARADO (driver sin `snapshotDecisions: true`): dos lecturas del puerto sin foto común. Un método
+        // `readSnapshot` de un driver que no declara la capacidad NO se llama (puede ser otra cosa con el mismo nombre).
+        const roles = request.chain ? await this.#readRoles(driver, subject, request.chain, request.catalog) : undefined;
+        const scopes = request.permission !== undefined ? await driver.listScopes(subject, request.permission) : undefined;
+        return { roles, scopes, denies: await listDenies(subject) };
+    }
+    /**
+     * Cómo se nombra en un error el driver que lo EMITIÓ (cierre 3c, J3): la clave de `config.drivers` que lo resolvió y la
+     * clase del objeto que devolvió la factory (una vista `Object.create`/`withClock` hereda la del driver). La clave sola
+     * puede no decir qué objeto respondió (una factory que elige entre varios, una vista).
+     */
+    #emitter(driver) {
+        const kind = driver?.constructor?.name;
+        return typeof kind === 'string' && kind !== '' && kind !== 'Object'
+            ? `'${this.#config.default}' (${kind})`
+            : `'${this.#config.default}'`;
+    }
     // ── Roles locales a un scope (3B · B3): la API de DELEGACIÓN ─────────
     // Un administrador de un scope (el actor) define roles que solo existen
     // dentro de ese scope (owner) con permisos que él mismo tiene efectivos
@@ -2787,8 +2902,10 @@ export class AuthorizationManager {
         // Composición y lista blanca antes de leer hechos: lo barato primero.
         this.#assertComposable(parsed.permissions, parsed, catalog);
         await this.#assertLevelUnderOwner(parsed.scopeType, chain, 'defineScopedRole');
-        const { granted, rank: actorRank } = await this.#rolesAlong(driver, who, chain, catalog);
-        const denied = await this.#deniedAlong(driver, who, chain, 'defineScopedRole');
+        // Lo que el actor tiene y lo que tiene denegado, en UNA foto (rotación 2 · cierre 3, L12: `#decisionFacts`).
+        const facts = await this.#decisionFacts(driver, who, { chain, catalog }, 'defineScopedRole');
+        const { granted, rank: actorRank } = this.#grantedFrom(facts.roles, chain, catalog);
+        const denied = this.#deniedIn(facts.denies, chain);
         this.#assertDelegable(parsed.permissions, granted, denied, owner);
         this.#assertRank(parsed.rank, actorRank, catalog.topGlobalRank);
         const shadowedByAncestor = await this.#assertNoRoleCollision(parsed.slug, parsed.scopeType, owner, chain, catalog.rolesNamed(parsed.slug, parsed.scopeType));
@@ -2808,18 +2925,20 @@ export class AuthorizationManager {
             const known = new Set(catalog.rolesNamed(parsed.slug, parsed.scopeType).map((r) => r.owner));
             const fresh = [...new Set(rows.map((r) => String(r.owner_scope_key)).filter((o) => !known.has(o)))];
             if (fresh.length) {
-                // Los homónimos que el memo no tenía son de una escritura confirmada
-                // mientras validábamos. Los que se pueden juzgar SIN salir de la
-                // transacción (global, o un ancestro-o-igual del owner: la cadena ya
-                // está resuelta) dan el 422 preciso; el resto se rechaza igual —
-                // resolver su cadena aquí dentro pediría otra conexión mientras se
-                // sostiene el cerrojo del catálogo (con un pool de 1, un abrazo
-                // mortal). Reintentar es correcto: el memo ya está invalidado y el
-                // segundo intento valida con la foto buena.
+                // Los homónimos que el memo no tenía son de una escritura confirmada mientras validábamos. Se juzgan con la
+                // MISMA regla de colisión por AUTORIDAD que la comprobación previa (3F · S3, invariante 18), en lo que se puede
+                // juzgar SIN salir de la transacción —la cadena del owner ya está resuelta—: global o ancestro-o-igual ⇒ 422
+                // preciso (eso mantiene M2: dos `define` del mismo owner acaban en uno). **Cualquier otro owner NO es colisión**
+                // (rotación 2 · R2-05, decisión del dueño 2026-10-22): un hermano —otro tenant— puede tener el mismo slug, y
+                // un DESCENDIENTE queda ensombrecido, que es el segundo final legal de la carrera ancestro↔descendiente
+                // (3G · Y1). Hasta este cierre los dos se rechazaban con un 422 que NOMBRABA el owner ajeno («owner
+                // organization|<uuid de A>»): un oráculo de qué tenants definen qué slug, y una colisión falsa (reintentar
+                // entraba). Lo que NO se hace aquí, a propósito: resolver la cadena del owner nuevo dentro de la transacción
+                // (pediría otra conexión con el cerrojo del catálogo sostenido: abrazo mortal con pool 1), así que el rango
+                // sobre un descendiente confirmado EN la ventana no se mide (W3 protege a los roles que YA existían al validar;
+                // el mismo actor obtiene lo mismo yendo primero) y no sale en `shadowedByAncestor` del evento — sí en
+                // `authz:catalog:diff`. Declarado en el CHANGELOG.
                 await this.#assertNoRoleCollision(parsed.slug, parsed.scopeType, owner, chain, fresh.map((o) => ({ owner: o })), 'sin-árbol');
-                throw new CatalogConflictError(`El catálogo cambió mientras se validaba '${parsed.slug}@${parsed.scopeType}': apareció un rol con ese nombre ` +
-                    `(owner ${fresh.join(', ')}) que no estaba en la foto con la que se comprobaron las colisiones. ` +
-                    `No se escribe a ciegas; reintenta la operación.`);
             }
             const now = systemClock();
             await trx.table('authz_roles').insert({
@@ -2871,10 +2990,10 @@ export class AuthorizationManager {
         const catalog = await this.#catalogFor(driver).view();
         const role = this.#localRoleOrFail(catalog, roleUuid);
         const owner = this.#ownerOf(role);
-        const chain = await assertKnownScope(this.#freshResolver(), owner, 'updateScopedRole');
+        const chain = await this.#ownerChainOf(owner, role.uuid, 'updateScopedRole');
         // El scope contrastado es el OWNER del rol (3D · M3): editar un rol es
         // escribir dentro de su contenedor.
-        this.#assertWithinChain(owner, chain, options, 'updateScopedRole');
+        this.#assertWithinChain(owner, chain, options, 'updateScopedRole', `el rol ${role.uuid}`);
         const current = [...catalog.rolePermissionsOf(role.uuid)].sort();
         const next = {
             name: parsed.name ?? null,
@@ -2888,15 +3007,24 @@ export class AuthorizationManager {
         // POR ENCIMA de su owner (creado antes de 3E o a mano) no se perpetúa:
         // es una mina de slug y lo que toca es purgarlo, no editarlo.
         await this.#assertLevelUnderOwner(role.scopeType, chain, 'updateScopedRole');
-        const { granted, rank: actorRank } = await this.#rolesAlong(driver, who, chain, catalog);
+        // Con permisos nuevos la policy combina lo que el actor tiene con lo que tiene denegado: UNA foto (rotación 2 ·
+        // cierre 3, L12: `#decisionFacts`). Sin permisos solo hace falta el rank (una mitad: no rasga). Un driver SIN
+        // `listDenies` no tiene denies que leer: se leen solo los roles y el 500 `E_AUTHZ_UNSUPPORTED` sale DESPUÉS del 422
+        // de rango, en el orden de siempre (rotación 2 · cierre 3b, H4 del auditor).
+        const withDenies = Boolean(parsed.permissions) && typeof driver.listDenies === 'function';
+        const facts = withDenies
+            ? await this.#decisionFacts(driver, who, { chain, catalog }, 'updateScopedRole')
+            : { roles: await this.#readRoles(driver, who, chain, catalog), denies: [] };
+        const { granted, rank: actorRank } = this.#grantedFrom(facts.roles, chain, catalog);
         this.#assertAboveRole(actorRank, role);
         // 3G · W3: este rol puede estar ENSOMBRECIENDO al homónimo de un
         // descendiente (3F · S3). Cambiarle rank o permisos es seguir ejerciendo
         // esa autoridad, así que exige lo mismo que crearlo: superarlo en rango.
         this.#assertAboveShadowed(actorRank, await this.#shadowedBelow(scopeKey(owner), new Set(chain.map(scopeKey)), catalog.rolesNamed(role.slug, role.scopeType).filter((other) => other.uuid !== role.uuid), 'updateScopedRole'), 'updateScopedRole');
         if (parsed.permissions) {
-            const denied = await this.#deniedAlong(driver, who, chain, 'updateScopedRole');
-            this.#assertDelegable(parsed.permissions, granted, denied, owner);
+            if (!withDenies)
+                this.#optional(driver, 'listDenies', 'updateScopedRole');
+            this.#assertDelegable(parsed.permissions, granted, this.#deniedIn(facts.denies, chain), owner);
         }
         if (parsed.rank !== undefined)
             this.#assertRank(parsed.rank, actorRank, catalog.topGlobalRank);
@@ -2965,8 +3093,8 @@ export class AuthorizationManager {
         const catalog = await this.#catalogFor(driver).view();
         const role = this.#localRoleOrFail(catalog, roleUuid);
         const owner = this.#ownerOf(role);
-        const chain = await assertKnownScope(this.#freshResolver(), owner, 'deleteScopedRole');
-        this.#assertWithinChain(owner, chain, options, 'deleteScopedRole');
+        const chain = await this.#ownerChainOf(owner, role.uuid, 'deleteScopedRole');
+        this.#assertWithinChain(owner, chain, options, 'deleteScopedRole', `el rol ${role.uuid}`);
         const { rank: actorRank } = await this.#rolesAlong(driver, who, chain, catalog);
         this.#assertAboveRole(actorRank, role);
         const permissions = [...catalog.rolePermissionsOf(role.uuid)].sort();
@@ -3063,6 +3191,21 @@ export 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
@@ -3071,6 +3214,12 @@ export class AuthorizationManager {
      * una petición.
      */
     async pruneOrphanRoles(options = {}) {
+        // R2-04: la cota es una entrada del operador y se valida antes de leer nada (L5: entrada inerte o rechazada).
+        const maxLocalRoles = options.maxLocalRoles;
+        if (maxLocalRoles !== undefined && !(Number.isInteger(maxLocalRoles) && maxLocalRoles >= 1)) {
+            throw new AuthorizationConfigError(`pruneOrphanRoles: maxLocalRoles (--max-local-roles) debe ser un entero >= 1 (llegó ${String(maxLocalRoles)}). ` +
+                `No se ha leído nada.`);
+        }
         const force = options.force === true;
         this.#resolver('authz:catalog:prune-orphans');
         const driver = await this.driver();
@@ -3082,7 +3231,7 @@ export class AuthorizationManager {
         if (force)
             await this.#assertNotFrozen('authz:catalog:prune-orphans');
         const resolver = this.#freshResolver();
-        const locals = await readLocalRoles({ driver: this.#config.default });
+        const locals = await readLocalRoles({ driver: this.#config.default, maxLocalRoles });
         const resolved = new Map();
         const orphans = [];
         for (const { role, permissions } of locals) {
@@ -3115,15 +3264,33 @@ export class AuthorizationManager {
         }
         const owners = new Set(locals.map(({ role }) => role.owner));
         const orphanOwners = new Set(orphans.map(({ role }) => role.owner));
-        const massPurge = orphans.length > 0 && (orphanOwners.size === owners.size || orphans.length * 2 > locals.length);
+        // Los TRES disparadores del seguro (AA2 + R2-02). Cada uno se reporta: el `--dry-run` dice POR QUÉ lo marca.
+        const granting = orphans.filter(({ stillGranting }) => stillGranting !== false);
+        const massPurgeReasons = [];
+        if (orphans.length > 0) {
+            if (orphanOwners.size === owners.size)
+                massPurgeReasons.push('all-owners');
+            if (orphans.length * 2 > locals.length)
+                massPurgeReasons.push('proportion');
+            if (orphanOwners.size > 1 && granting.length > 0)
+                massPurgeReasons.push('granting-across-owners');
+        }
+        const massPurge = massPurgeReasons.length > 0;
         if (!force)
-            return { orphans, purged: [], skipped: [], massPurge, dryRun: true };
+            return { orphans, purged: [], skipped: [], massPurge, massPurgeReasons, dryRun: true };
         if (massPurge && options.allowMassPurge !== true) {
+            // Solo CUENTAS: ni uuids ni slugs de owners (la lista ya la ve el operador en el `--dry-run`).
+            const motivos = massPurgeReasons.map((reason) => reason === 'all-owners'
+                ? `todos los owners distintos (${orphanOwners.size} de ${owners.size}) salen huérfanos`
+                : reason === 'proportion'
+                    ? `los huérfanos son más del 50 % de los roles locales (${orphans.length} de ${locals.length})`
+                    : `los huérfanos son de ${orphanOwners.size} owners distintos y ${granting.length} de ellos TODAVÍA conceden ` +
+                        `o no se sabe (stillGranting true/undefined)`);
             throw new MassPurgeRefusedError(`pruneOrphanRoles: ${orphans.length} de ${locals.length} roles locales (${orphanOwners.size} de ${owners.size} ` +
-                `owners distintos) tienen el owner fuera del árbol. Esa es la firma de un 'scopes.resolveChain' ciego —filtrado ` +
-                `por el tenant de la petición, o sin contexto— que devuelve null para todo: una pasada así borra el catálogo ` +
-                `local de todos los tenants. No se ha borrado nada. Comprueba el resolutor y, si la poda es real, repite con ` +
-                `allowMassPurge: true (--allow-mass-purge).`);
+                `owners distintos) tienen el owner fuera del árbol, y ${motivos.join('; ')}. Esa es la firma de un ` +
+                `'scopes.resolveChain' ciego —filtrado por el tenant de la petición, con el contexto de UN tenant colado en el ` +
+                `job, o sin contexto—: una pasada así borra el catálogo local, y las asignaciones vivas, de otros tenants. No se ` +
+                `ha borrado nada. Comprueba el resolutor y, si la poda es real, repite con allowMassPurge: true (--allow-mass-purge).`);
         }
         const purged = [];
         const skipped = [];
@@ -3161,7 +3328,7 @@ export class AuthorizationManager {
             purged.push(role);
             await this.#notifyCatalog({ action: 'role_purged', role, owner, permissions });
         }
-        return { orphans, purged, skipped, massPurge, dryRun: false };
+        return { orphans, purged, skipped, massPurge, massPurgeReasons, dryRun: false };
     }
     /** El actor de la API de delegación: obligatorio SIEMPRE (sin él no hay policy que evaluar) y bien formado. */
     async #requireActor(actor, operation) {
@@ -3686,12 +3853,13 @@ export class AuthorizationManager {
         // resuelven una vez.
         const view = this.#readResolver ? this : this.forRequest();
         const driver = await view.#reader();
-        const listDenies = this.#optional(driver, 'listDenies', 'authorizedScopes');
         const key = _a.#scopeKey;
-        const direct = await driver.listScopes(subject, permission);
+        // Los scopes directos que conceden y los denies, en UNA foto (rotación 2 · cierre 3, L12: `#decisionFacts`).
+        const facts = await view.#decisionFacts(driver, subject, { permission }, 'authorizedScopes');
+        const direct = facts.scopes;
         if (direct.length === 0)
             return { kind: 'none' };
-        const denied = (await listDenies(subject)).filter((d) => d.permission === permission).map((d) => d.scope);
+        const denied = facts.denies.filter((d) => d.permission === permission).map((d) => d.scope);
         if (direct.some((s) => s.type === APP_SCOPE_TYPE)) {
             if (denied.length > maxScopes) {
                 throw new TooManyScopesError(`authorizedScopes: ${denied.length} subárboles excluidos superan maxScopes=${maxScopes}; no se devuelve una lista parcial.`);
@@ -3771,7 +3939,7 @@ export class AuthorizationManager {
     }
     /**
      * Clave LAXA de un scope, solo para agrupar/deduplicar candidatos dentro
-     * de una operación (`authorizedScopes`, el anti-ciclo de `#assertEdge`).
+     * de una operación (`authorizedScopes`, el anti-ciclo de `#judgeEdge`).
      * NO es `scopeKey` de `identity.ts` —esa valida la gramática y es la que
      * identifica hechos, owners e ids de binding, y es la que usa
      * `#rolesAlong` (3D · N5)—: aquí los scopes vienen del `descendantsOf` del

package/build/src/scope_outbox.d.ts

@@ -89,7 +89,9 @@ interface DatabaseLike {
  * 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
@@ -118,9 +120,41 @@ export declare 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 declare const SCOPE_OUTBOX_TAKES_LEGACY_LOCK = false;
-export declare function scopeOutboxLockNames(connection: string | undefined, table: string): {
+/**
+ * **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 declare function scopeOutboxLockNames(connection: string | undefined, table: string, database?: string | null): {
     legacy: string;
+    unscoped: string;
     current: string;
 };
+/**
+ * **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 declare const SCOPE_OUTBOX_UNSCOPED_LOCK_RETIRED_IN = "2.6.0-alpha.0";
+export declare const SCOPE_OUTBOX_TAKES_UNSCOPED_LOCK = true;
 export declare function sqlScopeOutbox(options?: SqlScopeOutboxOptions, database?: DatabaseLike): ScopeOutbox;
 export {};