@intentius/chant 0.124.27 → 0.124.29

package/dist/components/release-gate.js

@@ -0,0 +1,288 @@
+/**
+ * The release gate (#4045, ws-104 questions 2 and 6): the gate `chant
+ * components promote --release` passes for an environment.
+ *
+ * ## What it binds
+ *
+ * A promote under a release plans the release's change set for the
+ * environment it deploys to ({@link planReleaseChangeSet}), stores it on
+ * `chant/lifecycle` under its digest (`../lifecycle/gate-change-set.ts`), and
+ * decides every gate its components reach against three values:
+ *
+ * - the change-set document's `digest`, in `planDigest`;
+ * - the release, in `releaseDigest`;
+ * - the environment, in `environment`.
+ *
+ * An approval counts only when all three match (`evaluateGate` in
+ * `../op/gate.ts`). The document itself names the release and the environment
+ * it was planned for, and both are part of its digest, so a stored document
+ * names the one release its gate bound and two releases never share a digest.
+ *
+ * Every gate a promote under a release reaches is recorded in one ledger,
+ * {@link RELEASE_GATE_OP}, rather than in each component's. The gate name a
+ * composition authors is kept, so components that share a gate name share one
+ * gate per environment, and one approval of the release's change set passes
+ * each of them. A promote of one component (`--component`) plans that
+ * component's subset, which has its own digest and needs its own approval.
+ *
+ * ## Empty change sets
+ *
+ * When the change set changes nothing ({@link isEmptyChangeSet}), the
+ * promote writes an `empty: true` resolution for each gate, with the actor
+ * running it in `resolvedBy` ({@link emptyResolution}). A gate counts it only
+ * after it reads the stored document back and finds it empty
+ * ({@link emptyVerifier}). Quorum and signing rules don't apply to it.
+ *
+ * ## The members
+ *
+ * A component with a step whose capability can plan (`terraform-apply`) is
+ * planned by that capability, as a pull request's plan is. A plan that
+ * returns no change-set part is a hole, since nothing says what it changes.
+ *
+ * Any other component is a `chant` member compared with what the
+ * environment runs now: its latest deploy record and the release that record
+ * names. The artifact digest, each template the release's target records for
+ * the component, and the target's parameters are compared, and each one that
+ * differs is an attribute of one `update` entry (a `create` when the
+ * environment has no deploy of the component). When they are all equal the
+ * member has no entries. When the environment's deploy names no release, or
+ * the release it names can't be read, the member has a hole: nothing says
+ * what the environment runs, so the change can't be shown empty. So does a
+ * component a promote, rollback or redeploy left failed or gated with nothing
+ * recorded since (#4035): its record names what ran before that run.
+ */
+import { deployContext, resolveComponentGraph, resolveStepInput } from "./driver.js";
+import { componentPlanDigest } from "./gate-plan.js";
+import { gateName, RELEASE_GATE_OP } from "../op/gate-name.js";
+import { capabilitySteps, planContext, readComponentOutputs } from "./wave-plan.js";
+import { composeChangeSet, isEmptyChangeSet, } from "../change-set.js";
+/** The gate ledger every release gate is recorded in: `_gates/release.jsonl`, under the member's prefix. */
+export { RELEASE_GATE_OP };
+/** The address and type a `chant` member's one entry has. */
+export const RELEASE_COMPONENT_ENTRY_TYPE = "chant:component";
+function isGate(step) {
+    return step.kind === "gate";
+}
+function isPhase(step) {
+    return typeof step.phase === "string" && Array.isArray(step.steps);
+}
+/** The name of every gate the compositions declare, nested phases included, sorted and distinct. */
+export function gateNamesOf(components) {
+    const names = new Set();
+    const walk = (steps) => {
+        for (const step of steps) {
+            if (isPhase(step))
+                walk(step.steps);
+            else if (isGate(step))
+                names.add(gateName(step));
+        }
+    };
+    for (const c of components)
+        for (const phase of c.deploy)
+            walk(phase.steps);
+    return [...names].sort();
+}
+const byString = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/** One attribute per key whose value differs between `before` and `after`, sorted by path. */
+function differing(before, after, prefix) {
+    const out = [];
+    for (const key of [...new Set([...before.keys(), ...after.keys()])].sort(byString)) {
+        const was = before.get(key);
+        const now = after.get(key);
+        if (was === now)
+            continue;
+        out.push({ path: `${prefix}${key}`, ...(was !== undefined ? { before: was } : {}), ...(now !== undefined ? { after: now } : {}) });
+    }
+    return out;
+}
+/** What one target says a component deploys: its templates by path, and the target's parameters by name. */
+function deployedInputs(release, env, component) {
+    const target = release.targets.find((t) => t.env === env);
+    if (!target)
+        return null;
+    return {
+        templates: new Map(target.templates.filter((t) => t.component === component).map((t) => [t.path, t.digest])),
+        params: new Map(target.params.map((p) => [p.name, JSON.stringify(p.value)])),
+    };
+}
+/**
+ * A component no capability plans, as a `chant` member: what the release
+ * deploys compared with what the environment runs now. See the module doc.
+ */
+export function chantComponentPart(input) {
+    const { component, release, env, digest, current } = input;
+    const name = component.name;
+    const member = {
+        member: name,
+        lexicon: "chant",
+        planner: "chant",
+        status: "planned",
+        planDigest: componentPlanDigest({ environment: env, component, release: digest }),
+        holes: [],
+    };
+    const want = deployedInputs(release, env, name);
+    if (!want) {
+        member.holes.push({ address: name, type: RELEASE_COMPONENT_ENTRY_TYPE, reason: `release ${release.releaseDigest} has no target for "${env}"` });
+        return { member, entries: [] };
+    }
+    const entry = (action, attributes) => ({
+        member,
+        entries: [
+            {
+                member: name,
+                lexicon: "chant",
+                planner: "chant",
+                address: name,
+                type: RELEASE_COMPONENT_ENTRY_TYPE,
+                name,
+                action,
+                ...(action === "update" ? { disruption: "unknown" } : {}),
+                scope: env,
+                attributes,
+            },
+        ],
+    });
+    if (input.unsettled !== undefined) {
+        member.holes.push({ address: name, type: RELEASE_COMPONENT_ENTRY_TYPE, reason: input.unsettled });
+        return { member, entries: [] };
+    }
+    if (!current) {
+        return entry("create", [
+            { path: "artifact", after: digest },
+            ...differing(new Map(), want.templates, "template:"),
+            ...differing(new Map(), want.params, "param:"),
+        ]);
+    }
+    const named = current.record.releaseDigest;
+    if (named === undefined) {
+        member.holes.push({
+            address: name,
+            type: RELEASE_COMPONENT_ENTRY_TYPE,
+            reason: `the "${env}" deploy of ${name} (run ${current.record.runId}) names no release, so what it runs can't be compared with this release`,
+        });
+        return { member, entries: [] };
+    }
+    const have = current.release ? deployedInputs(current.release, env, name) : null;
+    if (!have) {
+        member.holes.push({
+            address: name,
+            type: RELEASE_COMPONENT_ENTRY_TYPE,
+            reason: current.release
+                ? `release ${named}, which the "${env}" deploy of ${name} names, has no target for "${env}"`
+                : `release ${named}, which the "${env}" deploy of ${name} names, can't be read from chant/lifecycle`,
+        });
+        return { member, entries: [] };
+    }
+    const attributes = [
+        ...differing(new Map([["", current.record.digest]]), new Map([["", digest]]), "artifact"),
+        ...differing(have.templates, want.templates, "template:"),
+        ...differing(have.params, want.params, "param:"),
+    ];
+    return attributes.length === 0 ? { member, entries: [] } : entry("update", attributes);
+}
+/**
+ * Plan the release's change set for `env`: one part per promoted component
+ * (or per member its planning capability names), composed into a document
+ * that names the release and the environment. Never throws for a component
+ * that fails to plan: it becomes a failed member.
+ */
+export async function planReleaseChangeSet(input) {
+    const { release, env, registry } = input;
+    const components = [...input.components];
+    const byName = new Map(components.map((c) => [c.name, c]));
+    const outputs = { ...(input.seededOutputs ?? {}) };
+    const read = new Set(Object.keys(outputs));
+    const parts = [];
+    const { order } = resolveComponentGraph(components.map((c) => ({ ...c, dependsOn: (c.dependsOn ?? []).filter((d) => byName.has(d)) })));
+    for (const name of order) {
+        const component = byName.get(name);
+        const digest = input.digests.get(name) ?? "";
+        const plannable = capabilitySteps(component.deploy).filter((s) => registry.has(s.kind) && registry.resolve(s.kind).plan !== undefined);
+        if (plannable.length === 0) {
+            parts.push(chantComponentPart({ component, release, env, digest, current: input.current.get(name), unsettled: input.unsettled?.get(name) }));
+            continue;
+        }
+        const ctx = deployContext({ env }, name);
+        try {
+            for (const dep of component.dependsOn ?? []) {
+                if (read.has(dep) || !byName.has(dep))
+                    continue;
+                read.add(dep);
+                const found = await readComponentOutputs(byName.get(dep), registry, deployContext({ env }, dep), outputs);
+                if (found)
+                    outputs[dep] = found;
+            }
+            for (const step of plannable) {
+                const { kind, ...rest } = step;
+                const planned = await registry.resolve(kind).plan(planContext(ctx, rest, outputs), resolveStepInput(rest, {}, outputs));
+                parts.push(planned.changeSet ?? {
+                    member: {
+                        member: planned.member,
+                        lexicon: "chant",
+                        planner: "chant",
+                        status: "planned",
+                        planDigest: planned.planDigest,
+                        holes: [{ address: planned.member, reason: `its ${kind} plan describes no changes, so what it changes is unknown` }],
+                    },
+                    entries: [],
+                });
+            }
+        }
+        catch (err) {
+            parts.push({
+                member: {
+                    member: name,
+                    lexicon: "chant",
+                    planner: "chant",
+                    status: "failed",
+                    error: err instanceof Error ? err.message : String(err),
+                    planDigest: null,
+                    holes: [],
+                },
+                entries: [],
+            });
+        }
+    }
+    return composeChangeSet(parts, {
+        ...(input.chant !== undefined ? { chant: input.chant } : {}),
+        planned: { releaseDigest: release.releaseDigest, environment: env },
+    });
+}
+/** The members a release gate refuses: provisional ones, which no approval of the document covers (`change-set.mdx`). */
+export function provisionalMembers(doc) {
+    return doc.members.filter((m) => m.provisional === true).map((m) => m.member);
+}
+/**
+ * The `verifyEmpty` a release gate decides with: the document stored under
+ * the digest, read back and checked against its digest by `read`, is the
+ * one planned for this release and environment, and it is empty.
+ */
+export function emptyVerifier(read, planned) {
+    return async (digest) => {
+        const stored = await read(digest);
+        return (stored.status === "found" &&
+            stored.document.releaseDigest === planned.releaseDigest &&
+            stored.document.environment === planned.environment &&
+            isEmptyChangeSet(stored.document));
+    };
+}
+/** The `empty: true` resolution a promote writes for one release gate over an empty change set. */
+export function emptyResolution(input) {
+    const { doc } = input;
+    if (doc.releaseDigest === undefined || doc.environment === undefined) {
+        throw new Error(`change set ${doc.digest} names no release and environment, so no release gate can pass on it`);
+    }
+    return {
+        op: RELEASE_GATE_OP,
+        gate: input.gate,
+        resolvedBy: input.actor,
+        timestamp: input.timestamp,
+        note: `the change set of release ${doc.releaseDigest} for "${doc.environment}" is empty`,
+        planDigest: doc.digest,
+        environment: doc.environment,
+        releaseDigest: doc.releaseDigest,
+        empty: true,
+        ...(input.gitSha ? { gitSha: input.gitSha } : {}),
+        ...(input.runId ? { runId: input.runId } : {}),
+    };
+}

