@intentius/chant 0.124.32 → 0.124.33

package/src/components/driver.ts

@@ -52,6 +52,7 @@ import { evaluateGate, gitGateLedgerPort, type GateDigestMismatch, type GateLedg
 import { gateName } from "../op/gate-name";
 import { GateNotRecordableError } from "../lifecycle/no-record";
 import { componentPlanDigest } from "./gate-plan";
+import { componentDeployInputs } from "./deploy-inputs";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import type { CapabilityRegistry, DeployContext } from "./capability";
 import { isPlanMovedError, PLAN_MOVED_EXIT_CODE } from "./capability";
@@ -853,6 +854,13 @@ async function rollbackExecuted(
 
 // ── Per-component deploy ─────────────────────────────────────────────────
 
+/** Whether a component's composition has a gate step anywhere, nested phases and `rollback` included. */
+function hasGateStep(component: DriverComponent): boolean {
+  const walk = (steps: DriverPhase["steps"]): boolean =>
+    steps.some((step) => isGateStep(step) || (Array.isArray((step as DriverPhase).steps) && walk((step as DriverPhase).steps)));
+  return [...component.deploy, ...(component.rollback ?? [])].some((p) => walk(p.steps));
+}
+
 /**
  * Run one component's `deploy` composition. On terminal failure: unwind every
  * executed step in reverse via its capability's `rollback` (saga
@@ -900,6 +908,9 @@ export async function runComponentDeploy(
         component,
         ...(ctx.vars ? { vars: ctx.vars } : {}),
         ...(release !== undefined ? { release } : {}),
+        // #4155: the files the steps deploy from, read where the steps read
+        // them. Only a gate reads the digest, so a run with none skips the hashing.
+        ...(hasGateStep(component) ? { inputs: componentDeployInputs(component.deploy, process.cwd()).inputs } : {}),
       }),
   };
   const records: DriverStepRecord[] = [];

package/src/components/gate-plan.ts

@@ -17,6 +17,11 @@
  *   its publish output against a recorded digest that is not in the
  *   composition, so it passes that digest here.
  * - `vars`, the environment config the caller resolved ahead of the run.
+ * - The content digests of the local files the steps deploy from (#4155,
+ *   ./deploy-inputs.ts): a chart, a manifest, a site's tree, a build step's
+ *   sources. A file changed after review moves the digest. The key is left
+ *   out when no step names an existing file, so a composition that deploys
+ *   none keeps the digest it had before #4155.
  *
  * ## What it leaves out
  *
@@ -28,6 +33,7 @@
  */
 
 import { computePlanDigest } from "../lifecycle/plan-digest";
+import type { DeployInputDigest } from "./deploy-inputs";
 import type { DriverComponent } from "./driver";
 
 /** What a component gate's plan digest is taken over. */
@@ -37,6 +43,8 @@ export interface ComponentGatePlan {
   vars?: Record<string, unknown>;
   /** The recorded digest a promote or rollback deploys, when the caller has one. */
   release?: string;
+  /** What the steps deploy from (`componentDeployInputs`), when the caller read it. */
+  inputs?: readonly DeployInputDigest[];
 }
 
 /** The plan digest a component gate records and approves. */
@@ -49,5 +57,6 @@ export function componentPlanDigest(plan: ComponentGatePlan): string {
     rollback: component.rollback ?? null,
     vars: plan.vars ?? null,
     release: plan.release ?? null,
+    ...(plan.inputs && plan.inputs.length > 0 ? { inputs: plan.inputs } : {}),
   });
 }

package/src/components/pr-pipeline.ts

