@jantstack/adonis-authz 2.5.0-alpha.2 → 2.5.0-alpha.4

package/build/src/relations/reconcile.d.ts

@@ -1,5 +1,6 @@
 import type { Clock } from '../clock.js';
 import type { RelationsDriver, ScopeRef } from '../types.js';
+import type { DenyReachFinding } from './deny_reach.js';
 import type { RelationsConfig } from './define_relations_config.js';
 export interface RelationsReconcileOptions {
     /** El driver del que se LEEN las tuplas (origen). Necesita `enumerateRelations`. */
@@ -50,6 +51,16 @@ export interface RelationsReconcileOptions {
      * sigue — nunca un throw a mitad de pasada.
      */
     toConfig?: RelationsConfig;
+    /**
+     * **El detector del alcance de los denies (8)**: con él, la pasada lista en `report.denyReach` los denies vivos de sus
+     * particiones (origen y destino) cuyo alcance encoge de `baseline` (la config persistida; `null` = sin línea base, solo
+     * huérfanos) a `current` (la config que sirve el proceso). Solo LEE lo que la pasada ya enumeró: cero lecturas y cero
+     * escrituras de más. Lo pide `authz:relations:reconcile --dry-run`.
+     */
+    denyReach?: {
+        baseline: RelationsConfig | null;
+        current: RelationsConfig;
+    };
     /**
      * El reloj que decide qué tupla del ORIGEN está CADUCADA (R-15): una caducada
      * no se migra —se cuenta en `skipped.expired`— y no respalda nada en el
@@ -71,6 +82,17 @@ export interface RelationsReconcileOptions {
  * 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 declare const RELATIONS_RECONCILE_DETAIL_REASONS: readonly ["invalid-identity", "userset-unsupported", "undeclared", "deny-conditional", "renewal-unsafe", "invalid-condition"];
+export type RelationsReconcileDetailReason = (typeof RELATIONS_RECONCILE_DETAIL_REASONS)[number];
 export interface RelationsReconcileDetail {
     /** De qué store llegó enumerada. */
     side: 'origen' | 'destino';
@@ -95,8 +117,14 @@ export interface RelationsReconcileDetail {
      * (hasta el cierre 3 ese 422 salía como stack crudo a mitad de pasada,
      * después de escribir, y `--prune` quedaba inutilizable para esa partición).
      * Receta: retírala a mano o vuelve a declarar la relación en el destino.
+     * `deny-conditional` (cierre 1 de D2 · 🟡 4; cierre 4 · 🟡 C3-2, solo `destino`): un deny del destino CON caducidad
+     * (escrito fuera del paquete, D3) —vivo con otra caducidad o YA VENCIDO— que el origen tiene, en un destino que no
+     * declara `atomicRenewal` (`openfga` no reemplaza la misma clave en un `Write`, M5). Lo decide el PLAN (mismos números
+     * en `--dry-run` y real): no se reescribe, y desde el cierre 5 de D2 (opción A) NIEGA SU PARTICIÓN —cero escrituras y
+     * cero borrados en ella (`partitionsRefused`), el resto migra—; lleva la receta (`removeDeny` + `deny`, con su ventana
+     * declarada) y es deriva.
      */
-    reason: 'invalid-identity' | 'userset-unsupported' | 'undeclared';
+    reason: RelationsReconcileDetailReason;
     /** La tupla, legible: `<partición> <tipo>:<id>#<relación>@<sujeto>`. */
     tuple: string;
     /** El porqué: el mensaje de la gramática que la rechazó. */
@@ -244,11 +272,255 @@ export interface RelationsReconcileReport {
         from: string;
         allowed: boolean;
     };
+    /**
+     * **Los DENIES de la pasada, aparte** (plan 2.5 · lote D · D2; analista §4.7, tester T3): el SUBCONJUNTO de los
+     * contadores de arriba que son denies (`written`/`updated`/`deleted`/`unchanged`/`extra` cuentan allows + denies).
+     * `updated` = un deny del destino CON caducidad (escrito a mano) que el origen tiene distinto: se rehace permanente
+     * con `to.deny` (D3: el deny no caduca; `database` lo rehace en una transacción, `openfga` responde 409 ⇒ 503 ruidoso).
+     * Opcional en el tipo exportado (un reporte de terceros anterior sigue compilando).
+     */
+    denies?: {
+        written: number;
+        updated: number;
+        deleted: number;
+        unchanged: number;
+        extra: number;
+    };
+    /**
+     * **Los denies que la pasada NO puede migrar** (D2; S6/R2-5): solo en `--dry-run` (la pasada real lanza 500
+     * `E_AUTHZ_DENY_MIGRATION_REFUSED` con CERO escrituras y las mismas entradas en `error.refusals`). Es deriva: el
+     * verificador sale ≠ 0 con la línea «deny NO migrable (<motivo>) …». Ausente = ninguno.
+     */
+    denyRefused?: DenyRefusal[];
+    /**
+     * **El reporte POR PARTICIÓN** (roadmap 2.5, 🟡 3 del auditor de alpha.6): el desglose de los contadores y el
+     * estado de cada partición pedida, en orden. Si la pasada revienta a mitad, el error lleva `report` con
+     * `partial: true`, las particiones ya escritas `done`, la que reventó `failed` (con lo que llegó a escribir) y las
+     * demás `pending`, y va marcado con `markPartialWrite` si se escribió algo.
+     */
+    partitions?: RelationsReconcilePartitionReport[];
+    /**
+     * Solo en el reporte que viaja en un error (`error.report`): `true` si la pasada se cortó a mitad DESPUÉS de escribir
+     * algo; `false` si reventó sin haber escrito nada (⚪ 10 del cierre 1 de D2: hasta entonces era `true` siempre y el
+     * comando imprimía «pasada PARCIAL: escritas 0»). Desde el cierre 2 de D2 (🟠 N1) también `true` si el DRIVER marcó
+     * el error como escritura parcial (`isPartialWrite`: un `relate` de renovación que ya borró), aunque la pasada no
+     * hubiera completado ninguna escritura.
+     */
+    partial?: boolean;
+    /**
+     * **El RESIDUO del orden** (cierre 2 de D2 · 🟡 N3, linaje L10): las membresías de un CICLO del grafo de precedencias de
+     * `relationTransitionOrder` — dos membresías que cambian en la misma pasada cuyas exigencias de orden se contradicen
+     * (típicamente: el mismo sujeto entra, o sale, a la vez en dos grupos y cada uno trae un deny que corta un allow que
+     * trae el otro). Para ellas no hay orden garantizado: un corte entre las dos puede conceder lo que ni el estado inicial
+     * ni el final concedían (para el resto de la pasada, la garantía vale). El estado FINAL es el correcto; no es deriva:
+     * el comando lo AVISA con el prefijo estable «orden SIN garantía». Lo mismo en `--dry-run` que en la pasada real.
+     * Opcional en el tipo exportado; ausente = `[]`.
+     */
+    orderResidue?: string[];
+    /**
+     * **Las particiones NEGADAS** (cierre 5 de D2, decisión del dueño §2026-10-16 (10), opción A): una partición con al
+     * menos un `renewal-unsafe` (la caducidad de una membresía que transporta un deny cambia, y el destino no la puede
+     * renovar en una escritura) o un `deny-conditional` (un deny del destino con caducidad que no se puede rehacer) recibe
+     * CERO escrituras y CERO borrados —también con `--prune`, también las vencidas—: su destino queda EXACTAMENTE como
+     * estaba, con la deriva previa a la vista (`pending`). El resto de particiones migra. Lo decide el PLAN: `--dry-run` y
+     * la pasada real dan los mismos números. Es deriva (exit ≠ 0) mientras exista. Opcional en el tipo; ausente = `[]`.
+     */
+    partitionsRefused?: RelationsPartitionRefusal[];
+    /**
+     * **Las particiones cuya cadena de grupos FINAL excede el techo del destino** (lote «antes de RC» · R1, decisión del
+     * dueño 2026-10-17 (5); 🔴 C-1 del auditor): por cada una, la profundidad (saltos `group⊂group` del camino más largo,
+     * con los ciclos contados de forma conservadora), el techo (`to.groupDepthLimit()`, el CALIBRADO del destino) y la
+     * cadena. Esa partición está además en `partitionsRefused` (causa `too-deep`): cero escrituras en ella — saltar la
+     * arista que excede quitaría los denies que transporta y fabricaría una concesión —. Lo decide el PLAN: mismos números
+     * en `--dry-run` y en la real. Opcional en el tipo; ausente = `[]`.
+     */
+    tooDeep?: Array<{
+        partition: string;
+        depth: number;
+        limit: number;
+        chain: string[];
+    }>;
+    /**
+     * **El detector de (8)** (lote RC · sublote (8)): solo si se pidió (`denyReach` en las opciones; el comando lo pide en
+     * `--dry-run`). Los denies VIVOS de las particiones de la pasada —en el ORIGEN y en el DESTINO, enumerados por la misma
+     * pasada— juzgados con `denyReachCheck` (`src/relations/deny_reach.ts`, el mismo punto de paso que la guarda de
+     * `database` y que `checkRelationsConfigDenyReach`), en las dos direcciones entre la línea base (`baseline`: la config
+     * persistida) y la config que SIRVE el proceso (`current`). Sirve a los dos drivers; `findings` y `stale` son deriva
+     * (exit ≠ 0); `unjudged` (sin línea base) NO lo es (firma (8 · `--dry-run`): exit 0 con su línea, el runbook no cambia).
+     */
+    denyReach?: {
+        /** `'persisted'`: se comparó contra la config persistida; `'none'`: sin línea base, solo se buscan huérfanos. */
+        baseline: 'persisted' | 'none';
+        /** Persistida → servida: `shrunk` y `orphan` (también sin línea base). `count` = claves de tupla DISTINTAS (firma (8 · `count`)). */
+        findings: Array<DenyReachFinding & {
+            sides: Array<'origen' | 'destino'>;
+        }>;
+        /** Servida → persistida: la línea base RANCIA (`stale`, solo con línea base; firma (8 · rancia)). */
+        stale: Array<DenyReachFinding & {
+            sides: Array<'origen' | 'destino'>;
+        }>;
+        /** Sin línea base: cuántos denies vivos (claves distintas, no huérfanos) quedan SIN juzgar. `0` con línea base. */
+        unjudged: number;
+    };
+}
+/**
+ * Por qué se NIEGA una partición: `renewal-unsafe` (membresía portadora que cambia de caducidad), `deny-conditional` (deny
+ * con caducidad que el destino no puede rehacer) o, desde el cierre de L11 (🟡 A2 del auditor), `invalid-condition`: una
+ * tupla de `group` (una membresía, portadora posible) con una condición que el paquete no escribe ni sabe leer
+ * (`foreign`/`unparseable`) en una partición con ALGÚN deny — el servidor puede estar evaluándola VIVA (un `not_expired`
+ * con `current_time` congelado lo está, medido) y transportando ese deny; saltarla como allow fabricaba una concesión.
+ */
+export type RelationsPartitionRefusalReason = 'renewal-unsafe' | 'deny-conditional' | 'invalid-condition' | 'too-deep';
+/** Una partición NEGADA (cierre 5 de D2): por qué, qué receta, y lo que la pasada habría hecho en ella y NO hizo. */
+export interface RelationsPartitionRefusal {
+    partition: string;
+    /** Las causas, una por tupla: `renewal-unsafe` (membresía portadora) o `deny-conditional` (deny con caducidad). */
+    causes: Array<{
+        reason: RelationsPartitionRefusalReason;
+        tuple: string;
+    }>;
+    /** La deriva que queda a la vista: lo que la pasada escribiría, renovaría y (con `--prune`) borraría en ella. */
+    pending: {
+        write: number;
+        update: number;
+        delete: number;
+    };
+    /** La receta (`partitionRefusalRecipe`): honesta — en un destino sin `atomicRenewal` no hay forma sin ventana. */
+    recipe: string;
+    /**
+     * Cierre 6 de D2 · ⚪ D5-3: «COMO ESTABA» no es estático. Por cada membresía portadora que el origen ALARGA: desde `at`
+     * (su caducidad vieja en el destino) el destino deja de transportar los denies `cut` a `member` y CONCEDE lo que cortan
+     * si otro camino lo da —el origen lo sigue negando—. Ausente si no aplica.
+     */
+    evolves?: Array<{
+        at: string;
+        member: string;
+        cut: string[];
+    }>;
+}
+/** El desglose de UNA partición (D2). `status`: `done` (terminó), `failed` (reventó aquí), `pending` (no se tocó), `refused` (cierre 5: negada por el plan, cero escrituras). */
+export interface RelationsReconcilePartitionReport {
+    partition: string;
+    status: 'done' | 'failed' | 'pending' | 'refused';
+    written: number;
+    updated: number;
+    deleted: number;
+    unchanged: number;
+    extra: number;
+    denies: {
+        written: number;
+        updated: number;
+        deleted: number;
+        unchanged: number;
+        extra: number;
+    };
 }
+/**
+ * Un deny que la pasada no puede migrar (D2), con su motivo — uno de un conjunto CERRADO (cada uno su línea):
+ *  - `no-capability`: el destino no declara `relationDenies` (o no trae `deny`/`removeDeny`);
+ *  - `no-deny-phase`: el destino declara `relationDenies` pero no trae `denyPhase` (no puede decir si el tipo admite deny);
+ *  - `phase`: el tipo no está en la fase que hace falta EN EL DESTINO (`'write'` para escribir; con opt-in para uno ya presente);
+ *  - `undeclared`: el destino no declara el par tipo/relación (F-05);
+ *  - `model`: el modelo FIJADO del destino no declara `denied_<rel>` (D-31, `openfga`);
+ *  - `unmarked`: el ORIGEN enumera una tupla `denied_*` sin `kind: 'deny'` (un driver que no marca);
+ *  - `invalid`: el deny del origen tiene una identidad o un sujeto que el destino no admite (gramática / B3).
+ *
+ * `carrier-conflict` (cierre 4 de D2) se fue en el cierre 5 con la retención: lo que no viaja niega SU partición
+ * (`partitionsRefused`), nunca la pasada entera.
+ */
+export interface DenyRefusal {
+    objectType: string;
+    relation: string;
+    reason: 'no-capability' | 'no-deny-phase' | 'phase' | 'undeclared' | 'model' | 'unmarked' | 'invalid';
+    message: string;
+    /**
+     * Cierre 1 de D2 · 🟡 6: la receta de SU motivo (`denyRefusalRecipe`), una que funciona por la API o que dice «a mano»
+     * cuando la API no puede. Hasta el cierre todas llevaban la misma («pon el tipo en 'write' o retira esos denies del
+     * origen»), que para `undeclared` daba 422 (F-05 en `removeDeny`) y para `unmarked`/`invalid` no aplicaba.
+     */
+    recipe: string;
+}
+/**
+ * **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 declare function denyRefusalRecipe(reason: DenyRefusal['reason'], objectType: string, relation: string, honor?: boolean): string;
+/**
+ * **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 declare function partitionRefusalRecipe(reasons: Iterable<RelationsPartitionRefusalReason>): string;
 /**
  * Migra las tuplas de relación de `from` a `to` en `partition`. Idempotente
  * (una segunda pasada no escribe nada) y bidireccional (funciona en cualquier
  * sentido). Nunca silenciosa: devuelve `written`/`deleted`/`unchanged`/`extra`.
  */
 export declare function reconcileRelations(options: RelationsReconcileOptions): Promise<RelationsReconcileReport>;
-//# sourceMappingURL=reconcile.d.ts.map
+/**
+ * **¿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 declare function liveInDestination(tuple: {
+    expiresAt?: Date | null;
+}, now: Date): boolean;
+/**
+ * **El REGISTRO de los 422 del puerto de relaciones, clasificados** (plan 2.5 · lote D · D2; linaje **L9** «clasificación
+ * en el punto equivocado», decisión del dueño 2026-10-15 (7): R2-5 → lote B decisión 4 → cierre 3 N9). Propiedad
+ * universal: **el PLAN clasifica toda tupla por su motivo ANTES del driver; el driver solo rechaza; ningún catch convierte
+ * un 422 en otro bucket que no sea el que este registro dice**. Cada clase 422 que el puerto de relaciones puede lanzar
+ * tiene aquí UNA entrada:
+ *
+ *  - `classified`: el plan la anticipa (`enumeratedKey` / `classifySubject` / `classifyDestinationRow` / `toConfig`) y la
+ *    lista con `reason` en `details` (o la cuenta en `skipped`) sin pedírsela al driver; si el driver la lanza igual (sin
+ *    `toConfig`, o un driver de terceros que contradice al plan), la capa 2 (`relateOrSkip`/`deleteOrClassify`) la
+ *    clasifica con ESTE mismo `reason` y sigue;
+ *  - `refused`: el plan NIEGA la pasada (500 `E_AUTHZ_DENY_MIGRATION_REFUSED`, cero escrituras) con ese motivo — la puerta
+ *    del deny (`denyGate`, por `denyPhase` del destino);
+ *  - `unreachable`: ninguna llamada que el reconcile hace al driver con una tupla PLANIFICADA puede lanzarla, con su porqué.
+ *
+ * `tests/relations_reconcile_l9.spec.ts` lo cruza POR REFLEXIÓN con las clases 422 de `src/errors.ts` que nombran los
+ * ficheros del puerto (`src/relations/`, los dos drivers de relaciones, el doble y `src/identity.ts`): una clase 422 nueva
+ * sin entrada nace ROJA con su nombre, una entrada sin clase es rancia, y cada entrada `classified`/`refused` tiene un
+ * caso que la ejecuta. `RELATION_422_REASONS` (la tabla de la capa 2, cierre 3 del lote B) se DERIVA de aquí.
+ */
+export type RelationRejection = {
+    kind: 'classified';
+    reason: RelationsReconcileDetail['reason'];
+    where: string;
+} | {
+    kind: 'refused';
+    refusal: DenyRefusal['reason'];
+    where: string;
+} | {
+    kind: 'unreachable';
+    why: string;
+};
+export declare const RELATION_REJECTIONS: Readonly<Record<string, RelationRejection>>;
+/**
+ * **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 declare const RELATION_422_REASONS: Readonly<Record<string, RelationsReconcileDetail['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 declare const RELATION_RESIDUES: Readonly<Record<RelationsReconcileDetailReason, {
+    where: 'plan';
+    how: string;
+} | {
+    where: 'pass';
+    how: string;
+    why: string;
+}>>;