@intentius/chant 0.124.31 → 0.124.33

package/dist/components/pr-run.js

@@ -8,26 +8,42 @@
  * everything before applying anything is what makes the two digests
  * comparable: each member is planned against the same state both times.
  *
- * ## Dependents read the outputs standing now
+ * ## What a dependent is planned against
  *
  * A member that reads another one's output through `stackOutput()` is
- * planned with the value that output has now, read through the capability's
- * `outputs` (`readComponentOutputs`). When the change moves that output, the
- * dependent's approved plan still carries the old value; the apply applies
- * it as approved and marks the member `inputsMoved`, and the next run plans
- * it against the new value. A change that must carry a moved output through
- * its dependents in one rollout is what gated waves are for (#3049): each
- * wave is planned after the one before it applied.
+ * planned with one of three values (#3999):
  *
- * A dependency the change did not select is read the same way (#4104), so
- * a change to one cluster plans it against the network it sits on. That is
- * why `components` is every component in the project and not the selection.
- * `--seed-outputs` wins over a read, and a dependency whose steps cannot say
- * leaves its dependents' references unresolved. The apply stage's plan reads
- * the same dependencies, so on the same estate it gets the digest the plan
- * stage showed, and it applies against the outputs its plans read
- * (`set.outputs`). A resume plans against the outputs the approved plans
- * read, from the record (`planOutputs`), and reads nothing those cover.
+ * - the upstream is in the change too: the value its plan says it will
+ *   expose (`CapabilityPlan.outputs`). The report lists these under
+ *   `plannedOutputs`.
+ * - the upstream is not in the change (#4104): the value it has now, read
+ *   through its capability's `outputs` (`readComponentOutputs`). The report
+ *   lists these under `deployedOutputs`. A change to one cluster is planned
+ *   against the network it sits on, which is why `components` is every
+ *   component in the project and not the selection.
+ * - the upstream is in the change and its plan cannot say, or says the value
+ *   is known only after apply: no value. The dependent's members list the
+ *   reference under `unknownInputs`, and the approval does not cover what
+ *   it will do with it.
+ *
+ * `--seed-outputs` wins over both. The apply stage's plan reads the same
+ * values, so on the same estate it gets the digest the plan stage showed.
+ * A resume plans against the outputs the approved plans read, from the
+ * record (`planOutputs`), and reads nothing those cover.
+ *
+ * ## Planning again once an upstream applied
+ *
+ * The apply runs each member's approved plan, except a member whose plan
+ * read an upstream output that is not the value standing when its turn
+ * comes (`movedWiringReferences`): the upstream applied as another value
+ * than its plan said, or the value was unknown. That member, and what is
+ * downstream of it, is held back. Once the rest settled, the held members
+ * are planned again against the outputs the apply left, and that set's
+ * digest is decided at its own gate, `<gate>-round-<n>` (`prRoundGate`), as
+ * a gated wave decides each wave (#3049). Approved, it applies, and a member
+ * that is held again goes to the next round. Not approved, the apply stops
+ * `waiting` with the new digest named, and the same apply with its
+ * `--resume` record carries on from there.
  *
  * ## Finishing an apply that failed partway
  *
@@ -41,15 +57,24 @@
  * the rest applies. Planning everything again would give the applied members
  * empty plans and the set a new digest, and so ask for a second approval of
  * work already approved.
+ *
+ * ## A gate per wave on merge
+ *
+ * `pr-apply --wave-gate` (#4003) applies the approved set a wave at a time.
+ * {@link prWavePlan} narrows the derivation to one wave, which is planned
+ * against the outputs the waves before it left, and {@link waveNotCovered}
+ * says whether the approved change set covers what it planned, by the same
+ * test a resume uses ({@link planCoveredBy}). Covered, the wave applies under
+ * the pull request's approval; not covered, it needs its own.
  */
 import { composeChangeSet, verifyChangeSetDigest } from "../change-set.js";
 import { evaluateGate } from "../op/gate.js";
-import { memberCounts, PR_REPORT_CONTRACT, PR_REPORT_SCHEMA_ID, } from "../pr-loop.js";
-import { deployContext } from "./driver.js";
+import { memberCounts, PR_APPLY_GATE, prRoundGate, PR_REPORT_CONTRACT, PR_REPORT_SCHEMA_ID, } from "../pr-loop.js";
+import { deployContext, movedWiringReferences, unresolvedWiringReferences, } from "./driver.js";
 import { deployUnits } from "./deploy-units.js";
 import { runFanOut } from "./fan-out-run.js";
 import { remainingFanOut } from "./fan-out.js";
-import { planWaveComponent, readDeployedOutputs } from "./wave-plan.js";
+import { capabilitySteps, planWaveComponent, readDeployedOutputs } from "./wave-plan.js";
 /** The phase a pull request's planning is, in its run's events. */
 export const PR_PLAN_PHASE = "plan";
 /** A failed component's members: the units its steps target, else the component itself. */
@@ -61,36 +86,51 @@ function failedParts(component, error) {
     }));
 }
 /**
- * Plan every component in `plan.order`, a wave at a time, each against the
- * outputs its dependencies have now. Never throws for a component that fails
- * to plan: it becomes a failed member, and `failed` is set. Throws when a
- * planned member's dependency is not among `components`, which means the
- * caller passed the selection where the whole graph belongs.
+ * Plan every component in `plan.order`, a wave at a time, each against its
+ * dependencies' planned outputs when the change plans them too, and against
+ * the outputs they have now otherwise. Never throws for a component that
+ * fails to plan: it becomes a failed member, and `failed` is set. Throws
+ * when a planned member's dependency is not among `components`, which means
+ * the caller passed the selection where the whole graph belongs.
  */
 export async function planPrSet(options) {
     const byName = new Map(options.components.map((c) => [c.name, c]));
     const outputs = { ...(options.seededOutputs ?? {}) };
     const read = new Set(Object.keys(outputs));
+    const inChange = new Set(options.plan.order);
+    /** What each component of the change planned to expose, once its wave planned. */
+    const plannedBy = new Map();
     const deployed = {};
+    const planned = {};
     const parts = [];
     const componentOf = new Map();
+    const unknownOf = new Map();
     const plans = {};
     let failed = false;
     const emit = options.onRunEvent;
     emit?.({ type: "phase-start", component: null, phase: PR_PLAN_PHASE });
     for (const wave of options.plan.waves) {
-        // The dependencies' outputs first, each read once. A dependency that
-        // cannot say leaves its references unresolved, which its dependent's
-        // plan reports if it needs them. A dependency outside the selection is
-        // read the same way (#4104).
+        // The dependencies' outputs first, each once. One the change plans is
+        // read from its plan, which an earlier wave made (#3999). Any other is
+        // read from the deployed estate (#4104). A dependency that cannot say
+        // leaves its references unresolved, which its dependent's plan reports
+        // if it needs them.
         const deps = [...new Set(wave.flatMap((name) => byName.get(name)?.dependsOn ?? []))].filter((dep) => !read.has(dep));
+        const fromEstate = [];
         for (const dep of deps) {
             read.add(dep);
             if (!byName.has(dep))
                 throw new Error(`planPrSet: ${dep}, a dependency of a planned member, is not among the components; pass every component in the project`);
+            if (!inChange.has(dep)) {
+                fromEstate.push(dep);
+                continue;
+            }
+            const known = plannedBy.get(dep)?.known ?? {};
+            outputs[dep] = { ...known };
+            planned[dep] = Object.keys(known).sort();
         }
-        Object.assign(deployed, await readDeployedOutputs(deps, byName, options.registry, (dep) => deployContext(options, dep), outputs));
-        const planned = await Promise.all(wave.map(async (name) => {
+        Object.assign(deployed, await readDeployedOutputs(fromEstate, byName, options.registry, (dep) => deployContext(options, dep), outputs));
+        const results = await Promise.all(wave.map(async (name) => {
             const at = { component: name, phase: PR_PLAN_PHASE, step: "plan" };
             emit?.({ type: "step-start", ...at });
             const start = Date.now();
@@ -104,16 +144,21 @@ export async function planPrSet(options) {
             });
             return p;
         }));
-        for (const p of planned) {
+        for (const p of results) {
             const component = byName.get(p.component);
+            const unknown = unknownInputsOf(component, outputs, inChange);
+            if (unknown.unknown.length > 0 || unknown.build.length > 0)
+                unknownOf.set(p.component, unknown);
             if ("error" in p) {
                 failed = true;
+                plannedBy.set(p.component, undefined);
                 for (const part of failedParts(component, p.error)) {
                     parts.push(part);
                     componentOf.set(part.member.member, p.component);
                 }
                 continue;
             }
+            plannedBy.set(p.component, p.outputs);
             plans[p.component] = p.plans;
             for (const part of p.parts) {
                 parts.push(part);
@@ -123,16 +168,71 @@ export async function planPrSet(options) {
     }
     emit?.({ type: "phase-settle", component: null, phase: PR_PLAN_PHASE, status: failed ? "failed" : "ok" });
     const doc = composeChangeSet(parts);
-    const members = doc.members.map((m) => ({
-        member: m.member,
-        component: componentOf.get(m.member) ?? m.member,
-        planDigest: m.planDigest,
-        status: m.status === "failed" ? "plan-failed" : "planned",
-        counts: memberCounts(doc, m.member),
-        ...(m.error ? { error: m.error } : {}),
-    }));
-    const deployedOutputs = Object.fromEntries(Object.entries(deployed).sort(([a], [b]) => a.localeCompare(b)));
-    return { doc, members, plans, outputs, failed, ...(Object.keys(deployedOutputs).length > 0 ? { deployedOutputs } : {}) };
+    const members = doc.members.map((m) => {
+        const component = componentOf.get(m.member) ?? m.member;
+        const unknown = unknownOf.get(component);
+        return {
+            member: m.member,
+            component,
+            planDigest: m.planDigest,
+            status: m.status === "failed" ? "plan-failed" : "planned",
+            counts: memberCounts(doc, m.member),
+            ...(m.error ? { error: m.error } : {}),
+            ...(unknown?.unknown.length ? { unknownInputs: unknown.unknown } : {}),
+            ...(unknown?.build.length ? { buildInputs: unknown.build } : {}),
+        };
+    });
+    const sorted = (r) => Object.fromEntries(Object.entries(r).sort(([a], [b]) => a.localeCompare(b)));
+    const deployedOutputs = sorted(deployed);
+    const plannedOutputs = sorted(planned);
+    return {
+        doc,
+        members,
+        plans,
+        outputs,
+        failed,
+        ...(Object.keys(deployedOutputs).length > 0 ? { deployedOutputs } : {}),
+        ...(Object.keys(plannedOutputs).length > 0 ? { plannedOutputs } : {}),
+    };
+}
+/**
+ * The references `component`'s steps make to an output of a component in
+ * the change that `outputs` holds no value for (#3999), known only after
+ * that upstream applies, each sorted. `build` are the published artifact
+ * identities a build in the change produces (`WiringReference.publish`):
+ * the build's provenance binds those, so they are never approved again.
+ * `unknown` are the rest.
+ */
+function unknownInputsOf(component, outputs, inChange) {
+    const unknown = new Set();
+    const build = new Set();
+    for (const step of capabilitySteps(component.deploy)) {
+        const { kind: _kind, ...rest } = step;
+        for (const r of unresolvedWiringReferences(rest, outputs)) {
+            if (inChange.has(r.source))
+                (r.publish ? build : unknown).add(r.ref);
+        }
+    }
+    return { unknown: [...unknown].sort(), build: [...build].sort() };
+}
+/**
+ * Why `component` cannot apply the plan that read `read` now that `now`
+ * stands (#3999): each reference its steps make that resolves to another
+ * value, said once. `undefined` when every one resolves as it did. A
+ * published artifact's identity from a build in `inChange` never holds a
+ * member back: the build's provenance binds it, not this approval.
+ */
+export function heldReason(component, read, now, inChange = new Set()) {
+    const refs = new Set();
+    for (const step of capabilitySteps(component.deploy)) {
+        const { kind: _kind, ...rest } = step;
+        for (const r of movedWiringReferences(rest, read, now))
+            if (!(r.publish && inChange.has(r.source)))
+                refs.add(r.ref);
+    }
+    if (refs.size === 0)
+        return undefined;
+    return `its plan read ${[...refs].sort().join(", ")} before ${refs.size === 1 ? "that output" : "those outputs"} applied as another value`;
 }
 /**
  * A ledger that reads the real one and records nothing. The plan stage
@@ -178,58 +278,132 @@ export function approversWithoutReview(approvedBy, reviewers) {
     const allowed = new Set(reviewers.map(norm));
     return approvedBy.filter((by) => !allowed.has(norm(by)));
 }
-const sameJson = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+/**
+ * Who approved the gate but wrote the change (#4000): each approval's
+ * `resolvedBy` that names one of `authors`, the forge's naming of the pull
+ * request's author and of its commits' authors and committers. Their own
+ * approval never counts, whether a forge review or a ledger line backs it.
+ */
+export function approversWhoAuthored(approvedBy, authors) {
+    const norm = (s) => s.trim().toLowerCase();
+    const wrote = new Set(authors.map(norm));
+    return approvedBy.filter((by) => wrote.has(norm(by)));
+}
+/** Two runs of one apply as one: `b` ran after `a`, against the outputs `a` left. */
+function joinRuns(a, b) {
+    const status = a.status === "fail" || b.status === "fail" ? "fail" : a.status === "gated" || b.status === "gated" ? "gated" : "ok";
+    const gate = a.gate ?? b.gate;
+    return {
+        plan: a.plan,
+        status,
+        results: [...a.results, ...b.results],
+        completed: [...new Set([...a.completed, ...b.completed])].sort(),
+        failed: [...new Set([...a.failed, ...b.failed])].sort(),
+        blocked: [...a.blocked, ...b.blocked],
+        componentOutputs: b.componentOutputs,
+        ...(gate ? { gate } : {}),
+        ...(b.held ? { held: b.held } : {}),
+    };
+}
 /**
  * Apply the approved plans in dependency order. A failed component blocks
- * its dependents and nothing else (`runFanOut`).
+ * its dependents and nothing else (`runFanOut`). A member whose plan read an
+ * upstream output that is not the value standing when its turn comes is held
+ * back with what is downstream of it, planned again once the rest settled,
+ * and applied when `decideRound` approves that plan (#3999).
  */
 export async function applyPrSet(options) {
-    const before = options.set.outputs;
-    const run = await runFanOut(options.plan, options.components, options.registry, {
+    const byName = new Map(options.components.map((c) => [c.name, c]));
+    const priorCompleted = new Set(options.resumed?.completed ?? []);
+    const inChange = new Set([...options.set.members.map((m) => m.component), ...options.plan.order]);
+    const toApply = new Set([...inChange].filter((name) => !priorCompleted.has(name)));
+    // The outputs standing as the apply starts: what the plans read of
+    // components outside the change, and what an earlier attempt's components
+    // left (the values the plans read, where its record kept none). A planned
+    // value of a component still to apply stands nowhere until it applies.
+    const standing = {
+        ...Object.fromEntries(Object.entries(options.set.outputs).filter(([name]) => !toApply.has(name))),
+        ...(options.resumed?.outputs ?? {}),
+    };
+    const runRound = (plan, plans, read, outputs) => runFanOut(plan, options.components, options.registry, {
         env: options.env,
         ...(options.vars ? { vars: options.vars } : {}),
-        plans: options.set.plans,
-        componentOutputs: { ...before },
+        plans,
+        componentOutputs: outputs,
+        hold: (name, now) => heldReason(byName.get(name), read, now, inChange),
         ...(options.onProgress ? { onProgress: options.onProgress } : {}),
         ...(options.onRunEvent ? { onRunEvent: options.onRunEvent } : {}),
         ...(options.onComponentSettled ? { onComponentSettled: options.onComponentSettled } : {}),
     });
+    let run = await runRound(options.plan, options.set.plans, options.set.outputs, { ...standing });
+    const rounds = [];
+    /** Per component, the round that applied it or holds it, and that round's set, after the first. */
+    const roundOf = new Map();
+    let stopped;
+    while (run.held && run.held.length > 0 && run.status === "ok" && options.decideRound) {
+        const round = rounds.length + 2;
+        const gate = prRoundGate(options.gate ?? PR_APPLY_GATE, round);
+        const heldNames = new Set(run.held.map((h) => h.component));
+        const plan = remainingFanOut(options.plan, options.components, { completed: options.plan.order.filter((name) => !heldNames.has(name)) });
+        const set = await planPrSet({
+            components: options.components,
+            plan,
+            registry: options.registry,
+            env: options.env,
+            ...(options.vars ? { vars: options.vars } : {}),
+            seededOutputs: run.componentOutputs,
+        });
+        for (const name of plan.order)
+            roundOf.set(name, { round, set });
+        const record = (status, approval, message) => {
+            rounds.push({ round, gate, digest: set.doc.digest, components: plan.order, approval, status, ...(message ? { message } : {}), changeSet: set.doc });
+        };
+        if (set.failed) {
+            record("plan-failed", { status: "pending" });
+            stopped = "plan-failed";
+            break;
+        }
+        const decision = await options.decideRound({ round, gate, set, plan });
+        if (!decision.satisfied) {
+            record("waiting", decision.approval, decision.message);
+            stopped = "waiting";
+            break;
+        }
+        const next = await runRound(plan, set.plans, set.outputs, run.componentOutputs);
+        record(next.status === "fail" ? "failed" : "applied", decision.approval);
+        run = joinRuns(run, next);
+    }
     const completed = new Set(run.completed);
-    const priorCompleted = new Set(options.resumed?.completed ?? []);
-    /**
-     * Whether a dependency's outputs moved from what the plans read: by this
-     * run's apply, or by the earlier attempt's when the record kept them.
-     */
-    const movedBy = (dep) => {
-        if (completed.has(dep))
-            return !sameJson(before[dep], run.componentOutputs[dep]);
-        const earlier = options.resumed?.outputs;
-        return priorCompleted.has(dep) && earlier !== undefined && dep in earlier && !sameJson(before[dep], earlier[dep]);
-    };
+    const held = new Map((run.held ?? []).map((h) => [h.component, h]));
     const blocked = new Set(run.blocked.map((b) => b.component));
     const errorOf = (component) => {
-        const result = run.results.find((r) => r.component === component);
+        const result = [...run.results].reverse().find((r) => r.component === component);
         if (result?.status === "gated")
             return `stopped at its own gate ${result.gate?.gate ?? ""}`.trim();
         return result?.records.find((r) => r.status === "fail")?.error;
     };
-    const byName = new Map(options.components.map((c) => [c.name, c]));
     const members = options.set.members.map((m) => {
         if (priorCompleted.has(m.component))
             return { ...m, status: "applied" };
-        if (completed.has(m.component)) {
-            const moved = (byName.get(m.component)?.dependsOn ?? [])
-                .filter(movedBy)
-                .sort();
-            return { ...m, status: "applied", ...(moved.length > 0 ? { inputsMoved: moved } : {}) };
-        }
+        const later = roundOf.get(m.component);
+        const fresh = later?.set.members.find((x) => x.member === m.member);
+        const asPlanned = later && fresh ? { ...m, planDigest: fresh.planDigest, counts: fresh.counts, round: later.round } : m;
+        if (completed.has(m.component))
+            return { ...asPlanned, status: "applied" };
+        const h = held.get(m.component);
+        if (h)
+            return { ...asPlanned, status: "waiting", held: h.heldBy ? `${h.heldBy} is held: ${h.reason}` : h.reason };
+        if (fresh?.status === "plan-failed")
+            return { ...asPlanned, status: "plan-failed", ...(fresh.error ? { error: fresh.error } : {}) };
         if (blocked.has(m.component))
-            return { ...m, status: "blocked" };
+            return { ...asPlanned, status: "blocked" };
         const error = errorOf(m.component);
-        return { ...m, status: "failed", ...(error ? { error } : {}) };
+        return { ...asPlanned, status: "failed", ...(error ? { error } : {}) };
     });
-    return { members, status: run.status === "ok" ? "applied" : "failed", run };
+    const status = run.status !== "ok" || stopped === "plan-failed" ? "failed" : held.size > 0 || stopped === "waiting" ? "waiting" : "applied";
+    return { members, status, run, ...(rounds.length > 0 ? { rounds } : {}) };
 }
+const sameJson = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
 const entryKey = (e) => `${e.member}\u0000${e.address}\u0000${e.deposed ?? ""}`;
 /**
  * Why `member`'s fresh plan is not covered by the approved change set, or
@@ -361,6 +535,48 @@ export async function resumePrSet(options) {
         },
     };
 }
+/**
+ * The fan-out narrowed to wave `wave` of `plan` (1-based), less the
+ * components in `completed` (#4003). Its one wave is what is left of that
+ * wave; a dependency outside it, an earlier wave's component among them, is
+ * a seed. The digest is the derivation's, as {@link remainingFanOut} keeps it.
+ */
+export function prWavePlan(plan, components, wave, completed = []) {
+    const done = new Set(completed);
+    const order = (plan.waves[wave - 1] ?? []).filter((name) => !done.has(name));
+    const inWave = new Set(order);
+    const byName = new Map(components.map((c) => [c.name, c]));
+    const seeds = [
+        ...new Set([...plan.seeds, ...order.flatMap((name) => (byName.get(name)?.dependsOn ?? []).filter((dep) => !inWave.has(dep)))]),
+    ].sort();
+    return { order, waves: order.length > 0 ? [order] : [], skipped: [], seeds, indeterminate: plan.indeterminate, digest: plan.digest };
+}
+/**
+ * Why the approved change set does not cover a wave's new plan, one line per
+ * member, or `[]` when it covers every member (#4003). A member is covered
+ * as {@link planCoveredBy} says, with one rule more: a member whose planner
+ * describes no changes (chant's own empty part, for a capability that
+ * returns no change set) is covered only by the digest it was approved
+ * with, since with no entries there is nothing to compare a moved plan by.
+ */
+export function waveNotCovered(approved, fresh, approvedMembers = []) {
+    // #3999: a member whose approved plan waited only on an artifact a build in
+    // the change publishes is covered by that build's provenance, as it is
+    // without --wave-gate.
+    const byBuild = new Set(approvedMembers.filter((m) => m.buildInputs?.length && !m.unknownInputs?.length).map((m) => m.member));
+    return fresh.members
+        .map((m) => {
+        if (byBuild.has(m.member))
+            return undefined;
+        const was = approved.members.find((a) => a.member === m.member);
+        const opaque = m.planner === "chant" && m.lexicon === "chant" && m.status === "planned";
+        if (opaque && was && was.planDigest !== m.planDigest) {
+            return `${m.member} now plans to ${m.planDigest}, not the approved ${was.planDigest ?? "(none)"}, and its planner describes no changes to compare`;
+        }
+        return planCoveredBy(approved, fresh, m.member);
+    })
+        .filter((r) => r !== undefined);
+}
 /** The report a stage writes. */
 export function prReport(input) {
     const changed = new Set(input.signal.changed);
@@ -381,7 +597,11 @@ export function prReport(input) {
         ...(input.message ? { message: input.message } : {}),
         ...(input.resumed ? { resumed: { applied: [...input.resumed].sort() } } : {}),
         ...(input.set.deployedOutputs ? { deployedOutputs: input.set.deployedOutputs } : {}),
+        ...(input.set.plannedOutputs ? { plannedOutputs: input.set.plannedOutputs } : {}),
+        ...(input.rounds && input.rounds.length > 0 ? { rounds: input.rounds } : {}),
         approval: input.approval,
+        ...(input.waveGate ? { waveGate: input.waveGate } : {}),
+        ...(input.waveGate && input.waves?.length ? { waves: [...input.waves].sort((a, b) => a.wave - b.wave) } : {}),
         selection: {
             changed: input.plan.order.filter((c) => changed.has(c)),
             dependents: input.plan.order.filter((c) => !changed.has(c)),

package/dist/components/release-compile.d.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
@@ -28,7 +35,7 @@ import { type DriverComponent, type DriverStep } from "./driver.js";
 import type { CapabilityRegistry } from "./capability.js";
 import type { ReleaseArtifact, ReleaseParam } from "../lifecycle/release-store.js";
 /** The deploy step fields whose literal file paths are a component's templates. */
-export declare const TEMPLATE_FIELDS: readonly string[];
+export { TEMPLATE_FIELDS } from "./deploy-inputs.js";
 /** One template a component's deploy reads, as the step names it. */
 export interface TemplateRef {
     component: string;
@@ -44,7 +51,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. */
 export interface CompiledTarget {
@@ -66,6 +75,11 @@ 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. */
 export interface TargetCompiler {
@@ -74,6 +88,17 @@ export interface TargetCompiler {
 }
 /** The templates a component's deploy reads: literal paths in {@link TEMPLATE_FIELDS} of its steps other than build and publish steps. */
 export declare function templateRefs(component: DriverComponent): TemplateRef[];
+/** 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 declare function recordedInputRefs(component: DriverComponent): RecordedInputRef[];
+/** The fields of a step of `kind` whose paths a cut records and a promote points at the recorded copy. */
+export declare function recordedFields(kind: string): string[];
+/** A file's bytes as a template: its text when it is UTF-8, else base64. */
+export declare function templateOf(component: string | null, path: string, file: string): CompiledTemplate;
 /** A component's build-time steps ({@link BUILD_STEP_KINDS}), each as declared, in composition order. */
 export declare function buildStepsOf(component: DriverComponent): DriverStep[];
 /** A component's publish steps ({@link PUBLISH_STEP_KINDS}), each as declared, in composition order. */
@@ -98,7 +123,17 @@ 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 declare 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

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

@@ -1 +1 @@
-{"version":3,"file":"release-compile.d.ts","sourceRoot":"","sources":["../../src/components/release-compile.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"release-compile.d.ts","sourceRoot":"","sources":["../../src/components/release-compile.ts"],"names":[],"mappings":"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"}