@@ -1,6 +1,7 @@
 /**
  * The jobs of a generated pull-request pipeline (#3183): a plan job on every
- * pull request and an apply job on every push to the target branch.
+ * pull request and, on every push to the target branch, a record job, or an
+ * apply job when the pipeline opts into apply on merge (#4168).
  *
  * Each forge's generator (the github, gitlab and forgejo lexicons) adds its
  * own triggers, permissions and artifact handling; the commands and the
@@ -9,11 +10,19 @@
  * - The plan job runs `chant components pr-plan` against the pull request's
  *   target commit. It posts the note and the `chant/plan` status and writes
  *   nothing to `chant/lifecycle`, since it runs the pull request's code.
- * - The apply job runs `chant components pr-apply` against the commit the
+ * - The record job (#4168 step 1, the default) runs `chant components
+ *   pr-record` against the commit the push replaced. It plans the same
+ *   members on the merged commit, stores the change set and writes the merge
+ *   record, `_merges/<commit>.json` on `chant/lifecycle`. It applies nothing:
+ *   a release that carries the commit deploys it. It needs write access to
+ *   `chant/lifecycle`. One record runs at a time per environment.
+ * - With `applyOnMerge` the apply job takes the record job's place. It runs
+ *   `chant components pr-apply` against the commit the
  *   push replaced, finds the pull request that merged the pushed commit
  *   through the forge, and applies only when an approval stands for the
- *   digest it plans. With `requireReview` (the default) the approver must
- *   also have approved the pull request on the forge. It needs write access
+ *   digest it plans. With `requireReview` (off by default since #4168, on
+ *   under the `review-rules` security group) the approver must also have
+ *   approved the pull request on the forge. It needs write access
  *   to `chant/lifecycle`, to record the pending fact when the gate stops it.
  *   One apply runs at a time per environment.
  *
@@ -35,6 +44,7 @@
  * it too. With `reportUrl` both pass `--report-url`, which copies the report,
  * the change set and the events where a reader outside CI can fetch them;
  * the job's own environment brings the credentials an `s3://` URL needs.
+ * The record job passes the same flags as the apply.
  *
  * With `build` (#4088) both jobs run the project's build and `chant lint`
  * before their command, and fail on an error. A `cfn-deploy` member's plan
@@ -123,8 +133,16 @@ export interface PrLoopPipelineOptions {
    * GitHub and Forgejo; on GitLab, the project's default branch.
    */
   branch?: string;
-  /** Count an approval only from someone who approved the pull request on the forge. Default true. */
+  /** Count an approval only from someone who approved the pull request on the forge. Default false (#4168): review rules are opt-in. */
   requireReview?: boolean;
+  /** The job on merge (apply, or record since #4168) has `chant ci run` refuse to start without a runner-start statement for it (`--require-runner-start`, #4147), as under the `isolated-runners` security group (#4168). Default false. */
+  requireRunnerStart?: boolean;
+  /**
+   * Apply the approved plan on merge (#4168), as every pull-request pipeline
+   * did before #4168: the apply job in place of the record job. Default
+   * false, so a merge deploys nothing. `waveGate` needs it.
+   */
+  applyOnMerge?: boolean;
   /**
    * Stream each job's run events (#4007): `--events-json` on both commands,
    * and `CHANT_RUN_EVENTS_DIR` set to {@link PR_LOOP_EVENTS_DIR}. Default false.
@@ -166,8 +184,8 @@ export interface PrLoopPipelineOptions {
 
 /** One job's command and the forge values it reads, as environment variables for its step. */
 export interface PrLoopJob {
-  /** `plan` or `apply`. */
-  jobName: "plan" | "apply";
+  /** `plan`, `apply` or `record` (#4168). */
+  jobName: "plan" | "apply" | "record";
   /** The command line. Reads `$BASE_SHA` and, for the plan, `$PR_NUMBER`. */
   command: string;
   /**
@@ -200,9 +218,10 @@ export function prLoopBuildLines(env: string, options: PrLoopPipelineOptions = {
 }
 
 /**
- * The two jobs for `forge`. `member` is the workspace member the pipeline is
- * generated for; the commands then run in its directory, so `--output` is
- * relative to it.
+ * The jobs for `forge`: plan, apply and record, in that order. A generator
+ * writes the plan and, on merge, {@link prLoopMergeJob}'s choice of the
+ * other two. `member` is the workspace member the pipeline is generated for;
+ * the commands then run in its directory, so `--output` is relative to it.
  */
 export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelineOptions = {}, member?: string): PrLoopJob[] {
   const gate = options.gate ?? PR_APPLY_GATE;
@@ -220,13 +239,14 @@ export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelin
     ...(options.events ? { CHANT_RUN_EVENTS_DIR: PR_LOOP_EVENTS_DIR } : {}),
   };
   // #4156: the flags `chant ci run` rebuilds `command` from. It finds the member from the directory it runs in.
