@jantstack/adonis-authz 2.4.0-alpha.9 → 2.5.0-alpha.1

package/build/src/manager.js

@@ -1,15 +1,16 @@
 var _a;
 import { Exception } from '@adonisjs/core/exceptions';
 import { v7 as uuidv7 } from 'uuid';
-import { assertCatalogUuid, assertIdentity, assertScope, assertScopeType, assertSubject, assertValidSlug, chainKeysFrom, normalizeRoleQuery, scopeFromKey, scopeKey, scopeSpellings, } from './identity.js';
+import { activeRelationsDriverKey } from './define_config.js';
+import { assertCatalogUuid, assertIdentity, assertScope, assertScopeType, assertSubject, assertValidSlug, chainKeysFrom, normalizeRoleQuery, scopeFromKey, scopeKey, } from './identity.js';
 import { expiryChanged } from './expiry.js';
 import { randomBytes } from 'node:crypto';
-import { DEFAULT_FREEZE_LEASE_MS, acquireFreeze, freezeIsLive, freezeKindOf, readFreezeRow, assertNotFrozenRow, releaseFreeze, renewFreeze, } from './freeze.js';
-import { assertKnownScope, isAuthzError, resolveChain, rootOnlyResolver } from './shared/backend_guard.js';
+import { DEFAULT_FREEZE_LEASE_MS, acquireFreezeOutcome, UNKNOWN_HOLDER, freezeIsLive, freezeKindOf, readFreezeRow, assertNotFrozenRow, releaseFreeze, renewFreeze, } from './freeze.js';
+import { assertKnownScope, canonicalScopeTargets, isAuthzError, resolveChain, rootOnlyResolver } from './shared/backend_guard.js';
 import { CatalogCache, GLOBAL_OWNER_KEY, invalidateAuthzCatalog, isRoleVisibleWith, readLocalRoles, withAuthzCatalogWrite } from './catalog/catalog_cache.js';
 import { assertAssignableAt } from './catalog/catalog.js';
 import { systemClock } from './clock.js';
-import { ActorRequiredError, AuthorizationBackendError, AuthorizationBackendTimeoutError, AuthorizationFrozenError, AuthorizationConfigError, AuthorizationInternalError, CatalogConflictError, InvalidIdentityError, MassPurgeRefusedError, PruneInterruptedError, NoDescendantsResolverError, NotWithinError, PermissionNotDelegableError, RankExceededError, RoleImmutableError, RoleLevelAboveOwnerError, ScopeCycleError, ScopeResolverError, TooManyScopesError, UnknownPermissionError, UnknownRoleError, FreezeHeldError, UnsupportedOperationError, ViewExpiredError, WithinRequiredError, WithinRootForbiddenError, ScopeDriftUnguardedError, ScopeDepthLimitError, ScopeRequeueRefusedError, } from './errors.js';
+import { ActorRequiredError, AuthorizationBackendError, AuthorizationBackendTimeoutError, AuthorizationFrozenError, AuthorizationConfigError, AuthorizationInternalError, CatalogConflictError, InvalidIdentityError, MassPurgeRefusedError, PruneInterruptedError, NoDescendantsResolverError, NotWithinError, PermissionNotDelegableError, RankExceededError, RoleImmutableError, RoleLevelAboveOwnerError, ScopeCycleError, ScopeResolverError, TooManyScopesError, UnknownPermissionError, UnknownRoleError, FreezeHeldError, UnsupportedOperationError, ViewExpiredError, WithinRequiredError, WithinRootForbiddenError, ScopeDriftUnguardedError, ScopeDepthLimitError, ScopeRequeueRefusedError, StaleSourceRefusedError, OperatorWindowExpiredError, } from './errors.js';
 import { APP_SCOPE_TYPE, normalizeAuthorizationCapabilities } from './types.js';
 import { memoizeAncestors } from './memoize_ancestors.js';
 import { AUTHZ_TABLES_ORIGIN } from './reconcile.js';
