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

package/build/src/relations_config_store.js

@@ -22,14 +22,45 @@
  * sin uso (cleanup futuro).
  */
 import { systemClock } from './clock.js';
-import { RelationConfigError } from './errors.js';
+import { AuthorizationConfigError, DenyReachRefusedError, RelationConfigError } from './errors.js';
 import { guardSql } from './shared/backend_guard.js';
 import db from '@adonisjs/lucid/services/db';
 import { invalidateAuthzCatalog, withAuthzCatalogWrite } from './catalog/catalog_cache.js';
 import { defineRelationsConfig } from './relations/define_relations_config.js';
+import { DENY_REACH_KEY_PATTERN, deniedPublicRelation, denyReachBaselineOf, denyReachCheck, denyReachKey, denyReachLine, judgeDenyReach } from './relations/deny_reach.js';
 const TABLE = 'authz_relations_config';
 const ROW_ID = 1;
 const DEFAULT_TIMEOUT_MS = 5_000;
+/** La lista de la salida forzada acotada, validada (L5): `undefined` ⇒ ninguna; array de `tipo#relación` ⇒ esa; otra cosa ⇒ 500. */
+function namedShrinkExemptions(value) {
+    if (value === undefined)
+        return new Set();
+    const ok = Array.isArray(value) && value.every((key) => typeof key === 'string' && DENY_REACH_KEY_PATTERN.test(key));
+    if (!ok) {
+        throw new AuthorizationConfigError(`saveRelationsConfig: allowDenyReachShrink tiene que ser una lista de 'tipo#relación' (llegó ${JSON.stringify(value) ?? String(value)}). ` +
+            `Desde el sublote (8) la salida forzada exime SOLO los hallazgos que nombras —p. ej. { allowDenyReachShrink: ['note#editor'] }—; ` +
+            `no hay un true global.`);
+    }
+    return new Set(value);
+}
+/** Los nombres de la lista que no eximen ningún hallazgo `shrunk`/`orphan` de este guardado (orden de la lista). */
+function unusedShrinkExemptions(exempt, judged) {
+    const used = new Set(judged.filter((finding) => finding.reason !== 'no-baseline').map(denyReachKey));
+    return [...exempt].filter((key) => !used.has(key));
+}
+function unusedShrinkExemptionsError(unused) {
+    return new AuthorizationConfigError(`saveRelationsConfig: allowDenyReachShrink nombra ${JSON.stringify(unused)}, y en este guardado ningún deny vivo de ` +
+        `esa(s) relación(es) encoge ni queda huérfano: no exime nada. Quita ese nombre de la lista (la salida forzada acotada ` +
+        `se usa en el guardado que la necesita y se retira después; pegada, eximiría en silencio un encogimiento futuro). ` +
+        `No se ha escrito nada (ni la fila ni la versión del catálogo).`);
+}
+/** `establishBaseline` validado (L5): solo `undefined`, `false` o `true`. */
+function establishBaselineOf(value) {
+    if (value === undefined || value === false || value === true)
+        return value === true;
+    throw new AuthorizationConfigError(`saveRelationsConfig: establishBaseline tiene que ser true o false (llegó ${JSON.stringify(value) ?? String(value)}): ` +
+        `solo true adopta la línea base, y una opción mal escrita no puede levantar la guarda.`);
+}
 function connectionOf(options) {
     return options?.connection ? db.connection(options.connection) : db;
 }
