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

package/build/src/relations/define_relations_config.js

@@ -18,6 +18,7 @@
  */
 import { RelationConfigError, RelationConfigUnknownKeyError, RelationNotDenyableError, RelationDenyExpiryError, RelationTypeUnknownError, RelationUnknownError, RelationUsersetUnsupportedError, } from '../errors.js';
 import { RESERVED_FACTS_TYPES, RESERVED_SLUGS, RESERVED_SLUG_PREFIXES } from '../identity.js';
+import { assertGroupDepthSettings } from './group_depth.js';
 /**
  * **El ÚNICO userset que el modelo admite como sujeto** (plan 2.5 · lote B · B3):
  * `group#member`. El generador del modelo fusionado emite, para CADA relación de
@@ -58,10 +59,10 @@ const FGA_NAME_FORMAT = /^[a-z0-9][a-z0-9._-]*$/;
  * Las claves del lote D entran AQUÍ, en el mismo commit que su efecto.
  */
 export const RELATIONS_SPEC_KEYS = Object.freeze({
-    root: Object.freeze(['objectTypes', 'holderTypes', 'database']),
+    root: Object.freeze(['objectTypes', 'holderTypes', 'database', 'maxGroupDepth']),
     objectType: Object.freeze(['type', 'relations', 'deny']),
     relation: Object.freeze(['name', 'includes']),
-    database: Object.freeze(['membersOf']),
+    database: Object.freeze(['membersOf', 'enforceGroupDepth']),
 });
 const _exhaustiveRelationsRoot = {};
 const _exhaustiveRelationsObjectType = {};
@@ -431,9 +432,14 @@ export function defineRelationsConfig(spec) {
             ? Object.freeze({ type: objectType.type, relations: Object.freeze(relations) })
             : Object.freeze({ type: objectType.type, relations: Object.freeze(relations), deny: objectType.deny });
     });
+    // R1 (decisión del dueño 2026-10-17 (5); V2-1 del auditor): el techo se valida AL ARRANCAR, 500 y no 422 — un valor
+    // así no es una pregunta mal hecha, es un despliegue que apagaría el límite en silencio.
+    const { maxGroupDepth, enforceGroupDepth } = assertGroupDepthSettings(spec.maxGroupDepth, spec.database?.enforceGroupDepth);
     return Object.freeze({
         objectTypes: Object.freeze(frozenTypes),
         membersOf: spec.database?.membersOf === true,
+        ...(maxGroupDepth === undefined ? {} : { maxGroupDepth }),
+        ...(enforceGroupDepth === true ? { enforceGroupDepth: true } : {}),
         hasType: (objectType) => declared.has(objectType),
         isDeclared: (objectType, relation) => declared.get(objectType)?.has(relation) ?? false,
     });
@@ -596,4 +602,3 @@ export function assertDenyNoExpiry(options) {
             `caduca el GRANT (relate con expiresAt), no el deny. No se ha escrito nada.`);
     }
 }
-//# sourceMappingURL=define_relations_config.js.map

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

