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

package/build/src/relations/tuple_order.js

@@ -0,0 +1,599 @@
+/**
+ * **El ORDEN de las escrituras y de los borrados de relaciones — punto de paso ÚNICO** (plan 2.5 · lote D; linaje L10
+ * «el estado intermedio de una operación multi-request concede», PROMOVIDO: 3b-2f R3, 3b-6 P1, D1 🟠 1 —la purga de
+ * `openfga`—, D2 🟠 1 —el reconcile— y, en el cierre 2 de D2, 🟡 N3 —escrituras y poda COMPUESTAS—). Lo usan los DOS
+ * caminos que escriben o borran relaciones en varias requests: `applyPartition` del reconcile
+ * (`src/relations/reconcile.ts`) y `purgeWrites` de las purgas de `openfga` (`src/drivers/openfga_relations_driver.ts`).
+ *
+ * **Cierre 2 de D2 · 🟡 N3 (estructural).** Hasta aquí había DOS órdenes (uno de escritura y otro de borrado) y el reconcile
+ * los encadenaba: TODAS las escrituras y luego TODA la poda. Un ex-miembro componía con un allow nuevo (U ∈ g sobra,
+ * `g#member viewer X` es nuevo: cortada tras la 1.ª escritura, U concedía sobre X y ni el inicial ni el final lo hacían).
+ * Ahora hay UNA función, `relationTransitionOrder`, que ordena la TRANSICIÓN entera (escrituras, borrados y renovaciones)
+ * y una propiedad que se DEMUESTRA por fuerza bruta (`tests/helpers/order_bruteforce.ts`, propiedad
+ * `relations.order.exhaustive` de la guardia y `tests/relations_order_exhaustive.spec.ts`).
+ *
+ * **Cinco fases** (las cuatro de los extremos solo restringen o solo amplían; lo difícil es la de en medio):
+ *
+ *  1. escribir los DENIES nuevos (y rehacer los que cambian) — solo restringe;
+ *  2. borrar los ALLOWS sobrantes sobre objetos que no son `group` — solo restringe;
+ *  3. las MEMBRESÍAS `group:*#member` que entran y que salen, en el orden de un GRAFO DE PRECEDENCIAS (abajo); con los
+ *     allows reducidos a los que están en los dos estados y TODOS los denies de los dos estados presentes, que es el
+ *     contexto más restrictivo posible para el paso difícil;
+ *  4. escribir los ALLOWS nuevos (y las renovaciones que no son denies) — con las membresías y los denies finales
+ *     presentes, solo puede conceder lo que concede el final;
+ *  5. borrar los DENIES sobrantes, los ÚLTIMOS — idem.
+ *
+ * **El grafo de la fase 3.** Para cada membresía que cambia (arista `sujeto → grupo`) se calcula, en el grafo UNIÓN de
+ * los dos estados, qué objetos DENIEGA lo que alcanza su grupo (`D`) y qué objetos le CONCEDE de forma efectiva (`A`: los
+ * allows que están en los dos estados, menos los que cortan los denies que su grupo alcanza por aristas que no cambian —
+ * el «auto-corte», que solo se aplica con el predicado `cuts` de la config: sin él, ningún allow se da por cortado, lo
+ * conservador). Las precedencias, entre aristas que comparten algún sujeto:
+ *
+ *  - **C1** (dos que entran): la que trae un deny sobre X antes que la que trae un allow sobre X;
+ *  - **C2** (dos que salen): la que lleva un allow sobre X antes que la que lleva un deny sobre X (salvo que el sujeto
+ *    solo alcance la primera a través de la segunda);
+ *  - **C3** (una que sale y otra que entra en el MISMO camino anidado, `U ∈ h` sobra y `h ⊂ g` es nueva): la que sale
+ *    antes, si el camino compuesto llevaría un allow efectivo — es el 🟡 N3 con anidamiento;
+ *  - **C4** (una que entra y otra que sale y las dos traen un deny sobre X que protege un allow del sujeto): la que entra
+ *    antes — el sujeto cambia de grupo denegado sin un instante sin deny.
+ *
+ * Se ordena por componentes fuertemente conexas (Tarjan) en orden topológico; entre las disponibles, escrituras antes que
+ * borrados, las escrituras de más lejos del sujeto primero y los borrados de más cerca primero, y (objeto, sujeto): el
+ * reparto NO depende del orden de enumeración del origen ni del `Read`.
+ *
+ * **Lo que garantiza, exactamente** (demostrado por fuerza bruta; README «Denies migrate as denies»): **si el grafo de
+ * precedencias no tiene un CICLO, ningún PREFIJO (el estado del store tras cada `Write` de la secuencia) concede algo que
+ * no concedían el estado inicial o el final, y ningún sujeto denegado en los dos concede en ninguno.** Es una garantía
+ * sobre PREFIJOS —una operación CORTADA—, no sobre lectores: un `Check` que abarca dos `Write` consecutivos puede mezclar
+ * lecturas de uno y otro (lector rasgado, fila «torn read» de Limits; decisión (6a) del dueño, linaje L12). El RESIDUO es exactamente el ciclo (`residue`): dos membresías
+ * que cambian en la misma pasada cuyas exigencias se contradicen —la forma típica: 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—. Ahí NO existe en general ningún orden
+ * seguro (la fuerza bruta lo mide: de los casos del ciclo que conceden, una parte no admite NINGUNA permutación del diff
+ * segura), así que el orden aplica las aristas del ciclo en el orden de prioridad y lo DEVUELVE para que la pasada lo diga.
+ *
+ * Pura (regla 2 de pureza): no importa nada del paquete. Coste: lineal en las tuplas más los pares de membresías que
+ * cambian de un MISMO sujeto, y los de cada arista anidada (`group:x#member`) con las de los sujetos que tiene debajo.
+ */
+/** El tipo built-in que transporta usersets (`group:g#member`). */
+const GROUP_PREFIX = 'group:';
+const MEMBER_SUFFIX = '#member';
+export function relationOrderClass(view) {
+    if (view.deny)
+        return 'deny';
+    return view.object.startsWith(GROUP_PREFIX) ? 'membership' : 'allow';
+}
+/** `group:<id>#member` ⇒ `group:<id>`; cualquier otro sujeto ⇒ `null`. */
+function usersetGroup(user) {
+    return user.startsWith(GROUP_PREFIX) && user.endsWith(MEMBER_SUFFIX) ? user.slice(0, -MEMBER_SUFFIX.length) : null;
+}
+function viewKey(v) {
+    return `${v.deny ? 'd' : 'a'}\u0000${v.object}\u0000${v.user}\u0000${v.relation ?? ''}`;
+}
+function objectTypeOf(object) {
+    const colon = object.indexOf(':');
+    return colon < 0 ? object : object.slice(0, colon);
+}
+/**
+ * Los grupos PORTADORES de deny: el `#member` de cada uno es sujeto de algún deny de `views`, más el cierre por la
+ * anidación (`group:G#member@group:H#member` con G portador ⇒ H portador). Devuelve los OBJETOS (`group:<id>`). Lo usa
+ * el reconcile para clasificar la renovación de una membresía PORTADORA (cierre 2 de D2 · 🟠 N1, `renewal-unsafe`).
+ */
+export function denyCarrierGroups(views) {
+    const all = [...views];
+    const carriers = new Set();
+    for (const v of all) {
+        const group = v.deny ? usersetGroup(v.user) : null;
+        if (group !== null)
+            carriers.add(group);
+    }
+    const nested = all.filter((v) => relationOrderClass(v) === 'membership' && usersetGroup(v.user) !== null);
+    for (let grew = true; grew;) {
+        grew = false;
+        for (const v of nested) {
+            const inner = usersetGroup(v.user);
+            if (carriers.has(v.object) && !carriers.has(inner)) {
+                carriers.add(inner);
+                grew = true;
+            }
+        }
+    }
+    return carriers;
+}
+/**
+ * **Los denies que TRANSPORTA un grupo** (cierre 6 de D2 · ⚪ D5-3, para la letra): los `deny` cuyo sujeto es el `#member`
+ * del grupo o de un grupo que lo contiene, transitivamente (`group:G#member@group:H#member`: los miembros de H heredan los
+ * denies de G). Devuelve las VISTAS de esos denies, en el orden de entrada. Misma regla que `denyCarrierGroups`, al revés.
+ */
+export function carriedDenies(views, group) {
+    const all = [...views];
+    const reach = new Set([group]);
+    const nested = all.filter((v) => relationOrderClass(v) === 'membership' && usersetGroup(v.user) !== null);
+    for (let grew = true; grew;) {
+        grew = false;
+        for (const v of nested) {
+            if (reach.has(usersetGroup(v.user)) && !reach.has(v.object)) {
+                reach.add(v.object);
+                grew = true;
+            }
+        }
+    }
+    return all.filter((v) => v.deny && reach.has(usersetGroup(v.user) ?? ''));
+}
+/** Un grafo de membresías (aristas `sujeto → grupo`): hacia arriba (`up`), hacia abajo (`below`) y altura. */
+class MembershipGraph {
+    #parents = new Map();
+    #into = new Map();
+    #childGroups = new Map();
+    #up = new Map();
+    #below = new Map();
+    #height = new Map();
+    constructor(edges) {
+        for (const e of edges) {
+            let list = this.#into.get(e.object);
+            if (!list)
+                this.#into.set(e.object, (list = []));
+            list.push(e);
+            const child = usersetGroup(e.user);
+            if (child === null)
+                continue;
+            let parents = this.#parents.get(child);
+            if (!parents)
+                this.#parents.set(child, (parents = new Set()));
+            parents.add(e.object);
+            let children = this.#childGroups.get(e.object);
+            if (!children)
+                this.#childGroups.set(e.object, (children = new Set()));
+            children.add(child);
+        }
+    }
+    /** Los grupos que alcanza `group` (él incluido). */
+    up(group) {
+        let seen = this.#up.get(group);
+        if (seen)
+            return seen;
+        seen = new Set([group]);
+        const stack = [group];
+        while (stack.length > 0) {
+            for (const parent of this.#parents.get(stack.pop()) ?? []) {
+                if (!seen.has(parent)) {
+                    seen.add(parent);
+                    stack.push(parent);
+                }
+            }
+        }
+        this.#up.set(group, seen);
+        return seen;
+    }
+    /** Los sujetos (holders y usersets) que alcanzan al sujeto `user` (él incluido), opcionalmente SIN la arista `without`. */
+    below(user, without) {
+        if (usersetGroup(user) === null)
+            return new Set([user]);
+        if (without === undefined) {
+            const memo = this.#below.get(user);
+            if (memo)
+                return memo;
+        }
+        const out = new Set([user]);
+        const stack = [user];
+        while (stack.length > 0) {
+            const group = usersetGroup(stack.pop());
+            if (group === null)
+                continue;
+            for (const e of this.#into.get(group) ?? []) {
+                if (without !== undefined && viewKey(e) === without)
+                    continue;
+                if (!out.has(e.user)) {
+                    out.add(e.user);
+                    stack.push(e.user);
+                }
+            }
+        }
+        if (without === undefined)
+            this.#below.set(user, out);
+        return out;
+    }
+    /** Distancia de un sujeto a los holders: 0 un holder; un userset, 1 + la de su grupo hijo más profundo. */
+    depth(user) {
+        const group = usersetGroup(user);
+        return group === null ? 0 : this.#groupHeight(group, new Set());
+    }
+    #groupHeight(group, path) {
+        const memo = this.#height.get(group);
+        if (memo !== undefined)
+            return memo;
+        if (path.has(group))
+            return 1;
+        path.add(group);
+        let height = 1;
+        for (const child of this.#childGroups.get(group) ?? [])
+            height = Math.max(height, 1 + this.#groupHeight(child, path));
+        path.delete(group);
+        this.#height.set(group, height);
+        return height;
+    }
+}
+/** Índice de tuplas (allows o denies) por sujeto: `sujeto → objeto → relaciones`. */
+function bySubject(views) {
+    const out = new Map();
+    for (const v of views) {
+        let objects = out.get(v.user);
+        if (!objects)
+            out.set(v.user, (objects = new Map()));
+        let relations = objects.get(v.object);
+        if (!relations)
+            objects.set(v.object, (relations = new Set()));
+        relations.add(v.relation ?? '');
+    }
+    return out;
+}
+/** Lo que alcanza un grupo por un grafo: `objeto → relaciones` (los `#member` de los grupos de `up`). */
+function reach(graph, index, group) {
+    const out = new Map();
+    for (const g of graph.up(group)) {
+        for (const [object, relations] of index.get(g + MEMBER_SUFFIX) ?? []) {
+            let set = out.get(object);
+            if (!set)
+                out.set(object, (set = new Set()));
+            for (const r of relations)
+                set.add(r);
+        }
+    }
+    return out;
+}
+/**
+ * **El orden de una TRANSICIÓN** (cierre 2 de D2 · 🟡 N3): ver el docblock del módulo. `residue` = las membresías de los
+ * ciclos del grafo de precedencias (sin garantía); vacío ⇒ ningún PREFIJO concede fuera de inicial ∪ final.
+ */
+export function relationTransitionOrder(transition, view, options = {}) {
+    const writes = (transition.writes ?? []).map((item) => ({ item, view: view(item) }));
+    const deletes = (transition.deletes ?? []).map((item) => ({ item, view: view(item) }));
+    const renewals = (transition.renewals ?? []).map((item) => ({ item, view: view(item) }));
+    const shortening = new Set(transition.shortening ?? []);
+    const renewedMemberships = renewals.filter((r) => relationOrderClass(r.view) === 'membership');
+    const changing = new Set([...writes, ...deletes, ...renewedMemberships].map((w) => viewKey(w.view)));
+    const everything = new Map();
+    for (const v of [...(transition.context ?? []), ...writes.map((w) => w.view), ...deletes.map((d) => d.view), ...renewals.map((r) => r.view)]) {
+        everything.set(viewKey(v), v);
+    }
+    const edges = [];
+    const keptAllows = [];
+    const denies = [];
+    for (const [key, v] of everything) {
+        const cls = relationOrderClass(v);
+        if (cls === 'deny')
+            denies.push(v);
+        else if (cls === 'membership')
+            edges.push(v);
+        else if (!changing.has(key))
+            keptAllows.push(v);
+    }
+    const renewedAs = (r) => (shortening.has(r.item) ? 'delete' : 'write');
+    const membership = planMemberships([
+        ...writes.filter((w) => relationOrderClass(w.view) === 'membership').map((w) => ({ ...w, emit: 'write' })),
+        ...renewedMemberships.filter((r) => renewedAs(r) === 'write').map((r) => ({ ...r, emit: 'renew' })),
+    ], [
+        ...deletes.filter((d) => relationOrderClass(d.view) === 'membership').map((d) => ({ ...d, emit: 'delete' })),
+        ...renewedMemberships.filter((r) => renewedAs(r) === 'delete').map((r) => ({ ...r, emit: 'renew' })),
+    ], { edges, keptAllows, denies, changing, cuts: options.cuts });
+    const steps = [];
+    // 1. denies nuevos (y los que se rehacen: un deny no caduca, D3) — solo restringen.
+    for (const w of writes)
+        if (w.view.deny)
+            steps.push({ item: w.item, op: 'write' });
+    for (const r of renewals)
+        if (r.view.deny)
+            steps.push({ item: r.item, op: 'renew' });
+    // 2. allows sobrantes sobre objetos que no son `group` — solo restringen; y (cierre 4) las renovaciones de allows que
+    //    ACORTAN: en su caducidad nueva salen.
+    for (const d of deletes)
+        if (relationOrderClass(d.view) === 'allow')
+            steps.push({ item: d.item, op: 'delete' });
+    for (const r of renewals)
+        if (relationOrderClass(r.view) === 'allow' && renewedAs(r) === 'delete')
+            steps.push({ item: r.item, op: 'renew' });
+    // 3. membresías (y, cierre 4, sus renovaciones como la entrada o la salida que son en el horizonte), por el grafo.
+    steps.push(...membership.steps);
+    // 4. allows nuevos y las renovaciones de allows que ALARGAN (en `now` no cambian lo que se concede).
+    for (const w of writes)
+        if (relationOrderClass(w.view) === 'allow')
+            steps.push({ item: w.item, op: 'write' });
+    for (const r of renewals)
+        if (relationOrderClass(r.view) === 'allow' && renewedAs(r) === 'write')
+            steps.push({ item: r.item, op: 'renew' });
+    // 5. denies sobrantes, los ÚLTIMOS.
+    for (const d of deletes)
+        if (d.view.deny)
+            steps.push({ item: d.item, op: 'delete' });
+    return { steps, residue: membership.residue };
+}
+function planMemberships(writes, deletes, context) {
+    if (writes.length + deletes.length === 0)
+        return { steps: [], residue: [] };
+    const union = new MembershipGraph(context.edges);
+    const kept = new MembershipGraph(context.edges.filter((e) => !context.changing.has(viewKey(e))));
+    const allowIndex = bySubject(context.keptAllows);
+    const denyIndex = bySubject(context.denies);
+    const cuts = context.cuts;
+    const deniedBy = new Map();
+    /** Objetos denegados por lo que alcanza `group` en el grafo unión. */
+    const deniedObjects = (group) => {
+        let out = deniedBy.get(group);
+        if (!out)
+            deniedBy.set(group, (out = new Set(reach(union, denyIndex, group).keys())));
+        return out;
+    };
+    /**
+     * Objetos que concede de forma EFECTIVA lo que alcanza `group` (grafo unión, allows de los dos estados), menos los que
+     * corta TODO lo que deniegan, por aristas que NO cambian, los grupos `cutters` (el auto-corte). Sin `cuts`, nada se corta.
+     */
+    const effective = (group, cutters) => {
+        const allowed = reach(union, allowIndex, group);
+        if (!cuts)
+            return new Set(allowed.keys());
+        const keptDenies = new Map();
+        for (const cutter of cutters) {
+            for (const [object, relations] of reach(kept, denyIndex, cutter)) {
+                let set = keptDenies.get(object);
+                if (!set)
+                    keptDenies.set(object, (set = new Set()));
+                for (const r of relations)
+                    set.add(r);
+            }
+        }
+        const out = new Set();
+        for (const [object, relations] of allowed) {
+            const denied = keptDenies.get(object);
+            const type = objectTypeOf(object);
+            const cut = denied !== undefined && [...relations].every((a) => [...denied].some((d) => cuts(type, d, a)));
+            if (!cut)
+                out.add(object);
+        }
+        return out;
+    };
+    const effectiveMemo = new Map();
+    const ops = [];
+    for (const [list, op] of [
+        [writes, 'write'],
+        [deletes, 'delete'],
+    ]) {
+        for (const { item, view, emit } of list) {
+            let allows = effectiveMemo.get(view.object);
+            if (!allows)
+                effectiveMemo.set(view.object, (allows = effective(view.object, [view.object])));
+            ops.push({
+                item,
+                view,
+                op,
+                emit,
+                key: viewKey(view),
+                head: view.object,
+                tail: usersetGroup(view.user),
+                denies: deniedObjects(view.object),
+                allows,
+                depth: union.depth(view.user),
+            });
+        }
+    }
+    const subjectAllows = new Map();
+    /** Los objetos con algún allow (de los dos estados) que alcanza el sujeto, directo o por cualquier grupo (grafo unión). */
+    const allowsOfSubject = (subject) => {
+        let out = subjectAllows.get(subject);
+        if (out)
+            return out;
+        out = new Set([...(allowIndex.get(subject)?.keys() ?? [])]);
+        for (const e of context.edges) {
+            if (e.user !== subject)
+                continue;
+            for (const object of reach(union, allowIndex, e.object).keys())
+                out.add(object);
+        }
+        subjectAllows.set(subject, out);
+        return out;
+    };
+    const intersects = (a, b) => {
+        const [small, large] = a.size <= b.size ? [a, b] : [b, a];
+        for (const x of small)
+            if (large.has(x))
+                return true;
+        return false;
+    };
+    /**
+     * C3: ¿`d` (sale) y `w` (entra) componen un camino NUEVO? Cierre 5 de D2 (D4-2; el oráculo cuenta los objetos `group:`):
+     * el camino compuesto concede SIEMPRE algo —la propia membresía del sujeto en el grupo de arriba (`check(member)`,
+     * `membersOf`)—, así que ya no se exige un allow efectivo al final del camino (hasta el cierre 4 sí, y un corte entre
+     * `+U∈h` y `-h⊂g` hacía a U miembro de g, cosa que ni el inicial ni el final hacían).
+     */
+    const composes = (d, w) => {
+        if (w.tail !== null && union.up(d.head).has(w.tail))
+            return true;
+        if (d.tail !== null && union.up(w.head).has(d.tail))
+            return true;
+        return false;
+    };
+    /** ¿`a` va ANTES que `b`? (C1–C4). */
+    const before = (a, b) => {
+        if (a.op === 'write' && b.op === 'write') {
+            return [...a.denies].some((x) => b.allows.has(x)) && intersects(union.below(a.view.user), union.below(b.view.user));
+        }
+        if (a.op === 'delete' && b.op === 'delete') {
+            return [...a.allows].some((x) => b.denies.has(x)) && intersects(union.below(a.view.user, b.key), union.below(b.view.user));
+        }
+        if (a.op === 'delete')
+            return composes(a, b);
+        // C4, con la exclusión de C2 (cierre 5 de D2): un sujeto que solo alcanza la que sale A TRAVÉS de la que entra (o la
+        // que entra a través de la que sale) no tenía ese deny en el inicial (o no lo tiene en el final): no hay «instante sin
+        // deny» que evitar. Sin la exclusión, C4 chocaba con C3 —que ahora cuenta la membresía como concesión— en ciclos
+        // espurios (`+U∈h`, `-h⊂g` con el deny en g: U nunca estuvo en g).
+        const belowB = union.below(b.view.user, a.key);
+        const common = [...union.below(a.view.user, b.key)].filter((s) => belowB.has(s));
+        if (common.length === 0)
+            return false;
+        return [...a.denies].some((x) => b.denies.has(x) && common.some((s) => allowsOfSubject(s).has(x)));
+    };
+    // Los pares que pueden tener precedencia: los de un MISMO sujeto holder, y los de cada arista anidada con todas las
+    // que tienen un sujeto por debajo de ella o un grupo en su camino.
+    const succ = ops.map(() => []);
+    const link = (i, j) => {
+        if (before(ops[i], ops[j]))
+            succ[i].push(j);
+    };
+    const byHolder = new Map();
+    const nested = [];
+    ops.forEach((o, i) => {
+        if (o.tail !== null)
+            nested.push(i);
+        else {
+            let list = byHolder.get(o.view.user);
+            if (!list)
+                byHolder.set(o.view.user, (list = []));
+            list.push(i);
+        }
+    });
+    for (const list of byHolder.values())
+        for (const i of list)
+            for (const j of list)
+                if (i !== j)
+                    link(i, j);
+    for (const i of nested) {
+        for (let j = 0; j < ops.length; j++) {
+            if (i === j || (ops[j].tail !== null && j < i))
+                continue;
+            link(i, j);
+            link(j, i);
+        }
+    }
+    const order = orderByPrecedence(ops, succ);
+    return {
+        steps: order.order.map((i) => ({ item: ops[i].item, op: ops[i].emit })),
+        residue: order.cyclic.map((i) => ops[i].item),
+    };
+}
+/** Prioridad entre disponibles: escrituras antes que borrados; escrituras de lejos primero, borrados de cerca; (objeto, sujeto). */
+function priority(a, b) {
+    if (a.op !== b.op)
+        return a.op === 'write' ? -1 : 1;
+    if (a.depth !== b.depth)
+        return a.op === 'write' ? b.depth - a.depth : a.depth - b.depth;
+    if (a.view.object !== b.view.object)
+        return a.view.object < b.view.object ? -1 : 1;
+    if (a.view.user !== b.view.user)
+        return a.view.user < b.view.user ? -1 : 1;
+    return 0;
+}
+/**
+ * Orden topológico por componentes fuertemente conexas (Tarjan, iterativo): una componente sale cuando no le queda
+ * ninguna predecesora; entre las disponibles, la de mayor prioridad. Dentro de una componente con CICLO, Kahn sobre sus
+ * aristas internas y, cuando se atasca, la de mayor prioridad (`cyclic` las devuelve todas: el residuo).
+ */
+function orderByPrecedence(ops, succ) {
+    const n = ops.length;
+    const index = new Array(n).fill(-1);
+    const low = new Array(n).fill(0);
+    const onStack = new Array(n).fill(false);
+    const component = new Array(n).fill(-1);
+    const stack = [];
+    const members = [];
+    let counter = 0;
+    for (let root = 0; root < n; root++) {
+        if (index[root] !== -1)
+            continue;
+        const work = [{ v: root, next: 0 }];
+        index[root] = low[root] = counter++;
+        stack.push(root);
+        onStack[root] = true;
+        while (work.length > 0) {
+            const frame = work[work.length - 1];
+            const edges = succ[frame.v];
+            if (frame.next < edges.length) {
+                const w = edges[frame.next++];
+                if (index[w] === -1) {
+                    index[w] = low[w] = counter++;
+                    stack.push(w);
+                    onStack[w] = true;
+                    work.push({ v: w, next: 0 });
+                }
+                else if (onStack[w])
+                    low[frame.v] = Math.min(low[frame.v], index[w]);
+                continue;
+            }
+            work.pop();
+            if (work.length > 0)
+                low[work[work.length - 1].v] = Math.min(low[work[work.length - 1].v], low[frame.v]);
+            if (low[frame.v] === index[frame.v]) {
+                const list = [];
+                let w;
+                do {
+                    w = stack.pop();
+                    onStack[w] = false;
+                    component[w] = members.length;
+                    list.push(w);
+                } while (w !== frame.v);
+                members.push(list);
+            }
+        }
+    }
+    const pending = new Array(members.length).fill(0);
+    for (let v = 0; v < n; v++)
+        for (const w of succ[v])
+            if (component[v] !== component[w])
+                pending[component[w]]++;
+    const best = members.map((list) => list.reduce((a, b) => (priority(ops[a], ops[b]) <= 0 ? a : b)));
+    const ready = members.map((_, c) => c).filter((c) => pending[c] === 0);
+    const order = [];
+    const cyclic = [];
+    while (ready.length > 0) {
+        let pick = 0;
+        for (let k = 1; k < ready.length; k++)
+            if (priority(ops[best[ready[k]]], ops[best[ready[pick]]]) < 0)
+                pick = k;
+        const c = ready.splice(pick, 1)[0];
+        const list = members[c];
+        if (list.length === 1)
+            order.push(list[0]);
+        else {
+            cyclic.push(...list);
+            const inside = new Set(list);
+            const done = new Set();
+            const preds = new Map(list.map((v) => [v, 0]));
+            for (const v of list)
+                for (const w of succ[v])
+                    if (inside.has(w))
+                        preds.set(w, preds.get(w) + 1);
+            while (done.size < list.length) {
+                const left = list.filter((v) => !done.has(v));
+                const free = left.filter((v) => preds.get(v) === 0);
+                const pool = free.length > 0 ? free : left;
+                const v = pool.reduce((a, b) => (priority(ops[a], ops[b]) <= 0 ? a : b));
+                done.add(v);
+                order.push(v);
+                for (const w of succ[v])
+                    if (inside.has(w) && !done.has(w))
+                        preds.set(w, preds.get(w) - 1);
+            }
+        }
+        for (const v of list)
+            for (const w of succ[v])
+                if (component[w] !== c && --pending[component[w]] === 0)
+                    ready.push(component[w]);
+    }
+    return { order, cyclic };
+}
+/**
+ * **El orden de ESCRITURA** de un conjunto que solo ENTRA (atajo de `relationTransitionOrder` sin borrados): `context` =
+ * las tuplas que existen y no se escriben.
+ */
+export function relationWriteOrder(items, view, context = []) {
+    return relationTransitionOrder({ writes: items, context }, view).steps.map((s) => s.item);
+}
+/** **El orden de BORRADO** de un conjunto que solo SALE (las purgas de `openfga`): allows → membresías → denies. */
+export function relationDeleteOrder(items, view, context = []) {
+    return relationTransitionOrder({ deletes: items, context }, view).steps.map((s) => s.item);
+}
+/*
+ * Cierre 5 de D2 (decisión del dueño §2026-10-16 (10), opción A): aquí vivía `relationWithheldWrites` (cierre 4), la
+ * RETENCIÓN de lo que un deny que no viaja (`renewal-unsafe`, `deny-conditional`) dejaría conceder. Se fue entera: en vez
+ * de retener tupla a tupla —con su cascada, su conflicto global `carrier-conflict` y el hueco D4-1 que el auditor midió—,
+ * la PARTICIÓN afectada recibe CERO escrituras y cero borrados (`src/relations/reconcile.ts`, `planPartition` ⇒
+ * `refusal`), y el resto migra. Una partición negada queda exactamente como estaba, que es lo único que se puede
+ * certificar sin una escritura atómica de la renovación (openfga/openfga#2151).
+ */

package/build/src/relations_config_store.d.ts

@@ -1,8 +1,33 @@
 import type { RelationsConfig, RelationsConfigSpec } from './relations/define_relations_config.js';
+import type { DenyReachFinding } from './relations/deny_reach.js';
 export interface RelationsConfigStoreOptions {
     connection?: string;
     timeoutMs?: number;
 }
+/**
+ * Opciones de `saveRelationsConfig`: las del store más las DOS salidas con nombre de la guarda del alcance de los denies
+ * (8), separadas a propósito (A3 del auditor del panel: una salida que se usa como paso rutinario de adopción y no caduca es
+ * un interruptor de apagado).
+ */
+export interface SaveRelationsConfigOptions extends RelationsConfigStoreOptions {
+    /**
+     * **La adopción de la línea base** (firma (8 · línea base)): levanta SOLO el motivo `no-baseline`, y SOLO cuando no hay
+     * línea base utilizable (sin fila, o una fila que la lectura TODO O NADA no puede tipar); con una línea base utilizable es
+     * INERTE (no sirve para estrechar después). Sigue juzgando los huérfanos. Solo `true` la levanta; un valor que no es
+     * boolean es 500 `E_AUTHZ_CONFIG` (L5). Úsala UNA vez, con la spec que la flota sirve HOY, en una release que no cambie
+     * `relations.config` (adoptar en una release que estrecha certifica el estrechamiento: A4).
+     */
+    establishBaseline?: boolean;
+    /**
+     * **La salida forzada ACOTADA** (firma (8 · salida forzada)): la lista de `tipo#relación` cuyos hallazgos `shrunk`/`orphan`
+     * se guardan aunque encojan el alcance de sus denies vivos. Exime SOLO esos: un hallazgo no nombrado se niega igual (un
+     * encogimiento nuevo en otra relación no viaja en el mismo guardado forzado). No exime `no-baseline` (esa es
+     * `establishBaseline`). No hay `true` global: cualquier forma que no sea un array de `tipo#relación` es 500
+     * `E_AUTHZ_CONFIG` (L5). Y un nombre que en ESE guardado no exime ningún `shrunk`/`orphan` también es 500
+     * `E_AUTHZ_CONFIG` sin escribir (cierre 1 del sublote (8)): la lista se retira tras el guardado que la necesita.
+     */
+    allowDenyReachShrink?: readonly string[];
+}
 /**
  * **Guarda (persiste) la config de relaciones** bajo el gate de versión: la
  * valida (⚪4/F-05 de config), la serializa a JSON y hace UPSERT de la fila
@@ -10,7 +35,38 @@ export interface RelationsConfigStoreOptions {
  * última sentencia (invariante 14): un sync en otro proceso la ve en la
  * siguiente pregunta—. Devuelve la config congelada.
  */
-export declare function saveRelationsConfig(spec: RelationsConfigSpec, options?: RelationsConfigStoreOptions): Promise<RelationsConfig>;
+export declare function saveRelationsConfig(spec: RelationsConfigSpec, options?: SaveRelationsConfigOptions): Promise<RelationsConfig>;
+/** Lo que devuelve `checkRelationsConfigDenyReach`. */
+export interface RelationsConfigDenyReachCheck {
+    /** `'persisted'`: hay línea base utilizable; `'none'`: no la hay (sin fila, o una fila que no se puede tipar). */
+    baseline: 'persisted' | 'none';
+    /**
+     * Persistida → servida: `shrunk`, `orphan` (también sin línea base) y, con `baseline: 'none'` y denies vivos,
+     * `no-baseline` — lo mismo que juzgaría la guarda al guardar la config servida, sin salidas forzadas.
+     */
+    findings: DenyReachFinding[];
+    /** Servida → persistida: `stale` — la línea base es más estrecha que lo servido en grupos con denies vivos (A1/S-B). */
+    staleBaseline: DenyReachFinding[];
+    /** `true` sii no hay ningún hallazgo en ninguna dirección (`no-baseline` cuenta como hallazgo). */
+    ok: boolean;
+    /** Una línea por hallazgo, con el prefijo estable de su rama (`denyReachLine`). */
+    lines: string[];
+}
+/**
+ * **El detector de UN solo driver** (firma (8 · detector de un driver), R4 del analista del panel): en un despliegue
+ * solo-`database` el detector de `authz:relations:reconcile --dry-run` no corre (necesita DOS drivers de relaciones:
+ * origen = destino es 500). Esta función compara la config que SIRVE el proceso (`served`) con la línea base persistida
+ * sobre los denies vivos de `authz_relations`, en las DOS direcciones:
+ *  - persistida → servida: lo que la guarda negaría (`shrunk`, `orphan`, `no-baseline`);
+ *  - servida → persistida: la línea base RANCIA (`stale`), que la guarda no puede ver.
+ *
+ * Solo LEE (la fila y un `GROUP BY` de `authz_relations`, por `options.connection` o la primaria), sin transacción y sin el
+ * cerrojo del catálogo, con el MISMO punto de paso que la guarda (`baselineOf` + `liveDenyGroups` + `denyReachCheck`).
+ * **Receta**: en CI, DESPUÉS del paso que guarda la config y ANTES de servir, y en un cron; falla el job si `ok` es `false`.
+ * **Nunca** como fallo duro en `ready`: durante un despliegue un pod viejo que se reinicia sirve la config estrecha contra la
+ * fila nueva y entraría en un bucle de reinicios.
+ */
+export declare function checkRelationsConfigDenyReach(served: Pick<RelationsConfig, 'objectTypes'>, options?: RelationsConfigStoreOptions): Promise<RelationsConfigDenyReachCheck>;
 /** Lee el spec persistido (o `null` si no hay relaciones declaradas — opt-in). */
 export declare function readRelationsConfigSpec(options?: RelationsConfigStoreOptions): Promise<RelationsConfigSpec | null>;
 /**
@@ -19,4 +75,3 @@ export declare function readRelationsConfigSpec(options?: RelationsConfigStoreOp
  * relación de la base, así que el modelo que republique los lleva.
  */
 export declare function readRelationsConfig(options?: RelationsConfigStoreOptions): Promise<RelationsConfig | null>;
-//# sourceMappingURL=relations_config_store.d.ts.map