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

package/build/src/relations/reconcile.js

@@ -27,12 +27,14 @@
  * clave, niega la dirección rancia y congela; la guardia de superficie de
  * `command_flags.spec.ts` impide re-exportarlo por ningún subpath.
  */
-import { AuthorizationConfigError, InvalidIdentityError, MassReconcileRefusedError, RelationTypeUnknownError, RelationUnknownError, UnsupportedOperationError, } from '../errors.js';
+import { ActorRequiredError, AuthorizationConfigError, CheckManyBatchError, DenyMigrationRefusedError, InvalidIdentityError, InvalidSlugError, MassReconcileRefusedError, NoScopeResolverError, RelationConfigError, RelationConfigUnknownKeyError, RelationDenyExpiryError, RelationNotDenyableError, RelationTypeUnknownError, RelationUnknownError, RelationUsersetUnsupportedError, UnknownScopeError, UnsupportedOperationError, isPartialWrite, markPartialWrite, } from '../errors.js';
 import { systemClock } from '../clock.js';
 import { isActiveExpiry, sameInstant } from '../expiry.js';
 import { assertPartition, scopeKey } from '../identity.js';
 import { isRelUserset } from '../types.js';
+import { assertRelationDeclared, assertSupportedUserset, RELATION_DENY_PREFIX, RELATION_USERSET_TYPE, relationsUp } from './define_relations_config.js';
 import { relationTupleKey } from './tuple_key.js';
+import { carriedDenies, denyCarrierGroups, relationTransitionOrder } from './tuple_order.js';
 /**
  * La clave con la que se casan origen y destino es `relationTupleKey` (plan
  * 2.5 · lote A, P3-4): la MISMA función pura y exportada que un consumidor
@@ -43,6 +45,101 @@ import { relationTupleKey } from './tuple_key.js';
  * (`tests/relation_tuple_key.spec.ts` lo vigila por fuente).
  */
 const tupleKey = relationTupleKey;
