@intentius/chant 0.124.32 → 0.124.33

package/src/cli/main.ts

@@ -249,22 +249,28 @@ CI:
                         chant/lifecycle; with ci.green.signedSince, the ones a
                         runner key signed. Pushes the
                         tags. --key, or the PEM in CHANT_RUNNER_KEY, signs
-                        each tag with a runner key.
+                        each tag with a runner key. A cancelled run leaves a
+                        commit unbuilt, not red, and a failed run is run
+                        again once. A phase with build: newest leaves the
+                        commits a newer run superseded unbuilt, and a red
+                        one starts a bisect: a ci/build/<sha> tag the tick
+                        starts the phase's workflow at. Each commit judged
+                        gets a _ci/<sha>.json record on chant/lifecycle.
   ci run plan|apply --env <env> --base <sha> [--pr <n>] [--commit <sha>]
               [--forge github|gitlab|forgejo] [--gate <name>] [--wave-gate <name>]
               [--branch <name>] [--events-json] [--report-url <url>] [--image <image>]
               [--before-script <line>]... [--pr-build]
               [--pr-build-command <line>] [--chant <command>]
               [--pass-env <NAME>]... [--secrets <file>] [--key <runner key.pem>]
-              [-o <dir>] [--wave <k>] [--no-require-review]
+              [-o <dir>] [--wave <k>] [--require-review]
               [--no-status] [--status-url <url template>]
-              [--in-place | --local] [--no-push] [--verbose]
-                        Run the pull-request pipeline's plan or apply job as
+              [--in-place | --local] [--no-push] [--require-runner-start] [--verbose]
+                        Run the pull-request pipeline's plan, record or apply job as
                         a pipeline Op in a fresh worktree of --commit (default
                         HEAD) with a clean environment. --base and --pr stand
                         in for the forge's event values. --pr-build runs
                         the job's build and lint lines first. Records the run as
-                        pr-plan or pr-apply on chant/lifecycle, which ci tick
+                        pr-plan, pr-record or pr-apply on chant/lifecycle, which ci tick
                         from runs counts, signed when --key or CHANT_RUNNER_KEY
                         gives a runner key, and copies the report to -o
                         (default .chant/pr). --in-place runs in this checkout
@@ -286,17 +292,39 @@ CI:
                         kept on the local chant/lifecycle with runOrigin
                         local and is never pushed, no status is set, nothing
                         goes under a report URL, and ci tick does not count it.