package/dist/components/release-promote.d.ts

@@ -0,0 +1,96 @@
+/**
+ * A promote under a release (#4026, ws-104 question 5): the deploy reads the
+ * templates the release recorded for the target environment, not the ones in
+ * the promoting checkout.
+ *
+ * Each template a promoted component's deploy names ({@link templateRefs}) has
+ * to be one the release's target records for that component. Its bytes are
+ * read from `_releases/templates/` on `chant/lifecycle` and checked against
+ * the target's digest, the way a promote checks the publish digest, and a
+ * mismatch refuses the promote before anything runs. The bytes are written
+ * under `.chant/release-templates/<digest>/` in the member's directory and the
+ * step reads them from there. The path is relative and fixed by the digest,
+ * so a gate approval bound to the promote's plan still matches on a re-run.
+ */
+import type { DriverComponent } from "./driver.js";
+import type { Release, ReleaseTarget } from "../lifecycle/release-store.js";
+import type { ReleaseRecord } from "../lifecycle/release-ledger.js";
+import type { BuildArchiveManifest } from "./verbs/build-archive.js";
+/** Where a promote under a release writes the recorded templates, relative to the member's directory. */
+export declare const RELEASE_TEMPLATES_DIR = ".chant/release-templates";
+/** A template ready to write: where, and its bytes. */
+export interface PinnedTemplate {
+    /** Relative to the member's directory. */
+    path: string;
+    content: string;
+}
+/** The release's target for `env`, or an error naming the environments it has. */
+export declare function targetFor(release: Release, env: string): {
+    target: ReleaseTarget;
+} | {
+    error: string;
+};
+/** Whether a release is of a project with no components (#4046): no artifact, and every template it records has `component: null`. */
+export declare function isImplicitRelease(release: Release): boolean;
+/**
+ * Point every template `components` read at the target's recorded bytes.
+ * Returns the rewritten compositions and the files to write, or the reasons
+ * the promote is refused: a template the target does not record, one whose
+ * bytes are missing, or one whose bytes do not hash to the target's digest.
+ */
+export declare function pinReleaseTemplates(components: readonly DriverComponent[], release: Release, target: ReleaseTarget, readTemplate: (digest: string) => Promise<string | null>): Promise<{
+    components: DriverComponent[];
+    files: PinnedTemplate[];
+} | {
+    errors: string[];
+}>;
+/**
+ * The files a release's target records, read back by digest and checked, for
+ * `chant release export` (#4046). A project with no components has no deploy
+ * step for a promote to point at the recorded bytes, so its deploy (an Op such
+ * as `chant run deploy`, or a CI job) reads the files this writes instead of
+ * building them again. Each path is the one the build wrote, relative to the
+ * member's directory; a template whose bytes are missing or don't hash to the
+ * target's digest is refused, as {@link pinReleaseTemplates} refuses one.
+ */
+export declare function targetFiles(release: Release, target: ReleaseTarget, readTemplate: (digest: string) => Promise<string | null>): Promise<{
+    files: PinnedTemplate[];
+} | {
+    errors: string[];
+}>;
+/** Write the pinned templates under `dir`, the member's directory. */
+export declare function writePinnedTemplates(dir: string, files: readonly PinnedTemplate[]): void;
+/**
+ * Remove the templates {@link writePinnedTemplates} wrote once the promote is
+ * done, and {@link RELEASE_TEMPLATES_DIR} with them when nothing else is in
+ * it, so a promote leaves the checkout as it found it. A re-run writes them
+ * again from the release.
+ */
+export declare function removePinnedTemplates(dir: string, files: readonly PinnedTemplate[]): void;
+/**
+ * Whether the artifact a promote deploys under a release is one the release
+ * built (#4045, the rule #4026 left open). The release records build digests
+ * (`artifactDigests`, the digest the archive step returned), and a deploy
+ * record carries the publish digest, which is another value for an image, so
+ * the two are compared through the build manifest the source deploy record
+ * names (`manifestDigest`), whose entries carry build digests at the same
+ * archive paths:
+ *
+ * - a source record that names this release in `releaseDigest` matches;
+ * - else, each of the release's artifacts for the component must be in that
+ *   manifest at its path with the release's digest, and one that differs is
+ *   a mismatch;
+ * - a record with no `manifestDigest`, a manifest that isn't stored, or an
+ *   artifact path the manifest doesn't hold can't be compared.
+ *
+ * A mismatch is a warning, not a refusal. The environment promoted from was
+ * deployed by its own `run --components`, which builds again, and an image
+ * build is not reproducible, so its digest differs from the cut's for the
+ * same commit. Refusing would refuse every image promote until a deploy can
+ * run the release's own artifacts (#4043).
+ */
+export declare function releaseArtifactMismatches(release: Release, sources: ReadonlyArray<{
+    component: string;
+    source: ReleaseRecord;
+}>, readManifest: (manifestDigest: string) => Promise<BuildArchiveManifest | null>): Promise<string[]>;
+//# sourceMappingURL=release-promote.d.ts.map