-  const ciRun = (job: "plan" | "apply"): string[] => [
+  const ciRun = (job: PrLoopJob["jobName"]): string[] => [
     "chant", "ci", "run", job, "--in-place", ...(job === "plan" ? ["--no-push"] : []),
     "--base", '"$BASE_SHA"', ...(job === "plan" ? ["--pr", '"$PR_NUMBER"'] : []),
     "--env", env, "--gate", gate, "--forge", forge,
-    ...(options.waveGate ? ["--wave-gate", options.waveGate] : []),
-    ...(job === "apply" && options.branch ? ["--branch", JSON.stringify(options.branch)] : []),
-    ...(job === "apply" && options.requireReview === false ? ["--no-require-review"] : []),
+    ...(job !== "record" && options.waveGate ? ["--wave-gate", options.waveGate] : []),
+    ...(job !== "plan" && options.branch ? ["--branch", JSON.stringify(options.branch)] : []),
+    ...(job === "apply" && options.requireReview === true ? ["--require-review"] : []),
+    ...(job !== "plan" && options.requireRunnerStart === true ? ["--require-runner-start"] : []),
     ...(options.events ? ["--events-json"] : []),
     ...(options.reportUrl ? ["--report-url", JSON.stringify(options.reportUrl)] : []),
   ];
@@ -248,7 +268,7 @@ export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelin
       jobName: "apply",
       command: [
         "chant", "components", "pr-apply", "--base", '"$BASE_SHA"', ...common,
-        ...(options.requireReview === false ? [] : ["--require-review"]),
+        ...(options.requireReview === true ? ["--require-review"] : []),
         ...(options.waveGate ? ["--wave-gate", options.waveGate] : []),
         "--resume", PR_APPLY_RECORD,
       ].join(" "),
@@ -257,9 +277,22 @@ export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelin
       ...build,
       run: { command: ciRun("apply").join(" "), env: runEnv(applyEnv) },
     },
+    {
+      jobName: "record",
+      command: ["chant", "components", "pr-record", "--base", '"$BASE_SHA"', ...common].join(" "),
+      env: applyEnv,
+      setup: [github ? githubBaseFallback(options.branch) : gitlabBaseFallback(options.branch)],
+      ...build,
+      run: { command: ciRun("record").join(" "), env: runEnv(applyEnv) },
+    },
   ];
 }
 