+                        --require-runner-start refuses the job before its
+                        first step unless a runner-start statement, signed by
+                        a runner key .chant/trust.json at --base lists, names
+                        this forge job.
+  ci runner-start sign --key <runner key.pem> --principal <name> --job <json|@file> [-o <file>]
+                        For the provisioner that starts a runner for one job:
+                        sign the job's system, repo, run, attempt, job,
+                        commit and runner name, and print the envelope.
+  ci runner-start verify [--base <rev>] [--commit <sha>] [--json]
+                        In the job: check the statement in CHANT_RUNNER_START,
+                        or the file CHANT_RUNNER_START_FILE names (default
+                        /run/chant/runner-start.json), against the forge's
+                        variables and .chant/trust.json at --base (default
+                        origin/HEAD). Exits 1 unless it verifies.
+  ci run --at <sha>     Ask for every required phase at a commit of the
+                        green branch with a ci/build/<sha> tag, and start the
+                        workflows holding them there on GitHub when a token
+                        is set; otherwise the next tick, or ci serve
+                        --build-command, does.
   ci runs [--report-url <url>] [--json]
                         List the runs in the index at the report URL (default
                         the workspace's ci.reportUrl), newest first.
   ci serve --forge forgejo|github --repo <owner/repo> --env <env>
               [--interval <s>] [--max-jobs <n>] [--state <dir>]
               [--author <login>]... [--once] [--rerun-failed] [--unsigned]
-              [ci run's job flags]
+              [--apply-on-merge] [--build-command <line>] [ci run's job flags]
                         Poll the forge for open pull requests and the target
                         branch's head, and run ci run plan for each new pull
-                        request head and ci run apply for each new commit on
-                        the branch. Dedupes on job and commit in a state file
+                        request head and ci run record for each new commit on
+                        the branch, then ci tick from the runs when the
+                        workspace declares ci.green. A merge deploys nothing;
+                        --apply-on-merge runs ci run apply in place of the
+                        record, and --wave-gate needs it. Dedupes on job and commit in a state file
                         under --state, takes a lease per apply group, keeps
                         each apply's resume record there, and runs at most
                         --max-jobs (default 1) jobs at once. --once runs one
@@ -304,7 +332,10 @@ CI:
                         failed apply or plan again. Signs runs with a runner
                         key when .chant/trust.json at the target's head lists
                         it, and serves unsigned otherwise; with
-                        ci.green.signedSince it refuses to start without one
+                        ci.green.signedSince it refuses to start without one.
+                        --build-command runs <line> once per ci/build/<sha>
+                        tag, in a fresh worktree of the commit, with
+                        CHANT_BUILD_COMMIT and CHANT_BUILD_PHASES set
   ci serve|run --setup-key [--trust [--principal <name>]] [--state <dir>] [--branch <name>]
                         Make the host's runner key (Ed25519, mode 0600) in the
                         state directory when there is none and print its public
@@ -322,10 +353,14 @@ CI:
                         or a GitHub App's id and key, pushes the tags with a
                         token that may tag commits changing workflow files.
                         --runner-key-secret hands the tick the runner key it
-                        signs its tags with.
+                        signs its tags with. For each phase that sets build,
+                        it also writes the triggers and concurrency of the
+                        workflows holding it: newest builds on pushes and by
+                        hand, one run at a time, and every gives each commit
+                        a run of its own.
 
 Releases:
-  release cut [<label>] [--yes] [--build <command>] [--param <k=v>]
+  release cut [<label>] [--at <sha>] [--yes] [--build <command>] [--param <k=v>]
               [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>]
               [--actor <name>] [--sign [<key file>]] [--json]
                         A dry run of a cut of this member from HEAD, which
@@ -344,19 +379,29 @@ Releases:
                         requires it. A project with no components releases
                         what chant build --env <env> writes: --src <dir> is
                         the build root, -o <file> the output (dist/build.yaml),
-                        --lexicon narrows it.
+                        --lexicon narrows it. --at <sha> cuts that commit of
+                        trunk from a temporary worktree instead of HEAD, so
+                        the checkout need not be clean. The label reaches
+                        every compile and build as CHANT_RELEASE_LABEL.
+  release candidates [--env <env>] [--json]
+                        The green commits of trunk a release can be cut from,
+                        newest first, each with the commits, work items, pull
+                        requests and flags it would ship, and what each
+                        environment runs.
   release publish <label|digest> [--yes] [--allow-unsigned]
                   [--require-provenance] [--json]
                         Publish a cut release to the targets release.publish
                         in chant.config.ts declares (npm, OCI registries,
-                        forge release assets), each with an SBOM and the
-                        release's provenance. A dry run without --yes.
-                        Refuses a revoked release, one whose signature does
-                        not verify against .chant/allowed_signers unless
-                        --allow-unsigned, and with a target a checkout that
-                        is not the release's commit. Warns first when the run
-                        has no OIDC token, so what it publishes carries no
-                        OIDC provenance; --require-provenance refuses instead.
+                        forge release assets), each with the release's
+                        provenance and an SBOM when it has a source. A dry
+                        run without --yes. Refuses a revoked release, and
+                        with a target a checkout that is not the release's
+                        commit. Under security verified-releases it refuses
+                        one whose signature does not verify against
+                        .chant/allowed_signers unless --allow-unsigned; under
+                        supply-chain it warns when the run has no OIDC token
+                        and refuses a target with no SBOM source.
+                        --require-provenance refuses a run with no OIDC.
   release verify <label|digest> [--json]
                         Check, offline, that the release was signed by a key
                         .chant/allowed_signers lists at the release's commit.
@@ -887,6 +932,10 @@ Lifecycle (alias: lc):
                             estate size rather than stack count (#2405)
   lifecycle affected        Stacks a change affects (--base <ref> [--include-dependents])
                             --json: emit the ChangeSet as JSON
+  lifecycle health <env>    Whether each declared service is up, separate from
+                            drift: ECS running vs desired, Route 53 health
+                            checks, Container Apps revisions, Cloud Run Ready.
+                            A failed read is "not read", never unhealthy (--json)
   lifecycle whoami <env>    Who chant would act as in each configured lexicon,
                             and what that principal is scoped to — read-only,
                             before anything acts (--json, --strict)
@@ -931,7 +980,12 @@ Component release ledger + status:
                             report and note (--base <ref> --pr <n>
                             [--forge github|gitlab|forgejo] posts them);
                             applies nothing
-  components pr-apply      On merge: plan the same members again and apply
+  components pr-record     On merge (#4168): plan the same members again,
+                            store the change set and write the merge record
+                            _merges/<commit>.json; applies and refuses
+                            nothing, and a plan that differs from the
+                            approved one sets a failing chant/record status
+  components pr-apply      With --apply-on-merge: plan the same members again and apply
                             them only if an approval stands for that digest
                             (chant approve pr-<n> pr-apply --plan <digest>);
                             a moved plan refuses with exit 3
@@ -1386,6 +1440,8 @@ export const commandRegistry: CommandDef[] = [
   // #4094: one pull-request job as a pipeline Op in a fresh checkout, the chant runner's first slice.
   { name: "ci run", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-run")).runCiRun(ctx) },
   // #4098: the run index at the report URL.
+  // #4147: a provisioner's signed word that it started a runner for one job, signed and checked.
+  { name: "ci runner-start", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-runner-start")).runCiRunnerStart(ctx) },
   { name: "ci runs", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-run-index")).runCiRuns(ctx) },
   { name: "ci serve", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-serve")).runCiServe(ctx) },
   // #4026: the release cut from a green commit (ws-104). Imported on first use.
@@ -1394,6 +1450,7 @@ export const commandRegistry: CommandDef[] = [
   { name: "release publish", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleasePublish(ctx) },
   // #4049: check a release's signature offline.
   { name: "release verify", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseVerify(ctx) },
+  { name: "release candidates", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseCandidates(ctx) },
   { name: "release list", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseList(ctx) },
   { name: "release export", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseExport(ctx) },
   { name: "release compile", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseCompile(ctx) },
@@ -1504,6 +1561,8 @@ export const commandRegistry: CommandDef[] = [
   { name: "lifecycle plan", requiresPlugins: true, handler: runLifecyclePlan },
   { name: "lifecycle affected", requiresPlugins: true, handler: runLifecycleAffected },
   { name: "lifecycle whoami", requiresPlugins: true, handler: runLifecycleWhoami },
+  // #4177 — runtime health, separate from drift. Imported on first use.
+  { name: "lifecycle health", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/lifecycle-health")).runLifecycleHealth(ctx) },
   { name: "lifecycle teardown", requiresPlugins: true, handler: runLifecycleTeardown },
   { name: "lifecycle log", handler: runLifecycleLog },
   // #4036 — retention's garbage collection. Imported on first use.
@@ -1519,6 +1578,7 @@ export const commandRegistry: CommandDef[] = [
   // #3183 — the pull-request loop the generated CI runs. Imported on first use.
   { name: "components pr-plan", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/pr")).runComponentsPrPlan(ctx) },
   { name: "components pr-apply", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/pr")).runComponentsPrApply(ctx) },
+  { name: "components pr-record", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/pr")).runComponentsPrRecord(ctx) },
   { name: "components status", requiresPlugins: true, handler: runComponentsStatus },
   { name: "components release", handler: runComponentsReleaseRecord },
   { name: "components export", handler: runComponentsExport },

package/src/cli/parse-args.ts

@@ -70,6 +70,7 @@ const BOOLEAN_FLAGS = new Set([
   "--trust",
   "--unsigned",
   "--in-place",
+  "--require-runner-start",
   "--no-push",
   "--no-require-review",
   "--expire",
@@ -409,9 +410,17 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.requireProvenance = true;
     } else if (arg === "--pr-loop") {
       result.prLoop = true;
+    } else if (arg === "--apply-on-merge") {
+      // `chant build --pr-loop --apply-on-merge` and `chant ci serve --apply-on-merge` (#4168): opt into applying on merge.
+      result.applyOnMerge = true;
     } else if (arg === "--pr-build") {
       // `chant build --pr-loop --pr-build` (#4088), and `chant ci run --pr-build` (#4094).
       result.prBuild = true;
+    } else if (arg === "--build-command") {
+      // `chant ci serve --build-command <line>` (#4169): the line that builds a requested commit.
+      const line = args[++i];
+      if (line === undefined || line === "") throw new Error("--build-command needs a shell line: --build-command '<line>'");
+      result.ciBuildCommand = line;
     } else if (arg === "--pr-build-command") {
       const line = args[++i];
       if (line === undefined || line === "") throw new Error("--pr-build-command needs a shell line: --pr-build-command '<line>'");
@@ -783,11 +792,18 @@ export function parseArgs(args: string[]): ParsedArgs {
     } else if (arg === "--in-place") {
       // `chant ci run --in-place` (#4156): run the job in this checkout, as a generated forge job does.
       result.ciInPlace = true;
+    } else if (arg === "--require-runner-start") {
+      // `chant ci run --require-runner-start` (#4147): refuse the job unless a provisioner's runner-start statement names it.
+      result.requireRunnerStart = true;
+    } else if (arg === "--job") {
+      // `chant ci runner-start sign --job <json|@file>` (#4147): the CI job a runner was started for.
+      result.ciJob = args[++i];
+      if (!result.ciJob || result.ciJob.startsWith("-")) throw new Error("--job needs the job as JSON or @<file>: --job @job.json");
     } else if (arg === "--no-push") {
       // `chant ci run --no-push` (#4156): keep the run record on the local chant/lifecycle.
       result.noPush = true;
     } else if (arg === "--no-require-review") {
-      // `chant ci run apply --no-require-review` (#4156): the apply without pr-apply's --require-review.
+      // `chant ci run apply --no-require-review` (#4156): the apply without pr-apply's --require-review, the default since #4168.
       result.requireReview = false;
     } else if (arg === "--unsigned") {
       // `chant ci serve --unsigned` (#4099): serve without a runner key listed at the target's head.

package/src/cli/registry.ts

@@ -311,8 +311,10 @@ export interface ParsedArgs {
   /**
    * `chant components pr-apply --require-review` (#3183) — count an approval
    * only when its approver has a standing approving review on the pull
-   * request. Needs `--forge`. `chant ci run apply --no-require-review`
-   * (#4156) sets it false, for a pipeline generated with `requireReview: false`.
+   * request. Needs `--forge`. `chant ci run apply --require-review`
+   * passes it on, and `chant build --pr-loop --require-review` generates a
+   * pipeline that does (#4168); `--no-require-review` (#4156) sets it false,
+   * which is the default.
    */
   requireReview?: boolean;
   /**
@@ -323,12 +325,20 @@ export interface ParsedArgs {
   reportUrl?: string;
   /**
    * `chant build --components --generate <lexicon> --pr-loop` (#3183) —
-   * generate the pull-request pipeline: plan on the pull request, apply on
-   * merge bound to the approved digest.
+   * generate the pull-request pipeline: plan on the pull request, and on
+   * merge record the plan (#4168), or apply it with `--apply-on-merge`.
    */
   prLoop?: boolean;
+  /**
+   * `chant build --pr-loop --apply-on-merge` and `chant ci serve
+   * --apply-on-merge` (#4168): on merge apply the approved plan, as before
+   * #4168, in place of recording it. Opt-in: a merge deploys nothing without it.
+   */
+  applyOnMerge?: boolean;
   /** `chant build --pr-loop --pr-build` (#4088) — build and lint before pr-plan and pr-apply. */
   prBuild?: boolean;
+  /** `chant ci serve --build-command <line>` (#4169) — the line that builds a commit a `ci/build/<sha>` tag asks for, in a worktree of it. */
+  ciBuildCommand?: string;
   /** `chant build --pr-loop --pr-build-command <line>` (#4088) — the build line to run in place of `chant build --env <env>`. */
   prBuildCommand?: string;
   /**
@@ -511,6 +521,10 @@ export interface ParsedArgs {
   unsigned?: boolean;
   /** `chant ci run --in-place` (#4156): run the job in this checkout at HEAD, as a generated forge job does. */
   ciInPlace?: boolean;
+  /** `chant ci run --require-runner-start` (#4147): refuse the job unless a runner-start statement names it. */
+  requireRunnerStart?: boolean;
+  /** `chant ci runner-start sign --job <json|@file>` (#4147): the CI job a runner was started for. */
+  ciJob?: string;
   /** `chant ci run --no-push` (#4156): write the run record on the local chant/lifecycle and push nothing. */
   noPush?: boolean;
   /** `chant ci serve|run --setup-key --trust --principal <name>` (#4099): the principal the runner key is listed for. */

package/src/components/deploy-inputs.test.ts

@@ -0,0 +1,108 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { componentDeployInputs, directoryDigest, directoryFiles, stepInputRefs } from "./deploy-inputs";
+import { componentPlanDigest } from "./gate-plan";
+import type { DriverComponent, DriverPhase } from "./driver";
+
+let root: string;
+
+const write = (path: string, content: string): void => {
+  mkdirSync(dirname(join(root, path)), { recursive: true });
+  writeFileSync(join(root, path), content);
+};
+const deploy = (...steps: Array<Record<string, unknown>>): DriverPhase[] => [{ phase: "Deploy", steps: steps as never }];
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "deploy-inputs-"));
+});
+
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+describe("stepInputRefs", () => {
+  test("a kind's own fields and the template fields, literal paths only", () => {
+    const refs = stepInputRefs("Deploy", { kind: "helm-upgrade", release: "web", chart: "chart", values: ["a.yaml", "@Cfg.values"] } as never);
+    expect(refs.map((r) => [r.field, r.path])).toEqual([["values", "a.yaml"], ["chart", "chart"]]);
+  });
+
+  test("an archive path or a wired value is a build output and is not named", () => {
+    expect(stepInputRefs("Deploy", { kind: "cfn-deploy", template: "archive:stack.json" } as never)).toEqual([]);
+    expect(stepInputRefs("Deploy", { kind: "s3-sync", from: "@Build.dir", to: "s3://b" } as never)).toEqual([]);
+  });
+
+  test("a Docker build's Dockerfile is named under its context", () => {
+    const refs = stepInputRefs("Build", { kind: "docker-build", context: "app", dockerfile: "Dockerfile.prod" } as never);
+    expect(refs.map((r) => r.path)).toEqual(["app", "app/Dockerfile.prod"]);
+  });
+});
+
+describe("componentDeployInputs", () => {
+  test("a file by its bytes, a directory by its files; a missing path is left out", () => {
+    write("values.yaml", "a: 1\n");
+    write("chart/Chart.yaml", "name: c\n");
+    const read = componentDeployInputs(deploy({ kind: "helm-upgrade", chart: "chart", values: ["values.yaml", "gone.yaml"] }), root);
+    expect(read.inputs.map((i) => i.path)).toEqual(["chart", "values.yaml"]);
+    expect(read.inputs.find((i) => i.path === "values.yaml")?.digest).toMatch(/^sha256:[0-9a-f]{64}$/);
+    expect(read.unbound).toEqual([]);
+  });
+
+  test("a directory's digest moves with a file's bytes, a new file and a renamed one", () => {
+    write("site/index.html", "<h1>a</h1>");
+    const before = directoryDigest(root, "site");
+    write("site/index.html", "<h1>b</h1>");
+    const edited = directoryDigest(root, "site");
+    expect(edited).not.toBe(before);
+    write("site/about.html", "x");
+    expect(directoryDigest(root, "site")).not.toBe(edited);
+  });
+
+  test("the same files under another parent hash the same: the digest reads paths from the directory", () => {
+    write("a/chart/Chart.yaml", "name: c\n");
+    write("b/chart/Chart.yaml", "name: c\n");
+    expect(directoryDigest(root, "a/chart")).toBe(directoryDigest(root, "b/chart"));
+  });
+
+  test("in a git repository, a directory leaves out what git ignores, and a directory git ignores is a build output", () => {
+    execFileSync("git", ["init", "-q"], { cwd: root });
+    write(".gitignore", "node_modules/\ndist/\n");
+    write("app/server.js", "1");
+    write("app/node_modules/dep/index.js", "1");
+    write("dist/index.html", "1");
+    expect(directoryFiles(root, "app")).toEqual(["app/server.js"]);
+    const read = componentDeployInputs(deploy({ kind: "docker-build", context: "app" }, { kind: "s3-sync", from: "dist", to: "s3://b" }), root);
+    expect(read.inputs.map((i) => i.path)).toEqual(["app"]);
+    expect(read.unbound).toEqual([{ phase: "Deploy", kind: "s3-sync", reason: expect.stringMatching(/"dist" is a directory git ignores, so a build output/) }]);
+  });
+
+  test("a file git ignores is still hashed when a step names it, as a template chant build writes", () => {
+    execFileSync("git", ["init", "-q"], { cwd: root });
+    write(".gitignore", "dist/\n");
+    write("dist/stack.json", "{}");
+    expect(componentDeployInputs(deploy({ kind: "cfn-deploy", template: "dist/stack.json" }), root).inputs.map((i) => i.path)).toEqual(["dist/stack.json"]);
+  });
+
+  test("a shell step is unbound; `include` limits the steps read", () => {
+    write("chart/Chart.yaml", "x");
+    const phases = deploy({ kind: "shell", cmd: "./go.sh", reason: "t" }, { kind: "helm-upgrade", chart: "chart" });
+    expect(componentDeployInputs(phases, root).unbound.map((u) => u.kind)).toEqual(["shell"]);
+    expect(componentDeployInputs(phases, root, (s) => s.kind !== "helm-upgrade").inputs).toEqual([]);
+  });
+});
+
+describe("componentPlanDigest with inputs", () => {
+  const component: DriverComponent = { name: "web", dependsOn: [], deploy: deploy({ kind: "helm-upgrade", chart: "chart" }) };
+
+  test("no inputs keeps the digest a composition had before #4155", () => {
+    expect(componentPlanDigest({ environment: "prod", component, inputs: [] })).toBe(componentPlanDigest({ environment: "prod", component }));
+  });
+
+  test("an input's digest moves the plan digest", () => {
+    const a = componentPlanDigest({ environment: "prod", component, inputs: [{ path: "chart", digest: "sha256:aa" }] });
+    const b = componentPlanDigest({ environment: "prod", component, inputs: [{ path: "chart", digest: "sha256:bb" }] });
+    expect(a).not.toBe(b);
+  });
+});

package/src/components/deploy-inputs.ts

@@ -0,0 +1,225 @@
+/**
+ * The local files a component's steps deploy from, and their content digests
+ * (#4155).
+ *
+ * A component gate approves `componentPlanDigest` (./gate-plan.ts). A step
+ * whose capability has a `plan` is bound by what it plans. Every other step
+ * was bound only by its input as written, so a Helm chart, a kustomize
+ * directory or a static site's tree could change after review without moving
+ * the digest. This module names those files and hashes them, so the digest
+ * moves when they do.
+ *
+ * Which fields name a path is data, as the template fields are in
+ * ./release-compile.ts and the unit fields in ./deploy-units.ts: a kind's
+ * fields in {@link DEPLOY_INPUT_FIELDS}, plus `template`, `manifest` and
+ * `values` on any step ({@link TEMPLATE_FIELDS}). Only a literal path counts:
+ * a value wired from another step (`@Build.uri`) or an `archive:` path is a
+ * build output, and binding it would make an approval unusable by a build
+ * that is not reproducible. The build steps' own sources are bound instead.
+ *
+ * - A file is hashed by its bytes.
+ * - A directory is hashed over the files under it that git does not ignore
+ *   (`git ls-files --cached --others --exclude-standard`), each by its path
+ *   and bytes, so `node_modules` and a build's `dist` inside a Docker context
+ *   are left out. Outside a git repository every file is hashed except under
+ *   `.git` and `node_modules`.
+ * - A directory git ignores as a whole is a build output. It is not hashed;
+ *   the step is listed as unbound, with that reason.
+ * - A path that does not exist is left out. One that appears later moves the
+ *   digest.
+ *
+ * A step whose kind runs content chant can't name, such as `shell`, is listed
+ * as unbound ({@link UNBOUND_KINDS}), so the plan note can show a reviewer
+ * what the approval does not cover.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { sha256Hex } from "../content-digest";
+import { computePlanDigest } from "../lifecycle/plan-digest";
+import type { DriverGate, DriverPhase, DriverStep } from "./driver";
+
+/** The fields that name every step's deployed file, whatever its kind (as ./release-compile.ts reads them). */
+export const TEMPLATE_FIELDS: readonly string[] = ["template", "manifest", "values"];
+
+/** Per kind, the fields beyond {@link TEMPLATE_FIELDS} that name a local file or directory the step deploys or builds from. */
+export const DEPLOY_INPUT_FIELDS: Readonly<Record<string, readonly string[]>> = {
+  "helm-upgrade": ["chart"],
+  "kustomize-apply": ["dir"],
+  "fly-release": ["plan"],
+  "fly-rollback": ["plan"],
+  "s3-sync": ["from"],
+  "r2-sync": ["from"],
+  "copy-to-host": ["from"],
+  "wrangler-deploy": ["config"],
+  "wrangler-versions-promote": ["config"],
+  "docker-build": ["context"],
+  "zip-package": ["source"],
+  "jvm-build": ["path"],
+};
+
+/** Kinds that deploy content chant can't name from their input: a command, an agent's work. */
+export const UNBOUND_KINDS: readonly string[] = ["shell", "run-agent"];
+
+/** One path a step names. */
+export interface DeployInputRef {
+  phase: string;
+  kind: string;
+  field: string;
+  /** Relative to the member's directory, as written. */
+  path: string;
+}
+
+/** A named path and the digest of what is there. */
+export interface DeployInputDigest {
+  path: string;
+  /** `sha256:<hex>` of a file's bytes, or a plan digest over a directory's files. */
+  digest: string;
+}
+
+/** A step the digest does not cover, and why. */
+export interface UnboundStep {
+  phase: string;
+  kind: string;
+  reason: string;
+}
+
+/** What a component's steps deploy from: the digests, and the steps they can't cover. */
+export interface ComponentDeployInputs {
+  inputs: DeployInputDigest[];
+  unbound: UnboundStep[];
+}
+
+function isGate(step: DriverStep | DriverGate | DriverPhase): step is DriverGate {
+  return (step as { kind?: unknown }).kind === "gate";
+}
+
+function isPhase(step: DriverStep | DriverGate | DriverPhase): step is DriverPhase {
+  return typeof (step as { phase?: unknown }).phase === "string" && Array.isArray((step as DriverPhase).steps);
+}
+
+const isLiteralPath = (v: unknown): v is string =>
+  typeof v === "string" && v !== "" && !v.startsWith("@") && !v.startsWith("$") && !v.startsWith("archive:");
+
+/** Every capability step of a composition with its phase, nested phases included, gates left out. */
+export function stepsWithPhase(phases: readonly DriverPhase[]): Array<{ phase: string; step: DriverStep }> {
+  const out: Array<{ phase: string; step: DriverStep }> = [];
+  const walk = (phase: DriverPhase): void => {
+    for (const step of phase.steps) {
+      if (isPhase(step)) walk(step);
+      else if (!isGate(step)) out.push({ phase: phase.phase, step });
+    }
+  };
+  phases.forEach(walk);
+  return out;
+}
+
+/** The literal paths one step names, in field order. A Docker build's Dockerfile is named under its context. */
+export function stepInputRefs(phase: string, step: DriverStep): DeployInputRef[] {
+  const out: DeployInputRef[] = [];
+  for (const field of [...TEMPLATE_FIELDS, ...(DEPLOY_INPUT_FIELDS[step.kind] ?? [])]) {
+    const raw = step[field];
+    for (const value of Array.isArray(raw) ? raw : [raw]) {
+      if (isLiteralPath(value)) out.push({ phase, kind: step.kind, field, path: value });
+    }
+  }
+  if (step.kind === "docker-build" && isLiteralPath(step.context) && isLiteralPath(step.dockerfile)) {
+    out.push({ phase, kind: step.kind, field: "dockerfile", path: join(step.context, step.dockerfile) });
+  }
+  return out;
+}
+
+function git(root: string, args: string[]): { ok: boolean; out: string } {
+  const r = spawnSync("git", ["-C", root, ...args], { encoding: "utf-8", maxBuffer: 256 * 1024 * 1024 });
+  return { ok: r.status === 0, out: r.stdout ?? "" };
+}
+
+/** The files under `dir` (relative to `root`) a directory digest covers, relative to `root`, sorted. */
+export function directoryFiles(root: string, dir: string): string[] {
+  const listed = git(root, ["ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", dir]);
+  if (listed.ok) {
+    return [...new Set(listed.out.split("\0").filter((p) => p !== ""))]
+      .filter((p) => {
+        const full = resolve(root, p);
+        return existsSync(full) && statSync(full).isFile();
+      })
+      .sort();
+  }
+  return walkFiles(root, dir);
+}
+
+/** Every file under `dir`, relative to `root`, sorted, leaving out `.git` and `node_modules`. What a cut records of a directory git ignores. */
+export function walkFiles(root: string, dir: string): string[] {
+  const out: string[] = [];
+  const walk = (abs: string): void => {
+    for (const entry of readdirSync(abs, { withFileTypes: true })) {
+      if (entry.name === ".git" || entry.name === "node_modules") continue;
+      const full = join(abs, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile()) out.push(relative(root, full).split(sep).join("/"));
+    }
+  };
+  walk(resolve(root, dir));
+  return out.sort();
+}
+
+/** Whether git ignores `path` (relative to `root`). False outside a git repository. */
+export function ignoredByGit(root: string, path: string): boolean {
+  return git(root, ["check-ignore", "-q", "--", path]).ok;
+}
+
+/** `sha256:<hex>` of a file's bytes. */
+export function fileDigest(file: string): string {
+  return `sha256:${sha256Hex(readFileSync(file))}`;
+}
+
+/** The digest of the files under `dir`: a plan digest over each file's path (from `dir`) and bytes. */
+export function directoryDigest(root: string, dir: string): string {
+  const base = resolve(root, dir);
+  const files = directoryFiles(root, dir).map((p) => ({
+    path: relative(base, resolve(root, p)).split(sep).join("/"),
+    digest: fileDigest(resolve(root, p)),
+  }));
+  return computePlanDigest("directory", files);
+}
+
+/**
+ * What a component's steps deploy from, read under `root` (the member's
+ * directory). `include` picks the steps to read, all of them by default; the
+ * wave planner passes the steps without a `plan`, which their plan does not
+ * already cover.
+ */
+export function componentDeployInputs(
+  phases: readonly DriverPhase[],
+  root: string,
+  include: (step: DriverStep) => boolean = () => true,
+): ComponentDeployInputs {
+  const inputs = new Map<string, string>();
+  const unbound: UnboundStep[] = [];
+  for (const { phase, step } of stepsWithPhase(phases)) {
+    if (!include(step)) continue;
+    if (UNBOUND_KINDS.includes(step.kind)) {
+      unbound.push({ phase, kind: step.kind, reason: `a ${step.kind} step runs content chant can't name from its input` });
+      continue;
+    }
+    for (const ref of stepInputRefs(phase, step)) {
+      if (inputs.has(ref.path)) continue;
+      const full = resolve(root, ref.path);
+      if (!existsSync(full)) continue;
+      if (statSync(full).isDirectory()) {
+        if (ignoredByGit(root, ref.path)) {
+          unbound.push({ phase, kind: step.kind, reason: `its ${ref.field} "${ref.path}" is a directory git ignores, so a build output; bind its sources through the step that builds it` });
+          continue;
+        }
+        inputs.set(ref.path, directoryDigest(root, ref.path));
+      } else {
+        inputs.set(ref.path, fileDigest(full));
+      }
+    }
+  }
+  return {
+    inputs: [...inputs].map(([path, digest]) => ({ path, digest })).sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)),
+    unbound,
+  };
+}