package/dist/components/release-promote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-promote.d.ts","sourceRoot":"","sources":["../../src/components/release-promote.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAuC,MAAM,UAAU,CAAC;AAErF,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAElE,yGAAyG;AACzG,eAAO,MAAM,qBAAqB,6BAA6B,CAAC;AAEhE,uDAAuD;AACvD,MAAM,WAAW,cAAc;IAC7B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,kFAAkF;AAClF,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,aAAa,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAMtG;AAED,sIAAsI;AACtI,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAG3D;AAUD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,aAAa,EACrB,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GACvD,OAAO,CAAC;IAAE,UAAU,EAAE,eAAe,EAAE,CAAC;IAAC,KAAK,EAAE,cAAc,EAAE,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAiD5F;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,aAAa,EACrB,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GACvD,OAAO,CAAC;IAAE,KAAK,EAAE,cAAc,EAAE,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CA2B7D;AAED,sEAAsE;AACtE,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,cAAc,EAAE,GAAG,IAAI,CAMxF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,cAAc,EAAE,GAAG,IAAI,CAQzF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,aAAa,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,CAAC,EACpE,YAAY,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,GAC7E,OAAO,CAAC,MAAM,EAAE,CAAC,CAmBnB"}

package/dist/components/release-promote.js

@@ -0,0 +1,204 @@
+/**
+ * A promote under a release (#4026, ws-104 question 5): the deploy reads the
+ * templates the release recorded for the target environment, not the ones in
+ * the promoting checkout.
+ *
+ * Each template a promoted component's deploy names ({@link templateRefs}) has
+ * to be one the release's target records for that component. Its bytes are
+ * read from `_releases/templates/` on `chant/lifecycle` and checked against
+ * the target's digest, the way a promote checks the publish digest, and a
+ * mismatch refuses the promote before anything runs. The bytes are written
+ * under `.chant/release-templates/<digest>/` in the member's directory and the
+ * step reads them from there. The path is relative and fixed by the digest,
+ * so a gate approval bound to the promote's plan still matches on a re-run.
+ */
+import { mkdirSync, readdirSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { contentDigest } from "../content-digest.js";
+import { TEMPLATE_FIELDS, templateRefs } from "./release-compile.js";
+/** Where a promote under a release writes the recorded templates, relative to the member's directory. */
+export const RELEASE_TEMPLATES_DIR = ".chant/release-templates";
+/** The release's target for `env`, or an error naming the environments it has. */
+export function targetFor(release, env) {
+    const target = release.targets.find((t) => t.env === env);
+    if (target)
+        return { target };
+    return {
+        error: `release ${release.releaseDigest} has no target for "${env}"; it was compiled for ${release.targets.map((t) => t.env).join(", ") || "no environment"}`,
+    };
+}
+/** Whether a release is of a project with no components (#4046): no artifact, and every template it records has `component: null`. */
+export function isImplicitRelease(release) {
+    const templates = release.targets.flatMap((t) => t.templates);
+    return release.artifactDigests.length === 0 && templates.length > 0 && templates.every((t) => t.component === null);
+}
+function isGate(step) {
+    return step.kind === "gate";
+}
+function isPhase(step) {
+    return typeof step.phase === "string" && Array.isArray(step.steps);
+}
+/**
+ * Point every template `components` read at the target's recorded bytes.
+ * Returns the rewritten compositions and the files to write, or the reasons
+ * the promote is refused: a template the target does not record, one whose
+ * bytes are missing, or one whose bytes do not hash to the target's digest.
+ */
+export async function pinReleaseTemplates(components, release, target, readTemplate) {
+    const errors = [];
+    const files = [];
+    const out = [];
+    for (const component of components) {
+        const replace = new Map();
+        for (const ref of templateRefs(component)) {
+            if (replace.has(ref.value))
+                continue;
+            const recorded = target.templates.find((t) => t.component === component.name && t.path === ref.path);
+            if (!recorded) {
+                errors.push(`component "${component.name}" reads ${ref.field} "${ref.value}", which release ${release.releaseDigest} does not record for "${target.env}"; ` +
+                    `this checkout's deploy is not the one the release was compiled from (commit ${release.commit.slice(0, 12)})`);
+                continue;
+            }
+            const content = await readTemplate(recorded.digest);
+            if (content === null) {
+                errors.push(`component "${component.name}": the bytes of template "${ref.path}" (${recorded.digest}) are not on the chant/lifecycle branch; fetch it and try again`);
+                continue;
+            }
+            const got = contentDigest(content);
+            if (got !== recorded.digest) {
+                errors.push(`component "${component.name}": template "${ref.path}" hashes to ${got}, but the release's target for "${target.env}" records ${recorded.digest}; refusing to deploy it`);
+                continue;
+            }
+            const path = join(RELEASE_TEMPLATES_DIR, recorded.digest.replace(/:/g, "_"), basename(ref.path));
+            files.push({ path, content });
+            replace.set(ref.value, path);
+        }
+        const rewrite = (phase) => ({
+            ...phase,
+            steps: phase.steps.map((step) => {
+                if (isPhase(step))
+                    return rewrite(step);
+                if (isGate(step))
+                    return step;
+                const next = { ...step };
+                for (const field of TEMPLATE_FIELDS) {
+                    const v = next[field];
+                    if (typeof v === "string" && replace.has(v))
+                        next[field] = replace.get(v);
+                    else if (Array.isArray(v))
+                        next[field] = v.map((x) => (typeof x === "string" && replace.has(x) ? replace.get(x) : x));
+                }
+                return next;
+            }),
+        });
+        out.push({ ...component, deploy: component.deploy.map(rewrite) });
+    }
+    return errors.length > 0 ? { errors } : { components: out, files };
+}
+/**
+ * The files a release's target records, read back by digest and checked, for
+ * `chant release export` (#4046). A project with no components has no deploy
+ * step for a promote to point at the recorded bytes, so its deploy (an Op such
+ * as `chant run deploy`, or a CI job) reads the files this writes instead of
+ * building them again. Each path is the one the build wrote, relative to the
+ * member's directory; a template whose bytes are missing or don't hash to the
+ * target's digest is refused, as {@link pinReleaseTemplates} refuses one.
+ */
+export async function targetFiles(release, target, readTemplate) {
+    const errors = [];
+    const files = [];
+    for (const t of target.templates) {
+        const who = t.component === null ? "" : `component "${t.component}": `;
+        if (t.path.startsWith("/") || t.path.split("/").includes("..")) {
+            errors.push(`${who}template "${t.path}" is not a path inside the member's directory; refusing to write it`);
+            continue;
+        }
+        const content = await readTemplate(t.digest);
+        if (content === null) {
+            errors.push(`${who}the bytes of template "${t.path}" (${t.digest}) are not on the chant/lifecycle branch; fetch it and try again`);
+            continue;
+        }
+        const got = contentDigest(content);
+        if (got !== t.digest) {
+            errors.push(`${who}template "${t.path}" hashes to ${got}, but release ${release.releaseDigest} records ${t.digest} for "${target.env}"; refusing to write it`);
+            continue;
+        }
+        const same = files.find((f) => f.path === t.path);
+        if (same) {
+            if (same.content !== content)
+                errors.push(`two components record different bytes at "${t.path}" for "${target.env}", so they can't both be written there`);
+            continue;
+        }
+        files.push({ path: t.path, content });
+    }
+    return errors.length > 0 ? { errors } : { files };
+}
+/** Write the pinned templates under `dir`, the member's directory. */
+export function writePinnedTemplates(dir, files) {
+    for (const f of files) {
+        const full = join(dir, f.path);
+        mkdirSync(dirname(full), { recursive: true });
+        writeFileSync(full, f.content);
+    }
+}
+/**
+ * Remove the templates {@link writePinnedTemplates} wrote once the promote is
+ * done, and {@link RELEASE_TEMPLATES_DIR} with them when nothing else is in
+ * it, so a promote leaves the checkout as it found it. A re-run writes them
+ * again from the release.
+ */
+export function removePinnedTemplates(dir, files) {
+    for (const f of files)
+        rmSync(dirname(join(dir, f.path)), { recursive: true, force: true });
+    const root = join(dir, RELEASE_TEMPLATES_DIR);
+    try {
+        if (readdirSync(root).length === 0)
+            rmdirSync(root);
+    }
+    catch {
+        // Already gone, or not ours to remove.
+    }
+}
+/**
+ * Whether the artifact a promote deploys under a release is one the release
+ * built (#4045, the rule #4026 left open). The release records build digests
+ * (`artifactDigests`, the digest the archive step returned), and a deploy
+ * record carries the publish digest, which is another value for an image, so
+ * the two are compared through the build manifest the source deploy record
+ * names (`manifestDigest`), whose entries carry build digests at the same
+ * archive paths:
+ *
+ * - a source record that names this release in `releaseDigest` matches;
+ * - else, each of the release's artifacts for the component must be in that
+ *   manifest at its path with the release's digest, and one that differs is
+ *   a mismatch;
+ * - a record with no `manifestDigest`, a manifest that isn't stored, or an
+ *   artifact path the manifest doesn't hold can't be compared.
+ *
+ * A mismatch is a warning, not a refusal. The environment promoted from was
+ * deployed by its own `run --components`, which builds again, and an image
+ * build is not reproducible, so its digest differs from the cut's for the
+ * same commit. Refusing would refuse every image promote until a deploy can
+ * run the release's own artifacts (#4043).
+ */
+export async function releaseArtifactMismatches(release, sources, readManifest) {
+    const out = [];
+    for (const { component, source } of sources) {
+        if (source.releaseDigest === release.releaseDigest)
+            continue;
+        const artifacts = release.artifactDigests.filter((a) => a.component === component);
+        if (artifacts.length === 0 || source.manifestDigest === undefined)
+            continue;
+        const manifest = await readManifest(source.manifestDigest);
+        if (!manifest)
+            continue;
+        for (const a of artifacts) {
+            const entry = manifest.contents.find((e) => e.path === a.path && e.kind === a.kind);
+            if (entry && entry.digest !== a.digest) {
+                out.push(`${component}: the ${source.env} deploy being promoted was built with ${a.path} at ${entry.digest}, ` +
+                    `but release ${release.releaseDigest} built it at ${a.digest}, so the artifact deployed is not the release's own`);
+            }
+        }
+    }
+    return out;
+}

package/dist/components/run-progress.d.ts

@@ -79,6 +79,13 @@ export interface RunDoneEvent {
     type: "run-done";
     status: RunProgressStatus;
 }
+/**
+ * @deprecated Read `RunEvent` (`../run-event.ts`, exported from
+ * `@intentius/chant`) instead: one contract for Op, component and pipeline
+ * runs, with the run id, commit and runtime on every event (#4019).
+ * `runEventOfProgress` maps each of these onto it. `--progress-json` keeps
+ * printing this shape until #4041 moves it to the run-event stream.
+ */
 export type RunProgressEvent = RunStartEvent | WaveStartEvent | ComponentStartEvent | PhaseStartEvent | StepEvent | PhaseDoneEvent | ComponentDoneEvent | WaveDoneEvent | RunDoneEvent;
 /** A sink that receives progress events as they occur. The driver only ever calls this — it never writes to a stream directly, so it stays testable without stdout. */
 export type RunProgressSink = (event: RunProgressEvent) => void;

package/dist/components/run-progress.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-progress.d.ts","sourceRoot":"","sources":["../../src/components/run-progress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,mPAAmP;AACnP,MAAM,MAAM,iBAAiB,GAAG,IAAI,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE1D,mMAAmM;AACnM,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC;CACnB;AAED,2GAA2G;AAC3G,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,YAAY,CAAC;IACnB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,4EAA4E;AAC5E,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,iBAAiB,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,2JAA2J;AAC3J,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,aAAa,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,+FAA+F;AAC/F,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,IAAI,GAAG,QAAQ,CAAC;IACpC,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,0LAA0L;AAC1L,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,YAAY,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,iBAAiB,CAAC;CAC3B;AAED,2IAA2I;AAC3I,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,iBAAiB,CAAC;CAC3B;AAED,uHAAuH;AACvH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,iBAAiB,CAAC;CAC3B;AAED,4FAA4F;AAC5F,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,iBAAiB,CAAC;CAC3B;AAED,MAAM,MAAM,gBAAgB,GACxB,aAAa,GACb,cAAc,GACd,mBAAmB,GACnB,eAAe,GACf,SAAS,GACT,cAAc,GACd,kBAAkB,GAClB,aAAa,GACb,YAAY,CAAC;AAEjB,uKAAuK;AACvK,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;AAEhE;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,GAAG,gBAAgB,EACrD,KAAK,GAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAA0C,GACnE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAEpB"}
+{"version":3,"file":"run-progress.d.ts","sourceRoot":"","sources":["../../src/components/run-progress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,mPAAmP;AACnP,MAAM,MAAM,iBAAiB,GAAG,IAAI,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE1D,mMAAmM;AACnM,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC;CACnB;AAED,2GAA2G;AAC3G,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,YAAY,CAAC;IACnB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,4EAA4E;AAC5E,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,iBAAiB,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,2JAA2J;AAC3J,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,aAAa,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,+FAA+F;AAC/F,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,IAAI,GAAG,QAAQ,CAAC;IACpC,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,0LAA0L;AAC1L,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,YAAY,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,iBAAiB,CAAC;CAC3B;AAED,2IAA2I;AAC3I,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,iBAAiB,CAAC;CAC3B;AAED,uHAAuH;AACvH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,iBAAiB,CAAC;CAC3B;AAED,4FAA4F;AAC5F,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,iBAAiB,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GACxB,aAAa,GACb,cAAc,GACd,mBAAmB,GACnB,eAAe,GACf,SAAS,GACT,cAAc,GACd,kBAAkB,GAClB,aAAa,GACb,YAAY,CAAC;AAEjB,uKAAuK;AACvK,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;AAEhE;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,GAAG,gBAAgB,EACrD,KAAK,GAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAA0C,GACnE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAEpB"}

package/dist/components/wave-plan.d.ts

@@ -18,7 +18,7 @@
  * plans as `undefined`. Cross-component wiring (`stackOutput()`,
  * `@<component>.publish.*`) resolves.
  */
-import { type DriverComponent } from "./driver.js";
+import { type DriverComponent, type DriverPhase, type DriverStep } from "./driver.js";
 import type { CapabilityRegistry, DeployContext } from "./capability.js";
 import type { WaveMember } from "../gated-waves.js";
 import type { ChangeSetPart } from "../change-set.js";
@@ -37,6 +37,13 @@ export type WaveComponentPlan = {
     component: string;
     error: string;
 };
+/** Every capability step in a composition, nested phases included, gates left out. */
+export declare function capabilitySteps(phases: readonly DriverPhase[]): DriverStep[];
+/**
+ * The context a step is planned with: `ctx`, plus the components whose
+ * outputs the step reads and could not read yet (`unresolvedInputs`, #4084).
+ */
+export declare function planContext(ctx: DeployContext, stepInput: Record<string, unknown>, componentOutputs: Record<string, Record<string, unknown>>): DeployContext;
 /** Plan one component against the outputs earlier waves produced. Never throws: a failure comes back as `error`. */
 export declare function planWaveComponent(component: DriverComponent, registry: CapabilityRegistry, ctx: DeployContext, componentOutputs: Record<string, Record<string, unknown>>): Promise<WaveComponentPlan>;
 /**

package/dist/components/wave-plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wave-plan.d.ts","sourceRoot":"","sources":["../../src/components/wave-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAoB,KAAK,eAAe,EAAqC,MAAM,UAAU,CAAC;AAErG,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,UAAU,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,KAAK,EAAE,aAAa,EAAE,CAAA;CAAE,GACpG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AA2BzC,oHAAoH;AACpH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,eAAe,EAC1B,QAAQ,EAAE,kBAAkB,EAC5B,GAAG,EAAE,aAAa,EAClB,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxD,OAAO,CAAC,iBAAiB,CAAC,CAgC5B;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,eAAe,EAC1B,QAAQ,EAAE,kBAAkB,EAC5B,GAAG,EAAE,aAAa,EAClB,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxD,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CAU9C"}
+{"version":3,"file":"wave-plan.d.ts","sourceRoot":"","sources":["../../src/components/wave-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAA6C,KAAK,eAAe,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AAE9H,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,UAAU,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,KAAK,EAAE,aAAa,EAAE,CAAA;CAAE,GACpG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAUzC,sFAAsF;AACtF,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,GAAG,UAAU,EAAE,CAc5E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,aAAa,EAClB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxD,aAAa,CAGf;AAED,oHAAoH;AACpH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,eAAe,EAC1B,QAAQ,EAAE,kBAAkB,EAC5B,GAAG,EAAE,aAAa,EAClB,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxD,OAAO,CAAC,iBAAiB,CAAC,CAgC5B;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,eAAe,EAC1B,QAAQ,EAAE,kBAAkB,EAC5B,GAAG,EAAE,aAAa,EAClB,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxD,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CAU9C"}