@intentius/chant 0.124.13 → 0.124.15

package/dist/op/activities/shell.js

@@ -0,0 +1,118 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { GateWait, asPendingGate } from "../gate-wait.js";
+import { liveRunEnv } from "../run-live.js";
+const execAsync = promisify(exec);
+/**
+ * How much stdout a command may produce, matching every other exec site in
+ * the tree (`../activities/apply.ts`, the terraform lexicon's activities,
+ * `../../components/verbs/process-runner.ts`).
+ *
+ * Node's default is 1 MiB, and this was the only exec call leaving it unset
+ * (#2412) — on the one activity whose output chant cannot predict, because
+ * the command is the author's. A verbose test run, a playbook or a wide plan
+ * passes 1 MiB without trying, and the overflow is a rejection rather than a
+ * truncation, so the step fails for a reason that has nothing to do with the
+ * command.
+ */
+const MAX_STDOUT_BYTES = 64 * 1024 * 1024;
+/** `result` with its stdout parsed as JSON, when the step asked for it. */
+function withJson(result, args) {
+    if (!args.json)
+        return result;
+    if (result.stdout === "")
+        return { ...result, json: null };
+    try {
+        return { ...result, json: JSON.parse(result.stdout) };
+    }
+    catch (err) {
+        const shown = result.stdout.length > 200 ? `${result.stdout.slice(0, 200)}...` : result.stdout;
+        throw new Error(`the step sets json, and its stdout is not JSON (${err instanceof Error ? err.message : String(err)}): ${shown}`);
+    }
+}
+/**
+ * Run an arbitrary shell command.
+ *
+ * Runs under the `atMostOnce` profile by default (#2411): one attempt, since
+ * nothing here can know whether repeating the author's command is safe.
+ */
+export async function shellCmd(args, signal) {
+    const okExit = args.okExit ?? [0];
+    try {
+        const { stdout, stderr } = await execAsync(args.cmd, {
+            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 },
+            maxBuffer: MAX_STDOUT_BYTES,
+            signal,
+        });
+        if (stderr)
+            console.error(stderr);
+        return withJson({ stdout: stdout.trim(), stderr: stderr.trim(), exitCode: 0 }, args);
+    }
+    catch (err) {
+        const failure = err;
+        const exitCode = typeof failure.code === "number" ? failure.code : undefined;
+        // A signal kill (Ctrl-C, the profile's timeout, a maxBuffer overflow) is
+        // not an exit status the author declared anything about, so it rethrows
+        // even if `okExit` happens to contain the code.
+        const died = failure.killed === true || typeof failure.signal === "string" || signal?.aborted === true;
+        if (exitCode !== undefined && !died && args.gatedExit !== undefined && exitCode === args.gatedExit) {
+            const stderrText = (failure.stderr ?? "").trim();
+            if (stderrText)
+                console.error(stderrText);
+            throw new GateWait(await commandGate(args, (failure.stdout ?? "").trim(), exitCode));
+        }
+        if (exitCode !== undefined && !died && okExit.includes(exitCode)) {
+            const stderrText = (failure.stderr ?? "").trim();
+            if (stderrText)
+                console.error(stderrText);
+            return withJson({ stdout: (failure.stdout ?? "").trim(), stderr: stderrText, exitCode }, args);
+        }
+        if (exitCode !== undefined && !died) {
+            // `local-executor` records `error` as message text, so the code has to
+            // be in the message or it is gone (#2413).
+            failure.message = `command exited ${exitCode} (expected ${okExit.join(", ")}): ${failure.message}`;
+        }
+        throw failure;
+    }
+}
+/** The pending fact a command's stdout carries: the whole of it as JSON, or its last line. */
+function pendingFromStdout(stdout) {
+    const lines = stdout.split("\n");
+    for (const text of [stdout, lines[lines.length - 1] ?? ""]) {
+        try {
+            const parsed = JSON.parse(text);
+            const pending = asPendingGate(parsed?.pending);
+            if (pending)
+                return pending;
+        }
+        catch {
+            // Not JSON: try the next reading, then the step's own `gate`.
+        }
+    }
+    return undefined;
+}
+/**
+ * The gate a command stopped at (#2779): the pending fact its stdout
+ * carries, or the newest one the gate ledger holds for the step's `gate`.
+ * Throws when neither names one, since a run can't be `gated` at a gate
+ * nobody can approve.
+ */
+async function commandGate(args, stdout, exitCode) {
+    const fromStdout = pendingFromStdout(stdout);
+    if (fromStdout)
+        return fromStdout;
+    const named = args.gate;
+    if (!named) {
+        throw new Error(`command exited ${exitCode}, its gatedExit, and named no gate: its stdout carries no \`pending\` gate fact as JSON, and the step has no \`gate\``);
+    }
+    const { readGateLedger, latestPendingGate } = await import("../../lifecycle/gate-ledger.js");
+    const { pending } = await readGateLedger(named.op, args.cwd ? { cwd: args.cwd } : undefined);
+    const latest = latestPendingGate(pending, named.gate);
+    if (!latest) {
+        throw new Error(`command exited ${exitCode}, its gatedExit, but the gate ledger holds no pending fact for ${named.op} / ${named.gate}, so there is no gate to stop at`);
+    }
+    return latest;
+}

