@intentius/chant 0.124.12 → 0.124.14

package/dist/gate-decision.js

@@ -0,0 +1,260 @@
+/**
+ * A gate's decision for a plan digest, and the seal check it needs, for a
+ * tool that runs from one bundled file (#3763, decision #3756).
+ *
+ * `@intentius/chant/gate-decision` holds what a tool needs to decide a
+ * plan-bound gate the way chant's own wave gate does (`chant run wave`,
+ * `./op/op-waves-run.ts`) under each approval mode:
+ *
+ * - `ledger`: an approval of this digest on `chant/lifecycle`, newer than the
+ *   gate's newest pending fact ({@link decideGateApproval}).
+ * - `sealed`: the same, counting only an approval whose seal verifies for its
+ *   approver against the signers file at base ({@link gateSignersAt},
+ *   {@link gateSealRefusal}). The seal is checked with node:crypto, so the job
+ *   needs no ssh-keygen.
+ * - `pr-review`: the same as `ledger`, or else the merged pull request's
+ *   approving review, when its head planned this digest
+ *   ({@link reviewApproval}).
+ *
+ * A gate the declaration at base names under `identity.gates` counts only a
+ * sealed approval from its class: {@link identityGateAdmissionAt} reads that
+ * rule from a bare clone at base and judges by `admitApprover`, the function
+ * chant's `gateAdmission` judges by (#3862); pass its `refuses` to
+ * {@link decideGateApproval}.
+ *
+ * With `spend` (#3784), an approval a wave already applied under is spent and
+ * counts for nothing, as terragucci's wave gate has it: the caller hands in
+ * the lines of `_gates/<op>/applied.jsonl` ({@link parseAppliedGateLines}).
+ *
+ * The module reads the ledger lines and the review it is handed; reading
+ * them is the caller's. It imports no TypeScript, esbuild, zod, lint, fold or
+ * codegen module, and none of chant's git ledger code, which
+ * `gate-decision-bundle.test.ts` holds it to. Its rules are chant's own:
+ * `./lifecycle/gate-ledger-select.ts` is what `evaluateGate` decides by, and
+ * `gate-decision.test.ts` decides the same ledgers both ways.
+ */
+import { spawnSync } from "node:child_process";
+import { isPendingGateExpired, latestPendingGate, latestResolutionForPlan, } from "./lifecycle/gate-ledger-select.js";
+import { samePlanDigest } from "./lifecycle/plan-digest.js";
+import { isApprovalSpent } from "./lifecycle/gate-applied.js";
+import { gateSealRefusal } from "./workspace/trust/gate-seal.js";
+import { DEFAULT_SIGNERS_PATH, TRUST_CONFIG_PATH, parseAllowedSigners, trustConfigProblems, } from "./workspace/trust/trust-files.js";
+import { parseJsonText } from "./workspace/jsonc.js";
+import { CORE_CLASSES, admitApprover } from "./workspace/identity-gate-rule.js";
+export { GATE_APPROVAL_SOURCES } from "./op/op-waves.js";
+export { isPendingGateExpired, latestPendingGate, latestResolutionForPlan, latestResolutionSince, } from "./lifecycle/gate-ledger-select.js";
+export { GATE_SEAL_NAMESPACE, gateSealPayload, gateSealRefusal, sshKeyFingerprint, verifySshSignatureWith, } from "./workspace/trust/gate-seal.js";
+export { DEFAULT_SIGNERS_PATH, TRUST_CONFIG_PATH, parseAllowedSigners, trustConfigProblems, } from "./workspace/trust/trust-files.js";
+export { CORE_CLASSES, admitApprover, grantedClasses, } from "./workspace/identity-gate-rule.js";
+export { appliedGateApplies, appliedGatePath, isApprovalSpent, parseAppliedGateLines, } from "./lifecycle/gate-applied.js";
+// ── reading at base ──────────────────────────────────────────────────────
+function git(repo, args) {
+    return spawnSync("git", args, { cwd: repo, encoding: "utf-8" });
+}
+/** A file's text at `base`, or undefined when `base` holds no file at `path`. */
+function showAt(repo, base, path) {
+    const r = git(repo, ["cat-file", "blob", `${base}:${path}`]);
+    return r.status === 0 ? r.stdout : undefined;
+}
+/**
+ * The commit a gate's rule is read at when the default branch applies its
+ * own commit: the first parent of HEAD, the branch as it stood before the
+ * merge, so a merge that adds a signer or drops a gate does not judge its own
+ * apply. A shallow checkout fetches that one commit from `origin`. A root
+ * commit has no parent and is its own base. Throws when it cannot be read.
+ */
+export function baseCommit(repo) {
+    const head = git(repo, ["rev-parse", "--verify", "-q", "HEAD^{commit}"]);
+    const sha = head.stdout.trim();
+    if (head.status !== 0 || !sha)
+        throw new Error(`${repo} has no commit checked out, so the gate cannot be decided`);
+    // The commit object's first `parent` line: a shallow clone keeps it even when it lacks the parent itself.
+    const header = git(repo, ["cat-file", "commit", sha]).stdout.split("\n\n")[0] ?? "";
+    const parent = /^parent ([0-9a-f]{40,64})$/m.exec(header)?.[1];
+    if (!parent)
+        return sha;
+    const has = () => git(repo, ["cat-file", "-e", `${parent}^{commit}`]).status === 0;
+    if (!has())
+        git(repo, ["fetch", "-q", "--depth=1", "origin", parent]);
+    if (!has())
+        throw new Error(`cannot fetch ${parent.slice(0, 12)}, the commit before this one, so the gate cannot be decided`);
+    return parent;
+}
+/** The signers and role grants at `base`, as chant's trust policy reads them. */
+function trustAt(repo, base) {
+    const off = (problems) => ({ signers: { base, signersPath: DEFAULT_SIGNERS_PATH, active: false, signers: [], problems }, roles: {} });
+    const configText = showAt(repo, base, TRUST_CONFIG_PATH);
+    let signersPath = DEFAULT_SIGNERS_PATH;
+    let roles = {};
+    if (configText !== undefined) {
+        let raw;
+        try {
+            raw = JSON.parse(configText);
+        }
+        catch (err) {
+            return off([`${TRUST_CONFIG_PATH} is not JSON: ${err instanceof Error ? err.message : String(err)}`]);
+        }
+        const problems = trustConfigProblems(raw);
+        if (problems.length > 0)
+            return off([`${TRUST_CONFIG_PATH} is invalid: ${problems.join("; ")}`]);
+        signersPath = raw.signers ?? DEFAULT_SIGNERS_PATH;
+        roles = raw.roles ?? {};
+    }
+    const text = showAt(repo, base, signersPath);
+    return { signers: { base, signersPath, active: text !== undefined, signers: text === undefined ? [] : parseAllowedSigners(text).signers, problems: [] }, roles };
+}
+/**
+ * The signers at `base`: the file `.chant/trust.json` names there, else
+ * `.chant/allowed_signers`, read as chant's trust policy reads it. A
+ * trust.json that is not valid (`trustConfigProblems`) turns attestation
+ * off, as it does in chant, so a sealed gate passes nothing. `base` is a
+ * commit the repository holds, such as {@link baseCommit}'s answer.
+ */
+export function gateSignersAt(repo, base) {
+    return trustAt(repo, base).signers;
+}
+/** The declaration at `base`, parsed, or null when there is none. Throws when it cannot be parsed. */
+function declarationAt(repo, base) {
+    for (const file of ["chant.workspace.json", "chant.workspace.jsonc"]) {
+        const text = showAt(repo, base, file);
+        if (text === undefined)
+            continue;
+        const parsed = parseJsonText(text, { jsonc: file.endsWith(".jsonc") });
+        if (!parsed.ok)
+            throw new Error(`${file} at base is not valid JSON (${parsed.message}), so the gate cannot be decided`);
+        return { file, value: parsed.value };
+    }
+    return null;
+}
+function identityGatesOf(declaration) {
+    const gates = declaration?.identity?.gates ?? {};
+    return Object.entries(gates).map(([gate, entry]) => ({ gate, class: typeof entry?.class === "string" ? entry.class : null }));
+}
+/**
+ * The gates `chant.workspace.json` (or `.jsonc`) at `base` names under
+ * `identity.gates`: each counts only a sealed approval, from its class when
+ * it names one. {@link identityGateAdmissionAt} judges an approval by one.
+ * Empty when there is no declaration at base. Throws when the declaration
+ * there cannot be parsed, since the gate cannot be decided.
+ */
+export function identityGatesAt(repo, base) {
+    const declaration = declarationAt(repo, base);
+    return declaration === null ? [] : identityGatesOf(declaration.value);
+}
+/**
+ * The `identity.gates` rule for `gate` at `base`, or null when the
+ * declaration there names none: what chant's `gateAdmission(cwd, gate, base)`
+ * answers, read from a bare clone. An approval counts when its seal verifies
+ * for its approver against the signers at base and, when the gate names a
+ * class, the role grants in `.chant/trust.json` at base put the approver in
+ * it. Both judge with the same function ({@link admitApprover}).
+ *
+ * The classes are the four core ones, then `classes`, the domain classes the
+ * caller read from the pinned packages (`./workspace-principals`), in pin
+ * order. This reader loads no package. A gate whose class is in neither
+ * refuses every approval, and when the declaration at base pins anything the
+ * reason says the pins were not read, since one of them may supply it.
+ * Throws when the declaration at base cannot be parsed.
+ */
+export function identityGateAdmissionAt(repo, base, gate, opts = {}) {
+    const declaration = declarationAt(repo, base);
+    const requirement = declaration === null ? undefined : identityGatesOf(declaration.value).find((g) => g.gate === gate);
+    if (!requirement)
+        return null;
+    const { signers, roles } = trustAt(repo, base);
+    const pins = declaration.value.pins;
+    const rule = {
+        gate,
+        class: requirement.class,
+        signers,
+        roles,
+        classes: [...CORE_CLASSES, ...(opts.classes ?? [])],
+        ...(Array.isArray(pins) && pins.length > 0
+            ? { unknownClass: `is not a core class, and this reader does not load the classes the pinned packages in ${declaration.file} at base supply` }
+            : {}),
+    };
+    return { requirement, refuses: (a) => admitApprover(rule, a) };
+}
+/**
+ * Whether the merged pull request's review approves `digest` (#3684): a
+ * writer other than its author approved its head, and the head planned this
+ * digest (`headDigest`, from the plans `chant run wave --record-plans`
+ * recorded for the head; undefined when none were). Reading the review and
+ * the plans is the caller's; under `pr-review` the caller records the
+ * approval on the ledger when this approves.
+ */
+export function reviewApproval(merged, headDigest, digest) {
+    const seen = { pr: merged.pr, head: merged.head, ...(merged.url ? { url: merged.url } : {}) };
+    if (merged.approvers.length === 0) {
+        const why = merged.refused.length > 0 ? merged.refused.join("; ") : "nobody approved it";
+        return { approved: false, review: { ...seen, reason: `no writer other than its author approved the head of #${merged.pr}: ${why}` } };
+    }
+    if (headDigest === undefined) {
+        return {
+            approved: false,
+            review: { ...seen, approvers: merged.approvers, reason: `no plans are recorded for the head ${merged.head.slice(0, 12)} of #${merged.pr} (its pipeline runs \`chant run wave --record-plans\`)` },
+        };
+    }
+    if (headDigest !== digest) {
+        return {
+            approved: false,
+            review: { ...seen, approvers: merged.approvers, reason: `the plan moved after the review: the head planned ${headDigest}, and the merge plans ${digest}` },
+        };
+    }
+    return { approved: true, review: { ...seen, approvers: merged.approvers } };
+}
+const EPOCH = new Date(0).toISOString();
+/**
+ * Decide a plan-bound gate against its ledger lines, as chant's wave gate
+ * does: an approval counts when it names this gate and digest (and
+ * environment, when set), is newer than the gate's newest pending fact, and
+ * passes the mode's rule: any under `ledger` and `pr-review`, a verified seal
+ * under `sealed`. With none, `pr-review` takes the review's answer. Writes
+ * nothing: recording a pending fact, or the review's approval, is the
+ * caller's.
+ */
+export function decideGateApproval(input) {
+    const { gate, planDigest, environment: env } = input;
+    const mode = input.mode ?? "ledger";
+    const pending = env === undefined ? input.ledger.pending : input.ledger.pending.filter((p) => p.environment === env);
+    const mine = (env === undefined ? input.ledger.resolutions : input.ledger.resolutions.filter((r) => r.environment === undefined || r.environment === env)).filter((r) => r.gate === gate);
+    const sealed = mode === "sealed";
+    const noSigners = { base: null, signersPath: DEFAULT_SIGNERS_PATH, active: false, signers: [], problems: ["no signers were read for this sealed gate"] };
+    const why = (r) => input.refuses?.(r) ?? (sealed ? gateSealRefusal(input.signers ?? noSigners, r) : null);
+    const standingFact = latestPendingGate(pending, gate);
+    const since = standingFact?.timestamp ?? EPOCH;
+    const counted = [];
+    const uncounted = [];
+    let spent;
+    for (const r of mine) {
+        if (input.spend && isApprovalSpent(input.ledger.applied ?? [], r)) {
+            if (new Date(r.timestamp).getTime() >= new Date(since).getTime() && (!spent || new Date(r.timestamp).getTime() >= new Date(spent.timestamp).getTime()))
+                spent = r;
+            continue;
+        }
+        const reason = why(r);
+        if (reason === null)
+            counted.push(r);
+        else if (samePlanDigest(r.planDigest, planDigest) && new Date(r.timestamp).getTime() >= new Date(since).getTime())
+            uncounted.push({ resolution: r, reason });
+    }
+    const found = latestResolutionForPlan(counted, gate, since, planDigest);
+    if (found.resolution)
+        return { status: "approved", via: "ledger", resolution: found.resolution };
+    const reviewSpent = input.spend === true && input.review?.approved === true &&
+        isApprovalSpent(input.ledger.applied ?? [], { gate, planDigest, review: { ...(input.review.review.head ? { head: input.review.review.head } : {}) } });
+    if (mode === "pr-review" && input.review?.approved && !reviewSpent)
+        return { status: "approved", via: "pr-review", review: input.review.review };
+    const now = input.now ?? new Date().toISOString();
+    const standing = standingFact && !isPendingGateExpired(standingFact, now) && samePlanDigest(standingFact.planDigest, planDigest) ? standingFact : undefined;
+    return {
+        status: "waiting",
+        ...(standing ? { standing } : {}),
+        ...(found.mismatched ? { mismatched: found.mismatched } : {}),
+        uncounted: uncounted.sort((a, b) => new Date(a.resolution.timestamp).getTime() - new Date(b.resolution.timestamp).getTime()),
+        ...(mode === "pr-review" && input.review
+            ? { review: reviewSpent ? { ...input.review.review, reason: `a wave already applied this digest under the review of ${input.review.review.head?.slice(0, 12) ?? "its head"}, so the review is spent` } : input.review.review }
+            : {}),
+        ...(spent ? { spent } : {}),
+    };
+}