+/** The job a push to the target branch runs (#4168): `record`, or `apply` when the pipeline opts into apply on merge. */
+export function prLoopMergeJob(jobs: readonly PrLoopJob[], options: PrLoopPipelineOptions = {}): PrLoopJob {
+  return jobs.find((j) => j.jobName === (options.applyOnMerge ? "apply" : "record"))!;
+}
+
 /**
  * The pull-request options with `--wave-gate` beside `--pr-loop` (#4003):
  * the apply gets a gate per wave. A canary or a fixed base is refused, since
@@ -268,6 +301,9 @@ export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelin
  */
 export function prLoopWithWaves(prLoop: PrLoopPipelineOptions, gatedWaves?: GatedWavePipelineOptions): PrLoopPipelineOptions {
   if (!gatedWaves) return prLoop;
+  if (!prLoop.applyOnMerge) {
+    throw new Error("--wave-gate beside --pr-loop gates the apply on merge, so it needs --apply-on-merge (#4168); without it a merge records the plan and a release deploys it");
+  }
   if (gatedWaves.canary?.length) throw new Error("a pull-request pipeline's waves are the change's derivation, so it takes no --canary; drop --canary");
   if (gatedWaves.base !== undefined) throw new Error("a pull-request pipeline measures each push from the commit before it, so it takes no --base; drop --base");
   return { ...prLoop, waveGate: gatedWaves.gate };
@@ -310,6 +346,11 @@ export function prApplyGroup(env: string, member?: string): string {
   return member ? `chant-apply.${member}.${env}` : `chant-apply-${env}`;
 }
 
+/** The group that keeps one record job at a time per environment and member (#4168), named as {@link prApplyGroup} names the apply's. */
+export function prRecordGroup(env: string, member?: string): string {
+  return member ? `chant-record.${member}.${env}` : `chant-record-${env}`;
+}
+
 /**
  * The cache key the apply job keeps its attempt record under (#3543), with
  * `commit` the forge's expression for the pushed commit. A push of another

package/src/components/pr-run.ts

@@ -737,7 +737,7 @@ export function waveNotCovered(approved: ChangeSetDocument, fresh: ChangeSetDocu
 }
 
 export interface PrReportInput {
-  stage: "plan" | "apply";
+  stage: "plan" | "apply" | "record";
   pr: number | null;
   env: string;
   /** The workspace member whose pipeline runs the stage (#3465). */

package/src/components/release-compile.test.ts

@@ -13,6 +13,7 @@ import {
   buildReleaseArtifacts,
   buildStepsOf,
   compileEnvironment,
+  recordedInputRefs,
   ReleaseCompileError,
   templateRefs,
   withOnlyArchiveSteps,
@@ -49,6 +50,18 @@ describe("templateRefs", () => {
   });
 });
 