@@ -0,0 +1,102 @@
+import type { RelationsConfig } from './define_relations_config.js';
+type ConfigLike = Pick<RelationsConfig, 'objectTypes'>;
+/** Un deny vivo, agregado por tipo y relación PÚBLICA (`editor`, no `denied_editor`). */
+export interface LiveDenyGroup {
+    objectType: string;
+    relation: string;
+    /**
+     * Cuántos denies vivos hay sobre `objectType#relation`: filas de `authz_relations` en la guarda; en el detector de
+     * reconcile, CLAVES DE TUPLA DISTINTAS (firma (8 · `count`): un deny espejado en origen y destino cuenta una vez).
+     */
+    count: number;
+}
+/**
+ * Por qué un grupo de denies vivos es un hallazgo: `shrunk`/`orphan` (la config nueva encoge su alcance), `no-baseline`
+ * (sin línea base utilizable no se puede juzgar) o `stale` (la línea base es más estrecha que lo servido; solo el detector).
+ */
+export type DenyReachReason = 'shrunk' | 'orphan' | 'no-baseline' | 'stale';
+/** Un grupo de denies vivos cuyo alcance encoge con la config nueva, con su receta. */
+export interface DenyReachFinding {
+    objectType: string;
+    relation: string;
+    reason: DenyReachReason;
+    count: number;
+    /**
+     * El alcance con la config VIEJA (`down*` en la línea base); `null` = sin línea base o ya huérfano allí. Con `stale`, el
+     * alcance que CREE la línea base (`null` si no declara la relación).
+     */
+    before: string[] | null;
+    /** El alcance con la config NUEVA; `[]` si quedó huérfano. Con `stale`, el de la config SERVIDA. */
+    after: string[];
+    /**
+     * Lo que deja de cortar (`before \ after`); con `orphan` sin línea base, `[relation]`; con `no-baseline`, `[]` (no se
+     * sabe); con `stale`, lo que el deny corta con lo servido y la línea base no sabe (`after \ before`).
+     */
+    lost: string[];
+    /** La receta (español, como el resto de la letra del paquete). */
+    recipe: string;
+}
+/**
+ * **El alcance de un deny sobre `objectType#relation`** con `config`: `down*(relation)` ordenado, o `null` si la config no
+ * declara ese tipo o esa relación (huérfano).
+ */
+export declare function denyReachOf(config: ConfigLike, objectType: string, relation: string): string[] | null;
+/** La relación ALMACENADA `denied_<rel>` ⇒ `<rel>`; cualquier otra ⇒ `null` (no es un deny). */
+export declare function deniedPublicRelation(stored: string): string | null;
+/** La clave `tipo#relación` de un grupo o hallazgo: la que nombra la salida forzada acotada (`allowDenyReachShrink`). */
+export declare function denyReachKey(group: {
+    objectType: string;
+    relation: string;
+}): string;
+/** La forma de una clave `tipo#relación` que acepta la salida forzada acotada (dos nombres no vacíos, sin `#` ni blancos). */
+export declare const DENY_REACH_KEY_PATTERN: RegExp;
+/**
+ * **La lectura de la LÍNEA BASE, TODO O NADA y tipada** (firma (8 · línea base); conflicto 6 del juez del panel): de la spec
+ * persistida (el JSON ya parseado) lee SOLO lo que decide un alcance —`objectTypes[].{type, relations[].{name, includes}}`—,
+ * sin pasar por `defineRelationsConfig` (una fila de 2.4/alpha.3 con una clave que 2.5 no conoce sigue siendo una línea
+ * base: la receta de B5, re-guardar la misma spec corregida, entra sin forzar). Cualquier forma rota EN LO QUE LEE —un
+ * objeto que no lo es, `objectTypes`/`relations` que no son arrays, un `type`/`name` que no es string, un `includes`
+ * presente que no es un array de strings— deja la línea base como NO UTILIZABLE (`null`): **nunca se filtra** (filtrar
+ * subestima el alcance viejo y deja pasar el estrechamiento: S-D3 del tester del panel). Un `includes` ausente es `[]`
+ * (la spec lo permite).
+ */
+export declare function denyReachBaselineOf(parsed: unknown): ConfigLike | null;
+/**
+ * **La propiedad de (8)**: para cada grupo de denies vivos, ¿`alcance(after) ⊇ alcance(before)`? Devuelve los que la
+ * violan (`shrunk` | `orphan`, orden estable por tipo y relación), vacío si ninguno. `before = null` = sin línea base: solo
+ * `orphan` (el motivo `no-baseline` lo añade `judgeDenyReach`).
+ */
+export declare function denyReachFindings(before: ConfigLike | null, after: ConfigLike, denies: Iterable<LiveDenyGroup>): DenyReachFinding[];
+/**
+ * **El juicio de la guarda (y la mitad «persistida → servida» de los detectores)**: `denyReachFindings` más, SIN línea base
+ * utilizable (`baseline === null`), un hallazgo `no-baseline` por cada grupo de denies vivos que no sea ya `orphan` (de un
+ * huérfano sí se sabe que encoge: su alcance es ∅). Sin denies vivos no hay hallazgo alguno: la primera fila se crea sin
+ * forzar. Orden estable por tipo, relación y motivo.
+ */
+export declare function judgeDenyReach(baseline: ConfigLike | null, next: ConfigLike, denies: Iterable<LiveDenyGroup>): DenyReachFinding[];
+/**
+ * **La línea base RANCIA** (firma (8 · rancia); conflicto 3 del juez): la dirección inversa, `denyReachFindings(servida,
+ * persistida)`. Un grupo de denies vivos cuyo alcance con lo SERVIDO no cabe en el de la línea base (la fila no declara la
+ * relación que se sirve, o la declara más estrecha) es un hallazgo `stale`: la flota sirvió (o sirve) algo que la fila no
+ * registra, y desde esa fila un estrechamiento de vuelta a ella parecería «sin cambio» (A1/S-B). Un grupo que lo servido
+ * tampoco declara no es rancio (es `orphan` en la otra dirección).
+ */
+export declare function staleDenyReach(baseline: ConfigLike, served: ConfigLike, denies: Iterable<LiveDenyGroup>): DenyReachFinding[];
+/** Lo que devuelven los dos detectores (el de un driver y el de `--dry-run`) para un estado: las dos direcciones. */
+export interface DenyReachCheck {
+    /** `'persisted'`: hay línea base utilizable; `'none'`: no la hay (sin fila, o fila que la lectura TODO O NADA no tipa). */
+    baseline: 'persisted' | 'none';
+    /** Persistida → servida: `shrunk`, `orphan` y, sin línea base, `no-baseline` (el juicio de la guarda, sin salidas). */
+    findings: DenyReachFinding[];
+    /** Servida → persistida: `stale` (solo con línea base). */
+    staleBaseline: DenyReachFinding[];
+}
+/** **Los dos sentidos sobre el mismo estado** (firma (8 · detector de un driver)): el punto de paso de los detectores. */
+export declare function denyReachCheck(baseline: ConfigLike | null, served: ConfigLike, denies: Iterable<LiveDenyGroup>): DenyReachCheck;
+/**
+ * Una línea por hallazgo, con el prefijo ESTABLE de su rama (CLAUDE.md punto 7): la usan el error de la guarda, el detector
+ * de un driver y el comando. Prefijos: «deny con alcance ENCOGIDO», «deny HUÉRFANO», «deny SIN línea base», «línea base
+ * RANCIA».
+ */
+export declare function denyReachLine(finding: DenyReachFinding): string;
+export {};

package/build/src/relations/deny_reach.js