package/dist/op/activities/source-release.js

@@ -0,0 +1,97 @@
+/**
+ * The release activities an Op ships a source tree with (#2782): archive the
+ * tree, plan the release, and record it once it serves.
+ *
+ * - {@link sourceArchive}: one directory of HEAD as a tar (../source-archive.ts),
+ *   named by its sha256. The same commit archives to the same bytes.
+ * - {@link releasePlan}: what a release will ship, as a JSON object named by
+ *   the sha256 of its own canonical form. The ship gate binds to that digest
+ *   (`gate("ship", { plan: plan.out.digest })`), the step that ships reads the
+ *   plan back by it, and the release ledger records it (ws-055: a release
+ *   record's digest names its plan). Nothing in a plan changes from one run of
+ *   the same commit to the next, so a retried release plans the same digest
+ *   and its approval still holds.
+ * - {@link releaseRecord}: persist the plan to `_plans/<digest>.json` on
+ *   chant/lifecycle and append the release record, as `chant components
+ *   release --release-plan` does. When the environment's latest record for
+ *   the component already names this digest, nothing is written, so a
+ *   retried release records once.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { sortedJsonReplacer } from "../../utils.js";
+import { archiveSourceTree, sha256Digest } from "../source-archive.js";
+/** Archive a directory of a commit (default HEAD); see ../source-archive.ts. */
+export async function sourceArchive(args) {
+    return archiveSourceTree({ dir: args.path, ref: args.ref, out: args.out, cwd: args.cwd });
+}
+/** The digest of a plan: sha256 of its canonical JSON (keys sorted), `digest` left out. Pure. */
+export function releasePlanDigest(plan) {
+    const { digest: _digest, ...rest } = plan;
+    return sha256Digest(JSON.stringify(rest, sortedJsonReplacer));
+}
+/** Write a release plan, named by its own digest. */
+export async function releasePlan(args) {
+    if (!args.component || !args.env || !args.gitSha)
+        throw new Error("releasePlan: a plan names its component, its environment and its commit");
+    const body = { component: args.component, env: args.env, gitSha: args.gitSha, ...args.content };
+    const digest = releasePlanDigest(body);
+    const dir = resolve(args.cwd ?? process.cwd(), args.dir ?? join("dist", "plans"));
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, `${digest.replace(":", "_")}.json`);
+    writeFileSync(file, JSON.stringify({ digest, ...body }, sortedJsonReplacer, 2) + "\n");
+    return { digest, file, gitSha: args.gitSha };
+}
+/** A plan `releasePlan` wrote, checked against its digest. */
+export function readReleasePlan(path, digest) {
+    const plan = JSON.parse(readFileSync(path, "utf-8"));
+    const actual = releasePlanDigest(plan);
+    if (plan.digest !== actual)
+        throw new Error(`${path} names digest ${plan.digest}, but its content is ${actual}`);
+    if (digest !== undefined && digest !== actual)
+        throw new Error(`${path} is plan ${actual}, not the approved ${digest}`);
+    return plan;
+}
+/** Persist the plan and record the release in the ledger, once. */
+export async function releaseRecord(args) {
+    const cwd = args.cwd;
+    const opts = cwd ? { cwd } : undefined;
+    const plan = readReleasePlan(resolve(cwd ?? process.cwd(), args.plan), args.digest);
+    const component = plan.component;
+    const env = plan.env;
+    const gitSha = plan.gitSha;
+    const { readReleaseLedger, latestPerComponent, appendReleaseRecord, resolveRunId } = await import("../../lifecycle/release-ledger.js");
+    const { persistReleasePlan } = await import("../../lifecycle/plan-ledger.js");
+    const { pushLifecycle } = await import("../../lifecycle/git.js");
+    let approver = null;
+    if (args.approval) {
+        const { readGateLedger } = await import("../../lifecycle/gate-ledger.js");
+        const { resolutions } = await readGateLedger(args.approval.op, opts);
+        const bound = resolutions.filter((r) => r.gate === args.approval.gate && r.planDigest === plan.digest);
+        approver = bound.length > 0 ? [...new Set(bound.map((r) => r.resolvedBy))].join(", ") : null;
+    }
+    const latest = latestPerComponent((await readReleaseLedger(env, opts)).records).get(component);
+    if (latest?.digest === plan.digest && latest.gitSha === gitSha) {
+        await persistReleasePlan(plan, opts);
+        await pushLifecycle(opts);
+        return { recorded: false, digest: plan.digest, env, component, approver };
+    }
+    const actor = args.actor || process.env.GITHUB_ACTOR || process.env.GITLAB_USER_LOGIN || process.env.USER;
+    if (!actor)
+        throw new Error("releaseRecord: no actor: pass one, or set GITHUB_ACTOR, GITLAB_USER_LOGIN or USER");
+    const { runId, runOrigin } = resolveRunId(args.runId);
+    await persistReleasePlan(plan, opts);
+    await appendReleaseRecord({
+        component,
+        env,
+        digest: plan.digest,
+        gitSha,
+        runId,
+        ...(runOrigin ? { runOrigin } : {}),
+        timestamp: new Date().toISOString(),
+        actor,
+        ...(approver ? { approver } : {}),
+    }, opts);
+    await pushLifecycle(opts);
+    return { recorded: true, digest: plan.digest, env, component, approver };
+}

