@intentius/chant 0.124.27 → 0.124.29

package/dist/cli/handlers/promote.js

@@ -12,25 +12,36 @@
  * failed or stopped at a gate, so the ledger never misses a deploy that
  * happened. Unlike an auto-recorded release, the record is what these
  * commands are for, so a failed write is an error rather than a warning.
+ * A run that applied partly, or failed, also appends a deploy outcome
+ * (#4035, ../../lifecycle/deploy-outcome.ts) naming what it did to each
+ * component, so `workspace status` reads the environment as mixed.
+ *
+ * `rollback --release` (#4035) is a promote of an earlier release into the
+ * environment: every component of the release at the digest the environment
+ * ran from it, through the release gate `promote --release` binds (#4045).
  */
 import { resolve } from "node:path";
 import { readFileSync } from "node:fs";
 import { loadChantConfig } from "../../config.js";
+import { promotionOrder } from "../../workspace/promotion-order.js";
+import { resolvePromotionSource } from "../../components/promote-order.js";
 import { fetchLifecycle, getHeadCommit, pushLifecycle } from "../../lifecycle/git.js";
-import { appendReleaseRecord, readReleaseLedger, resolveRunId, } from "../../lifecycle/release-ledger.js";
+import { appendReleaseRecord, latestPerComponent, readReleaseLedger, resolveRunId, } from "../../lifecycle/release-ledger.js";
 import { isComponentList, resolveComponentTargets } from "../../components/cli-support.js";
 import { applyConfigDefaults } from "../../components/config-defaults.js";
 import { fanOutRegistry } from "../../components/fan-out-support.js";
 import { renderDriverHuman } from "../../components/driver-output.js";
 import { ndjsonProgressSink } from "../../components/run-progress.js";
-import { parseDigestPins, planPromotion, planRollback, planRedeploy, withoutBuildSteps, runPromotion, promotionRecord, rollbackRecord, redeployRecord, gateApprover, } from "../../components/promote.js";
+import { openCliRunEvents, refusesBothStreams } from "../run-events.js";
+import { parseDigestPins, planPromotion, planRollback, planReleaseRollback, planRedeploy, withoutBuildSteps, runPromotion, promotionRecord, rollbackRecord, redeployRecord, gateApprover, gateAdmission, } from "../../components/promote.js";
 import { summaryLedgerPrefix, writeGatedRunSummary } from "../../op/gate-summary.js";
-import { approveCommand, describeGateMismatch, gateIsSealed } from "../../op/gate.js";
+import { approveCommand, describeGateMismatch, gateIsSealed, gitGateLedgerPort } from "../../op/gate.js";
 import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli.js";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format.js";
 import { GATED_EXIT_CODE } from "./run.js";
-const PROMOTE_USAGE = "chant components promote --from <env> --to <env> [--component <name> [--digest <sha256:...>] | --digest <component>=<sha256:...> ...] [--dry-run] [--json]";
-const ROLLBACK_USAGE = "chant components rollback <env> --component <name> [--digest <sha256:...>] [--dry-run] [--json]";
+import { redeployLine, releaseRollbackLine, rollbackTarget, unsettledComponents } from "../../lifecycle/mixed-environment.js";
+const PROMOTE_USAGE = "chant components promote --to <env> [--from <env>] [--allow-skip] [--release <label|digest>] [--component <name> [--digest <sha256:...>] | --digest <component>=<sha256:...> ...] [--dry-run] [--json]";
+const ROLLBACK_USAGE = "chant components rollback <env> (--component <name> [--digest <sha256:...>] | --release <label|digest>) [--dry-run] [--json]";
 const REDEPLOY_USAGE = "chant components redeploy <env> --component <name> [--digest <sha256:...>] [--dry-run] [--json]";
 function renderPlan(verb, plan, removed) {
     console.error(formatBold(verb === "promote" ? `promote ${plan.from} -> ${plan.to}` : `${verb} ${plan.to}`));
@@ -96,13 +107,118 @@ async function readLedger(env) {
     }
     return ledger.records;
 }
+/**
+ * Plan, store and bind the release gate for a promote under a release
+ * (#4045, ws-104 questions 2 and 6). Undefined when no promoted composition
+ * declares a gate, so there is nothing to bind. A number is the exit code of
+ * a refusal already printed: a provisional member, or a member that failed
+ * to plan. On an empty change set, each gate gets an `empty: true`
+ * resolution the run then counts once it reads the stored document back.
+ */
+async function bindReleaseGate(input) {
+    const { plan, under, port } = input;
+    const gate = await import("../../components/release-gate.js");
+    const gates = gate.gateNamesOf(input.prepared);
+    if (gates.length === 0)
+        return undefined;
+    const env = plan.to;
+    const releaseDigest = under.release.releaseDigest;
+    // What the environment runs now, to compare each component with.
+    const { readRelease } = await import("../../lifecycle/release-store.js");
+    const envRecords = (await readLedger(env)).filter((r) => r.env === env);
+    const latest = latestPerComponent(envRecords);
+    const releases = new Map();
+    const current = new Map();
+    for (const item of plan.items) {
+        const record = latest.get(item.component);
+        if (!record)
+            continue;
+        const named = record.releaseDigest;
+        if (named !== undefined && !releases.has(named))
+            releases.set(named, await readRelease(named).catch(() => null));
+        current.set(item.component, { record, release: named !== undefined ? (releases.get(named) ?? null) : null });
+    }
+    // #4035: a component a run left failed or gated runs something the ledger doesn't say.
+    const { readDeployOutcomes } = await import("../../lifecycle/deploy-outcome.js");
+    const unsettled = new Map();
+    for (const [component, u] of unsettledComponents(envRecords, await readDeployOutcomes(env).catch(() => []))) {
+        unsettled.set(component, `the ${u.outcome.verb} run ${u.outcome.runId} left ${component} ${u.state} in "${env}" and nothing has been recorded for it since, so what it runs is not known`);
+    }
+    const doc = await gate.planReleaseChangeSet({
+        release: under.release,
+        env,
+        components: input.prepared,
+        digests: new Map(plan.items.map((i) => [i.component, i.digest])),
+        registry: input.registry,
+        current,
+        unsettled,
+        seededOutputs: input.seededOutputs,
+    });
+    const provisional = gate.provisionalMembers(doc);
+    if (provisional.length > 0) {
+        console.error(formatError({
+            message: `the change set of release ${under.label ?? releaseDigest} for "${env}" has provisional members (${provisional.join(", ")}), which no approval covers; nothing was deployed`,
+            hint: "Deploy what they read first, so they plan against real values.",
+        }));
+        return 1;
+    }
+    const failed = doc.members.filter((m) => m.status === "failed");
+    if (failed.length > 0) {
+        for (const m of failed)
+            console.error(formatError({ message: `${m.member} failed to plan for "${env}"${m.error ? `: ${m.error}` : ""}` }));
+        console.error(formatError({ message: "nothing was deployed" }));
+        return 1;
+    }
+    // The document is stored before the gate is decided, so the plan a pending
+    // gate waits on can be read, and an empty pass can be checked.
+    const { storeGateChangeSet } = await import("../../lifecycle/gate-change-set.js");
+    try {
+        const stored = await storeGateChangeSet({ doc, cwd: input.projectPath, at: input.head ?? null });
+        if (stored.warning)
+            console.error(formatWarning({ message: stored.warning }));
+    }
+    catch (err) {
+        console.error(formatWarning({ message: `could not store the change set ${doc.digest}: ${err instanceof Error ? err.message : String(err)}` }));
+    }
+    const { isEmptyChangeSet } = await import("../../change-set.js");
+    const empty = isEmptyChangeSet(doc);
+    console.error(formatInfo(`release gate: change set ${doc.digest} for "${env}"` +
+        (empty ? ", empty: its gates pass without an approval" : `, ${doc.summary.entries} entr${doc.summary.entries === 1 ? "y" : "ies"}, ${doc.summary.holes} hole(s)`) +
+        ` (chant change-set show ${doc.digest})`));
+    if (empty) {
+        if (!port.appendResolution)
+            throw new Error("the gate ledger can't record a resolution, so an empty change set can't pass its gates");
+        const { resolutions } = await port.read(gate.RELEASE_GATE_OP);
+        const timestamp = new Date().toISOString();
+        for (const name of gates) {
+            const standing = resolutions.some((r) => r.empty === true && r.gate === name && r.environment === env && r.releaseDigest === releaseDigest && r.planDigest === doc.digest);
+            if (standing)
+                continue;
+            // Pushed with the resolution; the deploy records the promote writes push the same branch.
+            await port.appendResolution(gate.emptyResolution({ gate: name, doc, actor: input.actor, timestamp, ...(input.head ? { gitSha: input.head } : {}) }));
+        }
+    }
+    const { readStoredChangeSet } = await import("../../lifecycle/change-set-store.js");
+    return {
+        doc,
+        empty,
+        binding: {
+            op: gate.RELEASE_GATE_OP,
+            planDigest: doc.digest,
+            releaseDigest,
+            verifyEmpty: gate.emptyVerifier((digest) => readStoredChangeSet(digest, { cwd: input.projectPath }), { releaseDigest, environment: env }),
+        },
+    };
+}
 /**
  * Prepare, run and record a plan. Shared by promote, rollback and redeploy,
  * which differ only in how the plan was chosen, whether the publish step runs,
  * and which field names the earlier release on the new record.
  */
-async function deployPlan(ctx, verb, plan, project, actor, record) {
+async function deployPlan(ctx, verb, plan, project, actor, record, under) {
     const { args } = ctx;
+    if (refusesBothStreams(args))
+        return 1;
     const byName = new Map(project.targets.map((c) => [c.name, applyConfigDefaults(c, project.config)]));
     const prepared = [];
     const removed = new Map();
@@ -124,6 +240,34 @@ async function deployPlan(ctx, verb, plan, project, actor, record) {
         console.error(formatError({ message: `nothing was deployed` }));
         return 1;
     }
+    // #4026: under a release, the deploy reads the templates the release
+    // recorded for this environment, checked against their digests.
+    let pinnedFiles = [];
+    if (under) {
+        const { pinReleaseTemplates } = await import("../../components/release-promote.js");
+        const { readReleaseTemplate } = await import("../../lifecycle/release-store.js");
+        const pinned = await pinReleaseTemplates(prepared, under.release, under.target, (digest) => readReleaseTemplate(digest));
+        if ("errors" in pinned) {
+            for (const message of pinned.errors)
+                console.error(formatError({ message }));
+            console.error(formatError({ message: `nothing was deployed` }));
+            return 1;
+        }
+        prepared.splice(0, prepared.length, ...pinned.components);
+        pinnedFiles = pinned.files;
+        for (const item of plan.items) {
+            const named = item.source.releaseDigest;
+            if (named !== undefined && named !== under.release.releaseDigest) {
+                console.error(formatWarning({ message: `${item.component}: the ${plan.from} deploy being promoted came from release ${named}, not ${under.release.releaseDigest}` }));
+            }
+        }
+        // #4045: the artifact deployed against the artifacts the release built.
+        const { releaseArtifactMismatches } = await import("../../components/release-promote.js");
+        const { readBuildManifest } = await import("../../lifecycle/build-ledger-store.js");
+        const mismatches = await releaseArtifactMismatches(under.release, plan.items.map((i) => ({ component: i.component, source: i.source })), (digest) => readBuildManifest(digest).catch(() => null));
+        for (const message of mismatches)
+            console.error(formatWarning({ message }));
+    }
     // The composition deployed is this checkout's. Say so when it is not the
     // commit the artifact was built from.
     const head = await getHeadCommit().catch(() => undefined);
@@ -135,15 +279,29 @@ async function deployPlan(ctx, verb, plan, project, actor, record) {
             }));
         }
     }
+    const releaseJson = under
+        ? { release: { releaseDigest: under.release.releaseDigest, label: under.label, templates: under.target.templates } }
+        : {};
     if (args.dryRun) {
         if (args.json)
-            console.log(JSON.stringify(planJson(plan, removed), null, 2));
-        else
+            console.log(JSON.stringify({ ...planJson(plan, removed), ...releaseJson }, null, 2));
+        else {
             renderPlan(verb, plan, removed);
+            if (under)
+                console.error(`  under release ${under.label ?? under.release.releaseDigest}: ${under.target.templates.length} template(s) from its "${plan.to}" target`);
+        }
         return 0;
     }
     if (!args.json)
         renderPlan(verb, plan, removed);
+    // #4045: the pinned templates are written for this run and removed after it.
+    const { writePinnedTemplates, removePinnedTemplates } = await import("../../components/release-promote.js");
+    const tidy = () => {
+        if (pinnedFiles.length > 0)
+            removePinnedTemplates(project.projectPath, pinnedFiles);
+    };
+    if (pinnedFiles.length > 0)
+        writePinnedTemplates(project.projectPath, pinnedFiles);
     const seededOutputs = {};
     for (const file of args.seedOutputs ?? []) {
         try {
@@ -151,34 +309,88 @@ async function deployPlan(ctx, verb, plan, project, actor, record) {
         }
         catch (err) {
             console.error(formatError({ message: `--seed-outputs: could not read "${file}": ${err instanceof Error ? err.message : String(err)}` }));
+            tidy();
             return 1;
         }
     }
     const registry = await fanOutRegistry(project.projectPath, project.config);
-    const run = await runPromotion({
-        plan,
-        components: prepared,
-        registry,
-        componentOutputs: seededOutputs,
-        ...(args.progressJson ? { onProgress: ndjsonProgressSink() } : {}),
+    const port = gitGateLedgerPort();
+    // #4045: under a release, every gate binds the release's change set for this environment.
+    let releaseGate;
+    let changeSetJson;
+    if (under) {
+        try {
+            const bound = await bindReleaseGate({ plan, prepared, under, registry, port, seededOutputs, actor: actor, projectPath: project.projectPath, head });
+            if (typeof bound === "number") {
+                tidy();
+                return bound;
+            }
+            if (bound) {
+                releaseGate = bound.binding;
+                changeSetJson = { changeSet: bound.doc.digest, empty: bound.empty };
+            }
+        }
+        catch (err) {
+            tidy();
+            throw err;
+        }
+    }
+    // The run id the release records carry, chosen before the run so that
+    // `--events-json` (#4041) names the run by it too.
+    const { runId, runOrigin } = resolveRunId(args.runId);
+    const events = await openCliRunEvents(args, {
+        kind: "component",
+        name: `${verb} ${plan.items.map((i) => i.component).join(",")} in ${plan.to}`,
+        runId,
+        cwd: project.projectPath,
     });
+    let run;
+    try {
+        run = await runPromotion({
+            plan,
+            components: prepared,
+            registry,
+            componentOutputs: seededOutputs,
+            gates: port,
+            ...(releaseGate ? { releaseGate } : {}),
+            ...(args.progressJson ? { onProgress: ndjsonProgressSink() } : {}),
+            ...(events ? { onRunEvent: events.emit } : {}),
+        });
+    }
+    catch (err) {
+        events?.settle("failed", err instanceof Error ? err.message : String(err));
+        throw err;
+    }
+    finally {
+        tidy();
+    }
+    // The driver settles the stream; this only ends one it left open.
+    events?.settle(run.status === "fail" ? "failed" : run.status);
     if (!args.json)
         renderDriverHuman(run);
     // Record every component that deployed, whatever happened to the rest: a
     // component that reached the environment and is missing from its ledger
     // would be exactly the unrecorded deploy the ledger exists to rule out.
     const deployed = plan.items.filter((item) => run.results.some((r) => r.component === item.component && r.status === "ok"));
-    const { runId, runOrigin } = resolveRunId(args.runId);
     const timestamp = new Date().toISOString();
     const recorded = [];
     let recordError;
-    if (deployed.length > 0) {
+    // #4035: a run that applied partly, or failed, records what it did to each
+    // component, so the environment reads as mixed until it is settled.
+    const { deployOutcomeOf, appendDeployOutcome } = await import("../../lifecycle/deploy-outcome.js");
+    const outcome = deployOutcomeOf({ verb, plan, run, releaseDigest: under?.release.releaseDigest ?? null, runId, timestamp, actor: actor });
+    if (deployed.length > 0 || outcome) {
         try {
             for (const item of deployed) {
-                const approver = gateApprover(run.results.find((r) => r.component === item.component));
-                const { record: written } = await appendReleaseRecord(record(item, plan.to, { runId, ...(runOrigin ? { runOrigin } : {}), actor: actor, timestamp, ...(approver ? { approver } : {}) }));
+                const result = run.results.find((r) => r.component === item.component);
+                const approver = gateApprover(result);
+                const admission = gateAdmission(result);
+                const input = record(item, plan.to, { runId, ...(runOrigin ? { runOrigin } : {}), actor: actor, timestamp, ...(approver ? { approver } : {}), ...(admission ? { admission } : {}) });
+                const { record: written } = await appendReleaseRecord(under ? { ...input, releaseDigest: under.release.releaseDigest } : input);
                 recorded.push(written);
             }
+            if (outcome)
+                await appendDeployOutcome(outcome);
             await pushLifecycle();
         }
         catch (err) {
@@ -186,7 +398,8 @@ async function deployPlan(ctx, verb, plan, project, actor, record) {
         }
     }
     if (args.json) {
-        console.log(JSON.stringify({ ...planJson(plan, removed), run, recorded }, null, 2));
+        const withChangeSet = under && changeSetJson ? { release: { ...releaseJson.release, ...changeSetJson } } : releaseJson;
+        console.log(JSON.stringify({ ...planJson(plan, removed), ...withChangeSet, run, recorded, ...(outcome ? { outcome } : {}) }, null, 2));
     }
     else {
         for (const r of recorded) {
@@ -197,9 +410,20 @@ async function deployPlan(ctx, verb, plan, project, actor, record) {
                     : `Redeployed ${formatBold(r.component)} in ${plan.to} at ${r.digest}`));
         }
     }
+    if (outcome && recordError === undefined) {
+        const unsettled = outcome.components.filter((c) => c.outcome === "failed" || c.outcome === "gated");
+        console.error(formatWarning({
+            message: `"${plan.to}" now runs a mix: ${outcome.components.map((c) => `${c.component} ${c.outcome}`).join(", ")}. ` +
+                `chant workspace status ${plan.to} --json lists what each component runs and the rollback line`,
+        }));
+        for (const c of unsettled)
+            console.error(formatInfo(`settle ${c.component}: ${redeployLine(plan.to, c.component)}, or run the same ${verb} again`));
+    }
     if (recordError !== undefined) {
         console.error(formatError({
-            message: `deployed to "${plan.to}", but the release record was not written: ${recordError}`,
+            message: deployed.length > 0
+                ? `deployed to "${plan.to}", but the release record was not written: ${recordError}`
+                : `the outcome of the ${verb} in "${plan.to}" was not written: ${recordError}`,
             hint: `Pull the chant/lifecycle branch and check \`chant components status ${plan.to}\` before running this again.`,
         }));
         return 1;
@@ -245,12 +469,119 @@ function actorOrRefuse(ctx) {
     }
     return { actor };
 }
+/** The revoked commits, or the exit code of a refusal already printed when the ci tags can't be judged (#4033). */
+async function revokedOrRefuse(what) {
+    const { readRevokedCommits } = await import("../../lifecycle/release-revocation.js");
+    try {
+        return await readRevokedCommits(process.cwd());
+    }
+    catch (err) {
+        console.error(formatError({
+            message: `the ci tags can't be judged, so whether ${what} is revoked is unknown: ${err instanceof Error ? err.message : String(err)} [declaration-invalid]`,
+            hint: "Fix ci.green in chant.workspace.json at base; chant workspace check names the problem.",
+        }));
+        return 1;
+    }
+}
+/**
+ * Resolve `--release` for a promote or a rollback to `env` (#4026, #4035):
+ * the release, its label and its target for `env`. Refused, with the exit
+ * code returned, when the release can't be found, has no target for `env`,
+ * is of a project with no components (#4046), or was cut from a revoked
+ * commit (#4033), so a gate pending for it can't pass.
+ */
+async function resolveUnderRelease(ref, env, verb, fix) {
+    const { resolveRelease } = await import("../../lifecycle/release-store.js");
+    const { targetFor, isImplicitRelease } = await import("../../components/release-promote.js");
+    const found = await resolveRelease(ref);
+    if (!found) {
+        console.error(formatError({ message: `no release is labelled or digested "${ref}" in this member`, hint: "List them with: chant release list" }));
+        return 1;
+    }
+    const target = targetFor(found.release, env);
+    if ("error" in target) {
+        console.error(formatError({ message: target.error }));
+        return 1;
+    }
+    // #4046: a release of a project with no components records build output
+    // and no component, so there is no deploy step here to point at it.
+    if (isImplicitRelease(found.release)) {
+        const name = found.label ?? found.release.releaseDigest;
+        console.error(formatError({
+            message: `release ${name} is of a project with no components, so ${verb} has no component to deploy`,
+            hint: `Write its "${env}" build output with \`chant release export ${name} --env ${env}\`, then run the project's own deploy against those files.`,
+        }));
+        return 1;
+    }
+    // #4033 (ws-105): a release cut from a revoked commit is never deployed,
+    // so a gate pending for it can't pass. Read from local tags, as the cut reads them.
+    const revoked = await revokedOrRefuse(`release ${found.label ?? found.release.releaseDigest}`);
+    if (typeof revoked === "number")
+        return revoked;
+    const { revocationOf, revokedRefusal } = await import("../../lifecycle/release-revocation.js");
+    const revocation = revocationOf(found.release, revoked);
+    if (revocation) {
+        console.error(formatError(revokedRefusal({ releaseDigest: found.release.releaseDigest, label: found.label }, revocation, await fix(found.release))));
+        return 1;
+    }
+    return { release: found.release, label: found.label, target: target.target };
+}
+/**
+ * The line that rolls `env` back past `exclude` (#4035): to the newest
+ * release in its ledger that is still kept and not revoked, by label, or
+ * null when there is none.
+ */
+async function rollbackLineFor(env, records, exclude, revoked) {
+    const { readRelease, readCuts, labelsByDigest } = await import("../../lifecycle/release-store.js");
+    const { revocationOf } = await import("../../lifecycle/release-revocation.js");
+    const target = await rollbackTarget({
+        records,
+        exclude,
+        check: async (digest) => {
+            const release = await readRelease(digest).catch(() => null);
+            return { kept: release !== null, revoked: release !== null && revocationOf(release, revoked) !== null };
+        },
+    });
+    if (!target)
+        return null;
+    const labels = await readCuts().then((c) => labelsByDigest(c.cuts), () => new Map());
+    return releaseRollbackLine(env, target, labels.get(target));
+}
+/**
+ * Refuse a rollback or a redeploy that would put back a release cut from a
+ * revoked commit (#4033, #4035), naming the release to go back to instead.
+ * Returns the exit code of the refusal, or undefined when nothing restored
+ * names a revoked release.
+ */
+async function refuseRevokedRestore(verb, plan, records) {
+    const named = [...new Set(plan.items.map((i) => i.source.releaseDigest).filter((d) => d !== undefined))];
+    if (named.length === 0)
+        return undefined;
+    const revoked = await revokedOrRefuse(`the release this ${verb} restores`);
+    if (typeof revoked === "number")
+        return revoked;
+    if (revoked.size === 0)
+        return undefined;
+    const { readRelease, readCuts, labelsByDigest } = await import("../../lifecycle/release-store.js");
+    const { revocationOf, revokedRefusal } = await import("../../lifecycle/release-revocation.js");
+    for (const digest of named) {
+        const release = await readRelease(digest).catch(() => null);
+        const revocation = release ? revocationOf(release, revoked) : null;
+        if (!revocation)
+            continue;
+        const labels = await readCuts().then((c) => labelsByDigest(c.cuts), () => new Map());
+        const back = await rollbackLineFor(plan.to, records, new Set([digest]), revoked);
+        console.error(formatError(revokedRefusal({ releaseDigest: digest, label: labels.get(digest) ?? null }, revocation, back ? `Restore a release cut from a green commit instead: ${back}` : `No other release "${plan.to}" ran is kept and green; promote a release cut from a green commit (\`chant ci last-green\` names the newest).`)));
+        console.error(formatError({ message: "nothing was deployed" }));
+        return 1;
+    }
+    return undefined;
+}
 export async function runComponentsPromote(ctx) {
     const { args } = ctx;
-    const from = args.migrateFrom;
     const to = args.migrateTo;
-    if (!from || !to) {
-        console.error(formatError({ message: "--from <env> and --to <env> are required", hint: PROMOTE_USAGE }));
+    if (!to) {
+        console.error(formatError({ message: "--to <env> is required", hint: PROMOTE_USAGE }));
         return 1;
     }
     const who = actorOrRefuse(ctx);
@@ -259,6 +590,24 @@ export async function runComponentsPromote(ctx) {
     const project = await loadProject(ctx, args.component ?? "all");
     if (typeof project === "number")
         return project;
+    // The member's `environments` array is its promotion order (#4030). It
+    // defaults --from and refuses a skipped step; a member that declares none
+    // has no order, so --from is required and nothing is refused.
+    const resolved = resolvePromotionSource({
+        order: promotionOrder(project.config.environments),
+        to,
+        ...(args.migrateFrom ? { from: args.migrateFrom } : {}),
+        ...(args.allowSkip ? { allowSkip: true } : {}),
+    });
+    if ("error" in resolved) {
+        console.error(formatError({ message: `${resolved.error.message} [${resolved.error.code}]`, hint: resolved.error.fix }));
+        return 1;
+    }
+    const from = resolved.from;
+    if (!from) {
+        console.error(formatError({ message: "--from <env> is required: this member declares no environments, so there is no promotion order to default it from", hint: PROMOTE_USAGE }));
+        return 1;
+    }
     // Without --component, each --digest is <component>=<digest> (#2602): a
     // generated promote job pins every component to the release its own
     // pipeline run recorded, rather than whatever is latest in --from.
@@ -277,6 +626,14 @@ export async function runComponentsPromote(ctx) {
         return 1;
     }
     await fetchLifecycle().catch(() => false);
+    // #4026: --release names the release this promote deploys, by label or digest.
+    let under;
+    if (args.release) {
+        const found = await resolveUnderRelease(args.release, to, "promote", () => "Promote a release cut from a green commit: `chant ci last-green` names the newest, and `chant release list` marks the revoked releases. Fetch the tags first: git fetch origin --tags");
+        if (typeof found === "number")
+            return found;
+        under = found;
+    }
     const plan = planPromotion({
         from,
         to,
@@ -290,25 +647,36 @@ export async function runComponentsPromote(ctx) {
         console.error(formatError({ message: plan.error, hint: PROMOTE_USAGE }));
         return 1;
     }
-    return deployPlan(ctx, "promote", plan, project, who.actor, promotionRecord);
+    return deployPlan(ctx, "promote", plan, project, who.actor, promotionRecord, under);
 }
 export async function runComponentsRollback(ctx) {
     const { args } = ctx;
     const env = args.extraPositional;
-    if (!env || !args.component) {
-        console.error(formatError({ message: "an environment and --component <name> are required", hint: ROLLBACK_USAGE }));
+    if (!env || (!args.component && !args.release)) {
+        console.error(formatError({ message: "an environment and --component <name> or --release <label|digest> are required", hint: ROLLBACK_USAGE }));
+        return 1;
+    }
+    if (args.component && args.release) {
+        console.error(formatError({ message: "--release rolls back every component of a release, so it does not take --component", hint: ROLLBACK_USAGE }));
+        return 1;
+    }
+    if (args.release && args.digest) {
+        console.error(formatError({ message: "--digest picks one release of one component, so it needs --component, not --release", hint: ROLLBACK_USAGE }));
         return 1;
     }
     const who = actorOrRefuse(ctx);
     if (typeof who === "number")
         return who;
+    if (args.release)
+        return runReleaseRollback(ctx, env, args.release, who.actor);
     const project = await loadProject(ctx, args.component);
     if (typeof project === "number")
         return project;
     await fetchLifecycle().catch(() => false);
+    const records = await readLedger(env);
     const plan = planRollback({
         env,
-        records: await readLedger(env),
+        records,
         declared: project.targets.map((c) => c.name),
         component: args.component,
         ...(args.digest ? { digest: args.digest } : {}),
@@ -317,8 +685,48 @@ export async function runComponentsRollback(ctx) {
         console.error(formatError({ message: plan.error, hint: ROLLBACK_USAGE }));
         return 1;
     }
+    const refused = await refuseRevokedRestore("rollback", plan, records);
+    if (refused !== undefined)
+        return refused;
     return deployPlan(ctx, "rollback", plan, project, who.actor, rollbackRecord);
 }
+/**
+ * `chant components rollback <env> --release <label|digest>` (#4035): a
+ * gated promote of an earlier release into `env`. Every component of the
+ * release is restored at the digest `env` recorded running it from that
+ * release, its deploy reads the templates the release recorded for `env`,
+ * and its gates bind the release's change set planned against what `env`
+ * runs now, as `promote --release` binds them (#4045).
+ */
+async function runReleaseRollback(ctx, env, ref, actor) {
+    const project = await loadProject(ctx, "all");
+    if (typeof project === "number")
+        return project;
+    await fetchLifecycle().catch(() => false);
+    const records = await readLedger(env);
+    const under = await resolveUnderRelease(ref, env, "rollback", async (release) => {
+        const revoked = await revokedOrRefuse("the release before it").then((r) => (typeof r === "number" ? new Map() : r));
+        const back = await rollbackLineFor(env, records, new Set([release.releaseDigest]), revoked);
+        return back ? `Roll back to a release cut from a green commit: ${back}` : "Roll back to a release cut from a green commit; `chant release list` marks the revoked releases.";
+    });
+    if (typeof under === "number")
+        return under;
+    const { readDeployOutcomes } = await import("../../lifecycle/deploy-outcome.js");
+    const outcomes = await readDeployOutcomes(env).catch(() => []);
+    const plan = planReleaseRollback({
+        env,
+        records,
+        declared: project.targets.map((c) => c.name),
+        release: under.release,
+        label: under.label,
+        unsettled: new Set(unsettledComponents(records, outcomes).keys()),
+    });
+    if ("error" in plan) {
+        console.error(formatError({ message: plan.error, hint: ROLLBACK_USAGE }));
+        return 1;
+    }
+    return deployPlan(ctx, "rollback", plan, project, actor, rollbackRecord, under);
+}
 export async function runComponentsRedeploy(ctx) {
     const { args } = ctx;
     const env = args.extraPositional;
@@ -333,9 +741,10 @@ export async function runComponentsRedeploy(ctx) {
     if (typeof project === "number")
         return project;
     await fetchLifecycle().catch(() => false);
+    const records = await readLedger(env);
     const plan = planRedeploy({
         env,
-        records: await readLedger(env),
+        records,
         declared: project.targets.map((c) => c.name),
         component: args.component,
         ...(args.digest ? { digest: args.digest } : {}),
@@ -344,5 +753,8 @@ export async function runComponentsRedeploy(ctx) {
         console.error(formatError({ message: plan.error, hint: REDEPLOY_USAGE }));
         return 1;
     }
+    const refused = await refuseRevokedRestore("redeploy", plan, records);
+    if (refused !== undefined)
+        return refused;
     return deployPlan(ctx, "redeploy", plan, project, who.actor, redeployRecord);
 }