+/**
+ * **Una tupla ENUMERADA por un store con una identidad fuera de la gramática**
+ * (⚪ R2 del re-ataque al cierre del lote A, decisión del dueño 2026-10-15 (2)):
+ * `document:<key>|ABC` escrita a mano con el SDK, una fila con `object_uuid`
+ * en mayúsculas insertada por otro proceso… `relationTupleKey` valida cada
+ * componente (⚪ A9) y hasta el cierre-2 `planPartition` la aplicaba tal cual a
+ * lo enumerado, así que un dato malo del BACKEND salía como 422
+ * `E_AUTHZ_INVALID_IDENTITY` —«pregunta inválida» del llamante, invariante 5—
+ * y bloqueaba el reconcile de la partición entera, también con `--dry-run`.
+ * Ahora se CLASIFICA y se LISTA: en el destino es `extra` con motivo
+ * (`--prune` pide al driver que la borre; `--dry-run` la lista con su línea),
+ * en el origen no se migra (la API no puede escribirla) y es deriva. Nunca un
+ * 422 por un dato que no vino del llamante.
+ */
+/**
+ * **Los motivos de `RelationsReconcileDetail`, en RUNTIME** (cierre 2 de D2 · ⚪ N6): la guardia L9
+ * (`tests/relations_reconcile_l9.spec.ts`) los recorre y exige que cada uno tenga su entrada en `RELATION_RESIDUES`
+ * (dónde se clasifica: el PLAN o la PASADA) y su caso. `renewal-unsafe` (cierre 2 de D2 · 🟠 N1, solo `destino`): la
+ * renovación (otra caducidad) de una membresía `group:*#member` que TRANSPORTA un deny, en un destino que no declara
+ * `atomicRenewal` (renueva con delete + write, `openfga`): entre los dos `Write` el deny no alcanzaría al sujeto. Desde el
+ * cierre 5 de D2 (opción A) NIEGA SU PARTICIÓN (`partitionsRefused`: cero escrituras y cero borrados en ella, el resto
+ * migra); la línea la nombra con su receta y es deriva. `withheld-by-unsafe-deny` (cierre 4) se fue con la retención.
+ */
+export const RELATIONS_RECONCILE_DETAIL_REASONS = Object.freeze([
+    'invalid-identity',
+    'userset-unsupported',
+    'undeclared',
+    'deny-conditional',
+    'renewal-unsafe',
+]);
+/**
+ * **Una receta POR MOTIVO** (cierre 1 de D2 · 🟡 6, ⚪ 11). `honor` = el deny ya está en el destino y lo que falta es
+ * que lo honre (opt-in), no que lo escriba. La de `undeclared` está EJECUTADA en `relations_reconcile_deny.spec`
+ * (re-declarar → `removeDeny` → retirar ⇒ la pasada entra).
+ */
+export function denyRefusalRecipe(reason, objectType, relation, honor = false) {
+    const pair = `${objectType}#${relation}`;
+    switch (reason) {
+        case 'no-capability':
+            return (`el destino no sabe escribir ni honrar denies: migra a un destino que declare relationDenies (los dos drivers del ` +
+                `paquete lo hacen desde 2.5.0-alpha.3), o retira esos denies en el ORIGEN con removeDeny, y repite.`);
+        case 'no-deny-phase':
+            return (`un driver de terceros que declara relationDenies tiene que traer denyPhase(type, relation) (puerto, 2.5.0-alpha.3): ` +
+                `actualízalo; o retira esos denies en el ORIGEN con removeDeny, y repite.`);
+        case 'phase':
+            return honor
+                ? `declara el opt-in de '${objectType}' en la config del DESTINO (deny: 'read' basta para honrar un deny que ya está) ` +
+                    `—provision → fijar modelId → desplegar—, o retira ese deny del destino con removeDeny, y repite.`
+                : `pon '${objectType}' en deny: 'write' en la config del DESTINO —provision → fijar modelId → desplegar, README ` +
+                    `«Upgrading to 2.5.0-alpha.3»—, o retira esos denies en el ORIGEN con removeDeny, y repite.`;
+        case 'undeclared':
+            return (`${pair} no está declarado. Si es una relación RETIRADA con denies vivos: vuelve a declarar la relación ` +
+                `TEMPORALMENTE en la config del proceso que escribe en el ORIGEN (la relación basta: removeDeny no exige el opt-in), ` +
+                `retira esos denies con removeDeny, quítala otra vez y repite — removeDeny sobre un par NO declarado es 422 (F-05). ` +
+                `Si el destino debe tenerla: declárala en la config del DESTINO.`);
+        case 'model':
+            return (`el modelo FIJADO del destino no declara ${objectType}#denied_${relation}: publica el modelo desde la config del ` +
+                `destino (openfga:provision --store-id) y fija el OPENFGA_MODEL_ID nuevo en el proceso que corre la pasada (y en la ` +
+                `flota), y repite.`);
+        case 'unmarked':
+            return (`el driver que enumera esa tupla (origen o destino: lo dice el mensaje) no marca kind: 'deny' — un driver de terceros ` +
+                `o un proceso < 2.5.0-alpha.3 —: actualízalo y repite. La pasada no la toca: su dueño es ese driver.`);
+        case 'invalid':
+            return (`la identidad o el sujeto del deny no entra en la gramática del destino, y removeDeny también la rechazaría: bórralo ` +
+                `a mano en el ORIGEN (database: DELETE de esa fila de authz_relations; openfga: un Write con delete) y repite.`);
+    }
+}
+/**
+ * **La receta de una partición NEGADA** (cierre 5 de D2, opción A), por el conjunto de causas. HONESTA a propósito: en
+ * un destino sin `atomicRenewal` (`openfga`: FGA no reemplaza la misma clave en un `Write` —no hay upsert,
+ * openfga/openfga#2151—) NO existe forma sin ventana de cambiar la caducidad de una membresía que transporta un deny, ni
+ * de rehacer permanente un deny con caducidad. Ninguna de las salidas de abajo se presenta como segura.
+ */
+export function partitionRefusalRecipe(reasons) {
+    const set = new Set(reasons);
+    const out = [];
+    if (set.has('renewal-unsafe')) {
+        out.push(`renewal-unsafe: en este destino NO hay forma sin ventana de cambiar la caducidad de una membresía cuyo grupo ` +
+            `transporta un deny (la renovación son dos Write; openfga/openfga#2151, sin upsert). Salidas para ESTA partición ` +
+            `(ninguna sin precio): (1) unrelate de esa membresía en el ORIGEN, y repite (sin --prune el destino la conserva hasta ` +
+            `su caducidad; con --prune se borra, como en el origen). (2) unrelate + relate de esa membresía en el DESTINO con la ` +
+            `caducidad del ORIGEN (o SIN caducidad, si el origen no la tiene) aceptando la ventana de forma EXPLÍCITA — mientras ` +
+            `dura, el sujeto no recibe el deny del grupo y concede lo que otro camino le dé y ese deny corte —, y repite la pasada. ` +
+            `(3) Esperar a que venza la caducidad vieja del DESTINO: entonces la tupla cuenta como ausente, la reescritura es una ` +
+            `escritura normal y la partición migra sola — y en ese intervalo el destino concede lo que ese deny corta (la línea ` +
+            `lo fecha). Cambiar la membresía a SIN caducidad en el ORIGEN NO desbloquea la partición (la del destino caduca: sigue ` +
+            `siendo un cambio de caducidad). Para el FUTURO, el patrón recomendado: membresías SIN caducidad en los grupos con ` +
+            `deny, que se terminan con unrelate.`);
+    }
+    if (set.has('deny-conditional')) {
+        out.push(`deny-conditional: un deny no caduca (D3) y este destino no puede rehacerlo permanente en una escritura. removeDeny + ` +
+            `deny de esa tupla en el DESTINO aceptando la ventana de forma EXPLÍCITA — entre los dos el deny no niega —, y repite.`);
+    }
+    return out.join(' ');
+}
 /**
  * Enumera TODAS las tuplas de las particiones pedidas, repartidas por clave de
  * partición. UNA pasada con `enumerateRelationsMany` si el driver lo trae
@@ -104,16 +201,29 @@ export async function reconcileRelations(options) {
     // alpha.6: origen y destino se enumeran UNA vez para todas las particiones.
     const enumeratedByKey = await enumerateAllMany(from, partitions, 'origen');
     const destByKeyAll = await enumerateAllMany(to, partitions, 'destino');
-    // Primero se DECIDE todo (K diffs, K seguros R-17) y luego se escribe: un
-    // seguro que salte en la partición 3 no deja las dos primeras a medias.
+    // Primero se DECIDE todo (K diffs, K seguros R-17, la puerta del deny) y luego se escribe: un seguro que salte en la
+    // partición 3 no deja las dos primeras a medias.
+    // Cierre 2 de D2 · 🟡 N3: el auto-corte del orden (un deny de `d` corta un allow de `a` sii `d ∈ up*(a)`, D5) sale de la
+    // config del DESTINO; sin ella el orden no da ningún allow por cortado (lo conservador). Cierre 4: también la retención.
+    const cuts = toConfig
+        ? (objectType, denied, allowed) => {
+            try {
+                return relationsUp(toConfig, objectType, allowed).includes(denied);
+            }
+            catch {
+                return false;
+            }
+        }
+        : undefined;
     const plans = [];
     for (const partition of partitions) {
         const enumerated = enumeratedByKey.get(scopeKey(partition)) ?? [];
         const destTuples = destByKeyAll.get(scopeKey(partition)) ?? [];
-        plans.push(planPartition(partition, enumerated, destTuples, { now, prune, toConfig }));
+        plans.push(planPartition(partition, enumerated, destTuples, { now, prune, toConfig, atomicRenewal: to.capabilities?.atomicRenewal === true, cuts }));
     }
     const report = {
         dryRun,
+        prune,
         written: 0,
         updated: 0,
         deleted: 0,
@@ -122,8 +232,12 @@ export async function reconcileRelations(options) {
         modelDrift: [],
         massDelete: false,
         allowMassDelete,
-        skipped: { expired: 0, undeclared: 0, invalid: 0 },
+        skipped: { expired: 0, undeclared: 0, invalid: 0, usersetUnsupported: 0 },
         details: [],
+        denies: { written: 0, updated: 0, deleted: 0, unchanged: 0, extra: 0 },
+        partitions: plans.map((plan) => emptyPartitionReport(plan.partition)),
+        orderResidue: [],
+        partitionsRefused: [],
     };
     for (const plan of plans) {
         // **El seguro de borrado masivo** (R-17, paridad con `authz:reconcile` de
@@ -132,13 +246,11 @@ export async function reconcileRelations(options) {
         // vacío: vaciar el destino entero se rechaza con 500 antes de tocar nada,
         // salvo `allowMassDelete`. En `--dry-run` no lanza, lo marca. «Utilizable» =
         // una tupla VIVA del origen que cabe en el destino (las que `skipped`
-        // recoge no migran, así que no cuentan como respaldo).
+        // recoge no migran, así que no cuentan como respaldo) — **denies incluidos** (D2).
         if (plan.massDelete && !dryRun && !allowMassDelete) {
-            throw new MassReconcileRefusedError(`authz:relations:reconcile --prune borraría ${plan.toDelete.length} tupla(s) de relación del destino` +
+            throw new MassReconcileRefusedError(`authz:relations:reconcile --prune borraría ${plan.allowDelete.length + plan.denyDelete.length} tupla(s) de relación del destino` +
                 `${partitions.length > 1 ? ` (partición ${scopeKey(plan.partition)})` : ''} y el ` +
-                `ORIGEN no ha aportado NI UNA utilizable (${plan.enumerated} leídas` +
-                `${toConfig ? ', todas de tipos que el destino no declara' : ''}` +
-                `${plan.skipped.expired ? `, ${plan.skipped.expired} caducada(s)` : ''}). Eso es la firma de un --from ` +
+                `ORIGEN no ha aportado NI UNA utilizable (${plan.enumerated} leídas${describeSkipped(plan.skipped)}). Eso es la firma de un --from ` +
                 `equivocado o de un store vacío, no de un destino que sobra: esta pasada dejaría la partición sin ` +
                 `una sola relación. Comprueba el --from y el store; si de verdad quieres vaciarlo, --allow-mass-delete.` +
                 `${partitions.length > 1 ? ' No se ha escrito nada en ninguna partición.' : ''}`);
@@ -147,76 +259,347 @@ export async function reconcileRelations(options) {
         report.skipped.expired += plan.skipped.expired;
         report.skipped.undeclared += plan.skipped.undeclared;
         report.skipped.invalid += plan.skipped.invalid;
+        report.skipped.usersetUnsupported += plan.skipped.usersetUnsupported;
         for (const type of plan.modelDrift)
             if (!report.modelDrift.includes(type))
                 report.modelDrift.push(type);
     }
-    for (const plan of plans) {
-        let written = plan.toWrite.length;
-        let updated = plan.toUpdate.length;
-        if (!dryRun) {
-            // La caducidad viaja EXPLÍCITA (`Date` la fija, `null` la quita): un
-            // `relate` sin opciones PRESERVARÍA la del destino (invariante 10).
-            // L-0: el DRIVER del destino aplica F-05 (`assertRelationDeclared`), así que
-            // sin `toConfig` —o con una que no coincida con la del driver— es SU 422 el
-            // que embuda la tupla no declarada: se cuenta en `skipped.undeclared` y se
-            // descuenta de `written`/`updated`. Nunca un throw a mitad de pasada por
-            // una tupla que el reporte puede contar, y nunca un silencio.
-            for (const tuple of plan.toWrite) {
-                if (await relateOrSkip(to, tuple))
+    // **La puerta del deny, por el DRIVER DESTINO y en la fase de PLAN** (lote D · D2; S6, R2-5): antes de la primera
+    // escritura en CUALQUIER partición. Un deny que no se puede escribir (o que el destino no honraría) ⇒ 500 con CERO
+    // escrituras; jamás `skipped` (escribir los allows sin él concedería lo que el origen niega). `--dry-run` lo marca.
+    const refusals = await denyGate(to, plans);
+    if (refusals.length > 0) {
+        if (!dryRun)
+            throw denyRefusedError(refusals, partitions.length);
+        report.denyRefused = refusals;
+    }
+    // Lo escrito en TODA la pasada: decide la marca de escritura parcial si algo revienta (invariante 13).
+    const progress = { writes: 0 };
+    for (let i = 0; i < plans.length; i++) {
+        const plan = plans[i];
+        const row = report.partitions[i];
+        // Cierre 5 de D2 (opción A): la partición NEGADA por el plan no se toca —cero escrituras y cero borrados—; las demás
+        // siguen. Mismo resultado en `--dry-run` y en la pasada real.
+        if (plan.refusal) {
+            refusePartition(plan, row, report, prune);
+            continue;
+        }
+        try {
+            await applyPartition(plan, row, report, { to, dryRun, prune, progress, cuts });
+            row.status = 'done';
+        }
+        catch (error) {
+            row.status = 'failed';
+            throw partialReconcileError(error, report, progress.writes);
+        }
+        addPartition(report, row);
+    }
+    return report;
+}
+/**
+ * **Una partición NEGADA** (cierre 5 de D2, opción A): cero escrituras, cero borrados. El reporte dice lo que había
+ * (`unchanged`), lo que sobra y se queda (`extra`, también con `--prune`: no se borra nada) y, en `partitionsRefused`, por
+ * qué, la receta y la deriva pendiente. Los residuos de la partición (`details`) se listan igual que en una aplicada.
+ */
+function refusePartition(plan, row, report, prune) {
+    const refusal = plan.refusal;
+    const PRUNABLE = new Set(['invalid-identity', 'userset-unsupported', 'undeclared']);
+    for (const detail of plan.details) {
+        report.details.push(prune && detail.side === 'destino' && PRUNABLE.has(detail.reason) ? { ...detail, pruned: false } : detail);
+    }
+    row.status = 'refused';
+    row.unchanged = plan.unchanged + plan.denyUnchanged;
+    row.denies.unchanged = plan.denyUnchanged;
+    row.denies.extra = plan.denyDelete.length + plan.denyConditional;
+    row.extra = plan.allowDelete.length + plan.denyDelete.length + plan.destResidue + plan.denyConditional;
+    report.partitionsRefused.push(refusal);
+    addPartition(report, row);
+}
+/** Un reporte de partición a cero, `pending` hasta que se aplica. */
+function emptyPartitionReport(partition) {
+    return {
+        partition: scopeKey(partition),
+        status: 'pending',
+        written: 0,
+        updated: 0,
+        deleted: 0,
+        unchanged: 0,
+        extra: 0,
+        denies: { written: 0, updated: 0, deleted: 0, unchanged: 0, extra: 0 },
+    };
+}
+/** Suma una partición al total del reporte. */
+function addPartition(report, row) {
+    report.written += row.written;
+    report.updated += row.updated;
+    report.deleted += row.deleted;
+    report.unchanged += row.unchanged;
+    report.extra += row.extra;
+    for (const k of ['written', 'updated', 'deleted', 'unchanged', 'extra'])
+        report.denies[k] += row.denies[k];
+}
+/**
+ * **El reporte PARCIAL viaja en el error** (roadmap 2.5): las particiones `done` y lo que la `failed` llegó a escribir,
+ * sumados; `partial: true` si escribió algo (⚪ 10: `false` con cero escrituras); y la marca de escritura parcial (`markPartialWrite`, invariante 13) si la pasada escribió
+ * algo. El error, su clase y su `code` no cambian (un 503 sigue siendo un 503).
+ */
+function partialReconcileError(error, report, writes) {
+    const failed = report.partitions.find((p) => p.status === 'failed');
+    if (failed)
+        addPartition(report, failed);
+    // ⚪ 10 (cierre 1 de D2): «parcial» solo si la pasada YA escribió algo; con cero escrituras el reporte viaja igual
+    // (`partial: false`) y el comando dice que no se escribió nada — la marca `markPartialWrite` y la letra, de acuerdo.
+    // Cierre 2 de D2 · 🟠 N1: o lo dice el DRIVER — un `relate` de renovación de `openfga` (delete + write) cuyo 2.º
+    // `Write` falla ya BORRÓ: el error llega marcado (`isPartialWrite`) aunque la pasada no hubiera completado ninguna
+    // escritura, y «sin escribir nada» sería falso.
+    const partial = writes > 0 || isPartialWrite(error);
+    report.partial = partial;
+    const out = partial && error && typeof error === 'object' ? markPartialWrite(error) : error;
+    try {
+        if (out && typeof out === 'object' && Object.isExtensible(out))
+            out.report = report;
+    }
+    catch {
+        /* un error congelado no lleva el reporte; el original no se sustituye */
+    }
+    return out;
+}
+/**
+ * **Las fases de una partición** (lote D · D2; analista §4.7, juez ronda 2 · R2-5, tester S4/S5), en el ORDEN del punto
+ * de paso ÚNICO `relationTransitionOrder` (`src/relations/tuple_order.ts`, compartido con las purgas de `openfga`). Desde
+ * el cierre 2 de D2 (🟡 N3) el orden es el de la TRANSICIÓN entera —escrituras, renovaciones y poda en UNA secuencia—:
+ * (1) denies nuevos y rehechos (`to.deny`), (2) con `prune` allows sobrantes (`unrelate`), (3) membresías
+ * `group:*#member` que entran y que salen por el grafo de precedencias, (4) allows nuevos y renovaciones (`relate`), (5)
+ * con `prune` denies sobrantes (`to.removeDeny`), los ÚLTIMOS. Hasta el cierre 2 TODAS las escrituras iban antes que
+ * TODA la poda, y un ex-miembro componía con un allow nuevo (U ∈ g sobra y `g#member viewer X` es nuevo: cortada tras la
+ * primera escritura, U concedía sobre X). Cortada en cualquier punto, ningún estado concede lo que no concedían ni el
+ * estado inicial ni el final, salvo el RESIDUO que `relationTransitionOrder` devuelve (un ciclo del grafo de precedencias;
+ * se lista en `report.orderResidue`). **Ningún deny pasa por `relateOrSkip`**: un error al escribir un deny se propaga
+ * (la puerta del plan ya decidió que se puede escribir; si el driver dice otra cosa, es una contradicción que aborta).
+ * Son las propiedades `relations.reconcile.order` y `relations.order.exhaustive` de la guardia de superficie (L10).
+ */
+async function applyPartition(plan, row, report, context) {
+    const { to, dryRun, prune, progress, cuts } = context;
+    // Cierre 4 de D2 · 🟡 C3-2: el deny condicional que el destino no puede rehacer se decide en el PLAN (dry == real).
+    const conditional = plan.denyConditional;
+    row.unchanged = plan.unchanged + plan.denyUnchanged;
+    row.denies.unchanged = plan.denyUnchanged;
+    // ⚪ R2 + cierres 1, 2 y 3 del lote B (una regla por FILA): el residuo del destino y lo enumerado fuera de la
+    // gramática se LISTA siempre, en los dos lados; con `prune` el del destino lleva `pruned: false` desde el plan. El
+    // `renewal-unsafe` (cierre 2 de D2 · 🟠 N1) no es un borrado: no lleva `pruned`.
+    // Cierre 4 de D2: `deny-conditional` (ya del PLAN) lleva `pruned: false` siempre.
+    const PRUNABLE = new Set(['invalid-identity', 'userset-unsupported', 'undeclared']);
+    for (const detail of plan.details) {
+        report.details.push(prune && detail.side === 'destino' && PRUNABLE.has(detail.reason) ? { ...detail, pruned: false } : detail);
+    }
+    // Cierre 2 de D2 · 🟡 N3: UNA secuencia para la transición entera (el mismo cálculo en `--dry-run` y en la real).
+    // Cierre 3 de D2 · 🟡 C2-2: las sobrantes VENCIDAS no conectan nada: se borran PRIMERO y FUERA del orden. Dentro, un deny
+    // vencido que se poda contaba en el grafo unión como un deny que «ya niega» y quitaba una precedencia (medido por la
+    // fuerza bruta con vigencia: U ∈ h entraba antes de que h ⊂ g saliera).
+    const liveDeletes = [...plan.allowDelete, ...plan.denyDelete].filter((tuple) => !plan.expiredDelete.has(tuple));
+    const transition = relationTransitionOrder({
+        writes: [...plan.denyWrite, ...plan.toWrite],
+        deletes: prune ? liveDeletes : [],
+        renewals: [...plan.denyUpdate, ...plan.toUpdate],
+        // Cierre 4 de D2 · 🟡 horizonte: las renovaciones que ACORTAN salen en su caducidad nueva (y las que alargan entran
+        // en la vieja): el orden las trata así para que un corte que dure hasta entonces no conceda.
+        shortening: plan.shortening,
+        context: plan.orderContext,
+    }, orderView, cuts ? { cuts } : {});
+    for (const tuple of transition.residue)
+        report.orderResidue.push(describeTuple(tuple));
+    let refused = 0;
+    if (dryRun) {
+        row.written = plan.toWrite.length + plan.denyWrite.length;
+        row.updated = plan.toUpdate.length + plan.denyUpdate.length;
+        row.denies.written = plan.denyWrite.length;
+        row.denies.updated = plan.denyUpdate.length;
+        if (prune) {
+            row.deleted = plan.allowDelete.length + plan.denyDelete.length;
+            row.denies.deleted = plan.denyDelete.length;
+        }
+    }
+    else {
+        // La caducidad de un allow viaja EXPLÍCITA (`Date` la fija, `null` la quita): un `relate` sin opciones PRESERVARÍA
+        // la del destino (invariante 10). L-0: el DRIVER del destino aplica F-05 (`assertRelationDeclared`), así que sin
+        // `toConfig` —o con una que no coincida con la del driver— es SU 422 el que embuda la tupla no declarada: se cuenta en
+        // `skipped.undeclared` y se descuenta de `written`/`updated` (capa 2 del registro `RELATION_REJECTIONS`). La poda
+        // NUNCA lanza por un 422 de la familia de relaciones (🟠 N9, capa 2): se clasifica por `code` y se sigue.
+        const steps = [
+            ...(prune ? [...plan.expiredDelete].map((item) => ({ item, op: 'delete' })) : []),
+            ...transition.steps,
+        ];
+        for (const step of steps) {
+            const tuple = step.item;
+            if (step.op === 'delete') {
+                const op = kindOf(tuple) === 'deny' ? 'removeDeny' : 'unrelate';
+                const refusal = await deleteOrClassify(to, tuple, op);
+                if (refusal === null) {
+                    progress.writes++;
+                    row.deleted += 1;
+                    if (op === 'removeDeny')
+                        row.denies.deleted += 1;
                     continue;
-                report.skipped.undeclared += 1;
-                written -= 1;
+                }
+                report.details.push({ side: 'destino', reason: refusal.reason, tuple: describeTuple(tuple), message: refusal.message, pruned: false });
+                refused += 1;
+                if (op === 'removeDeny')
+                    row.denies.extra += 1;
+                continue;
             }
-            for (const tuple of plan.toUpdate) {
-                if (await relateOrSkip(to, tuple))
-                    continue;
-                report.skipped.undeclared += 1;
-                updated -= 1;
+            const counter = step.op === 'write' ? 'written' : 'updated';
+            if (kindOf(tuple) === 'deny') {
+                // Cierre 4 de D2 · 🟡 C3-2: el deny condicional que el destino no puede rehacer ya lo apartó el PLAN (sin
+                // `atomicRenewal`): desde el cierre 5 NIEGA su partición entera, que no llega aquí. Si el driver lo dice igual (500 `denyConditional` de un
+                // driver que declara `atomicRenewal`), es una contradicción con su capacidad: se propaga (hasta el cierre 4 la
+                // pasada lo listaba y SEGUÍA escribiendo los allows que ese deny cortaba).
+                await to.deny(tuple.subject, tuple.relation, tuple.object, tuple.partition);
+                progress.writes++;
+                row[counter] += 1;
+                row.denies[counter] += 1;
+                continue;
+            }
+            if (await relateOrSkip(to, tuple)) {
+                progress.writes++;
+                row[counter] += 1;
+                continue;
+            }
+            report.skipped.undeclared += 1;
+        }
+    }
+    if (!prune)
+        row.denies.extra += plan.denyDelete.length;
+    row.denies.extra += conditional;
+    // El residuo del destino (los tres motivos) sobra SIEMPRE, con o sin `prune`: no está en `toDelete`, así que se suma
+    // aparte — más lo que el driver rechazó con un 422 de la familia en la pasada real (capa 2 de N9). (Desde el cierre 5
+    // una partición con `deny-conditional` está NEGADA y no llega aquí: `conditional` es 0 en una partición aplicada.)
+    row.extra = (prune ? 0 : plan.allowDelete.length + plan.denyDelete.length) + plan.destResidue + refused + conditional;
+}
+/**
+ * **La puerta del deny** (lote D · D2): las negativas de TODAS las particiones, decididas por el DRIVER DESTINO
+ * (`capabilities.relationDenies` + `denyPhase`, que en `openfga` comprueba además el modelo fijado, D-31) y por lo que
+ * el plan ya vio (denies sin `kind`, F-05 con `toConfig`, identidad/sujeto que el destino no admite). Un par
+ * tipo/relación se pregunta UNA vez. Para ESCRIBIR un deny el tipo tiene que estar en `'write'`; para uno que el
+ * destino YA tiene basta con que lo honre (opt-in en cualquier fase). Nunca escribe.
+ */
+async function denyGate(to, plans) {
+    const refusals = [];
+    const seen = new Set();
+    const push = (refusal) => {
+        const id = `${refusal.objectType}#${refusal.relation}:${refusal.reason}`;
+        if (seen.has(id))
+            return;
+        seen.add(id);
+        refusals.push(refusal);
+    };
+    for (const plan of plans)
+        for (const refusal of plan.denyRefusals)
+            push(refusal);
+    // Qué fase hace falta por par: 'write' si hay algo que escribir; 'honored' si solo hay denies que ya están.
+    const needed = new Map();
+    for (const plan of plans) {
+        // Cierre 5 de D2: una partición NEGADA por el plan no escribe nada — sus denies no piden fase.
+        if (plan.refusal)
+            continue;
+        for (const [list, write] of [
+            [[...plan.denyWrite, ...plan.denyUpdate], true],
+            [plan.denyPresent, false],
+        ]) {
+            for (const tuple of list) {
+                const id = `${tuple.object.type}#${tuple.relation}`;
+                const prev = needed.get(id);
+                needed.set(id, { objectType: tuple.object.type, relation: tuple.relation, write: (prev?.write ?? false) || write });
             }
         }
-        // ⚪ R2: lo enumerado fuera de la gramática se LISTA siempre (origen y
-        // destino), con el veredicto de la poda cuando la hay.
-        let refused = 0;
-        for (const invalid of plan.invalid) {
-            const detail = {
-                side: invalid.side,
-                reason: 'invalid-identity',
-                tuple: invalid.tuple,
-                message: invalid.message,
-            };
-            if (invalid.side === 'destino' && prune)
-                detail.pruned = true;
-            report.details.push(detail);
+    }
+    if (needed.size === 0)
+        return refusals;
+    const capable = to.capabilities?.relationDenies === true && typeof to.deny === 'function' && typeof to.removeDeny === 'function';
+    for (const { objectType, relation, write } of needed.values()) {
+        if (!capable) {
+            push({
+                objectType,
+                relation,
+                reason: 'no-capability',
+                message: `el destino no declara relationDenies (o no trae deny/removeDeny): no puede escribir ni honrar el deny de ` +
+                    `${objectType}#${relation}`,
+                recipe: denyRefusalRecipe('no-capability', objectType, relation),
+            });
+            continue;
         }
-        if (!dryRun && prune) {
-            for (const tuple of plan.toDelete) {
-                // La tupla fuera de la gramática se le pide al DRIVER tal como él la
-                // enumeró. Si la rechaza por el puerto (422 de su propia gramática, R-16
-                // en `unrelate`) NO es la pregunta del llamante la que está mal: se
-                // apunta `pruned: false`, sigue contando como `extra` y la pasada lo
-                // dice (exit ≠ 0). Nunca un throw a mitad de pasada por un dato ajeno.
-                const invalid = plan.invalid.find((i) => i.side === 'destino' && i.ref === tuple);
-                try {
-                    await to.unrelate(tuple.subject, tuple.relation, tuple.object, tuple.partition);
-                }
-                catch (error) {
-                    if (!invalid || error?.status !== 422)
-                        throw error;
-                    refused += 1;
-                    const detail = report.details.find((d) => d.side === 'destino' && d.tuple === invalid.tuple);
-                    if (detail)
-                        detail.pruned = false;
-                }
+        if (typeof to.denyPhase !== 'function') {
+            push({
+                objectType,
+                relation,
+                reason: 'no-deny-phase',
+                message: `el destino declara relationDenies pero no trae denyPhase: no puede decir si ${objectType} admite deny (opt-in por tipo)`,
+                recipe: denyRefusalRecipe('no-deny-phase', objectType, relation),
+            });
+            continue;
+        }
+        let phase;
+        try {
+            phase = await to.denyPhase({ type: objectType }, relation);
+        }
+        catch (error) {
+            const rejection = error?.status === 422 ? RELATION_REJECTIONS[String(error?.code)] : undefined;
+            if (rejection?.kind === 'classified' && rejection.reason === 'undeclared') {
+                push({ objectType, relation, reason: 'undeclared', message: String(error?.message ?? error), recipe: denyRefusalRecipe('undeclared', objectType, relation) });
+                continue;
+            }
+            if (error?.status === 500 && error?.code === AuthorizationConfigError.code) {
+                push({ objectType, relation, reason: 'model', message: String(error?.message ?? error), recipe: denyRefusalRecipe('model', objectType, relation) });
+                continue;
             }
+            throw error;
+        }
+        if (write ? phase !== 'write' : phase === null) {
+            push({
+                objectType,
+                relation,
+                reason: 'phase',
+                message: `en el DESTINO el tipo '${objectType}' está ${phase === null ? 'SIN opt-in de deny' : `en la fase '${phase}'`} y ` +
+                    `${write ? "escribir un deny exige deny: 'write' (en TODO destino)" : 'un deny que ya está exige que el destino lo honre (opt-in)'} ` +
+                    `(su config, no la spec persistida)` +
+                    // ⚪ 11 (cierre 1 de D2): por qué se niega aunque un destino `database` honre la fila igual (D8).
+                    (write
+                        ? ''
+                        : '. Un destino database honra un denied_* existente también sin opt-in (D8), pero la pasada no puede saberlo por ' +
+                            'el puerto: denyPhase = null significa «sin opt-in», y certificar un deny que el destino no declara honrar ' +
+                            'convertiría un detalle de implementación en la garantía'),
+                recipe: denyRefusalRecipe('phase', objectType, relation, !write),
+            });
         }
-        report.written += written;
-        report.updated += updated;
-        report.deleted += prune ? plan.toDelete.length - refused : 0;
-        report.unchanged += plan.unchanged;
-        report.extra += prune ? refused : plan.toDelete.length;
     }
-    return report;
+    return refusals;
+}
+/** El 500 de la puerta (S6/R2-5): la letra empieza por el prefijo ESTABLE «deny NO migrable:» (punto 7). */
+function denyRefusedError(refusals, partitions) {
+    const error = new DenyMigrationRefusedError(`deny NO migrable: authz:relations:reconcile se NIEGA — ${refusals.length} caso(s): ` +
+        refusals.map((r) => `(${r.reason}) ${r.objectType}#${r.relation}: ${r.message}`).join('; ') +
+        `. Perder un deny no es una pérdida que se pueda declarar (escribir los allows sin él concedería lo que el origen niega). ` +
+        `No se ha escrito nada${partitions > 1 ? ' en ninguna partición' : ''}. Recetas (una por motivo): ` +
+        refusals.map((r) => `(${r.reason}) ${r.recipe}`).join(' '));
+    error.refusals = Object.freeze(refusals.map((r) => Object.freeze({ ...r })));
+    return error;
+}
+/**
+ * ⚪ N8 (cierre 2 del lote B): el desglose del seguro R-17, cada motivo POR SU
+ * NOMBRE y solo si cuenta (> 0). Hasta el cierre decía «todas de tipos que el
+ * destino no declara» siempre que había `toConfig`, también cuando el único
+ * aporte era residuo B3 — y sin `toConfig` no nombraba nada.
+ */
+function describeSkipped(skipped) {
+    const parts = [];
+    if (skipped.undeclared)
+        parts.push(`${skipped.undeclared} de tipo o relación que el destino no declara (skipped.undeclared)`);
+    if (skipped.usersetUnsupported)
+        parts.push(`${skipped.usersetUnsupported} con sujeto userset no admitido (B3, skipped.usersetUnsupported)`);
+    if (skipped.invalid)
+        parts.push(`${skipped.invalid} con identidad fuera de la gramática (skipped.invalid)`);
+    if (skipped.expired)
+        parts.push(`${skipped.expired} caducada(s)`);
+    return parts.length ? `: ${parts.join(', ')}` : '';
 }
 /** Una tupla enumerada, legible, para la línea del reporte (sin validar nada: puede estar fuera de la gramática). */
 function describeTuple(tuple) {
@@ -224,12 +607,12 @@ function describeTuple(tuple) {
     const subject = isRelUserset(s) ? `${s.object?.type}:${s.object?.id}#${s.relation}` : `${s?.type}:${s?.uuid}`;
     const p = tuple?.partition;
     const partition = p?.type === 'app' ? 'app' : `${p?.type}|${p?.uuid}`;
-    return `${partition} ${tuple?.object?.type}:${tuple?.object?.id}#${tuple?.relation}@${subject}`;
+    return `${tuple?.kind === 'deny' ? '[deny] ' : ''}${partition} ${tuple?.object?.type}:${tuple?.object?.id}#${tuple?.relation}@${subject}`;
 }
 /** `tupleKey` de una tupla ENUMERADA: la clave, o el motivo por el que su identidad no entra en la gramática (⚪ R2). */
 function enumeratedKey(tuple) {
     try {
-        return { key: tupleKey({ ...tuple, kind: 'allow' }) };
+        return { key: tupleKey({ ...tuple, kind: kindOf(tuple) }) };
     }
     catch (error) {
         if (error instanceof InvalidIdentityError)
@@ -237,6 +620,38 @@ function enumeratedKey(tuple) {
         throw error;
     }
 }
+/**
+ * **El sujeto de una tupla ENUMERADA, clasificado** (cierre 1 del lote B · 🟠 2;
+ * cierre 2 · 🟡 N2): `ok`, `userset-unsupported` (B3: userset ≠ `group#member`,
+ * con o sin config — `assertSupportedUserset` no necesita F-05), o `undeclared`
+ * (solo con `toConfig`: un `group#member` cuyo tipo/relación el destino no
+ * declara — F-05 del par; sin config esa cara la embuda el 422 del driver, como
+ * la del objeto). **La FORMA se juzga ANTES que F-05** (N2; decisión 3 del
+ * cierre 1 rechazada): un residuo B3 es inadmisible con cualquier config, así
+ * que un userset `folder#viewer` o `document#reader` que `toConfig` no declara
+ * es residuo con receta, nunca `undeclared` con el consejo falso «decláralo en
+ * el destino» (declarado, la pasada siguiente lo reclasificaba como residuo).
+ * Mutante «F-05 primero» ⇒ rojo. Nunca lanza por un dato del store
+ * (invariante 5).
+ */
+function classifySubject(tuple, toConfig) {
+    const subject = tuple?.subject;
+    if (!isRelUserset(subject))
+        return { kind: 'ok' };
+    try {
+        assertSupportedUserset(subject);
+        if (toConfig)
+            assertRelationDeclared(toConfig, subject.object, subject.relation);
+        return { kind: 'ok' };
+    }
+    catch (error) {
+        if (error instanceof RelationUsersetUnsupportedError)
+            return { kind: 'userset-unsupported', message: error.message };
+        if (error instanceof RelationTypeUnknownError || error instanceof RelationUnknownError)
+            return { kind: 'undeclared' };
+        throw error;
+    }
+}
 /** Exactamente uno de `partition` / `partitions` (y `partitions` no vacío): lo demás es 500 antes de leer nada. */
 function partitionsOf(options) {
     const { partition, partitions } = options;
@@ -273,7 +688,7 @@ function partitionsOf(options) {
     });
 }
 function planPartition(partition, enumerated, destTuples, context) {
-    const { now, prune, toConfig } = context;
+    const { now, prune, toConfig, atomicRenewal, cuts } = context;
     // R-15: la caducada LLEGA del origen (el puerto lo exige) y aquí se DESCARTA
     // contándola: no se migra ni respalda nada en el destino. Decidido con UN
     // `now` para toda la pasada.
@@ -282,31 +697,85 @@ function planPartition(partition, enumerated, destTuples, context) {
     // pasada real dan los mismos números— y tampoco respalda nada en el destino
     // (una que ya estuviera allí es `extra`, y `--prune` la barre). El tipo se
     // reporta además en `modelDrift` (deriva del modelo fusionado).
-    const skipped = { expired: 0, undeclared: 0, invalid: 0 };
+    // Lote D · D2: un DENY nunca se descarta así — lo que impide escribirlo es una NEGATIVA de la pasada (500), jamás
+    // `skipped` (perder un deny no es una pérdida que se pueda declarar). Solo la caducidad lo descarta (no niega nada).
+    const skipped = { expired: 0, undeclared: 0, invalid: 0, usersetUnsupported: 0 };
     const modelDrift = [];
     const sourceTuples = [];
     const invalid = [];
+    const usersetResidue = [];
+    const undeclaredResidue = [];
+    const denyRefusals = [];
+    const refuse = (tuple, reason, message) => {
+        const objectType = String(tuple?.object?.type);
+        const relation = String(tuple?.relation);
+        denyRefusals.push({ objectType, relation, reason, message, recipe: denyRefusalRecipe(reason, objectType, relation) });
+    };
     for (const tuple of enumerated) {
         if (!isActiveExpiry(tuple.expiresAt ?? null, now)) {
             skipped.expired += 1;
             continue;
         }
+        const kind = kindOf(tuple);
+        // Lote D · D2: una tupla con la relación ALMACENADA de un deny (`denied_*`, prefijo reservado) y sin `kind: 'deny'`
+        // es un deny que el driver de ORIGEN no marcó: migrarla como allow escribiría `relate(denied_viewer)` (422) o la
+        // contaría como no declarada — y el deny se perdería. Negativa (500), nunca `skipped`.
+        if (kind === 'allow' && typeof tuple.relation === 'string' && tuple.relation.startsWith(RELATION_DENY_PREFIX)) {
+            refuse(tuple, 'unmarked', `el ORIGEN enumera ${describeTuple(tuple)} sin kind: 'deny' (un driver que declara relationDenies tiene que marcar kind; ` +
+                `un proceso < 2.5.0-alpha.3 no lo hace)`);
+            continue;
+        }
         // ⚪ R2: una identidad fuera de la gramática en el ORIGEN no es una pregunta
         // del llamante (invariante 5): no se migra —la API del destino no podría
         // escribirla—, se lista y se cuenta. Nunca un 422 por un dato del store.
         const keyed = enumeratedKey(tuple);
         if ('message' in keyed) {
+            if (kind === 'deny') {
+                refuse(tuple, 'invalid', `identidad fuera de la gramática: ${keyed.message}`);
+                continue;
+            }
             skipped.invalid += 1;
-            invalid.push({ side: 'origen', tuple: describeTuple(tuple), message: keyed.message });
+            invalid.push({ side: 'origen', reason: 'invalid-identity', tuple: describeTuple(tuple), message: keyed.message });
+            continue;
+        }
+        // Cierre 1 del lote B · 🟠 2: el residuo pre-2.5 de B3 en el ORIGEN se
+        // clasifica AQUÍ, con o sin `toConfig` — no se migra (ninguna puerta del
+        // destino lo admite), se lista con su receta y se cuenta aparte. Hasta el
+        // cierre llegaba al driver, que lo rechazaba con 422, y `relateOrSkip` lo
+        // tragaba como `undeclared` (consejo falso; `--dry-run` decía `written`).
+        const subject = classifySubject(tuple, toConfig);
+        if (subject.kind === 'userset-unsupported') {
+            if (kind === 'deny') {
+                refuse(tuple, 'invalid', `sujeto que el destino no admite: ${subject.message}`);
+                continue;
+            }
+            skipped.usersetUnsupported += 1;
+            usersetResidue.push({ side: 'origen', reason: 'userset-unsupported', tuple: describeTuple(tuple), message: subject.message });
+            continue;
+        }
+        if (subject.kind === 'undeclared') {
+            if (kind === 'deny') {
+                refuse(tuple, 'undeclared', `el sujeto userset de ${describeTuple(tuple)} no está declarado en el destino`);
+                continue;
+            }
+            skipped.undeclared += 1;
             continue;
         }
         if (toConfig && !declaredIn(toConfig, tuple.object.type)) {
+            if (kind === 'deny') {
+                refuse(tuple, 'undeclared', `el destino no declara el tipo '${tuple.object.type}'`);
+                continue;
+            }
             skipped.undeclared += 1;
             if (!modelDrift.includes(tuple.object.type))
                 modelDrift.push(tuple.object.type);
             continue;
         }
         if (toConfig && !toConfig.isDeclared(tuple.object.type, tuple.relation)) {
+            if (kind === 'deny') {
+                refuse(tuple, 'undeclared', `el destino no declara la relación '${tuple.relation}' en '${tuple.object.type}'`);
+                continue;
+            }
             skipped.undeclared += 1;
             continue;
         }
@@ -314,26 +783,115 @@ function planPartition(partition, enumerated, destTuples, context) {
     }
     const sourceByKey = new Map();
     for (const tuple of sourceTuples)
-        sourceByKey.set(tupleKey({ ...tuple, kind: 'allow' }), tuple);
-    // ⚪ R2: una tupla del DESTINO fuera de la gramática es `extra` con motivo
-    // (`invalid-identity`): nadie del origen puede respaldarla (la clave no se
-    // puede ni componer), `--prune` pide borrarla y `--dry-run` la lista.
+        sourceByKey.set(tupleKey({ ...tuple, kind: kindOf(tuple) }), tuple);
+    // ⚪ R2 + cierre 2 · N3: una tupla del DESTINO fuera de la gramática es
+    // `extra` con motivo (`invalid-identity`): nadie del origen puede respaldarla
+    // (la clave no se puede ni componer) y NADIE la borra — ni `toDelete` (los dos
+    // drivers del paquete la rechazan por el puerto, R-16; hasta el cierre 2 se les
+    // pedía igual) ni un DELETE de plataforma—: se lista con `pruned: false` y es
+    // deriva en los cuatro modos, exactamente como el residuo de B3 de abajo.
     const destByKey = new Map();
-    const destInvalid = new Set();
+    /** Cierre 4 de D2 · 🟡 C3-2: los denies del destino VENCIDOS (no cuentan como presentes, pero el destino los tiene). */
+    const expiredDenyByKey = new Map();
+    const residue = new Set();
     for (const tuple of destTuples) {
+        // ⚪ 8 (cierre 1 de D2): un deny del DESTINO sin `kind` (un driver de terceros que no marca) es la MISMA negativa
+        // `unmarked` que en el origen, decidida en el PLAN: planificarlo como allow lo podaría con `unrelate(denied_*)` (que
+        // D-04 prohíbe y F-05 rechaza con un motivo equivocado) o lo contaría como allow que sobra.
+        if (kindOf(tuple) === 'allow' && typeof tuple?.relation === 'string' && tuple.relation.startsWith(RELATION_DENY_PREFIX)) {
+            residue.add(tuple);
+            refuse(tuple, 'unmarked', `el DESTINO enumera ${describeTuple(tuple)} sin kind: 'deny' (un driver que declara relationDenies tiene que marcar kind)`);
+            continue;
+        }
         const keyed = enumeratedKey(tuple);
         if ('message' in keyed) {
-            destInvalid.add(tuple);
-            invalid.push({ side: 'destino', tuple: describeTuple(tuple), message: keyed.message, ref: tuple });
+            residue.add(tuple);
+            invalid.push({ side: 'destino', reason: 'invalid-identity', tuple: describeTuple(tuple), message: keyed.message });
+            continue;
+        }
+        // Cierre 1 del lote B · 🟠 1: el residuo pre-2.5 de B3 en el DESTINO sobra
+        // (nadie del origen puede respaldarlo: el origen lo descarta arriba) pero
+        // NO entra en un borrado: la pasada no se lo pide al driver ni con `--prune`
+        // —`unrelate` lo rechazaría con 422 y hasta el cierre eso ABORTABA la pasada
+        // a mitad, con los `toWrite` ya escritos—. Se lista con `pruned: false` y
+        // la receta, cuenta en `extra` y es deriva.
+        const subject = classifySubject(tuple, undefined);
+        if (subject.kind === 'userset-unsupported') {
+            residue.add(tuple);
+            usersetResidue.push({ side: 'destino', reason: 'userset-unsupported', tuple: describeTuple(tuple), message: subject.message });
+            continue;
+        }
+        // Cierre 3 del lote B · 🟠 N9 (capa 1): la fila cuya RELACIÓN o TIPO el
+        // destino (`toConfig`) ya no declara — una relación retirada de la config con
+        // filas vivas — es la tercera fila que la API no admite: `unrelate`/`removeDeny`
+        // la rechazan por F-05, así que lleva la MISMA regla que las dos de arriba.
+        const undeclared = toConfig ? classifyDestinationRow(toConfig, tuple) : null;
+        if (undeclared !== null) {
+            residue.add(tuple);
+            undeclaredResidue.push({ side: 'destino', reason: 'undeclared', tuple: describeTuple(tuple), message: undeclared });
+            continue;
+        }
+        // Cierre 3 de D2 · 🟠 C2-1 / 🟡 C2-2: una tupla del destino VENCIDA en `now` (el MISMO `now` con el que el origen
+        // descarta las suyas) no conecta nada —ni en `database` ni en FGA— y el plan la trata como AUSENTE: su reescritura es
+        // una escritura normal (nunca `toUpdate`, nunca `renewal-unsafe`) y no entra en el contexto del orden (ni portadora,
+        // ni arista del auto-corte, ni «renovación» de la fase 4). Hasta el cierre 3 contaba como viva: una membresía
+        // portadora caducada se clasificaba `renewal-unsafe` mientras el allow nuevo SÍ se escribía, y el destino concedía a
+        // un denegado para siempre (R4 del auditor). Sin `--prune` sigue en el destino (sobra, vencida) y con él se barre.
+        if (!liveInDestination(tuple, now)) {
+            if (kindOf(tuple) === 'deny')
+                expiredDenyByKey.set(keyed.key, tuple);
             continue;
         }
         destByKey.set(keyed.key, tuple);
     }
     const toWrite = [];
     const toUpdate = [];
+    const denyWrite = [];
+    const denyUpdate = [];
+    const denyPresent = [];
+    const denyConditional = [];
     let unchanged = 0;
+    let denyUnchanged = 0;
     for (const [key, tuple] of sourceByKey) {
         const present = destByKey.get(key);
+        if (kindOf(tuple) === 'deny') {
+            // Cierre 4 de D2 · 🟡 C3-2: un deny del destino CON caducidad —vivo con otra, o ya VENCIDO— que el origen tiene, en
+            // un destino que no declara `atomicRenewal` (`openfga`: no reemplaza la misma clave en un `Write`, M5, y lo dice con
+            // 500 `conditionalDeny`), no se puede rehacer permanente. Se decide AQUÍ (mismos números en `--dry-run` y real;
+            // hasta el cierre 4 lo decidía el driver en la pasada real, y la pasada escribía los allows que ese deny corta):
+            // residuo `deny-conditional` y, desde el cierre 5 (opción A), su PARTICIÓN queda NEGADA (cero escrituras en ella).
+            // Para la puerta cuenta como un deny que el destino tiene (tiene que honrarlo).
+            const stale = present ?? expiredDenyByKey.get(key);
+            if (!atomicRenewal && stale && stale.expiresAt != null && !sameInstant(stale.expiresAt, tuple.expiresAt ?? null)) {
+                const expired = !present;
+                denyPresent.push(tuple);
+                denyConditional.push({
+                    side: 'destino',
+                    reason: 'deny-conditional',
+                    tuple: describeTuple(stale),
+                    message: `el deny del destino tiene caducidad (${stale.expiresAt.toISOString()}, ${expired ? 'YA VENCIDO: no niega nada' : 'vivo: niega hasta entonces'}) ` +
+                        `y el origen lo tiene ${tuple.expiresAt ? `hasta ${tuple.expiresAt.toISOString()}` : 'permanente'}; el destino no declara atomicRenewal ` +
+                        `(openfga no reemplaza la misma clave en un Write, M5) y no puede rehacerlo en una escritura. No se reescribe y la ` +
+                        `PARTICIÓN ${scopeKey(partition)} queda NEGADA: cero escrituras y cero borrados en ella (su destino queda como estaba, ` +
+                        `con su deriva a la vista); el resto de particiones migra. Receta: ${partitionRefusalRecipe(['deny-conditional'])}`,
+                    pruned: false,
+                });
+                continue;
+            }
+            // D3: un deny no caduca. Uno del destino SIN caducidad es el mismo deny (el del origen, con o sin una caducidad
+            // escrita a mano, deniega lo mismo o menos tiempo). Uno del destino CON caducidad distinta se rehace permanente
+            // (`to.deny`): dejarlo caducar concedería lo que el origen niega. Nunca delete+write (R2-8: no hay `toUpdate` de
+            // denies por `relate`).
+            if (!present)
+                denyWrite.push(tuple);
+            else if (present.expiresAt != null && !sameInstant(present.expiresAt, tuple.expiresAt ?? null))
+                denyUpdate.push(tuple);
+            else {
+                denyUnchanged += 1;
+                denyPresent.push(tuple);
+            }
+            continue;
+        }
         if (!present)
             toWrite.push(tuple);
         // Misma clave, OTRA caducidad ⇒ se reescribe con la del origen (R-15).
@@ -342,9 +900,245 @@ function planPartition(partition, enumerated, destTuples, context) {
         else
             unchanged += 1;
     }
-    const toDelete = destTuples.filter((tuple) => destInvalid.has(tuple) || !sourceByKey.has(tupleKey({ ...tuple, kind: 'allow' })));
-    const massDelete = prune && toDelete.length > 0 && sourceTuples.length === 0;
-    return { partition, enumerated: enumerated.length, toWrite, toUpdate, toDelete, unchanged, skipped, modelDrift, massDelete, invalid };
+    const allowDelete = [];
+    const denyDelete = [];
+    const expiredDelete = new Set();
+    for (const tuple of destTuples) {
+        if (residue.has(tuple))
+            continue;
+        if (sourceByKey.has(tupleKey({ ...tuple, kind: kindOf(tuple) })))
+            continue;
+        if (kindOf(tuple) === 'deny')
+            denyDelete.push(tuple);
+        else
+            allowDelete.push(tuple);
+        if (!liveInDestination(tuple, now))
+            expiredDelete.add(tuple);
+    }
+    const massDelete = prune && allowDelete.length + denyDelete.length > 0 && sourceTuples.length === 0;
+    const orderContext = [...sourceTuples, ...destByKey.values()].map(orderView);
+    // Cierre 2 de D2 · 🟠 N1: la RENOVACIÓN de una membresía que transporta un deny (en el grafo de los DOS estados: los
+    // denies del destino siguen vivos hasta el final de la pasada y los del origen se escriben primero) en un destino que
+    // renueva con delete + write (sin `atomicRenewal`) dejaría al sujeto SIN el deny entre los dos `Write`. El plan no la
+    // renueva: la lista (`renewal-unsafe`, con su receta) y es deriva. Los mismos números en `--dry-run` y en la real.
+    const renewalUnsafe = [];
+    const evolves = [];
+    /** La caducidad que el DESTINO tiene de una tupla de `toUpdate` (viva). */
+    const destExpiry = (tuple) => destByKey.get(tupleKey({ ...tuple, kind: kindOf(tuple) }))?.expiresAt ?? null;
+    /** ¿La renovación ALARGA la caducidad (la del origen es posterior o `null`)? */
+    const extends_ = (tuple) => {
+        const old = destExpiry(tuple);
+        return tuple.expiresAt == null || (old != null && tuple.expiresAt.getTime() > old.getTime());
+    };
+    if (!atomicRenewal && toUpdate.length > 0) {
+        const carriers = denyCarrierGroups(orderContext);
+        for (let i = toUpdate.length - 1; i >= 0; i--) {
+            const tuple = toUpdate[i];
+            if (tuple.object.type !== RELATION_USERSET_TYPE || !carriers.has(`${tuple.object.type}:${tuple.object.id}`))
+                continue;
+            toUpdate.splice(i, 1);
+            const old = destExpiry(tuple);
+            const newer = tuple.expiresAt ? tuple.expiresAt.toISOString() : 'sin caducidad';
+            // Cierre 6 de D2 · ⚪ D5-3 (E3): «como estaba» NO es estático. Si la renovación ALARGA, desde la caducidad vieja el
+            // destino ya no transporta los denies del grupo por esta membresía y CONCEDE lo que cortan (si otro camino lo da),
+            // cosa que el origen sigue negando: la línea lo dice con fecha y con qué, en vez de dejar que el operador lo deduzca.
+            const member = orderView(tuple).user;
+            const cut = carriedDenies([...destByKey.values()].map(orderView), `${tuple.object.type}:${tuple.object.id}`).map((v) => `${v.relation} sobre ${v.object}`);
+            if (extends_(tuple) && old !== null && cut.length > 0)
+                evolves.unshift({ at: old.toISOString(), member, cut });
+            const grantsLater = old !== null && cut.length > 0
+                ? ` A partir de ${old.toISOString()} el destino CONCEDERÁ a ${member} lo que cortan esos denies (${cut.join(', ')}) si ` +
+                    `otro camino se lo da, y el origen lo sigue negando: negar la partición NO congela el tiempo.`
+                : '';
+            renewalUnsafe.unshift({
+                side: 'destino',
+                reason: 'renewal-unsafe',
+                tuple: describeTuple(tuple),
+                message: `la membresía cambia de caducidad (destino ${old ? old.toISOString() : 'sin caducidad'}, origen ${newer}) y su grupo ` +
+                    `TRANSPORTA un deny vivo; el destino renueva con delete + write (no declara atomicRenewal) y entre los dos el deny no ` +
+                    `alcanzaría al sujeto. No se renueva y la PARTICIÓN ${scopeKey(partition)} queda NEGADA: cero escrituras y cero ` +
+                    `borrados en ella (su destino queda como estaba, con su deriva a la vista); el resto de particiones migra. ` +
+                    `${extends_(tuple) ? `Desde ${old ? old.toISOString() : '—'} el destino ya no transporta ese deny por esta membresía.${grantsLater}` : `Hasta ${old ? old.toISOString() : '—'} el destino la conserva más que el origen (${newer}).`} ` +
+                    `Receta: ${partitionRefusalRecipe(['renewal-unsafe'])}`,
+            });
+        }
+    }
+    // **Cierre 5 de D2 (decisión del dueño §2026-10-16 (10), opción A)**: una partición con ≥ 1 `renewal-unsafe` o
+    // `deny-conditional` —lo que el destino no puede escribir en una escritura— recibe CERO escrituras y CERO borrados
+    // (también con `--prune` y las vencidas): queda EXACTAMENTE como estaba, que es lo único certificable; el resto migra.
+    // Sustituye a la retención del cierre 4 (`relationWithheldWrites`, `withheld-by-unsafe-deny`, `carrier-conflict`): retener
+    // tupla a tupla no cubría lo que el destino YA concedía (D4-1) y su negativa era global (D4-3).
+    const causes = [...denyConditional, ...renewalUnsafe].map((detail) => ({ reason: detail.reason, tuple: detail.tuple }));
+    const refusal = causes.length > 0
+        ? {
+            partition: scopeKey(partition),
+            causes,
+            pending: {
+                write: toWrite.length + denyWrite.length,
+                update: toUpdate.length + denyUpdate.length + causes.length,
+                delete: prune ? allowDelete.length + denyDelete.length : 0,
+            },
+            recipe: partitionRefusalRecipe(causes.map((cause) => cause.reason)),
+            ...(evolves.length > 0 ? { evolves } : {}),
+        }
+        : undefined;
+    const shortening = toUpdate.filter((tuple) => !extends_(tuple));
+    return {
+        partition,
+        enumerated: enumerated.length,
+        toWrite,
+        toUpdate,
+        allowDelete,
+        unchanged,
+        denyWrite,
+        denyUpdate,
+        denyPresent,
+        denyUnchanged,
+        denyDelete,
+        expiredDelete,
+        denyRefusals,
+        skipped,
+        modelDrift,
+        // Una partición NEGADA no borra nada: el seguro de borrado masivo no aplica.
+        massDelete: massDelete && !refusal,
+        details: [...invalid, ...usersetResidue, ...undeclaredResidue, ...denyConditional, ...renewalUnsafe],
+        destResidue: residue.size,
+        orderContext,
+        shortening,
+        denyConditional: denyConditional.length,
+        refusal,
+    };
+}
+/**
+ * **¿Cuenta una tupla del DESTINO en el plan?** (cierre 3 de D2 · 🟠 C2-1 / 🟡 C2-2): sí si está VIVA en `now` (el mismo
+ * `now` de toda la pasada, con el que el origen descarta sus caducadas); una VENCIDA es AUSENTE — no conecta nada en
+ * ningún driver—, así que ni se «renueva» ni entra en el contexto del orden. Punto de paso ÚNICO de la regla: lo usa
+ * `planPartition` y la fuerza bruta del orden (`tests/helpers/order_bruteforce.ts`, universo con vigencia) deriva con
+ * ÉL qué es escritura, renovación y contexto — un mutante que ignore la vigencia aquí pone rojos los dos.
+ */
+export function liveInDestination(tuple, now) {
+    return isActiveExpiry(tuple.expiresAt ?? null, now);
+}
+/**
+ * La vista de ORDEN de una tupla ya planificada (cierre 1 de D2 · 🟠 1): objeto `<tipo>:<id>` y sujeto `<tipo>:<uuid>` o
+ * `<tipo>:<id>#<rel>` — sin partición: el plan es de UNA partición.
+ */
+function orderView(tuple) {
+    const s = tuple.subject;
+    return {
+        deny: kindOf(tuple) === 'deny',
+        object: `${tuple.object.type}:${tuple.object.id}`,
+        user: isRelUserset(s) ? `${s.object.type}:${s.object.id}#${s.relation}` : `${s.type}:${s.uuid}`,
+        relation: tuple.relation,
+    };
+}
+/** El `kind` de una tupla enumerada: `deny` solo si el driver lo marca; ausente = `allow` (tipo exportado opcional). */
+function kindOf(tuple) {
+    return tuple?.kind === 'deny' ? 'deny' : 'allow';
+}
+/**
+ * **F-05 del destino sobre una fila ENUMERADA del destino** (cierre 3 del lote B ·
+ * 🟠 N9, capa 1): la MISMA `assertRelationDeclared` que corre en la primera línea
+ * de `unrelate` de los dos drivers, aplicada en el plan para que `--dry-run` y la
+ * pasada real den los mismos números y la fila nunca llegue a un `unrelate` que
+ * la rechazaría. Devuelve el porqué (el mensaje de F-05: tipo o relación) o
+ * `null` si el destino la declara. Nunca lanza por un dato del store
+ * (invariante 5): cualquier otra excepción se propaga tal cual.
+ */
+function classifyDestinationRow(toConfig, tuple) {
+    try {
+        assertRelationDeclared(toConfig, tuple.object, tuple.relation);
+        return null;
+    }
+    catch (error) {
+        if (error instanceof RelationTypeUnknownError || error instanceof RelationUnknownError)
+            return error.message;
+        throw error;
+    }
+}
+export const RELATION_REJECTIONS = Object.freeze({
+    [RelationTypeUnknownError.code]: {
+        kind: 'classified',
+        reason: 'undeclared',
+        where: 'planPartition (toConfig: skipped.undeclared en el origen) · classifyDestinationRow (destino) · denyGate (denyPhase ⇒ refusal undeclared)',
+    },
+    [RelationUnknownError.code]: {
+        kind: 'classified',
+        reason: 'undeclared',
+        where: 'planPartition (toConfig) · classifyDestinationRow · denyGate (denyPhase ⇒ refusal undeclared)',
+    },
+    [RelationUsersetUnsupportedError.code]: { kind: 'classified', reason: 'userset-unsupported', where: 'classifySubject (origen y destino, con o sin toConfig)' },
+    [InvalidIdentityError.code]: { kind: 'classified', reason: 'invalid-identity', where: 'enumeratedKey (origen y destino)' },
+    [RelationNotDenyableError.code]: { kind: 'refused', refusal: 'phase', where: "denyGate: denyPhase del DESTINO ≠ 'write' ⇒ 500 antes de escribir" },
+    [RelationDenyExpiryError.code]: { kind: 'unreachable', why: 'el reconcile nunca pasa expiresAt a deny/removeDeny (D3: el deny no caduca)' },
+    [CheckManyBatchError.code]: { kind: 'unreachable', why: 'el reconcile no llama a checkMany ni a decideMany' },
+    [RelationConfigError.code]: { kind: 'unreachable', why: 'se lanza al DEFINIR la config; cuando el reconcile corre los drivers ya están construidos' },
+    [RelationConfigUnknownKeyError.code]: { kind: 'unreachable', why: 'se lanza al DEFINIR la config (clave desconocida de la spec, B2)' },
+    [InvalidSlugError.code]: { kind: 'unreachable', why: 'gramática de SLUGS del catálogo de roles: ninguna escritura de relaciones la invoca' },
+    [ActorRequiredError.code]: { kind: 'unreachable', why: 'solo el RelationsManager exige actor; el reconcile habla con los drivers' },
+    // ⚪ 7 (cierre 1 de D2): los 422 que nombra `src/shared/` (que importan los drivers de relaciones).
+    [UnknownScopeError.code]: {
+        kind: 'unreachable',
+        why: 'src/shared/backend_guard.ts: assertKnownScope/canonicalScopeTargets son del árbol de ROLES; los drivers de relaciones solo importan de ahí withDeadline/guardSql/isServerWriteLimit/isTimeoutLike/isDeadlock/isUniqueViolation',
+    },
+    [NoScopeResolverError.code]: {
+        kind: 'unreachable',
+        why: 'src/shared/backend_guard.ts: rootOnlyResolver/resolveChain son del árbol de ROLES; ningún driver de relaciones resuelve cadenas de scopes',
+    },
+});
+/**
+ * **Los 422 de la FAMILIA de relaciones, clasificados por `code`** (cierre 3 del lote B · 🟠 N9, capa 2) — DERIVADA del
+ * registro L9: las entradas `classified`. Por `code` y `status`, no por clase: un driver de terceros lanza su propia
+ * clase con el mismo código. Fuera de esta tabla NADA se absorbe.
+ */
+export const RELATION_422_REASONS = Object.freeze(Object.fromEntries(Object.entries(RELATION_REJECTIONS).flatMap(([code, entry]) => (entry.kind === 'classified' ? [[code, entry.reason]] : []))));
+/**
+ * **El registro de los RESIDUOS de la pasada, por motivo** (cierre 2 de D2 · ⚪ N6; linaje L9): cada motivo de
+ * `RelationsReconcileDetail` dice DÓNDE se clasifica —en el PLAN (antes del driver: los mismos números en `--dry-run` y
+ * en la pasada real, punto 2 de L9) o en la PASADA (solo el driver lo sabe: EXCEPCIÓN declarada al punto 2, con su
+ * porqué)—. `tests/relations_reconcile_l9.spec.ts` cruza las claves con `RELATIONS_RECONCILE_DETAIL_REASONS` (un motivo
+ * nuevo sin entrada nace ROJO) y ejecuta un caso por entrada. Hasta el cierre 2 `deny-conditional` (un `catch` del 500
+ * marcado en la pasada) quedaba fuera de la guardia, que solo enumeraba 422.
+ */
+export const RELATION_RESIDUES = Object.freeze({
+    'invalid-identity': { where: 'plan', how: 'enumeratedKey (origen y destino); capa 2 por RELATION_REJECTIONS' },
+    'userset-unsupported': { where: 'plan', how: 'classifySubject (origen y destino, con o sin toConfig); capa 2 por RELATION_REJECTIONS' },
+    'undeclared': { where: 'plan', how: 'classifyDestinationRow (destino, con toConfig); sin toConfig, capa 2 por RELATION_REJECTIONS' },
+    'renewal-unsafe': {
+        where: 'plan',
+        how: 'planPartition: una membresía de toUpdate cuyo grupo transporta un deny (denyCarrierGroups) y un destino sin capabilities.atomicRenewal — sale de toUpdate y NIEGA su partición (cierre 5: cero escrituras en ella)',
+    },
+    'deny-conditional': {
+        where: 'plan',
+        how: 'planPartition (cierre 4 de D2 · C3-2): un deny del destino CON caducidad —vivo con otra o VENCIDO— que el origen tiene, en un destino sin capabilities.atomicRenewal — no se reescribe y NIEGA su partición (cierre 5: cero escrituras en ella)',
+    },
+});
+/** El motivo de la capa 2 para un error del driver, o `undefined` si no es de la familia (por `status` Y `code` PROPIO de la tabla). */
+function classifiedReason(error) {
+    // `Object.hasOwn` (repaso del cierre 3 · ⚪ N13): un 422 con un `code` heredado del prototipo no es de la familia.
+    const code = String(error?.code);
+    return error?.status === 422 && Object.hasOwn(RELATION_422_REASONS, code) ? RELATION_422_REASONS[code] : undefined;
+}
+/**
+ * Borra la tupla del destino (`unrelate` un allow, `removeDeny` un deny — jamás al revés); devuelve `null` si se borró
+ * (o ya no estaba) y el motivo + porqué si el DRIVER la rechazó con un 422 de la familia (`RELATION_422_REASONS`): la
+ * pasada lo clasifica como residuo del destino con `pruned: false` y SIGUE con las demás filas (🟠 N9: nunca un throw a
+ * mitad de pasada por una fila que el reporte puede contar). Cualquier otro error se propaga tal cual.
+ */
+async function deleteOrClassify(to, tuple, op) {
+    try {
+        if (op === 'removeDeny')
+            await to.removeDeny(tuple.subject, tuple.relation, tuple.object, tuple.partition);
+        else
+            await to.unrelate(tuple.subject, tuple.relation, tuple.object, tuple.partition);
+        return null;
+    }
+    catch (error) {
+        const reason = classifiedReason(error);
+        if (reason === undefined)
+            throw error;
+        return { reason, message: String(error?.message ?? error) };
+    }
 }
 /** ¿El tipo de objeto cabe en el modelo fusionado del destino? (`group` es built-in: `hasType` lo incluye.) */
 function declaredIn(config, objectType) {
@@ -353,7 +1147,12 @@ function declaredIn(config, objectType) {
 /**
  * Escribe la tupla en el destino; `false` si el DRIVER la rechazó por F-05
  * (tipo o relación no declarados: 422 `E_AUTHZ_RELATION_TYPE_UNKNOWN` /
- * `E_AUTHZ_RELATION_UNKNOWN`). Cualquier otro error se propaga tal cual.
+ * `E_AUTHZ_RELATION_UNKNOWN`). Cualquier otro error se propaga tal cual —
+ * **también `E_AUTHZ_RELATION_USERSET_UNSUPPORTED`** (cierre 1 del lote B,
+ * decisión 4 rechazada): esa clase ya no hereda de F-05 y aquí no se absorbe;
+ * el residuo de B3 se clasifica en el PLAN y nunca llega a este `relate`. Un
+ * driver que lo lanzara por una tupla que el plan dio por buena está diciendo
+ * otra cosa, y eso se propaga (R2-5: el plan clasifica, el driver no absorbe).
  */
 async function relateOrSkip(to, tuple) {
     try {
@@ -363,7 +1162,9 @@ async function relateOrSkip(to, tuple) {
         return true;
     }
     catch (error) {
-        if (error instanceof RelationTypeUnknownError || error instanceof RelationUnknownError)
+        // L9: por el registro (capa 2) — SOLO `undeclared` se cuenta aquí (`skipped.undeclared`); el resto de la familia lo
+        // clasifica el plan antes y, si el driver lo lanza igual, es una contradicción que se propaga.
+        if (classifiedReason(error) === 'undeclared')
             return false;
         throw error;
     }