@intentius/chant 0.124.40 → 0.124.41

package/dist/wave-blocked.js

@@ -0,0 +1,245 @@
+/**
+ * A failed member blocks only the members that depend on it (#4291).
+ *
+ * A run applied a wave at a time stops a member when something it reads did
+ * not apply, and lets every other member go on. This module holds the rule
+ * and the records it reads, with no runner in it, so a product that runs its
+ * waves in its own CI stages (terragucci's roots, lifted from its
+ * `blocked.ts`) and chant's own wave jobs (`pr-apply --wave-gate`,
+ * `chant components fan-out --wave-gate`) block the same members for the
+ * same reasons. It imports `node:fs` and `node:path` and nothing else, so it
+ * bundles small (`wave-blocked-bundle.test.ts`).
+ *
+ * ## Outcomes
+ *
+ * Each member of an earlier wave has an outcome. `applied` and `unchanged`
+ * let a dependent through. Every other status holds it:
+ *
+ * - `failed`: its plan or its apply failed.
+ * - `waiting`: its wave waits for an approval.
+ * - `refused`: its wave was refused, held or stood down.
+ * - `decided`: its wave's deciding job decided it, and a share job applies it.
+ * - `not-applied`: its wave applied nothing because another member of it failed to plan.
+ * - `blocked`: something it reads did not apply. `by` names the member whose
+ *   outcome held it, past any member blocked in between.
+ *
+ * ## Outcome files
+ *
+ * A wave job that hands the next job its outcomes as files writes one per
+ * job, `outcome-wave-<k>[-group-<g>][-share-<i>].json`:
+ *
+ *   {
+ *     "version": 1, "wave": 2, "at": "2026-10-18T10:00:09.000Z",
+ *     "members": {
+ *       "cluster-b": { "status": "applied" },
+ *       "cluster-a": { "status": "failed" },
+ *       "app-01": { "status": "blocked", "by": "cluster-a" }
+ *     }
+ *   }
+ *
+ * A wave job runs again on a re-run, so the newest outcome of a member wins.
+ * A file written with `roots` in place of `members` (terragucci's, before
+ * this module) reads the same. `holds_all` marks a wave that holds every
+ * later member, such as a wave of state migrations that did not apply: each
+ * later member is blocked by `wave-<k>`.
+ */
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export const WAVE_OUTCOME_VERSION = 1;
+const THROUGH = new Set(["applied", "unchanged"]);
+/** Whether `outcome` lets a dependent through: it applied, or had nothing to apply. */
+export function passesThrough(outcome) {
+    return outcome !== undefined && THROUGH.has(outcome.status);
+}
+/**
+ * The members of `members` an upstream that did not apply holds, each with
+ * the member whose outcome holds it. `upstreams` is each member's upstreams;
+ * only those in `earlier` count (a member of this wave or a later one is no
+ * upstream it waits for here). An upstream with no outcome did not apply as
+ * far as this run knows, so it holds its dependents and names itself. A
+ * blocked upstream passes on the member that blocked it. With `holdsAll`,
+ * every member is blocked by `wave-<holdsAll>`.
+ */
+export function blockedMembers(members, upstreams, earlier, outcomes, holdsAll) {
+    if (holdsAll !== undefined)
+        return new Map(members.map((m) => [m, `wave-${holdsAll}`]));
+    const out = new Map();
+    for (const member of members) {
+        const by = [...(upstreams.get(member) ?? [])]
+            .filter((u) => earlier.has(u))
+            .sort()
+            .map((u) => {
+            const o = outcomes.get(u);
+            if (passesThrough(o))
+                return undefined;
+            return o?.status === "blocked" && o.by ? o.by : u;
+        })
+            .find((b) => b !== undefined);
+        if (by !== undefined)
+            out.set(member, by);
+    }
+    return out;
+}
+/**
+ * Walk waves 1 to `before - 1` and give each member that has no outcome the
+ * one it ends with: `blocked` behind an upstream that did not apply. A member
+ * with no outcome that nothing blocks has not run yet: it is in `unsettled`,
+ * and wave `before` cannot run until it has. `outcomes` is what the records
+ * say: `applied` for what applied, and `failed`, `waiting` or `not-applied`
+ * for what did not. Returns those outcomes with the blocked members added.
+ */
+export function settleEarlierWaves(waves, before, upstreams, outcomes) {
+    const out = new Map(outcomes);
+    const unsettled = [];
+    const earlier = new Set();
+    for (let k = 1; k < before && k <= waves.length; k++) {
+        const wave = waves[k - 1];
+        const open = wave.filter((m) => !out.has(m));
+        const blocked = blockedMembers(open, upstreams, earlier, out);
+        for (const m of open) {
+            const by = blocked.get(m);
+            if (by !== undefined)
+                out.set(m, { status: "blocked", by });
+            else
+                unsettled.push(m);
+        }
+        for (const m of wave)
+            earlier.add(m);
+    }
+    return { outcomes: out, unsettled };
+}
+/**
+ * Whether every member that did not apply waits for an approval, or is
+ * blocked behind one that does: the run waits rather than failed, so the
+ * job ends as waiting (exit 3), and the approval's re-run applies them.
+ */
+export function onlyWaiting(outcomes) {
+    let held = false;
+    for (const o of outcomes.values()) {
+        if (THROUGH.has(o.status))
+            continue;
+        held = true;
+        if (o.status === "waiting")
+            continue;
+        if (o.status === "blocked" && o.by !== undefined && outcomes.get(o.by)?.status === "waiting")
+            continue;
+        return false;
+    }
+    return held;
+}
+const byName = ([a], [b]) => (a < b ? -1 : a > b ? 1 : 0);
+/** The blocked members grouped by what blocked them, as a log and a note list them: `app-01, app-02 (blocked by cluster-a)`. */
+export function blockedWords(blocked) {
+    const byRoot = new Map();
+    for (const [member, by] of [...blocked].sort(byName))
+        byRoot.set(by, [...(byRoot.get(by) ?? []), member]);
+    return [...byRoot].map(([by, ms]) => `${ms.join(", ")} (blocked by ${by})`).join("; ");
+}
+/**
+ * How the run came out, from every member's newest outcome: "8 applied, 1
+ * failed, 6 blocked", with waiting, refused and the rest named when there
+ * are any, and undefined when every member applied or had nothing to apply.
+ */
+export function runSummary(outcomes) {
+    const counts = new Map();
+    for (const o of outcomes)
+        counts.set(o.status, (counts.get(o.status) ?? 0) + 1);
+    if (![...counts.keys()].some((s) => !THROUGH.has(s)))
+        return undefined;
+    const parts = [`${counts.get("applied") ?? 0} applied`, `${counts.get("failed") ?? 0} failed`, `${counts.get("blocked") ?? 0} blocked`];
+    for (const s of ["waiting", "refused", "decided", "not-applied"]) {
+        if (counts.get(s))
+            parts.push(`${counts.get(s)} ${s === "decided" ? "not reported by their share" : s}`);
+    }
+    if (counts.get("unchanged"))
+        parts.push(`${counts.get("unchanged")} unchanged`);
+    return parts.join(", ");
+}
+/** The outcome file of a wave's job, or of one group or share of it. */
+export function waveOutcomeFileName(wave, part = {}) {
+    const group = part.group !== undefined ? `-group-${part.group.replace(/[^A-Za-z0-9._-]/g, "_")}` : "";
+    const share = part.share !== undefined ? `-share-${part.share}` : "";
+    return `outcome-wave-${wave}${group}${share}.json`;
+}
+/** Write a wave job's outcome file in `dir`, members sorted by name. Returns its path. */
+export function writeWaveOutcomeFile(dir, wave, part, members, at = new Date().toISOString(), holdsAll = false) {
+    const file = join(dir, waveOutcomeFileName(wave, part));
+    const body = {
+        version: WAVE_OUTCOME_VERSION,
+        wave,
+        at,
+        members: Object.fromEntries(Object.entries(members).sort(byName)),
+        ...(holdsAll ? { holds_all: true } : {}),
+    };
+    writeFileSync(file, JSON.stringify(body, null, 2) + "\n");
+    return file;
+}
+/** Every outcome file under `dirs`, four directories deep at most: downloaded artifacts keep each job's in a directory of its own. */
+function outcomeFiles(dirs) {
+    const out = [];
+    const walk = (dir, depth) => {
+        let names;
+        try {
+            names = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            const abs = join(dir, name);
+            let isDir = false;
+            try {
+                isDir = statSync(abs).isDirectory();
+            }
+            catch {
+                continue;
+            }
+            if (isDir) {
+                if (depth < 4)
+                    walk(abs, depth + 1);
+            }
+            else if (/^outcome-wave-\d+.*\.json$/.test(name))
+                out.push(abs);
+        }
+    };
+    for (const d of dirs)
+        if (existsSync(d))
+            walk(d, 0);
+    return out.sort();
+}
+/**
+ * The outcome of each member of the waves before `wave`, as their jobs wrote
+ * them under `dirs`, and the earliest such wave that holds every later
+ * member, if any. For a member more than one job wrote (a re-run, or a split
+ * wave's deciding job and the share that applied it), the newest. A file
+ * that does not parse, or is of another version, is skipped.
+ */
+export function earlierWaveOutcomes(dirs, wave) {
+    const out = new Map();
+    const newest = new Map();
+    for (const file of outcomeFiles(dirs)) {
+        let f;
+        try {
+            f = JSON.parse(readFileSync(file, "utf-8"));
+        }
+        catch {
+            continue;
+        }
+        const members = (f?.members ?? f?.roots);
+        if (f?.version !== WAVE_OUTCOME_VERSION || !Number.isInteger(f.wave) || f.wave >= wave || typeof f.at !== "string")
+            continue;
+        if (typeof members !== "object" || members === null)
+            continue;
+        for (const [member, o] of Object.entries(members)) {
+            const had = out.get(member);
+            if (had && had.at > f.at)
+                continue;
+            out.set(member, { ...o, wave: f.wave, at: f.at });
+        }
+        const n = newest.get(f.wave);
+        if (!n || n.at <= f.at)
+            newest.set(f.wave, { at: f.at, holdsAll: f.holds_all === true });
+    }
+    const holding = [...newest].filter(([, n]) => n.holdsAll).map(([k]) => k).sort((a, b) => a - b);
+    return { members: out, ...(holding.length ? { holdsAll: holding[0] } : {}) };
+}