@@ -20,12 +21,26 @@ const ROLE_DESCRIPTION_MAX = 500;
 function describeAnswer(answer) {
     if (!Array.isArray(answer))
         return `${answer === null ? 'null' : typeof answer} (no es un array)`;
-    const offending = answer.find((b) => typeof b !== 'boolean');
-    if (offending !== undefined || answer.some((b) => typeof b !== 'boolean')) {
-        return `un array de ${answer.length} con un elemento que no es boolean (${typeof offending})`;
+    for (let i = 0; i < answer.length; i++) {
+        if (!(i in answer))
+            return `un array de ${answer.length} con un HUECO en la posición ${i}`;
+        if (typeof answer[i] !== 'boolean')
+            return `un array de ${answer.length} con un elemento que no es boolean en la posición ${i} (${typeof answer[i]})`;
     }
     return `un array de ${answer.length}`;
 }
+/**
+ * ¿Cada POSICIÓN del array es un boolean? Por índice, nunca con `some`/`every`
+ * (que saltan los huecos de un array disperso: 🟡 A3 del auditor del lote A;
+ * gemelo de `checkMany` en `src/relations/manager.ts`).
+ */
+function everyPositionBoolean(answers) {
+    for (let i = 0; i < answers.length; i++) {
+        if (typeof answers[i] !== 'boolean')
+            return false;
+    }
+    return true;
+}
 /**
  * Configs que ya recibieron el aviso de seguridad opt-in (B7/B1): una vez
  * por config, no por instancia — `forRequest()` construye managers hijos con
@@ -406,12 +421,30 @@ export class AuthorizationManager {
         const finalReason = reason ?? 'una operación de plataforma';
         const holder = `${kind}:${process.pid}:${randomBytes(4).toString('hex')}`;
         const nowMs = root.#wallMs();
-        const token = await acquireFreeze({ reason: finalReason, holder, untilMs: leaseMs === null ? null : nowMs + leaseMs, nowMs }, { driver: this.#config.default });
-        if (token === null) {
-            const row = await readFreezeRow({ driver: this.#config.default });
+        // alpha.10 · S2 (+ cierre del auditor · R2): una ventana de OPERADOR
+        // caducada no se pisa en silencio. Una fila con el lease vencido se toma
+        // encima (así la flota vuelve sola tras un SIGKILL de una pasada), pero la
+        // del operador es EVIDENCIA: pisarla y soltarla después la deja a NULL y
+        // borra el único rastro de que las escrituras volvieron a entrar a mitad
+        // del cutover. La exclusión vive DENTRO del UPDATE de `acquireFreezeOutcome`
+        // (atómica): aquí solo se lee el veredicto y la fila para redactarlo — un
+        // «compruebo y luego tomo» con dos lecturas del reloj era un TOCTOU.
+        const outcome = await acquireFreezeOutcome({ reason: finalReason, holder, untilMs: leaseMs === null ? null : nowMs + leaseMs, nowMs }, { driver: this.#config.default });
+        if (outcome.status === 'expired-operator') {
+            const row = outcome.row;
+            const when = row.untilMs === null ? '?' : new Date(row.untilMs).toISOString();
+            throw new OperatorWindowExpiredError(`freeze (${reason ?? kind}): la ventana del OPERADOR (${row.holder ?? '?'}, ${row.reason}, fence ` +
+                `${row.fence}) CADUCÓ el ${when} y nadie la cerró: desde entonces las escrituras volvieron a entrar en ` +
+                `toda la flota. No se toma una ventana propia encima —borraría ese rastro al soltarla y la pasada se ` +
+                `certificaría como si hubiera corrido dentro del cutover—. Reconócela con authz:unfreeze (dice cuánto ` +
+                `tiempo estuvo abierta y limpia la fila) y reabre la ventana con authz:freeze antes de repetir.`);
+        }
+        if (outcome.status === 'held') {
+            const row = outcome.row;
             throw new FreezeHeldError(`freeze: ya hay un freeze VIVO de otro dueño (${row.holder ?? '?'}, fence ${row.fence}, motivo: ${row.reason ?? '?'}). ` +
                 `Espera a que termine, o levántalo con authz:unfreeze si su proceso murió sin lease.`);
         }
+        const token = outcome.token;
         const held = { token, reason: finalReason, kind, leaseMs, timer: null, lapsed: false };
         if (leaseMs !== null) {
             const interval = Math.max(250, Math.floor(leaseMs / 3));
@@ -472,6 +505,39 @@ export class AuthorizationManager {
     get frozen() {
         return this.#root().#heldFreeze !== null;
     }
+    /**
+     * La clave (en `relations.drivers`) del driver de RELACIONES activo:
+     * `relations.default ?? default` (2.4.0-alpha.10). La lee el guard de la
+     * dirección rancia de `runRelationsReconcile`; desde el cierre del auditor
+     * (R4) el llamante ya no puede contradecirla con un `activeKey` propio.
+     */
+    relationsDriverKey() {
+        return activeRelationsDriverKey(this.#root().#config);
+    }
+    /** Las claves registradas en `relations.drivers` del config de ESTE manager (vacío si no hay relaciones). */
+    relationsDriverKeys() {
+        return Object.keys(this.#root().#config.relations?.drivers ?? {});
+    }
+    /**
+     * La factory registrada bajo `key` en `relations.drivers` de ESTE manager, o
+     * `undefined` (cierre del auditor de alpha.10 · R4). `runRelationsReconcile`
+     * resuelve el origen y el destino por aquí —del MISMO config que decide el
+     * activo— y juzga la identidad por la factory resuelta, no por la etiqueta:
+     * dos claves con la misma factory son el mismo driver (y dos factories DISTINTAS
+     * sobre el mismo backend NO: límite declarado, cierre-2 · C1).
+     *
+     * **API de PLATAFORMA, junto a `driver()`** (cierre-2 · C6): con esta factory
+     * cualquier código que tenga el manager —vistas de `forRequest()` incluidas—
+     * construye un driver de relaciones NO activo y escribe en él sin `assertWrite`,
+     * `requireActor`, freeze ni `onRelationWrite`. No añade capacidad (el config ya
+     * da las factories), pero es otra cosa que buscar en una revisión.
+     */
+    relationsDriverFactory(key) {
+        const drivers = this.#root().#config.relations?.drivers;
+        if (drivers === undefined || !Object.prototype.hasOwnProperty.call(drivers, key))
+            return undefined;
+        return drivers[key];
+    }
     /** El freeze VIVO de la fila compartida, o `null`. Lo lee cualquiera; solo el token lo levanta. */
     async freezeStatus() {
         const row = await readFreezeRow({ driver: this.#config.default });
@@ -479,12 +545,42 @@ export class AuthorizationManager {
             return null;
         return {
             reason: row.reason,
-            holder: row.holder ?? '?',
+            holder: row.holder ?? UNKNOWN_HOLDER,
             kind: freezeKindOf(row.holder),
             untilMs: row.untilMs,
             fence: row.fence,
         };
     }
+    /**
+     * **La ÚLTIMA ventana de la fila, también la CADUCADA** (2.4.0-alpha.10, 🟠 2
+     * del sexto informe de COGNITIV). `freezeStatus()` responde solo lo VIVO —y
+     * así lo siguen usando la barrera y los comandos—, de modo que una ventana
+     * cuyo lease venció era indistinguible de «nunca hubo»: `authz:unfreeze`
+     * decía éxito y el último paso del cutover no delataba que las escrituras
+     * habían vuelto a entrar a mitad. Se distingue por la fila: `releaseFreeze`
+     * pone el motivo a `null` al levantar, así que motivo puesto + `untilMs` en
+     * el pasado es una ventana que CADUCÓ sin que nadie la cerrase.
+     *
+     * `null` = nunca hubo o ya se levantó; `expired: false` = viva (lo mismo que
+     * `freezeStatus()`); `expired: true` = caducada. `checkedAtMs` es el instante
+     * del reloj del config con el que se decidió.
+     */
+    async lastFreezeStatus() {
+        const row = await readFreezeRow({ driver: this.#config.default });
+        if (row.reason === null)
+            return null;
+        const nowMs = this.#root().#wallMs();
+        return {
+            reason: row.reason,
+            holder: row.holder ?? UNKNOWN_HOLDER,
+            kind: freezeKindOf(row.holder),
+            untilMs: row.untilMs,
+            fence: row.fence,
+            expired: !freezeIsLive(row, nowMs),
+            // El instante (reloj del config) con el que se decidió `expired`.
+            checkedAtMs: nowMs,
+        };
+    }
     /**
      * `freeze()` + `finally unfreeze(token)`. El `finally` es la parte que
      * importa: una migración que revienta a la mitad no puede dejar la
@@ -502,7 +598,13 @@ export class AuthorizationManager {
             operatorAsContext: options.operatorAsContext === true,
         });
         try {
-            return await fn({ fence: context.fence, leaseMs: context.leaseMs, lapsed: context.lapsed });
+            return await fn({
+                fence: context.fence,
+                leaseMs: context.leaseMs,
+                lapsed: context.lapsed,
+                ...(context.untilMs === undefined ? {} : { untilMs: context.untilMs }),
+                ...(context.window === undefined ? {} : { window: context.window }),
+            });
         }
         finally {
             await context.release();
@@ -528,6 +630,7 @@ export class AuthorizationManager {
             return {
                 fence: outer.token.fence,
                 leaseMs: outer.leaseMs,
+                window: 'enclosing',
                 release: async () => { },
                 lapsed: () => root.#tokenLapsed(outer.token, outer.lapsed),
             };
@@ -536,9 +639,14 @@ export class AuthorizationManager {
             const status = await this.freezeStatus();
             if (status !== null && status.kind === 'operator') {
                 const token = { fence: status.fence, holder: status.holder };
+                // alpha.10 · 3: la caducidad REAL de la ventana adoptada. Hasta alpha.9
+                // `leaseMs: null` fijo — el reporte decía «sin caducidad» de una ventana
+                // abierta con `--lease-ms` (la certificación sí leía la fila).
                 return {
                     fence: status.fence,
-                    leaseMs: null,
+                    leaseMs: status.untilMs === null ? null : Math.max(0, status.untilMs - root.#wallMs()),
+                    untilMs: status.untilMs,
+                    window: 'operator',
                     release: async () => { },
                     lapsed: () => root.#tokenLapsed(token, false),
                 };
@@ -549,6 +657,7 @@ export class AuthorizationManager {
         return {
             fence: token.fence,
             leaseMs: held.leaseMs,
+            window: 'own',
             release: async () => {
                 try {
                     await this.unfreeze(token);
@@ -731,14 +840,19 @@ export class AuthorizationManager {
             //
             // Y cuando NO hay cadena —la fila ya no existe, que es el orden
             // soportado de `detached` (3F · S1)— no hay con qué canonizar: se
-            // purgan TODAS las ortografías de las que el uuid del llamante puede
-            // ser alias (`scopeSpellings`, 3b-2h · 🟠 3). Con la fila viva esto es
-            // exactamente una, la de la tabla; sin ella, la del llamante y la
-            // canónica que un motor pudo fundir con la suya. Antes se usaba la del
-            // llamante a secas: `purgeScope` demostraba cero sobre un objeto que no
-            // existe, devolvía OK, y el scope real seguía concediendo para siempre.
-            const chain = await resolveChain(this.#freshResolver(), child, 'scopes.detached');
-            const targets = chain ? [chain[0]] : scopeSpellings(child);
+            // purgan las ortografías de las que el uuid del llamante puede ser
+            // alias (`scopeSpellings`, 3b-2h · 🟠 3: lo que PG funde,
+            // `pgFusedSpellings`) MENOS las que el resolutor reconozca como un
+            // scope VIVO distinto del pedido (cierre-3 del lote A · 🟡 C2-2: con
+            // ids de texto, la canónica de un alias puede ser la unit viva de otro
+            // tenant, y `purgeScope` en `database` le borraría los denies). Con la
+            // fila viva esto es exactamente una, la de la tabla. El punto de paso
+            // es ÚNICO y compartido con `revoke`/`removeDeny` de los dos drivers
+            // (`canonicalScopeTargets`); un resolutor que falla al contrastar es
+            // 503, nunca «purgar por si acaso». Antes se usaba la del llamante a
+            // secas: `purgeScope` demostraba cero sobre un objeto que no existe,
+            // devolvía OK, y el scope real seguía concediendo para siempre.
+            const targets = await canonicalScopeTargets(this.#freshResolver(), child, 'scopes.detached');
             const outbox = this.#outbox();
             if (outbox) {
                 // La identidad se resuelve AQUÍ, con la fila del consumidor todavía
@@ -857,12 +971,13 @@ export class AuthorizationManager {
             throw new AuthorizationConfigError(`authz:scopes:relay: deadDetail solo admite 'full' (llegó ${JSON.stringify(options.deadDetail)}); sin él, bajo only, dead[] va sin error.`);
         }
         const inputs = await _a.#relayInputs(outbox, options.only, batchSize, options.deadDetail);
-        const { only, filter, dead, deadCount, deadEntries, missingOf } = inputs;
+        const { only, filter, dead, deadCount, deadEntries, unseenOf } = inputs;
         if (dryRun) {
             const batch = await outbox.pending(limit, undefined, filter);
             _a.#assertOnlyHonoured(batch, only);
             const extra = batch.length >= limit ? true : false;
             const seen = new Set([...batch.map((b) => String(b.id)), ...deadEntries.map((d) => String(d.id))]);
+            const unseen = await unseenOf(seen);
             // La edad es GLOBAL: sin filtro la cabeza es `batch[0]`; con `only` hay que mirar la cola entera.
             const queue = filter === undefined ? this.#queueOf(batch[0]) : (await this.#queueStatus(outbox)).queue;
             return {
@@ -878,7 +993,7 @@ export class AuthorizationManager {
                 dryRun: true,
                 wouldApply: batch.map((item) => ({ id: item.id, change: item.change, attempts: item.attempts })),
                 entries: deadEntries,
-                missing: missingOf(seen),
+                ...unseen,
             };
         }
         // El lease del escritor ÚNICO. Una outbox que no sabe darlo se comporta
@@ -919,8 +1034,14 @@ export class AuthorizationManager {
         // llegar a `batchSize`). Una sola lectura de más, y solo si no cabía.
         const census = dead.length < batchSize ? dead : await _a.#deadLetters(outbox, PARKED_CENSUS_MAX);
         const deadCount = census.length;
-        /** Lo aparcado que se pidió (con `only`) o todo lo aparcado, para `entries`. */
-        const deadEntries = read
+        /**
+         * Lo aparcado que se pidió (con `only`) o todo lo aparcado, para `entries`.
+         * Cierre-2 · C2 (gemelo): con `only` sale del CENSO completo si la lectura se
+         * cortó en `batchSize` — si no, un id pedido aparcado más allá del primer lote
+         * era `missing` («no estaba ni pendiente ni aparcado») estando aparcado.
+         */
+        const deadSource = only !== undefined && read.length >= batchSize ? census : read;
+        const deadEntries = deadSource
             .filter((item) => only === undefined || only.has(String(item.id)))
             .map((item) => ({
             id: item.id,
@@ -929,8 +1050,29 @@ export class AuthorizationManager {
             attempts: item.attempts,
             ...(item.error === undefined ? {} : { reason: item.error }),
         }));
-        const missingOf = (seen) => only === undefined ? [] : [...only.values()].filter((id) => !seen.has(String(id))).map((id) => _a.#rawId(onlyIds, id));
-        return { only, filter, dead, census, deadCount, deadEntries, missingOf };
+        /**
+         * **Qué fue de los ids pedidos que la pasada NO vio** (cierre-2 de alpha.10 ·
+         * C2). Hasta el cierre-2 todos eran `missing`; pero un id fuera del lote porque
+         * la pasada alcanzó `limit` sigue PENDIENTE. Se pregunta a la cola —filtrada por
+         * esos ids, sin límite propio, UNA lectura y solo si hay alguno sin ver—: lo que
+         * sigue pendiente es `notEvaluated`; el resto, `missing` (no está en la cola: lo
+         * aparcado ya está en `seen`).
+         */
+        const unseenOf = async (seen) => {
+            if (only === undefined)
+                return { missing: [], notEvaluated: [] };
+            const unseen = [...only.values()].filter((id) => !seen.has(id)).map((id) => _a.#rawId(onlyIds, id));
+            if (unseen.length === 0)
+                return { missing: [], notEvaluated: [] };
+            const stillPending = await outbox.pending(unseen.length, undefined, { ids: unseen });
+            _a.#assertOnlyHonoured(stillPending, new Set(unseen.map(String)));
+            const pendingIds = new Set(stillPending.map((item) => String(item.id)));
+            return {
+                missing: unseen.filter((id) => !pendingIds.has(String(id))),
+                notEvaluated: unseen.filter((id) => pendingIds.has(String(id))),
+            };
+        };
+        return { only, filter, dead, census, deadCount, deadEntries, unseenOf };
     }
     /** El reporte de una pasada que NO entró: otra tiene el lease. Nada aplicado, nada tocado. */
     async #busyReport(outbox, inputs) {
@@ -949,6 +1091,7 @@ export class AuthorizationManager {
             wouldApply: [],
             entries: inputs.deadEntries,
             missing: [],
+            notEvaluated: [],
         };
     }
     /**
@@ -1020,7 +1163,7 @@ export class AuthorizationManager {
      * (auditor 🟠 5: tomar el lease dos veces era `busy` en verde).
      */
     async #drainScopeChanges(outbox, input) {
-        const { limit, batchSize, only, filter, dead, census, deadCount, deadEntries, missingOf } = input;
+        const { limit, batchSize, only, filter, dead, census, deadCount, deadEntries, unseenOf } = input;
         const driver = await this.driver();
         const applied = [];
         const deferred = [];
@@ -1188,7 +1331,7 @@ export class AuthorizationManager {
             dryRun: false,
             wouldApply: [],
             entries,
-            missing: missingOf(new Set(entries.map((e) => String(e.id)))),
+            ...(await unseenOf(new Set(entries.map((e) => String(e.id))))),
         };
     }
     /**
@@ -1586,6 +1729,49 @@ export class AuthorizationManager {
             throw new UnsupportedOperationError('reconcile', `authz:reconcile --to=${name}`, name, `El driver '${name}' no sabe reconstruirse desde 'authz_*' + el árbol del consumidor. ` +
                 `El driver 'database' es ese caso a propósito: sus tablas son el ORIGEN.`);
         }
+        // **La dirección RANCIA** (2.4.0-alpha.10; 🔴 4 del sexto informe de
+        // COGNITIV y cuarta iteración del LINAJE «origen rancio del reconcile»:
+        // 3b-5 cerró la pasada por defecto, el primer guard de alpha.10 cerró
+        // `--from`, y quedaba abierto el origen elegido POR DESCARTE). Regla del
+        // dueño: el tercer defecto de un linaje se arregla estructuralmente, así
+        // que el guard NO mira la bandera, mira el ORIGEN RESUELTO — con la MISMA
+        // decisión que `#factsOrigin` (`#isMaintenancePass`), no con una copia:
+        // si `to` es el driver ACTIVO, el único origen legítimo es `to` mismo (la
+        // pasada de MANTENIMIENTO); cualquier otro —`--from`, el driver elegido por
+        // descarte o las tablas `authz_*`— dejó de ver los hechos en el cutover y la
+        // pasada re-escribiría lo revocado después (con o sin --prune; el seguro de
+        // borrado masivo no salta: el origen no está vacío). Se decide por `to`,
+        // nunca por `from`: el cutover inicial y la vuelta atrás ANTES de cambiar
+        // `default` tienen `to` ≠ activo y pasan. Antes de resolver el origen y de
+        // congelar. `--dry-run` no lanza (es el verificador): lo marca y
+        // `reconcileLines` lo hace deriva. `from === to` sigue siendo el 500
+        // E_AUTHZ_CONFIG de 3b-3b.
+        const stale = this.#sameDriver(name, this.#config.default) &&
+            (options.from === undefined || !this.#sameDriver(options.from, name)) &&
+            !this.#isMaintenancePass(name, target, options.from);
+        const allowStale = options.allowStaleSource === true;
+        if (stale && !allowStale && options.dryRun !== true) {
+            const how = options.from !== undefined ? `--from=${options.from}` : 'sin --from';
+            // Cierre del auditor (⚪ 8): con UN solo driver registrado no hay descarte que
+            // hacer; la letra no puede hablar de un origen que no existe.
+            const others = Object.keys(this.#config.drivers ?? {}).filter((key) => !this.#sameDriver(key, name));
+            const originLabel = options.from !== undefined
+                ? `el origen '${options.from}' no lo es`
+                : others.length === 0
+                    ? `no hay ningún otro driver registrado ni pasada de mantenimiento para él (no guarda sus hechos en su ` +
+                        `backend: no declara hierarchyFacts), así que no hay nada de dónde reconciliar hacia '${name}'`
+                    : `sin --from el origen se elegiría POR DESCARTE (las tablas authz_* u otro driver registrado: ` +
+                        `${others.join(', ')}), y no es '${name}'`;
+            throw new StaleSourceRefusedError(`authz:reconcile --to=${name} ${how}: '${name}' es el driver ACTIVO (config.default` +
+                `${name === this.#config.default ? '' : `: la clave resuelve la MISMA factory que '${this.#config.default}'`}) y ${originLabel}. ` +
+                `Esa dirección re-escribiría en el driver activo hechos que el origen ya no refleja: resucitaría las ` +
+                `revocaciones hechas desde el cutover (y con --prune borraría lo concedido después). No se ha leído, ` +
+                `congelado ni escrito nada. Hacia el driver activo el único origen es él mismo: la pasada de mantenimiento ` +
+                `(authz:reconcile --to=${name} [--dry-run], sin --from) si su driver guarda sus hechos; y si lo que quieres ` +
+                `es volver atrás, migra en la otra dirección ANTES de cambiar config.default. Si de verdad el origen sigue ` +
+                `siendo la fuente de verdad (el motor aún no ha escrito desde '${name}'), la decisión humana es ` +
+                `--allow-stale-source (allowStaleSource: true).`);
+        }
         // **De dónde salen los HECHOS** (3b-5): la decisión que faltaba, y la que
         // el destino no puede tomar por su cuenta. Ver `#factsOrigin`.
         const origin = await this.#factsOrigin(name, target, options.from);
@@ -1596,7 +1782,7 @@ export class AuthorizationManager {
             // `authz_*` no construye ningún driver de más. Y el origen se resuelve
             // UNA vez.
             facts: origin.enumerate,
-            factsOrigin: { name: origin.name, authzTables: origin.authzTables },
+            factsOrigin: { name: origin.name, authzTables: origin.authzTables, ...(origin.self ? { self: true } : {}) },
             // El techo de profundidad del consumidor, si lo declaró (alpha.5 · R0):
             // el mismo mando que el gate de `scopes.*`.
             ...(this.#config.scopes?.maxDepth === undefined ? {} : { maxDepth: this.#config.scopes.maxDepth }),
@@ -1618,6 +1804,8 @@ export class AuthorizationManager {
             // Quién fue el origen se DICE, siempre: es la diferencia entre una
             // migración y una pasada de mantenimiento contra el driver activo.
             report.factsFrom = origin.resolved();
+            if (stale)
+                report.staleSource = { to: name, from: origin.resolved(), allowed: allowStale };
             return report;
         };
         // La pasada que escribe congela; el verificador NO (ver el docblock).
@@ -1641,6 +1829,8 @@ export class AuthorizationManager {
                 lapsed: await window.lapsed(),
                 leaseMs: window.leaseMs,
                 fence: window.fence,
+                ...(window.untilMs === undefined ? {} : { untilMs: window.untilMs }),
+                ...(window.window === undefined ? {} : { window: window.window }),
             };
             return report;
         }
@@ -1668,7 +1858,9 @@ export class AuthorizationManager {
      *     MANTENIMIENTO: los hechos se leen del propio destino por el puerto
      *     (`enumerateFacts`), se rehace lo DERIVADO (marcador, catálogo, árbol)
      *     y se aplica el barrido de visibilidad del invariante 18 con el árbol
-     *     y el catálogo de HOY. No se inventa ni se borra un solo hecho. Un
+     *     y el catálogo de HOY. No se inventa ningún hecho; con `--prune` se
+     *     borran los que ya no respaldan nada (scopes que ya no resuelven,
+     *     caducados, roles/permisos retirados, y los que sobran). Un
      *     destino activo con `hierarchyFacts` que no sepa enumerar sus hechos
      *     es 500 `E_AUTHZ_UNSUPPORTED`: leerle `authz_*` sería justo el defecto.
      *  2. **`--from=<nombre>` manda**, y por eso se resuelve YA: de la
@@ -1682,7 +1874,7 @@ export class AuthorizationManager {
      *     de 3b-3b (`#factsEnumerator`).
      */
     async #factsOrigin(to, target, from) {
-        if (from === undefined && to === this.#config.default && target.capabilities?.hierarchyFacts === true) {
+        if (this.#isMaintenancePass(to, target, from)) {
             if (typeof target.enumerateFacts !== 'function') {
                 throw new UnsupportedOperationError('enumerateFacts', `authz:reconcile --to=${to}`, to, `El motor SIRVE desde '${to}' y ese driver declara que el árbol y los hechos viven en su backend ` +
                     `(hierarchyFacts), así que 'authz_assignments'/'authz_denies' NO son la fuente de verdad de sus ` +
@@ -1692,6 +1884,7 @@ export class AuthorizationManager {
             return {
                 name: to,
                 authzTables: false,
+                self: true,
                 enumerate: (page) => target.enumerateFacts(page),
                 resolved: () => to,
             };
@@ -1717,10 +1910,44 @@ export class AuthorizationManager {
         });
         return { name: AUTHZ_TABLES_ORIGIN, authzTables: true, enumerate, resolved: () => resolvedName };
     }
+    /**
+     * **¿Es la pasada de MANTENIMIENTO?** (3b-5; punto ÚNICO desde alpha.10): el
+     * destino es el driver ACTIVO, sus hechos viven en su backend
+     * (`hierarchyFacts`) y nadie nombró otro origen. Es la ÚNICA forma en la que
+     * el origen resuelto de una pasada hacia el driver activo es el propio
+     * destino, y la usan los dos que la necesitan: `#factsOrigin` (de dónde se
+     * leen los hechos) y el guard de la dirección rancia de `reconcile` (si ese
+     * origen es legítimo). Dos copias de esta condición eran dos respuestas.
+     */
+    #isMaintenancePass(to, target, from) {
+        return from === undefined && this.#sameDriver(to, this.#config.default) && target.capabilities?.hierarchyFacts === true;
+    }
+    /**
+     * **¿Dos claves de `drivers` son el MISMO driver?** (cierre del auditor de
+     * alpha.10 · R4, gemelo de roles): misma clave o la MISMA factory registrada
+     * bajo dos claves. El guard de la dirección rancia, el mantenimiento, el
+     * `from === to` y el descarte juzgan la identidad RESUELTA, no la etiqueta:
+     * con `drivers: { openfga: f, fga: f }` y `default: 'openfga'`, `--to=fga
+     * --from=database` es la misma dirección rancia que `--to=openfga`.
+     *
+     * **Límite DECLARADO (cierre-2 · C1)**: la identidad es la REFERENCIA de la
+     * factory, no el backend. Dos factories distintas que construyen el mismo
+     * store (`openfga: () => new OpenFga…(…)`, `fga: () => new OpenFga…(…)`) NO son
+     * el mismo driver para este predicado y el alias pasa el guard. Identidad de
+     * backend declarada por el driver ⇒ roadmap 2.5.
+     */
+    #sameDriver(a, b) {
+        if (a === b)
+            return true;
+        const drivers = this.#config.drivers ?? {};
+        const own = (key) => (Object.prototype.hasOwnProperty.call(drivers, key) ? drivers[key] : undefined);
+        const fa = own(a);
+        return fa !== undefined && fa === own(b);
+    }
     /** El driver que `--from` nombra, con los dos errores de 3b-3b intactos. */
     async #originDriver(from, to) {
         const registered = Object.keys(this.#config.drivers ?? {});
-        if (from === to) {
+        if (this.#sameDriver(from, to)) {
             throw new AuthorizationConfigError(`authz:reconcile --from=${from} --to=${to}: el origen y el destino son el mismo driver. ` +
                 `Si lo que quieres es VERIFICAR y reparar lo derivado del driver activo, no lo digas con --from: ` +
                 `la pasada ya lee sus hechos de él cuando es el driver por defecto.`);
@@ -1756,7 +1983,7 @@ export class AuthorizationManager {
             const registered = Object.keys(this.#config.drivers ?? {});
             const candidates = [];
             for (const candidate of registered) {
-                if (candidate === to)
+                if (this.#sameDriver(candidate, to))
                     continue;
                 const driver = await this.#config.drivers[candidate]();
                 if (typeof driver.enumerateFacts === 'function')
@@ -2188,7 +2415,7 @@ export class AuthorizationManager {
             const answer = await driver.authorizeMany(subject, permission, scopes);
             // Un `boolean[]` desalineado se leería por posición (F5, CR3): es un
             // bug del driver, no una decisión. 500 nombrando al culpable.
-            if (!Array.isArray(answer) || answer.length !== scopes.length || answer.some((b) => typeof b !== 'boolean')) {
+            if (!Array.isArray(answer) || answer.length !== scopes.length || !everyPositionBoolean(answer)) {
                 throw new AuthorizationInternalError(`authorizeMany: el driver '${this.#config.default}' devolvió ${describeAnswer(answer)} para ${scopes.length} scopes; ` +
                     `el puerto exige un boolean[] con exactamente una posición por scope.`);
             }