@@ -41,21 +72,141 @@ function connectionOf(options) {
  * siguiente pregunta—. Devuelve la config congelada.
  */
 export async function saveRelationsConfig(spec, options = {}) {
-    // Valida ANTES de escribir: una config inválida no ensucia la tabla.
+    // Valida ANTES de escribir: una config inválida no ensucia la tabla. Las dos salidas de la guarda (8), también antes
+    // (L5: una forma rota es 500 sin tomar el cerrojo).
     const config = defineRelationsConfig(spec);
-    const json = JSON.stringify(spec);
+    const json = JSON.stringify(persistableRelationsSpec(spec));
+    const { allowDenyReachShrink, establishBaseline, ...storeOptions } = options;
+    const exempt = namedShrinkExemptions(allowDenyReachShrink);
+    const adopt = establishBaselineOf(establishBaseline);
     await withAuthzCatalogWrite(async (trx) => {
         const existing = await trx.from(TABLE).where('id', ROW_ID).first();
+        // **La guarda (8) de `database`**, DENTRO de la transacción del catálogo (cerrojo de la fila de versión) y ANTES de la
+        // primera escritura: la línea base es la fila que acabamos de leer (TODO O NADA) y los denies vivos se leen por la
+        // MISMA trx. Cada hallazgo se niega salvo su salida con nombre: `no-baseline` ⇐ `establishBaseline: true` (solo existe
+        // sin línea base utilizable: con ella es inerte); `shrunk`/`orphan` ⇐ su `tipo#relación` en `allowDenyReachShrink`.
+        const judged = judgeDenyReach(baselineOf(existing), config, await liveDenyGroups(trx));
+        const refused = judged.filter((finding) => (finding.reason === 'no-baseline' ? !adopt : !exempt.has(denyReachKey(finding))));
+        if (refused.length > 0)
+            throw denyReachRefused(refused);
+        // **Un nombre de la salida acotada que no exime NADA en ESTE guardado ⇒ 500** (firma «(8 · cierre 1 · ronda)», 🟡 1 del
+        // auditor del cierre 1): «casa» = exime un `shrunk`/`orphan` de este guardado (un `no-baseline` no cuenta), calculado
+        // aquí, dentro de la trx. Así la salida se APAGA SOLA: una lista que se queda pegada en el pipeline no exime en silencio
+        // el encogimiento FUTURO de esa relación. Un huérfano heredado sigue siendo hallazgo en cada guardado: su nombre casa.
+        const unused = unusedShrinkExemptions(exempt, judged);
+        if (unused.length > 0)
+            throw unusedShrinkExemptionsError(unused);
         if (existing) {
             await trx.from(TABLE).where('id', ROW_ID).update({ spec: json, updated_at: systemClock() });
         }
         else {
             await trx.table(TABLE).insert({ id: ROW_ID, spec: json, model_id: null, updated_at: systemClock() });
         }
-    }, options);
+    }, storeOptions);
     invalidateAuthzCatalog();
     return config;
 }