package/dist/op/activities/source-rollback.js

@@ -0,0 +1,165 @@
+/**
+ * The rollback activities for a release a release Op shipped as a source tree
+ * (#2800): plan the rollback from the release ledger, and record it once the
+ * site serves the earlier release again.
+ *
+ * - {@link releaseRollbackPlan}: pick the release to go back to, read its plan
+ *   from `_plans/` (ws-055), archive the same directory of the same commit
+ *   again and refuse unless it hashes to the digest that plan recorded, then
+ *   write a rollback plan named by its own sha256. The rollback gate binds to
+ *   that digest. The step that restores the Machine reads the archive again,
+ *   checked against the same digest, before the Machine changes.
+ * - {@link releaseRollbackRecord}: append a release record with the restored
+ *   release's digest and commit, `restores` naming that release, the actor who
+ *   ran it and the gate's approver, the way `chant components rollback`
+ *   records one. Nothing is written when the ledger already records it.
+ *
+ * Which release: by default, the one the site served before the latest
+ * release the release Op shipped. A rollback's own record does not count as
+ * a release here, so running the rollback again plans the same rollback, its
+ * approval still holds, the Machine already serves it, and nothing is
+ * recorded twice. `to` names another release by its digest.
+ */
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { archiveSourceTree } from "../source-archive.js";
+import { readReleasePlan, releasePlan, releasePlanDigest } from "./source-release.js";
+/** A record's reference, the way `restores` and `promotedFrom` name one. */
+const refTo = (r) => ({ env: r.env, runId: r.runId, timestamp: r.timestamp });
+/**
+ * The release a rollback goes back to, and the release it replaces. Pure.
+ *
+ * The replaced release is the component's latest record that is not itself a
+ * rollback. By default the target is the latest record before it with another
+ * digest: what the site served before that release. With `to`, the target is
+ * the latest record with that digest.
+ */
+export function pickRollback(records, component, env, to) {
+    // Ledger order, oldest first; a later append wins a tied timestamp.
+    const own = records
+        .map((r, i) => ({ r, i }))
+        .filter(({ r }) => r.component === component)
+        .sort((a, b) => (a.r.timestamp === b.r.timestamp ? a.i - b.i : a.r.timestamp < b.r.timestamp ? -1 : 1))
+        .map(({ r }) => r);
+    if (own.length === 0)
+        return { error: `no release of "${component}" is recorded in "${env}"` };
+    const releasedAt = own.map((r) => !r.restores).lastIndexOf(true);
+    if (releasedAt < 0)
+        return { error: `"${component}" has no release in "${env}" that was not itself a rollback` };
+    const replaced = own[releasedAt];
+    if (to !== undefined) {
+        const target = own.filter((r) => r.digest === to).at(-1);
+        if (!target)
+            return { error: `no release of "${component}" in "${env}" has digest ${to}` };
+        return { target, replaced };
+    }
+    const target = own.slice(0, releasedAt).filter((r) => r.digest !== replaced.digest).at(-1);
+    if (!target)
+        return { error: `"${component}" has no release in "${env}" before ${replaced.digest} to roll back to` };
+    return { target, replaced };
+}
+/** Plan a rollback: the earlier release, its plan, and its source tree archived again and checked against the recorded digest. */
+export async function releaseRollbackPlan(args) {
+    if (!args.component || !args.env)
+        throw new Error("releaseRollbackPlan: name the component and the environment");
+    const cwd = resolve(args.cwd ?? process.cwd());
+    const opts = { cwd };
+    const { readReleaseLedger } = await import("../../lifecycle/release-ledger.js");
+    const { readReleasePlan: readPersistedPlan } = await import("../../lifecycle/plan-ledger.js");
+    const picked = pickRollback((await readReleaseLedger(args.env, opts)).records, args.component, args.env, args.to);
+    if ("error" in picked)
+        throw new Error(`releaseRollbackPlan: ${picked.error}`);
+    const { target, replaced } = picked;
+    // The restored release's plan, as it was approved: its content still hashes to its name.
+    const plan = await readPersistedPlan(target.digest, opts);
+    if (!plan)
+        throw new Error(`releaseRollbackPlan: no plan is recorded for ${target.digest} (_plans/ on chant/lifecycle), so its source tree is unknown`);
+    const planDigest = releasePlanDigest(plan);
+    if (planDigest !== target.digest)
+        throw new Error(`releaseRollbackPlan: the plan recorded for ${target.digest} hashes to ${planDigest}`);
+    const artifact = plan.artifact;
+    if (typeof artifact?.digest !== "string")
+        throw new Error(`releaseRollbackPlan: the plan for ${target.digest} records no artifact digest`);
+    const gitSha = plan.gitSha ?? target.gitSha;
+    // The same directory of the same commit, archived again: git archive gives the same bytes.
+    let dir;
+    if (typeof artifact.dir === "string") {
+        const root = realpathSync(execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf-8" }).trim());
+        dir = join(root, artifact.dir);
+    }
+    else if (args.path) {
+        dir = args.path;
+    }
+    else {
+        throw new Error(`releaseRollbackPlan: the plan for ${target.digest} records no artifact.dir; pass path, the directory the release archived`);
+    }
+    const archive = archiveSourceTree({ dir, ref: gitSha, cwd });
+    if (archive.digest !== artifact.digest) {
+        throw new Error(`releaseRollbackPlan: ${archive.dir} at ${gitSha.slice(0, 12)} archives to ${archive.digest}, not the ${artifact.digest} release ${target.digest} recorded; refusing to restore it`);
+    }
+    const written = await releasePlan({
+        component: args.component,
+        env: args.env,
+        gitSha,
+        content: {
+            rollback: { to: target.digest, from: replaced.digest, restores: refTo(target) },
+            artifact: { ...plan.artifact, digest: archive.digest, dir: archive.dir },
+        },
+        ...(args.dir ? { dir: args.dir } : {}),
+        cwd,
+    });
+    return {
+        digest: written.digest,
+        file: written.file,
+        to: target.digest,
+        from: replaced.digest,
+        gitSha,
+        archive: archive.archive,
+        archiveDigest: archive.digest,
+        dir: archive.dir,
+    };
+}
+/** Record a rollback in the release ledger, once. */
+export async function releaseRollbackRecord(args) {
+    const cwd = args.cwd;
+    const opts = cwd ? { cwd } : undefined;
+    const plan = readReleasePlan(resolve(cwd ?? process.cwd(), args.plan), args.digest);
+    const rollback = plan.rollback;
+    if (!rollback?.to || !rollback.restores)
+        throw new Error(`releaseRollbackRecord: ${args.plan} is not a rollback plan (no rollback.to)`);
+    const component = plan.component;
+    const env = plan.env;
+    const gitSha = plan.gitSha;
+    const { readReleaseLedger, latestPerComponent, appendReleaseRecord, resolveRunId } = await import("../../lifecycle/release-ledger.js");
+    const { pushLifecycle } = await import("../../lifecycle/git.js");
+    let approver = null;
+    if (args.approval) {
+        const { readGateLedger } = await import("../../lifecycle/gate-ledger.js");
+        const { resolutions } = await readGateLedger(args.approval.op, opts);
+        const bound = resolutions.filter((r) => r.gate === args.approval.gate && r.planDigest === plan.digest);
+        approver = bound.length > 0 ? [...new Set(bound.map((r) => r.resolvedBy))].join(", ") : null;
+    }
+    const latest = latestPerComponent((await readReleaseLedger(env, opts)).records.filter((r) => r.component === component)).get(component);
+    if (latest?.digest === rollback.to && latest.restores?.runId === rollback.restores.runId && latest.restores.timestamp === rollback.restores.timestamp) {
+        return { recorded: false, digest: rollback.to, env, component, approver };
+    }
+    const actor = args.actor || process.env.GITHUB_ACTOR || process.env.GITLAB_USER_LOGIN || process.env.USER;
+    if (!actor)
+        throw new Error("releaseRollbackRecord: no actor: pass one, or set GITHUB_ACTOR, GITLAB_USER_LOGIN or USER");
+    const { runId, runOrigin } = resolveRunId(args.runId);
+    await appendReleaseRecord({
+        component,
+        env,
+        digest: rollback.to,
+        gitSha,
+        runId,
+        ...(runOrigin ? { runOrigin } : {}),
+        timestamp: new Date().toISOString(),
+        actor,
+        ...(approver ? { approver } : {}),
+        restores: rollback.restores,
+    }, opts);
+    await pushLifecycle(opts);
+    return { recorded: true, digest: rollback.to, env, component, approver };
+}

package/dist/op/activities/teardown.js

@@ -0,0 +1,17 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+const execAsync = promisify(exec);
+/**
+ * Run `chant teardown` in the given project path.
+ * Uses longInfra profile — 20m timeout.
+ */
+export async function chantTeardown(args, signal) {
+    const { stdout, stderr } = await execAsync("npm run teardown", {
+        cwd: args.path,
+        signal,
+    });
+    if (stdout)
+        console.log(stdout);
+    if (stderr)
+        console.error(stderr);
+}

package/dist/op/activities/util.js

@@ -0,0 +1,6 @@
+/**
+ * Re-export shim — `sleep` is the shared activity-runtime helper one directory
+ * up (`../activity-runtime`). Kept here so existing `./util` imports resolve
+ * unchanged.
+ */
+export { sleep } from "../activity-runtime.js";

package/dist/op/activities/wait.js

@@ -0,0 +1,51 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { sleep } from "./util.js";
+const execAsync = promisify(exec);
+/**
+ * Poll until a Kubernetes Deployment or StatefulSet named `name` is fully rolled out.
+ * Uses the `k8sWait` profile — 15m timeout.
+ *
+ * Progress goes to stdout, one line per poll, which is the executor's step-record
+ * channel: the local executor streams an activity's output alongside the step it
+ * belongs to, so a long rollout is visible without a liveness protocol. Nothing
+ * mid-run is durable here by design (chant #2114) — the op re-runs and converges.
+ *
+ * Deliberately NOT migrated onto the generic `waitForReady` (#957): `kubectl
+ * rollout status` encodes rollout-specific semantics — progress-deadline
+ * timeouts, partial/paused rollouts, generation tracking — that a status-field
+ * predicate spec does not replicate, and it targets built-in workloads rather
+ * than arbitrary operator CRDs. `waitForReady` is the right tool for CRD
+ * readiness; `waitForStack` stays the right tool for workload rollouts.
+ */
+export async function waitForStack(args, signal) {
+    const ns = args.namespace ? `-n ${args.namespace}` : "";
+    const ctx = args.context ? `--context ${args.context}` : "";
+    const interval = args.intervalMs ?? 10000;
+    let attempt = 0;
+    while (true) {
+        if (signal?.aborted)
+            throw new Error("waitForStack aborted");
+        attempt++;
+        console.log(`[waitForStack] ${args.name}: poll ${attempt}`);
+        try {
+            await execAsync(`kubectl rollout status deployment/${args.name} ${ns} ${ctx} --timeout=30s`, { signal });
+            return;
+        }
+        catch {
+            if (signal?.aborted)
+                throw new Error("waitForStack aborted");
+            // Not ready yet — wait and retry
+        }
+        try {
+            await execAsync(`kubectl rollout status statefulset/${args.name} ${ns} ${ctx} --timeout=30s`, { signal });
+            return;
+        }
+        catch {
+            if (signal?.aborted)
+                throw new Error("waitForStack aborted");
+            // Not ready yet
+        }
+        await sleep(interval, signal);
+    }
+}

package/dist/op/activities/work-evidence.js

@@ -0,0 +1,35 @@
+/**
+ * `workEvidence` (#2772): attach one piece of evidence to an acceptance
+ * criterion of the work item the run holds the lease on.
+ *
+ * Meant for an Op that declares `workLease` (#2748), a steward's among them:
+ * the builder passes the run's lease (`workLeaseOutput()`) as `lease`, and the
+ * write goes through only while that lease is still the run's, under its
+ * token. The rules are `attachWorkEvidence`'s (`../../workspace/work-evidence.ts`):
+ * the criterion must be one the record lists, and a `manual` criterion is
+ * refused, since the run holding the lease is the item's implementer.
+ * A refusal fails the step with its code.
+ */
+export async function workEvidence(args) {
+    const lease = args.lease;
+    if (!lease || typeof lease.item !== "string" || typeof lease.holder !== "string" || typeof lease.token !== "string") {
+        throw new Error("workEvidence runs under a work lease: pass the run's lease as `lease` (workLeaseOutput()) from an Op that declares workLease");
+    }
+    const { attachWorkEvidence } = await import("../../workspace/work-evidence.js");
+    const out = await attachWorkEvidence({
+        cwd: args.cwd ?? process.cwd(),
+        item: lease.item,
+        holder: lease.holder,
+        token: lease.token,
+        criterion: args.criterion,
+        result: args.result,
+        title: args.title,
+        ...(args.url !== undefined ? { url: args.url } : {}),
+        ...(args.path !== undefined ? { path: args.path } : {}),
+        ...(args.kind !== undefined ? { kind: args.kind } : {}),
+    });
+    if ("error" in out)
+        throw new Error(`workEvidence refused for ${lease.item} ${args.criterion}: ${out.error.code}: ${out.error.message}`);
+    console.log(`workEvidence: ${out.item} ${args.criterion} ${args.result} (${out.acceptance.met}/${out.acceptance.total} met)`);
+    return { item: out.item, path: out.path, evidence: out.evidence, acceptance: out.acceptance };
+}

package/dist/op/activities/workflow-audit.js

@@ -0,0 +1,133 @@
+/**
+ * workflowSupplyChainAudit — the live counterpart to the github post-synth
+ * supply-chain checks (#286-#291).
+ *
+ * Some workflow-reference checks can only be answered against a moving external
+ * truth: whether a pinned SHA still corresponds to a real tag/release upstream,
+ * whether a referenced commit exists in the repo it claims, whether a ref is
+ * confusable as both a tag and a branch, whether a pin matches its version
+ * comment, or whether a new advisory now covers an action already in use. These
+ * change over time independent of the source, so they cannot live in the
+ * deterministic build — this activity owns *only* the checks that require live
+ * resolution.
+ *
+ * It is dependency-free and primitives-only: it reads the emitted workflow YAML
+ * (passed as a string) and resolves references through an injectable
+ * `ActionRefResolver`, so `chant run` can schedule it and tests can run
+ * it against recorded responses with no live network.
+ */
+/** Read `*.yml`/`*.yaml` files from a directory (best-effort). */
+async function readWorkflowDir(dir) {
+    try {
+        const { readdir, readFile } = await import("node:fs/promises");
+        const { join } = await import("node:path");
+        const files = (await readdir(dir)).filter((f) => f.endsWith(".yml") || f.endsWith(".yaml"));
+        return Promise.all(files.map((f) => readFile(join(dir, f), "utf-8")));
+    }
+    catch {
+        return [];
+    }
+}
+const SHA_RE = /^[0-9a-f]{40}$/;
+/**
+ * Collect external action references (`uses: owner/repo@ref`, with an optional
+ * trailing version comment) from a workflow YAML. Local (`./`) and `docker://`
+ * references are excluded.
+ */
+export function collectAuditRefs(yaml) {
+    const out = [];
+    const re = /uses:\s*['"]?([\w.-]+\/[\w.-]+(?:\/[\w./-]+)?)@([\w.-]+)['"]?\s*(?:#\s*(\S+))?/g;
+    let m;
+    while ((m = re.exec(yaml)) !== null) {
+        out.push({ slug: m[1].split("/").slice(0, 2).join("/"), ref: m[2], comment: m[3] });
+    }
+    return out;
+}
+/**
+ * Default resolver: query the GitHub REST API for whether the ref exists, what
+ * tags point at it, archive status, and advisories. Best-effort and resilient —
+ * a network/HTTP error yields an "unknown" resolution (exists=true, no findings)
+ * rather than a false positive.
+ */
+export const defaultActionRefResolver = async (slug, ref) => {
+    const base = `https://api.github.com/repos/${slug}`;
+    const headers = { Accept: "application/vnd.github+json" };
+    if (process.env.GITHUB_TOKEN)
+        headers.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
+    const unknown = { exists: true, tags: [], archived: false, advisories: [] };
+    try {
+        const repoResp = await fetch(base, { headers });
+        if (repoResp.status === 404)
+            return { exists: false, tags: [], archived: false, advisories: [] };
+        if (!repoResp.ok)
+            return unknown;
+        const repo = (await repoResp.json());
+        const refResp = await fetch(`${base}/commits/${ref}`, { headers });
+        if (refResp.status === 404)
+            return { exists: false, tags: [], archived: !!repo.archived, advisories: [] };
+        let tags = [];
+        if (SHA_RE.test(ref)) {
+            const tagsResp = await fetch(`${base}/tags?per_page=100`, { headers });
+            if (tagsResp.ok) {
+                const tagList = (await tagsResp.json());
+                tags = tagList.filter((t) => t.commit?.sha === ref).map((t) => t.name);
+            }
+        }
+        return { exists: refResp.ok, tags, archived: !!repo.archived, advisories: [] };
+    }
+    catch {
+        return unknown;
+    }
+};
+function renderSummary(findings) {
+    if (findings.length === 0)
+        return "## Workflow supply-chain audit\n\nNo live drift detected against upstream references.\n";
+    let out = `## Workflow supply-chain audit\n\n${findings.length} finding(s) against live upstream truth:\n\n`;
+    out += "| Action | Ref | Finding | Detail |\n|---|---|---|---|\n";
+    for (const f of findings)
+        out += `| ${f.slug} | ${f.ref} | ${f.kind} | ${f.detail} |\n`;
+    return out;
+}
+/**
+ * Resolve each pinned external reference in the emitted workflows against live
+ * upstreams and report drift.
+ */
+export async function workflowSupplyChainAudit(args) {
+    const resolver = args.resolver ?? defaultActionRefResolver;
+    const mode = args.mode ?? "report";
+    let yamls = args.yamls ?? (args.yaml ? [args.yaml] : []);
+    if (yamls.length === 0) {
+        yamls = await readWorkflowDir(args.workflowsDir ?? ".github/workflows");
+    }
+    const findings = [];
+    const seen = new Set();
+    for (const yaml of yamls) {
+        for (const { slug, ref, comment } of collectAuditRefs(yaml)) {
+            const key = `${slug}@${ref}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const res = await resolver(slug, ref);
+            if (!res.exists) {
+                findings.push({ slug, ref, kind: "impostor", detail: `ref does not exist in ${slug} — possible impostor or deleted ref` });
+                continue;
+            }
+            if (SHA_RE.test(ref) && res.tags.length === 0) {
+                findings.push({ slug, ref, kind: "stale-pin", detail: "pinned SHA is no longer on any tag/release upstream" });
+            }
+            if (res.ambiguousRef) {
+                findings.push({ slug, ref, kind: "ambiguous-ref", detail: "ref resolves as both a tag and a branch upstream (symbolic-ref confusion)" });
+            }
+            if (comment && res.tags.length > 0 && !res.tags.includes(comment)) {
+                findings.push({ slug, ref, kind: "pin-comment-mismatch", detail: `pin comment "${comment}" does not match the SHA's actual tag(s): ${res.tags.join(", ")}` });
+            }
+            if (res.archived) {
+                findings.push({ slug, ref, kind: "archived", detail: `${slug} has been archived upstream since pinning` });
+            }
+            for (const adv of res.advisories) {
+                findings.push({ slug, ref, kind: "advisory", detail: `disclosed advisory ${adv} covers ${slug}` });
+            }
+        }
+    }
+    return { mode, findings, summary: renderSummary(findings) };
+}