@@ -0,0 +1,230 @@
+/**
+ * **El ALCANCE de un deny vivo, y cuándo un cambio de config lo ENCOGE** (lote RC · sublote (8); decisión §2026-10-15 (8)
+ * del dueño y firmas «(8 · panel)» 2026-10-22). Módulo PURO (sin `db`, sin drivers: regla 2 de pureza) y PUNTO DE PASO
+ * ÚNICO de las tres piezas de (8) —los gemelos guarda ↔ detector de un driver ↔ `--dry-run`—:
+ *
+ *  - la **guarda de `database`** (`saveRelationsConfig`, `src/relations_config_store.ts`): `judgeDenyReach` sobre la línea
+ *    base persistida (leída TODO O NADA por `denyReachBaselineOf`), la config nueva y los denies vivos de `authz_relations`;
+ *    niega (500 `E_AUTHZ_DENY_REACH_REFUSED`, cero escrituras) salvo las dos salidas con nombre: `establishBaseline: true`
+ *    (solo el motivo `no-baseline`) y `allowDenyReachShrink: ['tipo#relación', …]` (solo esos hallazgos);
+ *  - el **detector de un solo driver** (`checkRelationsConfigDenyReach`, mismo módulo de la guarda): `denyReachCheck`, la
+ *    misma línea base y los mismos denies, en las DOS direcciones (persistida → servida, y servida → persistida: la línea
+ *    base RANCIA, A1/S-B del panel);
+ *  - el **detector de `authz:relations:reconcile --dry-run`** (`reconcileRelations({ denyReach })`): `denyReachCheck` sobre
+ *    los denies que la pasada YA enumeró, en origen y destino. En `openfga` es solo detección (regla (ritmo): cero
+ *    arreglos hasta 2.6; la guarda de `openfga:provision` sigue siendo el límite declarado `openfga.provision.deny-reach`).
+ *
+ * **El alcance** de un deny sobre `T#X` es el conjunto de relaciones cuyos grants CORTA (D5, corte de camino:
+ * `cutPathAllows` corta un grant de `g` sii algún deny vivo está en `up*(g)`, o sea sii `g ∈ down*(X)`):
+ * `alcance(T#X) = down*(X)`. Con `editor: { includes: ['owner'] }` un deny en `editor` corta `{editor, owner}`; estrechado
+ * a `includes: []` corta solo `{editor}` y el owner directo vuelve a conceder (el escenario firmado).
+ *
+ * **La propiedad firmada es «para todo deny vivo, alcance_nuevo ⊇ alcance_viejo»**, NO «la relación sigue existiendo».
+ * Motivos de un hallazgo:
+ *  - `shrunk`: `T#X` sigue declarada pero `down*_nuevo(X) ⊉ down*_viejo(X)` —un `includes` estrechado, directo o
+ *    TRANSITIVO, o una relación de `down*_viejo(X)` retirada del tipo—;
+ *  - `orphan`: `T#X` ya no está declarada (relación o tipo retirados): el deny no lo lee nadie (alcance ∅) y ningún
+ *    `removeDeny` lo alcanza (F-05); si la relación se vuelve a declarar, el deny resucita. Se juzga SIEMPRE contra la
+ *    config nueva, con o sin línea base, y aunque ya fuera huérfano en la línea base (firma (8 · salida forzada): P2 «juzgar
+ *    por delta» NO entra — una AUSENCIA en una fila que puede estar rancia no prueba que el deny ya fuera huérfano en la flota);
+ *  - `no-baseline`: no hay línea base UTILIZABLE (sin fila, o una fila que la lectura TODO O NADA no puede tipar) y el deny
+ *    vive: no se puede juzgar si encoge (firma (8 · línea base));
+ *  - `stale` (solo el detector): la línea base no sabe que el deny corta algo que la config SERVIDA sí corta — la fila es
+ *    más estrecha que lo servido, y desde ella un estrechamiento de vuelta parecería «sin cambio» (firma (8 · rancia)).
+ *
+ * Decisiones que siguen (informe `loteRC-8-informe.md`, sin cambio del dueño): una relación de `down*_viejo(X)` RETIRADA del
+ * tipo cuenta como encogimiento aunque sus grants ya no concedan (la propiedad, literal); retirar el opt-in `deny` de un tipo
+ * NO cambia el alcance en `database` (las lecturas honran la fila igual) y no se juzga aquí — en `openfga` lo juzga la guarda
+ * de `provision` (`--allow-drop-deny`).
+ */
+import { RELATION_DENY_PREFIX, relationsDown } from './define_relations_config.js';
+/**
+ * **El alcance de un deny sobre `objectType#relation`** con `config`: `down*(relation)` ordenado, o `null` si la config no
+ * declara ese tipo o esa relación (huérfano).
+ */
+export function denyReachOf(config, objectType, relation) {
+    const type = config.objectTypes.find((t) => t.type === objectType);
+    if (!type || !type.relations.some((r) => r.name === relation))
+        return null;
+    return relationsDown(config, objectType, relation).sort();
+}
+/** La relación ALMACENADA `denied_<rel>` ⇒ `<rel>`; cualquier otra ⇒ `null` (no es un deny). */
+export function deniedPublicRelation(stored) {
+    return typeof stored === 'string' && stored.startsWith(RELATION_DENY_PREFIX) && stored.length > RELATION_DENY_PREFIX.length
+        ? stored.slice(RELATION_DENY_PREFIX.length)
+        : null;
+}
+/** La clave `tipo#relación` de un grupo o hallazgo: la que nombra la salida forzada acotada (`allowDenyReachShrink`). */
+export function denyReachKey(group) {
+    return `${group.objectType}#${group.relation}`;
+}
+/** La forma de una clave `tipo#relación` que acepta la salida forzada acotada (dos nombres no vacíos, sin `#` ni blancos). */
+export const DENY_REACH_KEY_PATTERN = /^[^#\s]+#[^#\s]+$/;
+/**
+ * **La lectura de la LÍNEA BASE, TODO O NADA y tipada** (firma (8 · línea base); conflicto 6 del juez del panel): de la spec
+ * persistida (el JSON ya parseado) lee SOLO lo que decide un alcance —`objectTypes[].{type, relations[].{name, includes}}`—,
+ * sin pasar por `defineRelationsConfig` (una fila de 2.4/alpha.3 con una clave que 2.5 no conoce sigue siendo una línea
+ * base: la receta de B5, re-guardar la misma spec corregida, entra sin forzar). Cualquier forma rota EN LO QUE LEE —un
+ * objeto que no lo es, `objectTypes`/`relations` que no son arrays, un `type`/`name` que no es string, un `includes`
+ * presente que no es un array de strings— deja la línea base como NO UTILIZABLE (`null`): **nunca se filtra** (filtrar
+ * subestima el alcance viejo y deja pasar el estrechamiento: S-D3 del tester del panel). Un `includes` ausente es `[]`
+ * (la spec lo permite).
+ */
+export function denyReachBaselineOf(parsed) {
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    const objectTypes = parsed.objectTypes;
+    if (!Array.isArray(objectTypes))
+        return null;
+    const types = [];
+    for (const t of objectTypes) {
+        if (t === null || typeof t !== 'object' || Array.isArray(t))
+            return null;
+        if (typeof t.type !== 'string' || !Array.isArray(t.relations))
+            return null;
+        const relations = [];
+        for (const r of t.relations) {
+            if (r === null || typeof r !== 'object' || Array.isArray(r) || typeof r.name !== 'string')
+                return null;
+            if (r.includes !== undefined && !(Array.isArray(r.includes) && r.includes.every((i) => typeof i === 'string')))
+                return null;
+            relations.push({ name: r.name, includes: Array.isArray(r.includes) ? r.includes.filter((i) => typeof i === 'string') : [] });
+        }
+        types.push({ type: t.type, relations });
+    }
+    return { objectTypes: types };
+}
+function mergeGroups(denies) {
+    const groups = new Map();
+    for (const deny of denies) {
+        const key = denyReachKey(deny);
+        const seen = groups.get(key);
+        groups.set(key, seen ? { ...seen, count: seen.count + deny.count } : { ...deny });
+    }
+    return [...groups.values()];
+}
+const byKey = (a, b) => denyReachKey(a).localeCompare(denyReachKey(b)) || String(a.reason ?? '').localeCompare(String(b.reason ?? ''));
+/**
+ * **La propiedad de (8)**: para cada grupo de denies vivos, ¿`alcance(after) ⊇ alcance(before)`? Devuelve los que la
+ * violan (`shrunk` | `orphan`, orden estable por tipo y relación), vacío si ninguno. `before = null` = sin línea base: solo
+ * `orphan` (el motivo `no-baseline` lo añade `judgeDenyReach`).
+ */
+export function denyReachFindings(before, after, denies) {
+    const findings = [];
+    for (const group of mergeGroups(denies).sort(byKey)) {
+        const old = before ? denyReachOf(before, group.objectType, group.relation) : null;
+        const now = denyReachOf(after, group.objectType, group.relation);
+        if (now === null) {
+            findings.push({
+                ...group,
+                reason: 'orphan',
+                before: old,
+                after: [],
+                lost: old ?? [group.relation],
+                recipe: orphanRecipe(group),
+            });
+            continue;
+        }
+        if (old === null)
+            continue;
+        const lost = old.filter((relation) => !now.includes(relation));
+        if (lost.length === 0)
+            continue;
+        findings.push({ ...group, reason: 'shrunk', before: old, after: now, lost, recipe: shrunkRecipe(group, lost) });
+    }
+    return findings;
+}
+/**
+ * **El juicio de la guarda (y la mitad «persistida → servida» de los detectores)**: `denyReachFindings` más, SIN línea base
+ * utilizable (`baseline === null`), un hallazgo `no-baseline` por cada grupo de denies vivos que no sea ya `orphan` (de un
+ * huérfano sí se sabe que encoge: su alcance es ∅). Sin denies vivos no hay hallazgo alguno: la primera fila se crea sin
+ * forzar. Orden estable por tipo, relación y motivo.
+ */
+export function judgeDenyReach(baseline, next, denies) {
+    const groups = mergeGroups(denies);
+    const findings = denyReachFindings(baseline, next, groups);
+    if (baseline !== null)
+        return findings;
+    const judged = new Set(findings.map(denyReachKey));
+    for (const group of groups) {
+        if (judged.has(denyReachKey(group)))
+            continue;
+        findings.push({ ...group, reason: 'no-baseline', before: null, after: denyReachOf(next, group.objectType, group.relation) ?? [], lost: [], recipe: noBaselineRecipe(group) });
+    }
+    return findings.sort(byKey);
+}
+/**
+ * **La línea base RANCIA** (firma (8 · rancia); conflicto 3 del juez): la dirección inversa, `denyReachFindings(servida,
+ * persistida)`. Un grupo de denies vivos cuyo alcance con lo SERVIDO no cabe en el de la línea base (la fila no declara la
+ * relación que se sirve, o la declara más estrecha) es un hallazgo `stale`: la flota sirvió (o sirve) algo que la fila no
+ * registra, y desde esa fila un estrechamiento de vuelta a ella parecería «sin cambio» (A1/S-B). Un grupo que lo servido
+ * tampoco declara no es rancio (es `orphan` en la otra dirección).
+ */
+export function staleDenyReach(baseline, served, denies) {
+    return denyReachFindings(served, baseline, denies)
+        .filter((reverse) => reverse.before !== null)
+        .map((reverse) => ({
+        objectType: reverse.objectType,
+        relation: reverse.relation,
+        count: reverse.count,
+        reason: 'stale',
+        before: reverse.reason === 'orphan' ? null : reverse.after,
+        after: reverse.before,
+        lost: reverse.lost,
+        recipe: staleRecipe(reverse),
+    }));
+}
+/** **Los dos sentidos sobre el mismo estado** (firma (8 · detector de un driver)): el punto de paso de los detectores. */
+export function denyReachCheck(baseline, served, denies) {
+    const groups = mergeGroups(denies);
+    return {
+        baseline: baseline === null ? 'none' : 'persisted',
+        findings: judgeDenyReach(baseline, served, groups),
+        staleBaseline: baseline === null ? [] : staleDenyReach(baseline, served, groups),
+    };
+}
+function shrunkRecipe(group, lost) {
+    return (`antes de estrechar, vuelve a emitir cada uno de esos ${group.count} deny(s) sobre una relación de '${group.objectType}' que ` +
+        `con la config nueva siga cortando ${lost.map((r) => `'${r}'`).join(', ')} (deny(<sujeto>, '<esa relación>', <objeto>); ` +
+        `listDenies(<objeto>, '${group.relation}') los enumera), o deja el includes como estaba; si de verdad deben dejar de ` +
+        `cortarlo, nombra este hallazgo en la salida forzada: allowDenyReachShrink: ['${denyReachKey(group)}']`);
+}
+function orphanRecipe(group) {
+    return (`antes de retirar '${denyReachKey(group)}', quita esos ${group.count} deny(s) con removeDeny (o re-emítelos sobre ` +
+        `una relación que se quede) y retírala después; si ya la retiraste, vuelve a declararla, haz removeDeny y retírala — ` +
+        `un deny huérfano no lo lee nadie, ningún removeDeny lo alcanza (F-05) y resucita si la relación se vuelve a declarar ` +
+        `(y re-declararla tras forzar la retirada resucita también los grants que cortaba)`);
+}
+function noBaselineRecipe(group) {
+    return (`guarda UNA vez la spec que la flota sirve HOY, sin cambios, con saveRelationsConfig(spec, { establishBaseline: true }), ` +
+        `en una release que NO cambie relations.config (adoptar en una release que estrecha certifica el estrechamiento); ` +
+        `desde esa fila la guarda juzga cada cambio de '${denyReachKey(group)}'`);
+}
+function staleRecipe(reverse) {
+    return (`la línea base (authz_relations_config) es más estrecha que la config que se sirve: guarda con saveRelationsConfig la ` +
+        `config que sirve la flota —persistir la config es paso obligatorio de release si usas deny— y vuelve a correr la ` +
+        `comprobación; mientras la fila no lo sepa, un estrechamiento de vuelta a ella no lo niega la guarda y los ` +
+        `${reverse.count} deny(s) de '${denyReachKey(reverse)}' dejarían de cortar ${reverse.lost.map((r) => `'${r}'`).join(', ')}`);
+}
+/**
+ * Una línea por hallazgo, con el prefijo ESTABLE de su rama (CLAUDE.md punto 7): la usan el error de la guarda, el detector
+ * de un driver y el comando. Prefijos: «deny con alcance ENCOGIDO», «deny HUÉRFANO», «deny SIN línea base», «línea base
+ * RANCIA».
+ */
+export function denyReachLine(finding) {
+    const where = `${denyReachKey(finding)} (${finding.count} deny(s))`;
+    switch (finding.reason) {
+        case 'orphan':
+            return `deny HUÉRFANO ${where}: la config nueva no declara la relación (cortaba ${finding.lost.join(', ')}). Receta: ${finding.recipe}.`;
+        case 'no-baseline':
+            return (`deny SIN línea base ${where}: no hay config persistida utilizable en authz_relations_config con la que comparar, así que ` +
+                `no se puede saber si la config nueva encoge su alcance (hoy corta ${finding.after.join(', ')}). Receta: ${finding.recipe}.`);
+        case 'stale':
+            return (`línea base RANCIA ${where}: con la config servida el deny corta ${finding.after.join(', ')}, y la config persistida ` +
+                `${finding.before === null ? 'no declara la relación' : `solo sabe de ${finding.before.join(', ')}`} (no sabe de ` +
+                `${finding.lost.join(', ')}). Receta: ${finding.recipe}.`);
+        default:
+            return (`deny con alcance ENCOGIDO ${where}: cortaba ${finding.before.join(', ')} y con la config nueva solo ${finding.after.join(', ')} ` +
+                `(deja de cortar ${finding.lost.join(', ')}: lo que negaba vuelve a conceder). Receta: ${finding.recipe}.`);
+    }
+}

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

@@ -0,0 +1,215 @@
+/**
+ * **El límite de anidación de grupos** (lote «antes de RC» · R1; decisiones del dueño 2026-10-17 (5) «límite SEGÚN EL
+ * DRIVER» y (5-bis) opción (a) tras F0 · M-c). Piezas PURAS (sin backend), compartidas por los dos drivers de relaciones
+ * y por el plan de `reconcileRelations`, para que la regla sea UNA:
+ *
+ *  - **qué es una arista de anidación**: `group:<Gp>#member@group:<Gc>#member` (los miembros de Gc son miembros de Gp);
+ *  - **la profundidad es el camino MÁS LARGO** de aristas grupo⊂grupo (T-3 del tester: en un DAG con un camino corto y
+ *    otro largo hacia la misma cima, OpenFGA da 503 a los NO-miembros por el largo; un BFS por niveles admitiría ese
+ *    grafo). Un ciclo PREEXISTENTE se cuenta de forma CONSERVADORA: sus k nodos pesan k − 1 saltos (cota superior del
+ *    camino simple más largo que lo atraviesa) — más negativas, nunca menos;
+ *  - **la validación de `maxGroupDepth`** (V2-1 del auditor): entero 1..`GROUP_DEPTH_CONFIG_MAX` o `false` (el ÚNICO
+ *    «apagado»), y nada más — `''`, `NaN`, `0`, `-1`, `Infinity`, `24.5`, `'24'`, `null`, `true` ⇒ 500 al ARRANCAR
+ *    (`defineRelationsConfig`), jamás un gate apagado en silencio;
+ *  - **la calibración** (decisión 5 + 5-bis): el techo de `openfga` se MIDE contra el servidor con tuplas contextuales
+ *    (solo lectura) y es el MÍNIMO de la sonda POSITIVA (un miembro: T) y la NEGATIVA (un no-miembro CON alguna
+ *    membresía: F; una sonda sin membresías es CIEGA, F a cualquier profundidad, F0 · M-c). La búsqueda es pura sobre
+ *    una sonda inyectada.
+ *
+ * Pureza (regla 2): solo depende de los errores. Nada de `manager`/`drivers/*`.
+ */
+import { AuthorizationBackendError, GroupDepthLimitError } from '../errors.js';
+import type { RelObject, RelSubject } from '../types.js';
+/**
+ * **El techo medido** en OpenFGA v1.19.0 con `--resolve-node-limit` por defecto (25): un miembro resuelve 24 saltos
+ * grupo⊂grupo y un no-miembro CON membresías 22 (F0 · M-c, 200/200 en los dos bordes, independiente de `includes` 0..3 y
+ * del deny) ⇒ el MÍNIMO, 22. Es la cifra de la fila de «Limits»; la VERDAD de cada despliegue es la calibración.
+ */
+export declare const RELATIONS_GROUP_DEPTH_MEASURED = 22;
+/**
+ * **El mayor `maxGroupDepth` que se acepta** (auditor M4): la calibración usa una cadena de tuplas CONTEXTUALES y el
+ * servidor admite 100 por `Check`; la forma de dominio cuesta K + 2. Por encima no hay nada que medir.
+ */
+export declare const GROUP_DEPTH_CONFIG_MAX = 97;
+/**
+ * **El mayor K que la calibración prueba**: la sonda NEGATIVA lleva dos tuplas más (la membresía del no-miembro y la
+ * suya propia, M-c) ⇒ K + 4 ≤ 100. Un `maxGroupDepth: 97` es válido en la config y, contra un servidor que resolviera
+ * todo, la calibración lo deja en 96 ⇒ 500 (el techo pedido no se puede DEMOSTRAR).
+ */
+export declare const GROUP_DEPTH_CALIBRATION_MAX = 96;
+/**
+ * **Cuántos grupos recorre como mucho la comprobación de UNA arista** (hacia arriba desde Gp más hacia abajo desde Gc).
+ * Pasarla ⇒ 422 `E_AUTHZ_GROUP_DEPTH_LIMIT` con motivo `too-many-groups`, nunca «pasa». El recorrido además se corta en
+ * cuanto un nivel del BFS supera el techo (el camino más corto ya excede: el largo también).
+ */
+export declare const GROUP_DEPTH_MAX_NODES = 10000;
+/**
+ * **El presupuesto de la comprobación de UNA arista en `openfga`** (cierre de R1 · 🟠 1 del auditor: amplificación de
+ * lecturas contra el store COMPARTIDO). En `openfga` el gate hace un `Read` por grupo de la frontera, y el `Read` hacia
+ * ABAJO (objeto + `member`) trae también los HOLDERS —el servidor no admite filtrar por tipo de `user` (`user: 'group:'`
+ * ⇒ 400 `validation_error`, medido en :8090 v1.19)—: sin presupuesto, quien controla la anidación hacía pagar O(grupos ×
+ * miembros/100) requests a cada `relate`. Pasar cualquiera de los tres ⇒ 422 `E_AUTHZ_GROUP_DEPTH_LIMIT`, motivo
+ * `too-many-groups` (fail-closed: no se escribe). Requests (páginas de `Read`), tuplas leídas y un deadline TOTAL del
+ * veredicto (comprobado antes de cada request; una request en vuelo la acota el `timeoutMs` del cliente).
+ */
+export declare const GROUP_DEPTH_MAX_READS = 2000;
+export declare const GROUP_DEPTH_MAX_TUPLES = 50000;
+export declare const GROUP_DEPTH_DEADLINE_MS = 10000;
+/**
+ * **La espera tras una calibración FALLIDA** (cierre-2 de R1 · D5 (a), injerto del auditor; decisión del dueño 2026-10-20):
+ * la calibración de `openfga` son ~14 `Check` (bisección 0..96, dos sondas). Si cae (servidor caído, 503, deadline, el
+ * 500 de una sonda ciega), durante esta ventana la siguiente escritura de anidación recibe un error de la MISMA clase —una
+ * instancia nueva con el memorizado de `cause`, y un timeout como 503 no-timeout (cierre-3 · R-5)— sin volver a
+ * sondear —una flota de `relate` contra un servidor que se cae no lo remata con 14 `Check` cada uno—; pasada, la
+ * siguiente vuelve a calibrar (el fallo nunca se memoriza para siempre, C13a). Reloj MONÓTONO del driver.
+ */
+export declare const GROUP_DEPTH_CALIBRATION_BACKOFF_MS = 2000;
+/**
+ * **La cota de frecuencia de la RE-calibración** (cierre-2 de R1 · D5 (a) + P2 del juez): una lectura de `openfga` que
+ * recibe 503 `E_AUTHZ_RESOLUTION_LIMIT` (el servidor ya no resuelve lo que el techo memorizado prometía: el operador BAJÓ
+ * `OPENFGA_RESOLVE_NODE_LIMIT` sin reiniciar la app) invalida la calibración memorizada, como mucho UNA vez por este
+ * intervalo y por proceso; la siguiente escritura de anidación vuelve a medir. Sin la cota, una forma que dé 503 en cada
+ * lectura dispararía una calibración por lectura. SUBIR el límite del servidor no produce ningún 503 que lo delate: eso
+ * sigue pidiendo reiniciar la app.
+ */
+export declare const GROUP_DEPTH_RECALIBRATION_MIN_INTERVAL_MS = 60000;
+/** Qué cota del presupuesto se pasó (va en `details.budget` del 422). */
+export type GroupDepthBudgetKind = 'nodes' | 'reads' | 'tuples' | 'deadline';
+/** Señal INTERNA: el lector la lanza al pasar el presupuesto y `groupNestingVerdict` la convierte en `too-many-groups`. */
+export declare class GroupDepthBudgetExceeded extends Error {
+    readonly budget: Exclude<GroupDepthBudgetKind, 'nodes'>;
+    constructor(budget: Exclude<GroupDepthBudgetKind, 'nodes'>);
+}
+/** El contador de UN veredicto: `beforeRead()` antes de cada request, `charge(n)` con las tuplas de cada página. */
+export declare class GroupDepthBudget {
+    #private;
+    readonly limits: {
+        reads: number;
+        tuples: number;
+        deadlineMs: number;
+    };
+    readonly clock: () => number;
+    reads: number;
+    tuples: number;
+    constructor(limits?: {
+        reads: number;
+        tuples: number;
+        deadlineMs: number;
+    }, clock?: () => number);
+    beforeRead(): void;
+    charge(tuples: number): void;
+}
+/** Las opciones de `relate` de UNA arista planificada por el reconcile (solo el reconcile del paquete las crea). */
+export declare function plannedRelateOptions<T extends object>(options: T, tuple: {
+    subject: RelSubject;
+    relation: string;
+    object: RelObject;
+    partition: {
+        type: string;
+        uuid: string | null;
+    };
+}): T;
+/** ¿Llega ESTA arista (`child ⊂ parent` en `partition`) con las opciones que el reconcile creó para ella? */
+export declare function plannedByReconcile(options: unknown, partition: {
+    type: string;
+    uuid: string | null;
+}, edge: GroupEdge): boolean;
+/** `group:<Gp>#member@group:<Gc>#member`: la ÚNICA forma de anidar (B3: el único userset admitido es `group#member`). */
+export declare function isGroupNesting(subject: RelSubject, relation: string, object: RelObject): subject is Extract<RelSubject, {
+    relation: string;
+}>;
+/**
+ * **Valida `maxGroupDepth`** (V2-1; decisión 5: «entero 1..97 o `false`»): `undefined` ⇒ sin valor (el driver usa su
+ * techo), `false` ⇒ apagado EXPLÍCITO, entero en [1, 97] ⇒ ese techo. Cualquier otra cosa ⇒ 500 `E_AUTHZ_CONFIG`: el
+ * paquete no lee variables de entorno, y la línea típica `Number(env.get('X') ?? 24)` produce `0` (`''`) y `NaN` (`'abc'`),
+ * que con `if (depth > max)` o `if (!max)` APAGARÍAN el gate en silencio.
+ */
+export declare function assertMaxGroupDepth(value: unknown, where?: string): number | false | undefined;
+/**
+ * **Valida el PAR (`maxGroupDepth`, `enforceGroupDepth`)** — en `defineRelationsConfig` al arrancar y, desde el cierre de
+ * R1 (🟡 4 del auditor), OTRA VEZ en los dos drivers: una config extendida con spread
+ * (`{ ...defineRelationsConfig(spec), maxGroupDepth: Number(env.get('X')) }`) llegaba al driver sin pasar por la
+ * validación, y con `NaN` toda comparación `> limit` es `false`: el gate quedaba APAGADO en silencio. `enforceGroupDepth`
+ * solo admite `true`/`false`/ausente y `true` exige un número. Todo lo demás ⇒ 500 `E_AUTHZ_CONFIG`.
+ */
+export declare function assertGroupDepthSettings(maxGroupDepth: unknown, enforceGroupDepth: unknown, where?: string): {
+    maxGroupDepth: number | false | undefined;
+    enforceGroupDepth: boolean;
+};
+/** Una arista grupo⊂grupo: `child` es miembro de `parent` (ids de objeto del grupo, sin partición). */
+export interface GroupEdge {
+    child: string;
+    parent: string;
+}
+/**
+ * **La cadena más larga** (en aristas grupo⊂grupo) de un conjunto de aristas, con los ciclos colapsados de forma
+ * CONSERVADORA (cada componente fuertemente conexa de k nodos pesa k − 1). Devuelve la profundidad y una cadena
+ * representativa (los grupos, de abajo arriba) para la letra. Lineal en nodos + aristas (Tarjan iterativo + DP).
+ */
+export declare function groupChainDepth(edges: Iterable<GroupEdge>): {
+    depth: number;
+    chain: string[];
+};
+/** El veredicto de UNA arista nueva sobre la región recorrida. */
+export type GroupNestingVerdict = {
+    kind: 'ok';
+    depth: number;
+} | {
+    kind: 'cycle';
+    depth: null;
+} | {
+    kind: 'too-deep';
+    depth: number;
+    chain: string[];
+} | {
+    kind: 'too-many-groups';
+    depth: null;
+    budget: GroupDepthBudgetKind;
+};
+/** Cómo leer los vecinos de un conjunto de grupos (UNA llamada por nivel del BFS en SQL; una `Read` por grupo en FGA). */
+export interface GroupNeighbourReader {
+    /** Las aristas VIVAS cuyo `child` está en `groups` (los grupos que los contienen). */
+    parentsOf(groups: string[]): Promise<GroupEdge[]>;
+    /** Las aristas VIVAS cuyo `parent` está en `groups` (los grupos que contienen). */
+    childrenOf(groups: string[]): Promise<GroupEdge[]>;
+}
+/**
+ * **El veredicto de la arista `child ⊂ parent`** (gate de escritura de R1): recorre hacia ARRIBA desde `parent` y hacia
+ * ABAJO desde `child` (BFS por niveles, una lectura por nivel), y decide:
+ *
+ *  - `cycle` si `child` es `parent` o aparece por encima de `parent` (la arista lo cerraría);
+ *  - `too-deep` si el camino MÁS LARGO que atraviesa la arista (`alto(parent) + 1 + bajo(child)`) supera `limit` — y
+ *    también, sin terminar el recorrido, en cuanto los niveles del BFS ya lo superan (el camino corto es una cota
+ *    inferior del largo);
+ *  - `too-many-groups` si la región pasa de `maxNodes`, o si el LECTOR agota su presupuesto (`GroupDepthBudgetExceeded`:
+ *    requests, tuplas o deadline — `openfga`, cierre de R1 · 🟠 1 del auditor);
+ *  - `ok` en otro caso.
+ *
+ * La arista misma (si ya existe: renovación) no se cuenta dos veces.
+ */
+export declare function groupNestingVerdict(edge: GroupEdge, limit: number, reader: GroupNeighbourReader, maxNodes?: number): Promise<GroupNestingVerdict>;
+/**
+ * **El error de un veredicto que no es `ok`** (cierre-3 de R1 · R-2 del re-ataque; decisión firmada (3): lo transitorio es
+ * 503): el agotamiento del DEADLINE del presupuesto (`budget: 'deadline'`) no dice nada de los datos —el mismo grafo da
+ * `ok` con el servidor descargado— sino que el backend va LENTO (o lo satura otro tenant del store compartido), así que es
+ * 503 `AuthorizationBackendError` transitorio —NO la subclase timeout: la escritura no ocurrió y el manager no notifica
+ * `indeterminate` (invariante 13)— y nunca el 422 «aplana la anidación», que un cliente no reintenta. Las otras cotas
+ * (`nodes`, `reads`, `tuples`) son deterministas sobre los datos y siguen siendo 422 `too-many-groups`.
+ */
+export declare function groupNestingError(driver: string, verdict: Exclude<GroupNestingVerdict, {
+    kind: 'ok';
+}>, edge: string, limit: number): GroupDepthLimitError | AuthorizationBackendError;
+/** El 422 de un veredicto que no es `ok` (letra de `E_AUTHZ_SCOPE_DEPTH_LIMIT`: el `message` no nombra el backend). */
+export declare function groupDepthLimitError(verdict: Exclude<GroupNestingVerdict, {
+    kind: 'ok';
+}>, edge: string, limit: number): GroupDepthLimitError;
+/** Resultado de una sonda de calibración: el `Check` resolvió con la respuesta esperada, excedió, o dio la OTRA respuesta. */
+export type CalibrationProbe = 'ok' | 'too-complex' | 'blind';
+/**
+ * **La calibración del techo** (decisión 5 + 5-bis, opción (a)): el mayor K en [0, `max`] para el que la sonda
+ * POSITIVA (un miembro, T) Y la NEGATIVA (un no-miembro con membresía, F) resuelven — el MÍNIMO de las dos —, por
+ * bisección (el borde es determinista en relaciones, M-c: 200/200). Una sonda que da la OTRA respuesta (`blind`: el
+ * miembro F, el no-miembro T) es un servidor o un modelo que no evalúa como el medido ⇒ 500, jamás «pasa». Cualquier
+ * otro fallo de la sonda (503, deadline) se PROPAGA: quien llama no lo memoriza.
+ */
+export declare function calibrateGroupDepth(probe: (depth: number, side: 'positive' | 'negative') => Promise<CalibrationProbe>, max?: number): Promise<number>;