+/**
+ * La LÍNEA BASE de la guarda (8) y del detector de un driver: la config persistida, leída TODO O NADA
+ * (`denyReachBaselineOf`), o `null` = NO UTILIZABLE (sin fila, JSON roto, o una forma que la lectura no puede tipar). Una
+ * fila que no valida en 2.5 pero cuyos campos de alcance se tipan (p. ej. una clave que 2.5 no conoce) SÍ es línea base:
+ * re-guardarla con la spec corregida (la receta de B5) entra sin forzar.
+ */
+function baselineOf(row) {
+    if (!row)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(String(row.spec));
+    }
+    catch {
+        return null;
+    }
+    return denyReachBaselineOf(parsed);
+}
+/**
+ * Los denies VIVOS de `authz_relations` agrupados por tipo y relación (las filas del driver `database`), por la conexión o
+ * la trx que se le pase. Todas las filas `denied_*`: el deny no caduca (D3) y una fila con `expires_at` escrita a mano cuenta
+ * igual (contar de más rechaza de más: lo conservador). El filtro del deny es UNO, aquí (`deniedPublicRelation`): una fila
+ * que no es un deny no pide línea base (S-A0).
+ */
+async function liveDenyGroups(connection) {
+    return denyGroupsOf(await liveDenyQuery(connection));
+}
+/** La consulta (un `GROUP BY` de `authz_relations`): aparte para que el detector de un driver le ponga su deadline. */
+function liveDenyQuery(connection) {
+    return connection.from('authz_relations').select('object_type', 'relation').count('* as n').groupBy('object_type', 'relation');
+}
+function denyGroupsOf(rows) {
+    const groups = [];
+    for (const row of rows) {
+        const relation = deniedPublicRelation(String(row.relation));
+        if (relation !== null)
+            groups.push({ objectType: String(row.object_type), relation, count: Number(row.n) });
+    }
+    return groups;
+}
+function denyReachRefused(findings) {
+    const shrink = findings.filter((f) => f.reason !== 'no-baseline').map(denyReachKey);
+    const exits = [
+        ...(findings.some((f) => f.reason === 'no-baseline')
+            ? ['sin línea base utilizable, la adopción es saveRelationsConfig(spec, { establishBaseline: true }) con la spec que la flota sirve HOY, sin cambios']
+            : []),
+        ...(shrink.length > 0
+            ? [`si de verdad quieres que esos denies dejen de cortar, la salida forzada ACOTADA es saveRelationsConfig(spec, { allowDenyReachShrink: ${JSON.stringify(shrink)} })`]
+            : []),
+    ];
+    const error = new DenyReachRefusedError(`saveRelationsConfig NEGADO (E_AUTHZ_DENY_REACH_REFUSED): ${findings.length} hallazgo(s) sobre denies vivos de authz_relations — ` +
+        `una config que encoge su alcance haría conceder, de forma persistente, lo que negaban (decisión (8): para todo deny ` +
+        `vivo, alcance nuevo ⊇ alcance viejo). ${findings.map(denyReachLine).join(' ')} No se ha escrito nada (ni la fila ni la ` +
+        `versión del catálogo). ${exits.join('; ')}.`);
+    error.findings = findings.map(({ objectType, relation, reason, count, lost, recipe }) => ({ objectType, relation, reason, count, lost, recipe }));
+    return error;
+}
+/**
+ * **El detector de UN solo driver** (firma (8 · detector de un driver), R4 del analista del panel): en un despliegue
+ * solo-`database` el detector de `authz:relations:reconcile --dry-run` no corre (necesita DOS drivers de relaciones:
+ * origen = destino es 500). Esta función compara la config que SIRVE el proceso (`served`) con la línea base persistida
+ * sobre los denies vivos de `authz_relations`, en las DOS direcciones:
+ *  - persistida → servida: lo que la guarda negaría (`shrunk`, `orphan`, `no-baseline`);
+ *  - servida → persistida: la línea base RANCIA (`stale`), que la guarda no puede ver.
+ *
+ * Solo LEE (la fila y un `GROUP BY` de `authz_relations`, por `options.connection` o la primaria), sin transacción y sin el
+ * cerrojo del catálogo, con el MISMO punto de paso que la guarda (`baselineOf` + `liveDenyGroups` + `denyReachCheck`).
+ * **Receta**: en CI, DESPUÉS del paso que guarda la config y ANTES de servir, y en un cron; falla el job si `ok` es `false`.
+ * **Nunca** como fallo duro en `ready`: durante un despliegue un pod viejo que se reinicia sirve la config estrecha contra la
+ * fila nueva y entraría en un bucle de reinicios.
+ */
+export async function checkRelationsConfigDenyReach(served, options = {}) {
+    if (!served || !Array.isArray(served.objectTypes)) {
+        throw new AuthorizationConfigError('checkRelationsConfigDenyReach: pasa la config de relaciones que SIRVE este proceso (relations.config de config/authorization.ts, la de defineRelationsConfig).');
+    }
+    const connection = connectionOf(options);
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const row = await guardSql('relations-config', 'read', timeoutMs, () => connection.from(TABLE).where('id', ROW_ID).first());
+    const groups = denyGroupsOf(await guardSql('relations-config', 'read', timeoutMs, () => liveDenyQuery(connection)));
+    const check = denyReachCheck(baselineOf(row), served, groups);
+    return {
+        ...check,
+        ok: check.findings.length === 0 && check.staleBaseline.length === 0,
+        lines: [...check.findings, ...check.staleBaseline].map(denyReachLine),
+    };
+}
+/**
+ * **Lo que se persiste de la spec** (cierre-2 de R1 · P1, decisión del dueño 2026-10-20): `maxGroupDepth` y
+ * `database.enforceGroupDepth` son claves de DESPLIEGUE, no de modelo. Se VALIDAN (`defineRelationsConfig`, arriba: un
+ * valor malo es el mismo 500) pero NO se guardan. Nadie las lee de la base (el plan del reconcile toma el techo de
+ * `to.groupDepthLimit()`, no de la config persistida), y guardarlas rompía un despliegue mezclado: un proceso alpha.2/
+ * alpha.3 relee la fila con su lista blanca (B2, sin esas claves) y su `authz:relations:reconcile` sale con 1. No es el
+ * «descartar en silencio» de B2: se conocen y se validan; solo no se escriben. El resto de la spec va TAL CUAL.
+ */
+function persistableRelationsSpec(spec) {
+    const { maxGroupDepth: _deployment, ...rest } = spec;
+    if (rest.database === undefined || rest.database === null || typeof rest.database !== 'object')
+        return rest;
+    const { enforceGroupDepth: _enforce, ...database } = rest.database;
+    return { ...rest, database };
+}
 /** Lee el spec persistido (o `null` si no hay relaciones declaradas — opt-in). */
 export async function readRelationsConfigSpec(options = {}) {
     const row = await guardSql('relations-config', 'read', options.timeoutMs ?? DEFAULT_TIMEOUT_MS, () => connectionOf(options).from(TABLE).where('id', ROW_ID).first());
@@ -93,4 +244,3 @@ export async function readRelationsConfig(options = {}) {
     const spec = await readRelationsConfigSpec(options);
     return spec ? defineRelationsConfig(spec) : null;
 }
-//# sourceMappingURL=relations_config_store.js.map

package/build/src/relations_reconcile.d.ts

@@ -76,4 +76,3 @@ export type RunRelationsReconcileOptions = Omit<RelationsReconcileOptions, 'from
  *    Pásale el manager del servicio, nunca uno construido o envuelto a mano.
  */
 export declare function runRelationsReconcile(authorization: Pick<AuthorizationManager, 'withFrozenWrites' | 'relationsDriverKey' | 'relationsDriverFactory'>, options: RunRelationsReconcileOptions): Promise<RelationsReconcileReport>;
-//# sourceMappingURL=relations_reconcile.d.ts.map

package/build/src/relations_reconcile.js

@@ -82,4 +82,3 @@ export async function runRelationsReconcile(authorization, options) {
         return report;
     }, { kind: 'reconcile', operatorAsContext: true });
 }