package/dist/wave-engine.d.ts

@@ -27,6 +27,8 @@
  */
 import { type GateCheck, type GateLedgerPort } from "./op/gate.js";
 import type { AppliedGateRecord } from "./lifecycle/gate-applied.js";
+import type { ResolvedGateApproval } from "./op/gate-approval.js";
+import type { GateQuorumJudge } from "./op/gate-quorum.js";
 export { WAVE_GATE_NAME_PATTERN, waveGateNameFrom, waveShare } from "./wave-layout.js";
 export { layerWaves, waveGateName, waveDigestMembers, waveSetDigest, readWaveRecords, withWaveRecord, describeChangedWave, type WaveDigestOver, type WaveMember, type WaveNode, type WaveRecord, type WaveStatus, } from "./gated-waves.js";
 /** What a wave asks its gate. */
@@ -48,6 +50,10 @@ export interface WaveGateRequest {
     fields?: Record<string, unknown>;
     /** The pending fact carries `neverOverMcp` (#3821). */
     neverOverMcp?: boolean;
+    /** The approval rules the wave takes (#4290), as an `approval` block with a quorum. */
+    approval?: ResolvedGateApproval;
+    /** Judges approvals for those rules (#4290). */
+    judge?: GateQuorumJudge;
 }
 /**
  * Decide a wave's gate: an approval of `digest` under `gate` on `op`'s

package/dist/wave-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wave-engine.d.ts","sourceRoot":"","sources":["../src/wave-engine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"wave-engine.d.ts","sourceRoot":"","sources":["../src/wave-engine.ts"],"names":[],"mappings":"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"}

package/dist/wave-engine.js

@@ -47,6 +47,8 @@ export function decideWaveGate(port, request) {
         ...(request.spent ? { spent: request.spent } : {}),
         ...(request.fields ? { fields: request.fields } : {}),
         ...(request.neverOverMcp ? { neverOverMcp: true } : {}),
+        ...(request.approval ? { approval: request.approval } : {}),
+        ...(request.judge ? { judge: request.judge } : {}),
     });
 }
 /**