+describe("recordedInputRefs (#4155)", () => {
+  test("adds each kind's own fields to the template fields: a chart; a missing one need not exist", () => {
+    expect(recordedInputRefs(api).map((r) => [r.kind, r.field, r.path, r.required])).toEqual([
+      ["cfn-deploy", "template", "dist/api.template.json", true],
+      ["cfn-deploy", "template", "dist/edge.template.json", true],
+      ["helm-upgrade", "values", "values/base.yaml", true],
+      ["helm-upgrade", "chart", "charts/api", false],
+      ["kubectl-apply", "manifest", "k8s/api.yaml", true],
+    ]);
+  });
+});
+
 describe("withOnlyArchiveSteps", () => {
   test("keeps the archive steps alone, drops gates and every other step, and the dependencies", () => {
     expect(withOnlyArchiveSteps(api)).toEqual({
@@ -100,6 +113,27 @@ describe("compileEnvironment", () => {
     });
   });
 
+  test("records a chart directory file by file and names it in trees; a file that is not UTF-8 as base64 (#4155)", async () => {
+    await withTestDir(async (dir) => {
+      writeFileSync(
+        join(dir, "web.component.ts"),
+        `export const web = { name: "web", dependsOn: [], deploy: [{ phase: "Deploy", steps: [
+          { kind: "helm-upgrade", release: "web", chart: "chart" },
+          { kind: "helm-upgrade", release: "remote", chart: "bitnami/nginx", repo: "https://charts.example" },
+        ] }] };`,
+      );
+      mkdirSync(join(dir, "chart", "charts"), { recursive: true });
+      writeFileSync(join(dir, "chart", "Chart.yaml"), "name: web\n");
+      writeFileSync(join(dir, "chart", "charts", "dep.tgz"), Buffer.from([0x1f, 0x8b, 0xff, 0x00]));
+      const target = await compileEnvironment({ projectDir: dir }, "prod");
+      expect(target.trees).toEqual([{ component: "web", path: "chart" }]);
+      expect(target.templates).toEqual([
+        { component: "web", path: "chart/Chart.yaml", content: "name: web\n" },
+        { component: "web", path: "chart/charts/dep.tgz", content: Buffer.from([0x1f, 0x8b, 0xff, 0x00]).toString("base64"), encoding: "base64" },
+      ]);
+    });
+  });
+
   test("refuses when a template a deploy names does not exist after the build", async () => {
     await withTestDir(async (dir) => {
       project(dir);

package/src/components/release-compile.ts

@@ -15,7 +15,14 @@
  * ./promote.ts: a literal path in a deploy step's `template`, `manifest` or
  * `values` field ({@link TEMPLATE_FIELDS}), read after the environment's build
  * command has run. A path with the `archive:` prefix names the file after it.
- * A path that names a directory, such as a chart, is not a template.
+ *
+ * Since #4155 a cut also records the other local paths a deploy step names
+ * ({@link recordedInputRefs}: a Helm chart, a kustomize directory, a sync's
+ * source tree, the fields `./deploy-inputs.ts` lists). A directory is
+ * recorded file by file and named in the target's `trees`; a file that is not
+ * UTF-8 is recorded as base64. Such a path that does not exist after the
+ * build, as a chart named from a repository, is not recorded, and the
+ * promote leaves it as written.
  *
  * A project with no components (#4046) is compiled the way `chant build --env
  * <env> -o <output>` builds it ({@link compileBuildOutput}): every file that
@@ -25,6 +32,7 @@
  */
 
 import { spawn, spawnSync } from "node:child_process";
+import { isUtf8 } from "node:buffer";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
 import { loadChantConfig, type ChantConfig } from "../config";
@@ -40,7 +48,8 @@ import { memoryGateLedgerPort } from "../op/gate";
 import type { ReleaseArtifact, ReleaseParam } from "../lifecycle/release-store";
 
 /** The deploy step fields whose literal file paths are a component's templates. */
-export const TEMPLATE_FIELDS: readonly string[] = ["template", "manifest", "values"];
+export { TEMPLATE_FIELDS } from "./deploy-inputs";
+import { DEPLOY_INPUT_FIELDS, directoryFiles, ignoredByGit, TEMPLATE_FIELDS, walkFiles } from "./deploy-inputs";
 
 /** The prefix a step may write before an archive-relative template path. */
 const ARCHIVE_PREFIX = "archive:";
@@ -61,7 +70,9 @@ export interface TemplateRef {
 export interface CompiledTemplate {
   component: string | null;
   path: string;
+  /** The text, or the base64 of the bytes under `encoding: "base64"`. */
   content: string;
+  encoding?: "base64";
 }
 
 /** What one environment compiles to. */
@@ -84,6 +95,8 @@ export interface CompiledTarget {
   /** For each component, the file that declares it, relative to the member's directory. */
   componentFiles: Record<string, string>;
   templates: CompiledTemplate[];
+  /** The directories recorded file by file in `templates` (#4155). Absent from a compiler written before #4155. */
+  trees?: Array<{ component: string | null; path: string }>;
 }
 
 /** Compiles a member for one environment, and builds its artifacts. The cut talks to a compiler only, so a test can hand it fixtures. */
@@ -134,6 +147,40 @@ export function templateRefs(component: DriverComponent): TemplateRef[] {
   return out;
 }
 
+/** A path a deploy step names that a cut records (#4155): a {@link TemplateRef}, and whether its field is a template field, which must exist. */
+export interface RecordedInputRef extends TemplateRef {
+  /** True for `template`, `manifest` and `values`, whose path must exist after the build. */
+  required: boolean;
+}
+
+/** Every literal path a component's deploy names that a cut records: {@link templateRefs}, plus each kind's own fields in `DEPLOY_INPUT_FIELDS`. */
+export function recordedInputRefs(component: DriverComponent): RecordedInputRef[] {
+  const out: RecordedInputRef[] = [];
+  for (const { phase, step } of stepsOf(component.deploy)) {
+    if (BUILD_STEP_KINDS.includes(step.kind) || PUBLISH_STEP_KINDS.includes(step.kind)) continue;
+    for (const field of recordedFields(step.kind)) {
+      const raw = step[field];
+      for (const value of Array.isArray(raw) ? raw : [raw]) {
+        if (!isLiteralPath(value)) continue;
+        const path = value.startsWith(ARCHIVE_PREFIX) ? value.slice(ARCHIVE_PREFIX.length) : value;
+        out.push({ component: component.name, phase, kind: step.kind, field, value, path, required: TEMPLATE_FIELDS.includes(field) });
+      }
+    }
+  }
+  return out;
+}
+
+/** The fields of a step of `kind` whose paths a cut records and a promote points at the recorded copy. */
+export function recordedFields(kind: string): string[] {
+  return [...TEMPLATE_FIELDS, ...(DEPLOY_INPUT_FIELDS[kind] ?? [])];
+}
+
+/** A file's bytes as a template: its text when it is UTF-8, else base64. */
+export function templateOf(component: string | null, path: string, file: string): CompiledTemplate {
+  const bytes = readFileSync(file);
+  return isUtf8(bytes) ? { component, path, content: bytes.toString("utf-8") } : { component, path, content: bytes.toString("base64"), encoding: "base64" };
+}
+
 /** A component's build-time steps ({@link BUILD_STEP_KINDS}), each as declared, in composition order. */
 export function buildStepsOf(component: DriverComponent): DriverStep[] {
   return stepsOf(component.deploy).map((s) => s.step).filter((s) => BUILD_STEP_KINDS.includes(s.kind));
@@ -191,8 +238,19 @@ export interface CompileInputs {
   output?: string;
   /** For a project with no components: build only this lexicon, as `chant build --lexicon` does. */
   lexicon?: string;
+  /**
+   * The release's label (#4168, decision 5), passed to every compile and
+   * artifact build as `CHANT_RELEASE_LABEL`, so a version reaches the build
+   * without a version-bump commit. A build parameter reads it by declaring
+   * `env: "CHANT_RELEASE_LABEL"`, and a build step's own tool (cargo, npm)
+   * reads the variable. Unset for a cut with no label.
+   */
+  releaseLabel?: string;
 }
 
+/** The variable a cut's label reaches the build through (#4168). */
+export const RELEASE_LABEL_ENV = "CHANT_RELEASE_LABEL";
+
 /**
  * Where a project with no components writes its build output when the cut
  * names no `-o`. YAML, since the k8s and helm serializers write YAML whatever
@@ -258,21 +316,33 @@ export async function compileEnvironment(inputs: CompileInputs, env: string): Pr
   if (declared === 0) return compileBuildOutput(inputs, env, config);
   const rel = (p: string): string => (isAbsolute(p) ? relative(inputs.projectDir, p) : p);
   const templates: CompiledTemplate[] = [];
+  const trees: Array<{ component: string; path: string }> = [];
   const seen = new Set<string>();
   for (const { component } of components) {
-    for (const ref of templateRefs(component)) {
+    for (const ref of recordedInputRefs(component)) {
       const key = `${ref.component}\u0000${ref.path}`;
       if (seen.has(key)) continue;
       seen.add(key);
       const file = resolve(inputs.projectDir, ref.path);
       if (!existsSync(file)) {
+        if (!ref.required) continue;
         throw new ReleaseCompileError(
           `component "${ref.component}": its ${ref.kind} step in phase "${ref.phase}" reads ${ref.field} "${ref.value}", ` +
             `and no such file exists after the build for "${env}"`,
         );
       }
-      if (!statSync(file).isFile()) continue;
-      templates.push({ component: ref.component, path: ref.path, content: readFileSync(file, "utf-8") });
+      if (statSync(file).isFile()) {
+        templates.push(templateOf(ref.component, ref.path, file));
+        continue;
+      }
+      // #4155: a directory, file by file. One git ignores is the build's output, recorded whole.
+      const files = ignoredByGit(inputs.projectDir, ref.path) ? walkFiles(inputs.projectDir, ref.path) : directoryFiles(inputs.projectDir, ref.path);
+      const dir = ref.path.replace(/\/+$/, "");
+      for (const f of files) {
+        const under = relative(resolve(inputs.projectDir, dir), resolve(inputs.projectDir, f)).split("\\").join("/");
+        templates.push(templateOf(ref.component, `${dir}/${under}`, resolve(inputs.projectDir, f)));
+      }
+      trees.push({ component: ref.component, path: dir });
     }
   }
   return {
@@ -284,6 +354,7 @@ export async function compileEnvironment(inputs: CompileInputs, env: string): Pr
     buildInputs: Object.fromEntries(components.map(({ component }) => [component.name, buildInputPaths(component)])),
     componentFiles: Object.fromEntries(components.map(({ component, file }) => [component.name, rel(file)])),
     templates,
+    trees,
   };
 }
 
@@ -408,10 +479,20 @@ export function ownChantCommand(): string[] {
   return [process.execPath, ...process.execArgv, main];
 }
 
-function runChild(command: readonly string[], args: readonly string[], cwd: string, env: string): Promise<{ code: number; stdout: string; stderr: string }> {
+function runChild(
+  command: readonly string[],
+  args: readonly string[],
+  cwd: string,
+  env: string,
+  releaseLabel?: string,
+): Promise<{ code: number; stdout: string; stderr: string }> {
   return new Promise((resolvePromise, reject) => {
     const [bin, ...lead] = command;
-    const child = spawn(bin, [...lead, ...args], { cwd, stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, CHANT_ENV: env } });
+    const childEnv: NodeJS.ProcessEnv = { ...process.env, CHANT_ENV: env };
+    // A label never leaks in from the caller's shell: only the cut sets it.
+    delete childEnv[RELEASE_LABEL_ENV];
+    if (releaseLabel !== undefined) childEnv[RELEASE_LABEL_ENV] = releaseLabel;
+    const child = spawn(bin, [...lead, ...args], { cwd, stdio: ["ignore", "pipe", "pipe"], env: childEnv });
     const out: Buffer[] = [];
     const err: Buffer[] = [];
     child.stdout.on("data", (c: Buffer) => out.push(c));
@@ -440,7 +521,7 @@ export function spawnTargetCompiler(inputs: CompileInputs, command: readonly str
     return args;
   };
   const call = async (env: string, extra: string[]): Promise<unknown> => {
-    const run = await runChild(command, ["release", "compile", "--env", env, ...common(), ...extra, "--json"], inputs.projectDir, env);
+    const run = await runChild(command, ["release", "compile", "--env", env, ...common(), ...extra, "--json"], inputs.projectDir, env, inputs.releaseLabel);
     if (run.code !== 0) throw new ReleaseCompileError(`compiling "${env}" failed (exit ${run.code})`);
     try {
       return JSON.parse(run.stdout);

package/src/components/release-promote.test.ts

@@ -5,13 +5,13 @@
 
 import { describe, test, expect } from "vitest";
 import { contentDigest } from "../content-digest";
-import { makeRelease } from "../lifecycle/release-store";
+import { makeRelease, templateBytesDigest } from "../lifecycle/release-store";
 import type { DriverComponent } from "./driver";
 import { isImplicitRelease, pinReleaseTemplates, releaseArtifactMismatches, removePinnedTemplates, targetFiles, targetFor, writePinnedTemplates, RELEASE_TEMPLATES_DIR } from "./release-promote";
 import type { ReleaseRecord } from "../lifecycle/release-ledger";
 import type { BuildArchiveManifest } from "./verbs/build-archive";
 import { withTestDir } from "@intentius/chant-test-utils";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 const prodTemplate = `{"env":"prod"}\n`;
@@ -63,6 +63,59 @@ describe("pinReleaseTemplates", () => {
     expect("errors" in absent && absent.errors[0]).toMatch(/are not on the chant\/lifecycle branch/);
   });
 
+  test("a target cut since #4155 points a chart at its recorded tree, which a reader of the release can trust", async () => {
+    const chartFile = "name: web\n";
+    const tgz = Buffer.from([0x1f, 0x8b, 0xff]).toString("base64");
+    const tgzDigest = templateBytesDigest(tgz, "base64");
+    const cut = makeRelease({
+      member: null,
+      commit: "c".repeat(40),
+      artifactDigests: [],
+      targets: [{
+        env: "prod",
+        params: [],
+        templates: [
+          { component: "web", path: "chart/Chart.yaml", digest: contentDigest(chartFile) },
+          { component: "web", path: "chart/charts/dep.tgz", digest: tgzDigest, encoding: "base64" },
+        ],
+        trees: [{ component: "web", path: "chart" }],
+      }],
+    });
+    const web: DriverComponent = {
+      name: "web",
+      deploy: [{ phase: "Deploy", steps: [
+        { kind: "helm-upgrade", release: "web", chart: "chart" },
+        { kind: "helm-upgrade", release: "remote", chart: "bitnami/nginx" },
+      ] }],
+    };
+    const bytes: Record<string, string> = { [contentDigest(chartFile)]: chartFile, [tgzDigest]: tgz };
+    const pinned = await pinReleaseTemplates([web], cut, cut.targets[0]!, async (d, encoding) => (encoding === "base64" && d !== tgzDigest ? null : bytes[d] ?? null));
+    if ("errors" in pinned) throw new Error(pinned.errors.join("\n"));
+    const step = pinned.components[0]!.deploy[0]!.steps[0] as unknown as { chart: string };
+    expect(step.chart).toMatch(/^\.chant\/release-templates\/[^/]+\/chart$/);
+    expect(pinned.files.map((f) => f.path.slice(step.chart.length + 1)).sort()).toEqual(["Chart.yaml", "charts/dep.tgz"]);
+    expect(pinned.files.find((f) => f.path.endsWith("dep.tgz"))).toMatchObject({ encoding: "base64", content: tgz });
+    // A chart named from a repository is not a local path the release records, and is left as written.
+    expect(pinned.components[0]!.deploy[0]!.steps[1]).toEqual(web.deploy[0]!.steps[1]);
+
+    await withTestDir(async (dir) => {
+      writePinnedTemplates(dir, pinned.files);
+      expect(readFileSync(join(dir, step.chart, "charts", "dep.tgz"))).toEqual(Buffer.from([0x1f, 0x8b, 0xff]));
+      removePinnedTemplates(dir, pinned.files);
+      expect(existsSync(join(dir, RELEASE_TEMPLATES_DIR))).toBe(false);
+    });
+
+    const edited = await pinReleaseTemplates([web], cut, cut.targets[0]!, async (d) => (d === contentDigest(chartFile) ? "name: edited\n" : bytes[d] ?? null));
+    expect("errors" in edited && edited.errors.join("\n")).toMatch(/template "chart\/Chart.yaml" hashes to .* refusing to deploy it/);
+  });
+
+  test("a target cut before #4155 (no trees) is pinned as then: the chart is read from the checkout", async () => {
+    const web: DriverComponent = { name: "api", deploy: [{ phase: "Deploy", steps: [{ kind: "helm-upgrade", release: "web", chart: "chart" }, ...api.deploy[1]!.steps] }] };
+    const pinned = await pinReleaseTemplates([web], release, prod, store(prodTemplate));
+    if ("errors" in pinned) throw new Error(pinned.errors.join("\n"));
+    expect(pinned.components[0]!.deploy[0]!.steps[0]).toEqual({ kind: "helm-upgrade", release: "web", chart: "chart" });
+  });
+
   test("targetFor names the environments a release was compiled for", () => {
     expect(targetFor(release, "prod")).toEqual({ target: prod });
     expect(targetFor(release, "qa")).toEqual({ error: expect.stringMatching(/has no target for "qa"; it was compiled for prod, staging/) });