package/dist/gate-resume-run.js

@@ -0,0 +1,154 @@
+/**
+ * Resume the job that waits at a gate (#3683), bundle-safe (#3854).
+ *
+ * A CI job that reaches a gate nobody approved records a pending fact on
+ * `chant/lifecycle` and exits 3. Nothing re-runs it when the approval lands,
+ * because a push to the ledger branch starts no pipeline. This module closes
+ * that loop through the forge's API.
+ *
+ * When the job runs in CI, the pending fact it records carries a
+ * {@link GateRunLocator}, read from the job's environment by
+ * {@link resolveGateRunLocator}: which forge, the API base, the repository,
+ * the run, and what the forge needs to start it again. After an approval,
+ * {@link resumeGateRun} starts it again:
+ *
+ * | Forge | Call | Token |
+ * |---|---|---|
+ * | GitHub | `POST /repos/{repo}/actions/runs/{run}/rerun-failed-jobs` | `actions: write` (the job's `GITHUB_TOKEN` with that permission, or a fine-grained token with Actions read and write) |
+ * | GitLab | `POST /projects/{id}/jobs/{job}/retry` | a project or personal access token with the `api` scope and the Developer role; `CI_JOB_TOKEN` cannot retry jobs |
+ * | Forgejo | `POST /repos/{repo}/actions/workflows/{file}/dispatches` on the run's branch | a token with the `write:repository` scope; Forgejo has no API to re-run a run, so it starts a new run of the workflow |
+ *
+ * GitHub re-runs the failed job and the jobs that need it, at the same
+ * commit. GitLab retries the job, and the jobs it skipped run after it. A
+ * Forgejo dispatch runs the whole workflow again at the branch's head, so the
+ * jobs before the gate run again too; they must be safe to repeat (a wave
+ * whose runs already applied plans nothing and applies nothing new).
+ *
+ * Resuming approves nothing. The resumed job decides the gate again from the
+ * ledger, so resuming a run whose approval does not count only makes it wait
+ * again. {@link resumeGateRun} skips a run that is still going, that ended
+ * well, or that was already resumed (a later GitHub attempt, a newer GitLab
+ * job of the same name, a newer Forgejo run of the workflow), so a scheduled
+ * resume job can call it every few minutes without starting a run twice.
+ *
+ * This module imports no workspace, ledger, schema or git code, so a product
+ * that ships one bundled file (terragucci) can import it as
+ * `@intentius/chant/gate-resume-run` and resume a job in process. Which
+ * approval answers a pending fact is `./op/gate-resume.ts`'s
+ * `resolutionAnswering`, which reads the gate's quorum rules and does pull the
+ * workspace in; that module re-exports everything here.
+ */
+import { ForgeApiError } from "./pr-forge.js";
+export { isGateRunLocator, resolveGateRunLocator } from "./op/gate-run-locator.js";
+const trimSlash = (s) => s.replace(/\/+$/, "");
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+function client(base, headers, fetchImpl) {
+    return async (method, path, body) => {
+        const url = `${trimSlash(base)}${path}`;
+        const res = await fetchImpl(url, {
+            method,
+            headers: { ...headers, ...(body !== undefined ? { "Content-Type": "application/json" } : {}) },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        const text = await res.text();
+        if (!res.ok)
+            throw new ForgeApiError(method, url, res.status, text);
+        if (!text)
+            return null;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    };
+}
+/**
+ * Start the job a pending fact's locator names again, or say why not. Throws
+ * {@link ForgeApiError} when the forge refuses a call, such as a token
+ * without the access the table in the module doc lists.
+ */
+export async function resumeGateRun(loc, opts) {
+    const fetchImpl = opts.fetch ?? globalThis.fetch;
+    const url = loc.url ? { url: loc.url } : {};
+    const skip = (reason) => ({ status: "skipped", forge: loc.forge, reason, ...url });
+    const wouldResume = (how) => ({ status: "would-resume", forge: loc.forge, how: `would ${how}`, ...url });
+    if (loc.forge === "github") {
+        const call = client(loc.api, { Authorization: `Bearer ${opts.token}`, Accept: "application/vnd.github+json" }, fetchImpl);
+        const path = `/repos/${loc.repo}/actions/runs/${loc.run}`;
+        const run = await call("GET", path);
+        if (!isObject(run))
+            throw new Error(`GET ${path} returned no run`);
+        if (run.status !== "completed")
+            return skip(`run ${loc.run} is ${String(run.status)}, not finished`);
+        const attempt = typeof run.run_attempt === "number" ? run.run_attempt : undefined;
+        if (loc.attempt !== undefined && attempt !== undefined && attempt > loc.attempt) {
+            return skip(`run ${loc.run} was already re-run (attempt ${attempt}; attempt ${loc.attempt} waited)`);
+        }
+        if (run.conclusion === "success")
+            return skip(`run ${loc.run} succeeded`);
+        if (opts.dryRun)
+            return wouldResume(`re-run the failed jobs of run ${loc.run}`);
+        await call("POST", `${path}/rerun-failed-jobs`, {});
+        return { status: "resumed", forge: "github", how: `re-ran the failed jobs of run ${loc.run}`, ...url };
+    }
+    if (loc.forge === "gitlab") {
+        const call = client(loc.api, { "PRIVATE-TOKEN": opts.token }, fetchImpl);
+        const project = `/projects/${encodeURIComponent(decodeURIComponent(loc.repo))}`;
+        const job = await call("GET", `${project}/jobs/${loc.job}`);
+        if (!isObject(job))
+            throw new Error(`GET ${project}/jobs/${loc.job} returned no job`);
+        const status = String(job.status);
+        if (status === "success")
+            return skip(`job ${loc.job} succeeded`);
+        if (!["failed", "canceled", "skipped"].includes(status))
+            return skip(`job ${loc.job} is ${status}, not finished`);
+        const name = loc.jobName ?? (typeof job.name === "string" ? job.name : undefined);
+        if (name) {
+            // The pipeline's jobs list leaves retried jobs out, so the job of this name is its newest try.
+            const jobs = await call("GET", `${project}/pipelines/${loc.run}/jobs?per_page=100`);
+            const newest = Array.isArray(jobs) ? jobs.find((j) => isObject(j) && j.name === name) : undefined;
+            if (isObject(newest) && String(newest.id) !== String(loc.job)) {
+                return skip(`job ${loc.job} (${name}) was already retried as job ${String(newest.id)}`);
+            }
+        }
+        if (opts.dryRun)
+            return wouldResume(`retry job ${loc.job}`);
+        const retried = await call("POST", `${project}/jobs/${loc.job}/retry`);
+        const id = isObject(retried) && retried.id !== undefined ? ` as job ${String(retried.id)}` : "";
+        return { status: "resumed", forge: "gitlab", how: `retried job ${loc.job}${id}`, ...url };
+    }
+    const call = client(loc.api, { Authorization: `token ${opts.token}`, Accept: "application/json" }, fetchImpl);
+    const repo = `/repos/${loc.repo}`;
+    const run = await call("GET", `${repo}/actions/runs/${loc.run}`);
+    if (!isObject(run))
+        throw new Error(`GET ${repo}/actions/runs/${loc.run} returned no run`);
+    const status = String(run.status);
+    if (status === "success")
+        return skip(`run ${loc.run} succeeded`);
+    if (["waiting", "running", "blocked", "unknown"].includes(status))
+        return skip(`run ${loc.run} is ${status}, not finished`);
+    const listed = await call("GET", `${repo}/actions/runs?workflow_id=${encodeURIComponent(loc.workflow)}&limit=50`);
+    const runs = isObject(listed) && Array.isArray(listed.workflow_runs) ? listed.workflow_runs : Array.isArray(listed) ? listed : [];
+    // Forgejo reports `created` in whole seconds.
+    const since = opts.since ? Math.floor(new Date(opts.since).getTime() / 1000) * 1000 : undefined;
+    const later = runs.find((r) => isObject(r) && Number(r.id) > Number(loc.run) &&
+        (r.prettyref === undefined || r.prettyref === loc.ref) &&
+        (since === undefined || (typeof r.created === "string" && new Date(r.created).getTime() >= since)));
+    if (isObject(later))
+        return skip(`run ${String(later.id)} of ${loc.workflow} started after the approval`);
+    if (opts.dryRun)
+        return wouldResume(`dispatch ${loc.workflow} on ${loc.ref}`);
+    await call("POST", `${repo}/actions/workflows/${encodeURIComponent(loc.workflow)}/dispatches`, { ref: loc.ref });
+    return { status: "resumed", forge: "forgejo", how: `dispatched ${loc.workflow} on ${loc.ref}`, ...url };
+}
+/**
+ * The token a resume uses: `CHANT_FORGE_TOKEN`, else the forge's own
+ * (`GITHUB_TOKEN` or `GH_TOKEN` on GitHub and Forgejo, `GITLAB_TOKEN` on
+ * GitLab), the same order the pull-request loop reads (`../pr-forge.ts`).
+ */
+export function resumeTokenFromEnv(forge, env = process.env) {
+    if (env.CHANT_FORGE_TOKEN)
+        return env.CHANT_FORGE_TOKEN;
+    return forge === "gitlab" ? env.GITLAB_TOKEN : env.GITHUB_TOKEN ?? env.GH_TOKEN;
+}

package/dist/gated-waves.js

@@ -0,0 +1,165 @@
+/**
+ * Gated waves (#3049): one change rolled out across many roots, a wave at a
+ * time, each wave behind its own gate bound to that wave's set digest.
+ *
+ * `chant components fan-out --wave-gate` is the runner. This module holds the
+ * parts that need no runner: how a set of roots is cut into waves, what a
+ * wave's digest is, what its gate is called, and what the attempt record says
+ * about each wave. They are kept apart from the runner because terragucci
+ * calls them from its CI stages as one bundled file with no TypeScript
+ * toolchain (#3421). Everything here imports `./change-set` and nothing else,
+ * and `gated-waves-bundle.test.ts` holds that.
+ *
+ * ## The set digest
+ *
+ * A wave's digest is {@link changeSetDigest} over its members' `{ member,
+ * planDigest }` pairs, the function #3181's change-set document uses. A
+ * terraform-family member is named after its root, so this is the issue's
+ * `jcs1-sha256` over sorted `{ root, planDigest }`, and a wave's digest equals
+ * the change-set digest of the wave's members. Each member's plan digest is
+ * the one a gate on that root alone binds (`terraformPlanDigest`, #2300), so a
+ * one-root wave and a one-root `TerraformApplyOp` approve the same value.
+ *
+ * ## Why a wave is planned when it is reached
+ *
+ * A later wave planned up front reads outputs that do not exist yet. Planned
+ * after the wave before it applied, its digest describes the real upstream
+ * values, which is what an approver of that wave is shown.
+ */
+import { changeSetDigest } from "./change-set.js";
+/** Thrown when a canary names something that is not in the set being planned. */
+export class UnknownCanaryError extends Error {
+    constructor(canary, known) {
+        super(`canary names "${canary}", which is not in this set (known: ${known.join(", ") || "none"})`);
+        this.canary = canary;
+        this.name = "UnknownCanaryError";
+    }
+}
+/** Thrown when the nodes being layered depend on each other in a cycle. */
+export class WaveCycleError extends Error {
+    constructor(members) {
+        super(`dependency cycle among: ${members.join(", ")}`);
+        this.members = members;
+        this.name = "WaveCycleError";
+    }
+}
+/**
+ * Cut `nodes` into ordered waves: each node lands after every node it reads
+ * from, and each wave is sorted by name so the same graph always produces the
+ * same waves. With a canary list, those nodes are wave 1.
+ *
+ * A dependency on a name outside `nodes` does not hold a node back. That is
+ * the subset case: the dependency already applied, or is not changing.
+ */
+export function layerWaves(nodes, options = {}) {
+    const names = new Set(nodes.map((n) => n.name));
+    const known = new Set([...names, ...(options.known ?? [])]);
+    for (const canary of options.canary ?? []) {
+        if (!known.has(canary))
+            throw new UnknownCanaryError(canary, [...known].sort());
+    }
+    const canaries = [...new Set((options.canary ?? []).filter((c) => names.has(c)))].sort();
+    const waves = canaries.length > 0 ? [canaries] : [];
+    const remaining = new Set([...names].filter((n) => !canaries.includes(n)));
+    const deps = new Map(nodes.map((n) => [n.name, (n.dependsOn ?? []).filter((d) => remaining.has(d))]));
+    while (remaining.size > 0) {
+        const wave = [...remaining].filter((n) => deps.get(n).every((d) => !remaining.has(d))).sort();
+        if (wave.length === 0)
+            throw new WaveCycleError([...remaining].sort());
+        for (const n of wave)
+            remaining.delete(n);
+        waves.push(wave);
+    }
+    return waves;
+}
+/** Thrown when a wave's members include a provisional plan, which no gate may bind. */
+export class ProvisionalWaveMemberError extends Error {
+    constructor(members) {
+        super(`a wave cannot be gated on a provisional plan: ${members.join(", ")} planned before what it reads applied. ` +
+            `Plan it again in its own wave, after its upstream applied`);
+        this.members = members;
+        this.name = "ProvisionalWaveMemberError";
+    }
+}
+/**
+ * A wave's set digest: {@link changeSetDigest} over its members. Order does
+ * not matter, and it moves whenever one member's plan digest does. A wave
+ * naming one member twice has no digest and is refused, and so is a wave
+ * holding a provisional plan (#3416): a gate bound to it would approve
+ * values nobody has yet.
+ */
+export function waveSetDigest(members) {
+    const provisional = members.filter((m) => m.provisional === true).map((m) => m.member);
+    if (provisional.length > 0)
+        throw new ProvisionalWaveMemberError([...new Set(provisional)].sort());
+    return changeSetDigest(members);
+}
+/**
+ * The gate a wave waits on: `<gate>-wave-<n>`, under the fan-out's op.
+ *
+ * One gate name per wave keeps each wave's approvals apart. With one name
+ * shared by every wave, wave 2 would find wave 1's approval and report it as
+ * an approval of another plan, which is true and useless. Wave numbers come
+ * from the derivation, not from what is left to run, so wave 3 stays wave 3
+ * on a resumed attempt and its approval still applies.
+ */
+export function waveGateName(gate, wave) {
+    return `${gate}-wave-${wave}`;
+}
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const strings = (value) => Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+/**
+ * Read the `waves` array of an attempt record, dropping anything malformed.
+ * A record written before #3049 has none, which reads as no waves.
+ */
+export function readWaveRecords(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const raw of value) {
+        if (!isObject(raw))
+            continue;
+        const { wave, op, gate, digest, status } = raw;
+        if (typeof wave !== "number" || typeof op !== "string" || typeof gate !== "string" || typeof digest !== "string")
+            continue;
+        if (status !== "gated" && status !== "applied" && status !== "failed")
+            continue;
+        const members = Array.isArray(raw.members)
+            ? raw.members.filter((m) => isObject(m) && typeof m.member === "string" && typeof m.planDigest === "string")
+            : [];
+        const failed = Array.isArray(raw.failed)
+            ? raw.failed
+                .filter((f) => isObject(f) && typeof f.component === "string")
+                .map((f) => ({ component: f.component, ...(typeof f.error === "string" ? { error: f.error } : {}) }))
+            : [];
+        out.push({
+            wave,
+            op,
+            gate,
+            components: strings(raw.components),
+            digest,
+            members: members.map((m) => ({ member: m.member, planDigest: m.planDigest })),
+            status,
+            ...(typeof raw.approvedBy === "string" ? { approvedBy: raw.approvedBy } : {}),
+            ...(typeof raw.approved === "string" ? { approved: raw.approved } : {}),
+            ...(failed.length > 0 ? { failed } : {}),
+        });
+    }
+    return out;
+}
+/** Put `record` in `records` in place of any earlier record for the same wave, sorted by wave. */
+export function withWaveRecord(records, record) {
+    return [...records.filter((r) => r.wave !== record.wave), record].sort((a, b) => a.wave - b.wave);
+}
+/**
+ * The refusal for a wave whose set changed after it was approved: the digest
+ * that was approved, the one planned now, and that nothing in the wave ran.
+ * On a sealed gate the approve hint ends in `--sign`.
+ */
+export function describeChangedWave(record, 
+/** True when the gate is sealed (`identity.gates`): an approval without `--sign` doesn't count, so the hint says to sign. */
+sealed = false) {
+    return (`wave ${record.wave} changed after it was approved, so nothing in it was applied. ` +
+        `approved: ${record.approved ?? "(none)"}; planned now: ${record.digest}. ` +
+        `Read the new plan, then approve it: chant approve ${record.op} ${record.gate} --plan ${record.digest}${sealed ? " --sign" : ""}`);
+}

package/dist/governance.js

@@ -0,0 +1,43 @@
+/**
+ * Governance verb vocabulary .
+ *
+ * `resourceType` on a change-set entry is a free provider-specific string
+ * ("team", "branch-protection", "protected-tag", …) chosen per cycle. That is
+ * right for display but useless for reading two providers' plans as one
+ * grammar. The verb is the cross-provider category a cycle reconciles;
+ * provider-specific cycle names stay for display.
+ *
+ * SCM and cloud cycles stamp the same verbs, so a GitHub plan and an AWS plan
+ * group the same way:
+ *
+ * - `org-unit` — the containers and their settings: GitHub org/repo settings,
+ *   GitLab group/project/instance settings, cloud OUs/folders/accounts.
+ * - `policy-guardrail` — rules constraining what may happen: branch
+ *   protections, rulesets, push rules, MR approvals, security features,
+ *   dependency hygiene, SCPs, Org Policies.
+ * - `membership` — who belongs, directly or via teams: org members, team
+ *   membership, group members.
+ * - `identity-assignment` — non-person and delegated access: tokens, deploy
+ *   keys, service credentials, SSO/IAM assignments. `membership` is people
+ *   in containers; this is everything else that can act.
+ * - `audit-sink` — where events and evidence flow: webhooks, integrations,
+ *   CloudTrail/audit-log sinks.
+ * - `secret-material` — secrets and CI variables the platform stores.
+ *
+ * A cycle has exactly one verb. When a cycle plausibly spans two (GitHub
+ * `environments` carries both reviewer gates and secrets), stamp the verb of
+ * the cycle's primary object — the thing whose create/delete the cycle owns —
+ * not of fields it also happens to write.
+ */
+/** Every verb, for exhaustiveness checks ("does each cycle stamp one?"). */
+export const GOVERNANCE_VERBS = [
+    "org-unit",
+    "policy-guardrail",
+    "membership",
+    "identity-assignment",
+    "audit-sink",
+    "secret-material",
+];
+export function isGovernanceVerb(v) {
+    return typeof v === "string" && GOVERNANCE_VERBS.includes(v);
+}