@intentius/chant 0.124.28 → 0.124.30

package/dist/lifecycle/retention.js

@@ -0,0 +1,400 @@
+/**
+ * Garbage collection of stored change sets, releases and run events by the
+ * retention policy (#4036). `chant lifecycle gc` runs it.
+ *
+ * What it prunes on `chant/lifecycle`, in every member's ledger at once:
+ *
+ *   _change-sets/<digest>.json          a stored change set (#4022)
+ *   _releases/<digest>.json             a release (#4026)
+ *   _releases/templates/<digest>.txt    template bytes no kept release names
+ *
+ * A prune is one new commit on the local branch that removes those files. It
+ * never rewrites or force-pushes history: other clones and tools read the
+ * branch, and every pruned file stays reachable in the commits before the
+ * prune. So a prune bounds the tree a reader walks at the tip, and the
+ * repository's history keeps growing by what is written. `git log -- <path>`
+ * on the branch still finds a pruned file.
+ *
+ * What it never touches: the ledgers. `_releases/cuts.jsonl`,
+ * `<env>/releases.jsonl`, `_gates/<op>.jsonl`, the run ledgers and every other
+ * `.jsonl` on the branch are append-only and are not edited (#4034), and a
+ * whole ledger file is not removed either: the latest deploy record of an
+ * environment, a gate's standing fact and a release's label all live in them,
+ * and they are small next to what they index (one line per fact). Nor does it
+ * touch snapshots, `_plans/`, `_builds/` or checkpoints, which have no policy
+ * yet. A cut line whose release was pruned stays, so its label keeps naming
+ * that digest and can't be given to another release.
+ *
+ * What is never pruned, whatever its age:
+ *
+ * 1. A release an environment runs: the release the latest deploy record of
+ *    each component in each environment names, by its `releaseDigest` or the
+ *    release gate resolution its admission names (`releaseOfDeploy`, #4043),
+ *    and that release's templates. A promotion picks up what the step before
+ *    runs (#4030), so this also keeps every release a promotion can take by
+ *    default.
+ * 2. What a pending gate binds: the change set (`planDigest`) and release
+ *    (`releaseDigest`) of every pending fact that has not expired.
+ * 3. A release still promotable: one whose commit has no `ci/revoked` tag and
+ *    that was cut within `releases.days`, or is among the newest
+ *    `releases.keep` releases of its member.
+ * 4. A change set a gate fact (an approval, an `empty` resolution or a
+ *    pending fact) names together with a release that is kept.
+ *
+ * Anything else is pruned once it is older than its kind's window: a change
+ * set `changeSets.days` after it was stored or last named by a gate fact,
+ * whichever is later. A file that can't be read as a release is kept.
+ *
+ * Run events are local files under `<git-common-dir>/chant/run-events/`
+ * (`../run-event-store.ts`) and are deleted outright.
+ */
+import { execFileSync } from "node:child_process";
+import { RefCASConflictError, writeLedgerFiles, pushLifecycleReport } from "./git.js";
+import { MEMBERS_DIR } from "./member-ledger.js";
+import { CHANGE_SETS_DIR } from "./change-set-store.js";
+import { CUTS_FILE, RELEASES_DIR, TEMPLATES_SUBDIR, parseCuts, parseRelease } from "./release-store.js";
+import { parseGateLedger } from "./gate-ledger.js";
+import { parseReleaseLedger, releaseLedgerLines } from "./release-read.js";
+import { latestPerComponent } from "./release-ledger.js";
+import { releaseOfDeploy } from "./release-join.js";
+import { RELEASE_GATE_OP } from "../op/gate-name.js";
+import { planRunEventPrune, pruneRunEvents } from "../run-event-store.js";
+const STATE_BRANCH = "chant/lifecycle";
+const DAY_MS = 86400000;
+function git(cwd, args, input) {
+    return execFileSync("git", args, { cwd, input, maxBuffer: 1024 * 1024 * 1024, stdio: ["pipe", "pipe", "pipe"] });
+}
+function branchTip(cwd) {
+    try {
+        return git(cwd, ["rev-parse", "--verify", "--quiet", `refs/heads/${STATE_BRANCH}`]).toString().trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+function listTree(cwd, tip) {
+    const out = [];
+    for (const line of git(cwd, ["ls-tree", "-r", "-l", "--full-tree", tip]).toString().split("\n")) {
+        const m = line.match(/^\d+ blob ([0-9a-f]+)\s+(\d+)\t(.+)$/);
+        if (m)
+            out.push({ sha: m[1], bytes: Number(m[2]), path: m[3] });
+    }
+    return out;
+}
+/** The text of each blob, read in one `git cat-file --batch`. */
+function readBlobs(cwd, shas) {
+    const out = new Map();
+    const unique = [...new Set(shas)];
+    if (unique.length === 0)
+        return out;
+    const buf = git(cwd, ["cat-file", "--batch"], `${unique.join("\n")}\n`);
+    let at = 0;
+    while (at < buf.length) {
+        const nl = buf.indexOf(0x0a, at);
+        if (nl < 0)
+            break;
+        const header = buf.subarray(at, nl).toString().split(" ");
+        at = nl + 1;
+        if (header[1] === "missing" || header.length < 3)
+            continue;
+        const size = Number(header[2]);
+        out.set(header[0], buf.subarray(at, at + size).toString("utf8"));
+        at += size + 1;
+    }
+    return out;
+}
+/** When each change set and release file was last added on the branch, newest add first, in one `git log`. */
+function storedTimes(cwd, tip) {
+    const out = new Map();
+    const text = git(cwd, [
+        "log", "--format=%x00%cI", "--name-only", "--diff-filter=A", tip, "--",
+        `:(top,glob)**/${CHANGE_SETS_DIR}/*.json`, `:(top,glob)**/${RELEASES_DIR}/*.json`,
+    ]).toString();
+    for (const chunk of text.split("\0")) {
+        const lines = chunk.split("\n").filter(Boolean);
+        const when = lines.shift();
+        if (!when)
+            continue;
+        for (const path of lines)
+            if (!out.has(path))
+                out.set(path, when);
+    }
+    return out;
+}
+/** Split a branch path into the member prefix (`_members/<a>/_members/<b>/`) and the rest. */
+export function splitLedgerPath(path) {
+    const segs = path.split("/");
+    const names = [];
+    let i = 0;
+    while (segs[i] === MEMBERS_DIR && i + 2 < segs.length) {
+        names.push(segs[i + 1]);
+        i += 2;
+    }
+    return { prefix: segs.slice(0, i).map((s) => `${s}/`).join(""), member: names.length > 0 ? names.join("/") : null, rest: segs.slice(i).join("/") };
+}
+/**
+ * The key a digest is matched by: its hex. A plan digest written `sha256:<hex>`
+ * names the same plan as `jcs1-sha256:<hex>` (`samePlanDigest`), and a file
+ * name writes `:` as `_`, so both sides are reduced to the hex.
+ */
+export function digestKey(digestOrStem) {
+    const hex = digestOrStem.match(/[0-9a-f]{64}$/);
+    return hex ? hex[0] : digestOrStem.replace(/:/g, "_");
+}
+const stemOf = (name, ext) => name.slice(0, -ext.length);
+const fileDigest = (name, ext) => stemOf(name, ext).replace(/_/g, ":");
+function emptySize() {
+    const z = () => ({ files: 0, bytes: 0 });
+    return { files: 0, bytes: 0, changeSets: z(), releases: z(), templates: z(), ledgers: z(), other: z() };
+}
+function sizeOf(files, kinds) {
+    const s = emptySize();
+    for (const f of files) {
+        s.files++;
+        s.bytes += f.bytes;
+        const kind = kinds.get(f.path);
+        const slot = kind === "change-set" ? s.changeSets : kind === "release" ? s.releases : kind === "template" ? s.templates : f.path.endsWith(".jsonl") ? s.ledgers : s.other;
+        slot.files++;
+        slot.bytes += f.bytes;
+    }
+    return s;
+}
+/**
+ * Decide what a prune of `chant/lifecycle` removes and keeps, by the rules at
+ * the top of this file. Reads the branch at its local tip and writes nothing.
+ */
+export function planLifecycleGc(input) {
+    const { cwd, policy, now } = input;
+    const revoked = input.revokedCommits ?? new Set();
+    const tip = branchTip(cwd);
+    if (!tip)
+        return { tip: null, remove: [], keep: [], before: emptySize(), after: emptySize() };
+    const files = listTree(cwd, tip);
+    const stored = storedTimes(cwd, tip);
+    const members = new Map();
+    const kinds = new Map();
+    const ledgerOf = (prefix, member) => {
+        let m = members.get(prefix);
+        if (!m) {
+            m = { prefix, member, changeSets: new Map(), releases: new Map(), templates: new Map(), cuts: null, gates: [], deploys: [] };
+            members.set(prefix, m);
+        }
+        return m;
+    };
+    for (const f of files) {
+        const { prefix, member, rest } = splitLedgerPath(f.path);
+        const segs = rest.split("/");
+        const name = segs.at(-1);
+        const entry = (kind, digest) => {
+            kinds.set(f.path, kind);
+            return { kind, member, path: f.path, digest, bytes: f.bytes, sha: f.sha, storedAt: stored.get(f.path) ?? null };
+        };
+        if (segs.length === 2 && segs[0] === CHANGE_SETS_DIR && name.endsWith(".json")) {
+            const e = entry("change-set", fileDigest(name, ".json"));
+            ledgerOf(prefix, member).changeSets.set(digestKey(stemOf(name, ".json")), e);
+        }
+        else if (segs.length === 2 && segs[0] === RELEASES_DIR && name.endsWith(".json")) {
+            const e = entry("release", fileDigest(name, ".json"));
+            ledgerOf(prefix, member).releases.set(digestKey(stemOf(name, ".json")), e);
+        }
+        else if (segs.length === 3 && segs[0] === RELEASES_DIR && segs[1] === TEMPLATES_SUBDIR && name.endsWith(".txt")) {
+            const e = entry("template", fileDigest(name, ".txt"));
+            ledgerOf(prefix, member).templates.set(digestKey(stemOf(name, ".txt")), e);
+        }
+        else if (segs.length === 2 && segs[0] === RELEASES_DIR && name === CUTS_FILE) {
+            ledgerOf(prefix, member).cuts = f;
+        }
+        else if (segs.length === 2 && segs[0] === "_gates" && name.endsWith(".jsonl")) {
+            ledgerOf(prefix, member).gates.push(f);
+        }
+        else if (segs.length === 2 && name === "releases.jsonl" && !segs[0].startsWith("_")) {
+            ledgerOf(prefix, member).deploys.push({ env: segs[0], file: f });
+        }
+    }
+    const blobs = readBlobs(cwd, [...members.values()].flatMap((m) => [...m.releases.values()].map((r) => r.sha).concat(m.cuts ? [m.cuts.sha] : [], m.gates.map((g) => g.sha), m.deploys.map((d) => d.file.sha))));
+    const keep = [];
+    const remove = [];
+    const nowMs = now.getTime();
+    for (const m of members.values()) {
+        const reasons = new Map();
+        const keepFile = (f, reason) => {
+            if (!f)
+                return;
+            reasons.set(f, [...(reasons.get(f) ?? []), reason]);
+        };
+        // The gate facts of every op in the member.
+        const pending = [];
+        const resolutions = [];
+        let releaseGateResolutions = [];
+        for (const g of m.gates) {
+            const parsed = parseGateLedger(blobs.get(g.sha) ?? "");
+            pending.push(...parsed.pending);
+            resolutions.push(...parsed.resolutions);
+            if (g.path.endsWith(`/${RELEASE_GATE_OP}.jsonl`) || g.path === `_gates/${RELEASE_GATE_OP}.jsonl`)
+                releaseGateResolutions = parsed.resolutions;
+        }
+        // Releases, parsed.
+        const parsed = new Map();
+        for (const r of m.releases.values()) {
+            const release = parseRelease(blobs.get(r.sha) ?? "");
+            parsed.set(r, release && digestKey(release.releaseDigest) === digestKey(r.digest) ? release : null);
+        }
+        // Rule 1: what each environment runs.
+        for (const { env, file } of m.deploys) {
+            const { records } = parseReleaseLedger(releaseLedgerLines(blobs.get(file.sha) ?? null));
+            for (const record of latestPerComponent(records).values()) {
+                const digest = releaseOfDeploy(record, releaseGateResolutions);
+                if (digest !== undefined)
+                    keepFile(m.releases.get(digestKey(digest)), { code: "deployed", detail: `${env}/${record.component}` });
+            }
+        }
+        // Rule 2: what a pending gate binds, until its fact expires.
+        for (const p of pending) {
+            if (new Date(p.expiresAt).getTime() <= nowMs)
+                continue;
+            const detail = `${p.op}/${p.gate}${p.environment ? ` in ${p.environment}` : ""}`;
+            if (p.planDigest)
+                keepFile(m.changeSets.get(digestKey(p.planDigest)), { code: "pending-gate", detail });
+            if (p.releaseDigest)
+                keepFile(m.releases.get(digestKey(p.releaseDigest)), { code: "pending-gate", detail });
+        }
+        // Rule 3: a release still promotable.
+        const { cuts } = parseCuts(m.cuts ? (blobs.get(m.cuts.sha) ?? null) : null);
+        const cutAt = new Map();
+        for (const c of cuts) {
+            const k = digestKey(c.releaseDigest);
+            if (!cutAt.has(k) || c.timestamp > cutAt.get(k))
+                cutAt.set(k, c.timestamp);
+        }
+        const releaseCutoff = nowMs - policy.releases.days * DAY_MS;
+        const promotable = [];
+        for (const [k, file] of m.releases) {
+            const release = parsed.get(file);
+            if (!release) {
+                keepFile(file, { code: "unreadable" });
+                continue;
+            }
+            if (revoked.has(release.commit))
+                continue;
+            const when = cutAt.get(k) ?? file.storedAt;
+            promotable.push({ file, at: when ? new Date(when).getTime() : Number.POSITIVE_INFINITY });
+        }
+        promotable.sort((a, b) => b.at - a.at || (a.file.path < b.file.path ? -1 : 1));
+        promotable.forEach(({ file, at }, i) => {
+            if (i < policy.releases.keep)
+                keepFile(file, { code: "newest" });
+            if (at >= releaseCutoff)
+                keepFile(file, { code: "within-window" });
+        });
+        const keptReleases = new Set([...m.releases.values()].filter((r) => reasons.has(r)));
+        const keptKeys = new Set([...keptReleases].map((r) => digestKey(r.digest)));
+        // Templates follow the releases that name them.
+        const unreadableKept = [...keptReleases].some((r) => parsed.get(r) === null);
+        for (const r of keptReleases) {
+            const release = parsed.get(r);
+            if (!release)
+                continue;
+            for (const t of release.targets)
+                for (const tpl of t.templates)
+                    keepFile(m.templates.get(digestKey(tpl.digest)), { code: "kept-release", detail: r.digest });
+        }
+        if (unreadableKept)
+            for (const t of m.templates.values())
+                keepFile(t, { code: "unreadable", detail: "a release file of this member can't be read" });
+        // Rule 4, and the change-set window.
+        const lastNamed = new Map();
+        for (const fact of [...pending, ...resolutions]) {
+            if (!fact.planDigest)
+                continue;
+            const k = digestKey(fact.planDigest);
+            const t = new Date(fact.timestamp).getTime();
+            if (!lastNamed.has(k) || t > lastNamed.get(k))
+                lastNamed.set(k, t);
+            if (fact.releaseDigest && keptKeys.has(digestKey(fact.releaseDigest)))
+                keepFile(m.changeSets.get(k), { code: "kept-release", detail: fact.releaseDigest });
+        }
+        const changeSetCutoff = nowMs - policy.changeSets.days * DAY_MS;
+        for (const [k, file] of m.changeSets) {
+            const storedMs = file.storedAt ? new Date(file.storedAt).getTime() : Number.POSITIVE_INFINITY;
+            const last = Math.max(storedMs, lastNamed.get(k) ?? Number.NEGATIVE_INFINITY);
+            if (last >= changeSetCutoff)
+                keepFile(file, { code: "within-window" });
+        }
+        for (const f of [...m.changeSets.values(), ...m.releases.values(), ...m.templates.values()]) {
+            const why = reasons.get(f);
+            if (why)
+                keep.push({ ...f, reasons: dedupe(why) });
+            else
+                remove.push(f);
+        }
+    }
+    const byPath = (a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    remove.sort(byPath);
+    keep.sort(byPath);
+    const removed = new Set(remove.map((f) => f.path));
+    return { tip, remove, keep, before: sizeOf(files, kinds), after: sizeOf(files.filter((f) => !removed.has(f.path)), kinds) };
+}
+function dedupe(reasons) {
+    const seen = new Set();
+    return reasons.filter((r) => {
+        const k = `${r.code}\0${r.detail ?? ""}`;
+        if (seen.has(k))
+            return false;
+        seen.add(k);
+        return true;
+    });
+}
+/** The commit message of a prune. */
+export function pruneMessage(remove) {
+    const n = (kind) => remove.filter((f) => f.kind === kind).length;
+    return `Retention: remove ${n("change-set")} change set(s), ${n("release")} release(s) and ${n("template")} template(s)`;
+}
+const PRUNE_ATTEMPTS = 5;
+/**
+ * Plan and, unless `dryRun`, carry out a prune: one commit on the local
+ * `chant/lifecycle` that removes what the plan lets go, and the run event
+ * files it lets go deleted. The commit is planned against the tip it is
+ * written on: if the branch moved in between, the plan is made again. It is
+ * pushed only when `push` is set.
+ */
+export async function runLifecycleGc(input) {
+    let plan = planLifecycleGc(input);
+    let commit = null;
+    if (!input.dryRun && plan.tip && plan.remove.length > 0) {
+        for (let attempt = 1;; attempt++) {
+            const removals = plan.remove.map((f) => ({ path: f.path, remove: true, expectPriorSha: f.sha }));
+            try {
+                commit = await writeLedgerFiles(removals, pruneMessage(plan.remove), { cwd: input.cwd, expectTip: plan.tip });
+                break;
+            }
+            catch (err) {
+                if (!(err instanceof RefCASConflictError) || attempt >= PRUNE_ATTEMPTS)
+                    throw err;
+                plan = planLifecycleGc(input);
+                if (!plan.tip || plan.remove.length === 0)
+                    break;
+            }
+        }
+    }
+    let pushed = false;
+    let pushWarning;
+    if (commit && input.push) {
+        const r = await pushLifecycleReport({ cwd: input.cwd });
+        pushed = r.pushed;
+        pushWarning = r.pushWarning;
+    }
+    const events = await planRunEventPrune(input.cwd, input.policy.runEvents, input.now);
+    const deleted = input.dryRun ? 0 : pruneRunEvents(events);
+    return {
+        now: input.now.toISOString(),
+        policy: input.policy,
+        dryRun: input.dryRun,
+        lifecycle: { ...plan, commit, pushed, ...(pushWarning ? { pushWarning } : {}) },
+        runEvents: {
+            dir: events.dir,
+            remove: events.remove,
+            kept: { files: events.keep.length, bytes: events.keep.reduce((n, f) => n + f.bytes, 0) },
+            deleted,
+        },
+    };
+}

package/dist/lifecycle/run-ledger.d.ts

@@ -1,6 +1,6 @@
 import type { OpConfig } from "../op/types.js";
 import type { StepRecord } from "../op/local-executor.js";
-import type { OpRunRecord, OpRunRecordInput } from "../op/runtime.js";
+import { type OpRunRecord, type OpRunRecordInput } from "../op/runtime.js";
 /** The env a run records against when its Op declares no `labels.Env`. */
 export declare const DEFAULT_RUN_ENV = "local";
 /** The env a run records against: the Op's own `labels.Env`, else {@link DEFAULT_RUN_ENV}. */

package/dist/lifecycle/run-ledger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-ledger.d.ts","sourceRoot":"","sources":["../../src/lifecycle/run-ledger.ts"],"names":[],"mappings":"AAsCA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAqC,MAAM,eAAe,CAAC;AAStG,0EAA0E;AAC1E,eAAO,MAAM,eAAe,UAAU,CAAC;AAMvC,8FAA8F;AAC9F,wBAAgB,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,GAAG,MAAM,CAEjE;AAQD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAC,EACzC,OAAO,EAAE,SAAS,UAAU,EAAE,EAC9B,KAAK,EAAE;IACL,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC9B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC3B,KAAK,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,OAAO,CAAC,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;IACjC,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IACrC,0EAA0E;IAC1E,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC,GACA,gBAAgB,CAiDlB;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,gBAAgB,EACvB,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,CAAC,CAsBlD;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtB,OAAO,CAAC;IAAE,OAAO,EAAE,WAAW,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CA4BxD"}
+{"version":3,"file":"run-ledger.d.ts","sourceRoot":"","sources":["../../src/lifecycle/run-ledger.ts"],"names":[],"mappings":"AAsCA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAkB,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAA+C,MAAM,eAAe,CAAC;AASrI,0EAA0E;AAC1E,eAAO,MAAM,eAAe,UAAU,CAAC;AAMvC,8FAA8F;AAC9F,wBAAgB,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,GAAG,MAAM,CAEjE;AAQD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAC,EACzC,OAAO,EAAE,SAAS,UAAU,EAAE,EAC9B,KAAK,EAAE;IACL,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC9B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC3B,KAAK,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,OAAO,CAAC,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;IACjC,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IACrC,0EAA0E;IAC1E,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC,GACA,gBAAgB,CAiDlB;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,gBAAgB,EACvB,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,CAAC,CAsBlD;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtB,OAAO,CAAC;IAAE,OAAO,EAAE,WAAW,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAkCxD"}

package/dist/lifecycle/run-ledger.js

@@ -36,6 +36,7 @@
  */
 import { randomUUID } from "node:crypto";
 import { sortedJsonReplacer } from "../utils.js";
+import { opRunFailureOf } from "../op/runtime.js";
 import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASConflictError } from "./git.js";
 /** Prefix folding the per-op run ledgers into one flat name under `<env>/`. See the module doc. */
 const PREFIX = "runs__";
@@ -177,6 +178,14 @@ export async function readRunLedger(environment, op, opts) {
                 malformed++;
                 continue;
             }
+            // A `failure` (#4094) that is not one is dropped and the line kept, as a gate line's wrong-typed `gitSha` is.
+            if ("failure" in parsed) {
+                const failure = opRunFailureOf(parsed.failure);
+                if (failure)
+                    parsed.failure = failure;
+                else
+                    delete parsed.failure;
+            }
             records.push(parsed);
         }
         catch {

package/dist/op/activities/activity-contracts.d.ts

@@ -47,6 +47,7 @@ export declare const shellCmdContract: import("../index.js").ActivityContract<{
     cmd: string;
     env?: Record<string, string> | undefined;
     cwd?: string | undefined;
+    inheritEnv?: boolean | undefined;
     okExit?: number[] | undefined;
     gatedExit?: number | undefined;
     gate?: {

package/dist/op/activities/activity-contracts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"activity-contracts.d.ts","sourceRoot":"","sources":["../../../src/op/activities/activity-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,eAAO,MAAM,yBAAyB;;SAGrC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;EAIjC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;EAe5B,CAAC;AAEF,eAAO,MAAM,iBAAiB;;;;;;;;;EAgB7B,CAAC;AAEF,eAAO,MAAM,qBAAqB;;SAGjC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;EAUpC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;EAuBpC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;EA8B3C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgClC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;EAkBhC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;EAIjC,CAAC;AAOF,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;EAIpC,CAAC;AAEF,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;EAI1C,CAAC;AAEF,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;EAIrC,CAAC;AAEF,eAAO,MAAM,mBAAmB;;;;;;;;;;;EAW/B,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;EAWjC,CAAC;AAUF,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6B1B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;EAoBvC,CAAC;AAEF,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;EAWzC,CAAC;AAWF,eAAO,MAAM,mBAAmB;;;;;;;;;;;EAQ/B,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;YAIhC,CAAC;AAEF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;EAU9B,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;EAIhC,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;EAIhC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;EASjC,CAAC"}
+{"version":3,"file":"activity-contracts.d.ts","sourceRoot":"","sources":["../../../src/op/activities/activity-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,eAAO,MAAM,yBAAyB;;SAGrC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;EAIjC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;EAgB5B,CAAC;AAEF,eAAO,MAAM,iBAAiB;;;;;;;;;EAgB7B,CAAC;AAEF,eAAO,MAAM,qBAAqB;;SAGjC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;EAUpC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;EAuBpC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;EA8B3C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgClC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;EAkBhC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;EAIjC,CAAC;AAOF,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;EAIpC,CAAC;AAEF,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;EAI1C,CAAC;AAEF,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;EAIrC,CAAC;AAEF,eAAO,MAAM,mBAAmB;;;;;;;;;;;EAW/B,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;EAWjC,CAAC;AAUF,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6B1B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;EAoBvC,CAAC;AAEF,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;EAWzC,CAAC;AAWF,eAAO,MAAM,mBAAmB;;;;;;;;;;;EAQ/B,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;YAIhC,CAAC;AAEF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;EAU9B,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;EAIhC,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;EAIhC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;EASjC,CAAC"}

package/dist/op/activities/activity-contracts.js

@@ -41,6 +41,7 @@ export const shellCmdContract = activityContract("shellCmd", z.strictObject({
     cmd: z.string(),
     env: z.record(z.string(), z.string()).optional(),
     cwd: z.string().optional(),
+    inheritEnv: z.boolean().optional(),
     okExit: z.array(z.number()).optional(),
     gatedExit: z.number().optional(),
     gate: z.strictObject({ op: z.string(), gate: z.string() }).optional(),

package/dist/op/activities/shell.d.ts

@@ -4,6 +4,12 @@ export interface ShellCmdArgs {
     env?: Record<string, string>;
     /** Working directory. Default: process.cwd(). */
     cwd?: string;
+    /**
+     * Whether the command sees this process's environment. Default true. With
+     * false it sees `env` alone, plus the in-flight record's variable, so a job
+     * the chant runner runs (`chant ci run`, #4094) gets a clean environment.
+     */
+    inheritEnv?: boolean;
     /**
      * Exit codes that count as success. Default `[0]`.
      *

package/dist/op/activities/shell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../../../src/op/activities/shell.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,wCAAwC;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,iDAAiD;IACjD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,IAAI,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAgBD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAuBD;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CA0DhG"}
+{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../../../src/op/activities/shell.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,wCAAwC;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,iDAAiD;IACjD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,IAAI,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAgBD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAuBD;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CA0DhG"}

package/dist/op/activities/shell.js

@@ -54,7 +54,7 @@ export async function shellCmd(args, signal) {
             cwd: args.cwd,
             // In a run that keeps an in-flight record, CHANT_RUN_ACTIVITY names the
             // file the command appends activity lines to (../run-live.ts).
-            env: { ...process.env, ...liveRunEnv(), ...args.env },
+            env: { ...(args.inheritEnv === false ? {} : process.env), ...liveRunEnv(), ...args.env },
             maxBuffer: MAX_STDOUT_BYTES,
             signal,
         });

package/dist/op/local-executor.d.ts

@@ -33,7 +33,7 @@ import { type WaitingPoint } from "./steward-points.js";
 import type { OpRunRecord } from "./runtime.js";
 import { type WorkLeaseRunResult } from "./work-lease-run.js";
 import { type RunOrigin } from "../lifecycle/release-ledger.js";
-import { type RunEventRuntime } from "../run-event.js";
+import { type RunEventKind, type RunEventRuntime } from "../run-event.js";
 import type { ActivityContract } from "./activity-contract.js";
 export { parseDuration } from "./duration.js";
 /**
@@ -268,6 +268,28 @@ export interface RunOpOptions {
         runtime?: RunEventRuntime;
         runOrigin?: RunOrigin;
     };
+    /**
+     * What ran the Op, when a runner says so itself (#4094): `chant ci run`
+     * runs a pull-request job as an Op and passes `kind: "pipeline"`,
+     * `runtime: "ci"` and `runOrigin: { forge: "chant" }`. The run's events
+     * carry all three, kept on this host as well as written to
+     * {@link runEvents}, and the run record carries `runOrigin` in place of
+     * the CI run the environment names. Omitted, the run is an `op` run named
+     * as described on {@link runEvents}.
+     */
+    runner?: {
+        kind: RunEventKind;
+        runtime: RunEventRuntime;
+        runOrigin: RunOrigin;
+    };
+    /**
+     * Says why a failed run failed (#4094), given the run's step records once
+     * it has settled `fail`. What it returns is stored on the record as
+     * `failure`, before the record is signed, and carried on the `run-settle`
+     * event. `chant ci run` reads the job's pull-request report here, while
+     * the checkout it ran in still exists.
+     */
+    describeFailure?: (records: readonly StepRecord[]) => OpRunRecord["failure"];
     /**
      * Append the run's {@link OpRunRecord} to the run ledger
      * (`../lifecycle/run-ledger.ts`) when the run settles (#2118). Opt-in on

package/dist/op/local-executor.d.ts.map

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

package/dist/op/local-executor.js

@@ -1046,7 +1046,7 @@ async function runOpInTurn(config, activities, profiles, signal, options, run, e
     const eventsWrite = teeLines(options.runEvents?.write, store?.write.bind(store));
     const stream = eventsWrite
         ? openRunEventStream(runEventRunOf({
-            kind: "op",
+            kind: options.runner?.kind ?? "op",
             name: config.name,
             runId,
             ...(commit ? { gitSha: commit } : {}),
@@ -1054,6 +1054,7 @@ async function runOpInTurn(config, activities, profiles, signal, options, run, e
             steward: options.steward !== undefined,
             ...(options.runEvents?.runtime ? { runtime: options.runEvents.runtime } : {}),
             ...(options.runEvents?.runOrigin ? { runOrigin: options.runEvents.runOrigin } : {}),
+            ...(options.runner ? { runtime: options.runner.runtime, runOrigin: options.runner.runOrigin } : {}),
         }), eventsWrite)
         : undefined;
     events.stream = stream;
@@ -1178,9 +1179,14 @@ async function runOpInTurn(config, activities, profiles, signal, options, run, e
             ...(options.steward ? { steward: options.steward } : {}),
             ...(resumed ? { resumed } : {}),
             ...(commit ? { gitSha: commit } : {}),
-            ...(ciRun ? { runOrigin: ciRun.runOrigin } : {}),
+            ...(options.runner ? { runOrigin: options.runner.runOrigin } : ciRun ? { runOrigin: ciRun.runOrigin } : {}),
             phaseDurations,
         });
+        if (status === "fail" && options.describeFailure) {
+            const failure = options.describeFailure(settled);
+            if (failure)
+                input.failure = failure;
+        }
         let record = { version: 1, ...input, id: runId };
         if (options.signRecord) {
             try {
@@ -1194,7 +1200,7 @@ async function runOpInTurn(config, activities, profiles, signal, options, run, e
         }
         // The stream settles as the run does, with the first failing step's error.
         const firstError = status === "fail" ? settled.find((r) => r.status === "fail")?.error : undefined;
-        stream?.settle(status === "fail" ? "failed" : status, firstError);
+        stream?.settle(status === "fail" ? "failed" : status, firstError, input.failure);
         if (!options.ledger)
             return record;
         try {

package/dist/op/runtime.d.ts

@@ -211,7 +211,34 @@ export interface OpRunRecord {
             sig: string;
         }[];
     };
+    /**
+     * Why a failed run failed (#4094), for a reader that acts on it without
+     * reading the log: a short `code`, a one-line `reason`, the phase that
+     * failed and the exit code of the command that failed. `chant ci run`
+     * writes it on every failed job, from the job's pull-request report when
+     * it wrote one (`not-a-reviewer`, `plan-failed`, `failed` and the other
+     * refusals and statuses), else `command-failed`, `setup-failed` or
+     * `build-failed`. Optional within contract 1, written by chant
+     * {@link OP_RUN_FAILURE_FLOOR} and newer; absent on a run that passed and
+     * on a run nothing explained.
+     */
+    failure?: OpRunFailureReason;
+}
+/** Why a run failed, on {@link OpRunRecord.failure} and on the run's `run-settle` event (#4094). */
+export interface OpRunFailureReason {
+    /** A short code: a pull-request report's refusal or status, or `command-failed`, `setup-failed`, `build-failed`. */
+    code: string;
+    /** One line a person reads. */
+    reason: string;
+    /** The phase that failed, when one did. */
+    phase?: string;
+    /** The exit code of the command that failed, when it exited with one. */
+    exitCode?: number;
 }
+/** The first chant that writes {@link OpRunRecord.failure} and `failure` on `run-settle` (#4094). */
+export declare const OP_RUN_FAILURE_FLOOR = "0.124.30";
+/** `value` as an {@link OpRunFailureReason}, or undefined when it is not one, so a reader drops a malformed field and keeps the record. */
+export declare function opRunFailureOf(value: unknown): OpRunFailureReason | undefined;
 /** An {@link OpRunRecord} before the ledger stamps its version and mints an id. */
 export type OpRunRecordInput = Omit<OpRunRecord, "version" | "id"> & {
     id?: string;