-//# sourceMappingURL=relations_reconcile.js.map

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,10 +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 {};
-//# sourceMappingURL=scope_outbox.d.ts.map

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 };
                 }
@@ -532,4 +593,3 @@ export function sqlScopeOutbox(options = {}, database = db) {
         },
     };
 }
-//# sourceMappingURL=scope_outbox.js.map

package/build/src/shared/backend_guard.d.ts

@@ -66,6 +66,58 @@ export declare function isServerWriteLimit(error: unknown): boolean;
  * `cause`. Se mira la cadena entera de causas.
  */
 export declare function isTimeoutLike(error: unknown): boolean;
+/**
+ * Las clases de la decisión del dueño 2026-10-17 (3) y (4) (lote «antes de RC» · R3), separadas SIN leer el mensaje
+ * (F0 · M-d: 41 formas literales del SDK 0.9.6 contra OpenFGA v1.19, en `tests/fixtures/fga_errors/`):
+ *
+ * | clase | al llamante | en el relay |
+ * |---|---|---|
+ * | `timeout` (deadline propio, `ECONNABORTED`/`ETIMEDOUT`, el `FgaError` sin respuesta) | 503 `E_AUTHZ_BACKEND_TIMEOUT` | transitorio |
+ * | `transient` (5xx —501 incluido—, 408, 429, `deadline_exceeded`, sin respuesta, ítem `internal_error`; en una ESCRITURA el 504 y `deadline_exceeded` son `timeout`) | 503 `E_AUTHZ_BACKEND_UNAVAILABLE` | transitorio |
+ * | `resolution-limit` (`authorization_model_resolution_too_complex`, excepción o ítem) | 503 `E_AUTHZ_RESOLUTION_LIMIT` | transitorio |
+ * | `deployment` (401/403/404, 400 con código de la LISTA BLANCA, validación del cliente) | 500 `E_AUTHZ_CONFIG` «no es transitorio» | transitorio (marca) |
+ * | `race` (409, 400 `write_failed_due_to_invalid_input`) | 409 `E_AUTHZ_WRITE_CONFLICT` si escapa | transitorio (`isTransientRelayFailure`, cierre de R3) |
+ * | `unknown-4xx` (cualquier otro 4xx) | 500 `E_AUTHZ_CONFIG` con `cause` | transitorio (marca) |
+ */
+export type FgaFailureKind = 'timeout' | 'transient' | 'resolution-limit' | 'deployment' | 'race' | 'unknown-4xx';
+export interface FgaFailure {
+    kind: FgaFailureKind;
+    /** El `statusCode` HTTP de la respuesta (ausente sin respuesta y en el error por ítem de `batchCheck`). */
+    status?: number;
+    /** `apiErrorCode` del SDK, o el valor de la clave del error por ítem (`input_error`/`internal_error`). */
+    apiErrorCode?: string;
+}
+/** El código de OpenFGA que dice «el grafo excede lo que resuelvo» (decisión 4: 503 con código propio). */
+export declare const FGA_RESOLUTION_TOO_COMPLEX = "authorization_model_resolution_too_complex";
+/**
+ * **La LISTA BLANCA de códigos de despliegue** (F0 · M-d): solo códigos MEDIDOS. Un 400 con un código fuera de ella (y todo 422)
+ * es `unknown-4xx` (la clase `FgaApiValidationError` no basta: el 400 de código desconocido es la misma clase). Dentro de
+ * la clase no se separan sin el mensaje —y no hace falta, la decisión 3 los junta—: relación/tipo ausente del modelo
+ * fijado ↔ contexto ausente en la tupla ↔ `current_time` ausente (los tres `validation_error`), y store ↔ modelo ausente
+ * con pin (los dos `authorization_model_not_found`).
+ */
+export declare const FGA_DEPLOYMENT_CODES: ReadonlySet<string>;
+/**
+ * **`classifyFgaFailure(error)`**: la clase de un fallo de OpenFGA, por `statusCode` + `apiErrorCode` (lista blanca) o,
+ * en el error POR ÍTEM de un `batchCheck` 200, por la CLAVE del objeto `error` (`input_error`/`internal_error`). **Jamás
+ * lee `message` ni `apiErrorMessage`** (lo vigila la propiedad `fga.errors.classify` de la guardia; las ÚNICAS exenciones,
+ * por nombre y firmadas —decisión del dueño 2026-10-18 (5-bis)—, son `isDuplicateWrite`/`isTreeWriteRace`, que leen el
+ * SUB-tipo de la carrera «already exists» / «does not exist» y viven ENCIMA de esta clase). PUNTO DE PASO ÚNICO de los
+ * TRES sitios: `#guard` del driver de relaciones, `guardBackendErrors` y `alignBatchResults` (los dos drivers).
+ */
+export declare function classifyFgaFailure(error: unknown, context?: {
+    write?: boolean;
+}): FgaFailure;
+/**
+ * **El error PÚBLICO de un fallo de OpenFGA** (R3): `classifyFgaFailure` ⇒ la clase de la tabla de arriba. La causa
+ * original viaja SIEMPRE en `cause` (la carrera la leen `isDuplicateWrite`/`isTreeWriteRace` por la cadena). `timeoutMs`
+ * solo da la letra del timeout. `failure` deja pasar una clasificación ya hecha (el llamante que necesita mirarla antes).
+ */
+export declare function fgaFailureError(driver: string, operation: string, error: unknown, options?: {
+    timeoutMs?: number;
+    failure?: FgaFailure;
+    write?: boolean;
+}): Error;
 /**
  * Ejecuta una consulta SQL con deadline y traduce su fallo. El builder de
  * Lucid es perezoso (se ejecuta al hacer `await`), así que el `timeout` se
@@ -158,4 +210,3 @@ export declare function canonicalScope(resolver: ScopeChainResolver, scope: Scop
 export declare function canonicalScopeTargets(resolver: ScopeChainResolver, scope: ScopeRef, operation: string): Promise<ScopeRef[]>;
 /** La cadena canónica, o 422 `E_AUTHZ_UNKNOWN_SCOPE` si el scope no existe (para escrituras). */
 export declare function assertKnownScope(resolver: ScopeChainResolver, scope: ScopeRef, operation: string): Promise<ScopeRef[]>;
-//# sourceMappingURL=backend_guard.d.ts.map