@intentius/chant 0.124.12 → 0.124.14

package/dist/components/fan-out-support.js

@@ -0,0 +1,60 @@
+/**
+ * Discovery-to-plan wiring for `chant components fan-out` (#2420).
+ *
+ * `./cli-support.ts` does this for `chant run --components`: the CLI handler
+ * stays a thin dispatcher and the component-specific work lives beside the
+ * rest of the component subsystem. This is the same seam for the fan-out, and
+ * it exists mostly so the join can be tested against a real discovery result
+ * without a CLI, a git repo or a cloud.
+ *
+ * Nothing here decides anything. `componentsForUnits` joins the stack-level
+ * change signal to components, `planFanOut` derives the order, and both live
+ * in ./fan-out.ts. This finds the components those two need and hands them
+ * over.
+ */
+import { lexiconNames } from "../lexicon-module.js";
+import { resolveComponentTargets } from "./cli-support.js";
+import { applyConfigDefaults } from "./config-defaults.js";
+import { buildCapabilityRegistry } from "./capability-plugin-loader.js";
+import { componentsForUnits, planFanOut } from "./fan-out.js";
+import { loadChantConfig } from "../config.js";
+const EMPTY_PLAN = { order: [], waves: [], skipped: [], seeds: [], indeterminate: [], digest: "" };
+const EMPTY_SIGNAL = { changed: [], indeterminate: [], unclaimed: [] };
+/**
+ * Discover the project's components and derive the fan-out for `units`.
+ *
+ * Selection is `"all"`'s, borrowed wholesale from `resolveComponentTargets`, so
+ * a component a build parameter turned off (`enabled: false`, chant #1522) sits
+ * out of a fan-out exactly as it sits out of `chant run --components all`. Two
+ * commands disagreeing about which components exist would be worse than either
+ * answer on its own.
+ *
+ * Resolves with `success: false` and an `error` rather than throwing on a
+ * discovery failure; a cycle or an unknown `dependsOn` still throws out of
+ * `planFanOut`, which is #2417's "refuse by name, before anything is selected".
+ */
+export async function deriveFanOut(options) {
+    const resolved = await resolveComponentTargets(options.path, "all", options.sandbox, options.buildParams);
+    if (!resolved.success) {
+        return { success: false, components: [], signal: EMPTY_SIGNAL, plan: EMPTY_PLAN, error: resolved.error };
+    }
+    const { config } = options.config ? { config: options.config } : await loadChantConfig(options.path);
+    const components = resolved.targets.map((component) => applyConfigDefaults(component, config));
+    const signal = componentsForUnits(components, options.units);
+    const plan = planFanOut({
+        components,
+        changed: signal.changed,
+        ...(signal.indeterminate.length > 0 ? { indeterminate: signal.indeterminate } : {}),
+        ...(options.canary?.length ? { canary: options.canary } : {}),
+    });
+    return { success: true, components, signal, plan };
+}
+/**
+ * The capability registry a fan-out dispatches through — the project's own,
+ * built exactly the way `runComponents` builds it, so a fan-out and a
+ * `chant run --components` of the same component reach the same leaves.
+ */
+export async function fanOutRegistry(path, config) {
+    const resolved = config ?? (await loadChantConfig(path)).config;
+    return buildCapabilityRegistry({ plugins: resolved.capabilities, lexicons: lexiconNames(resolved.lexicons) });
+}

package/dist/components/fan-out.js

@@ -0,0 +1,273 @@
+/**
+ * Fan a change out downstream, in an order derived from the source (#2417).
+ *
+ * The order was never the missing piece. `resolveComponentGraph` (./driver.ts)
+ * already Kahn-layers a component set by `dependsOn` into parallel-safe waves,
+ * flattens to a topological order, refuses a cycle by name and refuses a
+ * `dependsOn` it has not been given. What it cannot do is order a *subset*:
+ * hand it the affected components alone and it throws `UnknownDependencyError`,
+ * because a selected component still names a dependency that is not in the set.
+ *
+ * That is what this module is. Given every component in the project and the
+ * ones whose inputs moved, it derives who else has to run, in what order, what
+ * has to be seeded because it is deliberately not running, and one digest that
+ * identifies the whole derivation so a single gate can be bound to it.
+ *
+ * ## Why derived rather than declared
+ *
+ * The competing shape is a registry where you write down that component B
+ * depends on component A. That registry is a second statement of a relationship
+ * the source already makes, and it is wrong the first time somebody adds a
+ * reference without updating it. `dependsOn` is in the component; the graph is
+ * a walk over it.
+ *
+ * ## Three outcomes, never two
+ *
+ * A component is selected, skipped as unaffected, or **indeterminate** — the
+ * same third answer `../lifecycle/affected.ts` already refuses to collapse. A
+ * component whose inputs arrive at deploy time cannot be judged from a source
+ * diff, so it is reported rather than guessed at in either direction. Fanning
+ * out to everything on any change is easy to build, worth nothing, and reads
+ * exactly like diligence in a log.
+ *
+ * This plans; it does not run. Executing the plan is ./driver.ts's job.
+ */
+import { resolveComponentGraph } from "./driver.js";
+import { deployUnits } from "./deploy-units.js";
+import { computePlanDigest } from "../lifecycle/plan-digest.js";
+import { layerWaves } from "../gated-waves.js";
+/** Thrown when `changed` or `indeterminate` names a component the project does not have. */
+export class UnknownComponentError extends Error {
+    constructor(field, component, known) {
+        super(`${field} names "${component}", which is not a component in this project ` +
+            `(known: ${known.join(", ") || "none"})`);
+        this.field = field;
+        this.component = component;
+        this.name = "UnknownComponentError";
+    }
+}
+/** Reverse the `dependsOn` edges: who has to re-run when this one moves. */
+function consumersOf(components) {
+    const consumers = new Map();
+    for (const c of components) {
+        for (const dep of c.dependsOn ?? []) {
+            const existing = consumers.get(dep);
+            if (existing)
+                existing.push(c.name);
+            else
+                consumers.set(dep, [c.name]);
+        }
+    }
+    return consumers;
+}
+/**
+ * Derive the fan-out for a change.
+ *
+ * Refuses a cycle and an unknown `dependsOn` before selecting anything, by
+ * resolving the **full** graph first — a broken graph is a broken graph whether
+ * or not the change happens to touch the broken part, and finding out halfway
+ * through a fan-out is worse than finding out before it starts.
+ */
+export function planFanOut(request) {
+    const { components, changed, indeterminate = [], inputDigests, canary = [] } = request;
+    // Refuses DependencyCycleError / UnknownDependencyError over the whole graph.
+    // Its `order` is deliberately not used: `topoSort` walks in declaration
+    // order, so two projects with the same graph and a different file layout
+    // would derive different-looking fan-outs and digest differently. The waves
+    // below are canonical, and this plan's order is their flattening.
+    resolveComponentGraph(components);
+    const byName = new Map(components.map((c) => [c.name, c]));
+    for (const name of changed) {
+        if (!byName.has(name))
+            throw new UnknownComponentError("changed", name, [...byName.keys()].sort());
+    }
+    for (const name of indeterminate) {
+        if (!byName.has(name))
+            throw new UnknownComponentError("indeterminate", name, [...byName.keys()].sort());
+    }
+    // Everything reachable downstream of a changed component, transitively. A
+    // component reached by two paths is added once, which is the diamond case.
+    const consumers = consumersOf(components);
+    const selected = new Set(changed);
+    const queue = [...changed];
+    while (queue.length > 0) {
+        const node = queue.shift();
+        for (const consumer of consumers.get(node) ?? []) {
+            if (selected.has(consumer))
+                continue;
+            selected.add(consumer);
+            queue.push(consumer);
+        }
+    }
+    // Waves over the selected subgraph only. An unselected dependency is already
+    // applied, so it is not a reason for its dependents to wait. The layering is
+    // the one terragucci calls without components (../gated-waves.ts).
+    // resolveComponentGraph already refused every cycle in the full graph, and a
+    // subgraph of an acyclic graph is acyclic, so it cannot stall.
+    const waves = layerWaves([...selected].map((name) => ({ name, dependsOn: byName.get(name).dependsOn ?? [] })), { canary, known: [...byName.keys()] });
+    // Every dependency lands in an earlier wave than its dependents, except
+    // where a canary list put a dependent first on purpose, so the flattening is
+    // a topological order, and a sorted one.
+    const order = waves.flat();
+    const seeds = [
+        ...new Set(order.flatMap((name) => (byName.get(name).dependsOn ?? []).filter((d) => !selected.has(d)))),
+    ].sort();
+    const unreachedIndeterminate = indeterminate.filter((name) => !selected.has(name)).sort();
+    const indeterminateSet = new Set(unreachedIndeterminate);
+    const skipped = [...byName.keys()]
+        .filter((name) => !selected.has(name))
+        .sort()
+        .map((component) => ({
+        component,
+        reason: indeterminateSet.has(component) ? "indeterminate" : "unaffected",
+    }));
+    // What the approver is approving: who runs, in what order, off which edges,
+    // and — when the caller knows it — what each one would apply. Never the run
+    // id or the moment, per ../lifecycle/plan-digest.ts's rules, so re-deriving
+    // an unchanged fan-out does not expire an approval.
+    const digest = computePlanDigest("component-fan-out", {
+        order,
+        waves,
+        seeds,
+        edges: order.map((name) => ({ component: name, dependsOn: [...(byName.get(name).dependsOn ?? [])].sort() })),
+        ...(inputDigests
+            ? { inputs: order.map((name) => ({ component: name, digest: inputDigests[name] ?? null })) }
+            : {}),
+    });
+    return { order, waves, skipped, seeds, indeterminate: unreachedIndeterminate, digest };
+}
+/**
+ * Join a stack-level change signal to the components that deploy those stacks.
+ *
+ * The key is `deployUnits` (./deploy-units.ts), which already answers "what
+ * live units does this component's composition target" for `chant components
+ * status --live`. Reusing it means a component's claim on a stack is stated
+ * once, by its deploy steps, rather than restated in a fan-out config — the
+ * same argument this module's doc makes about `dependsOn`.
+ *
+ * Changed beats indeterminate. A component deploying one stack that certainly
+ * moved and another that could not be judged is changed: the certainty already
+ * decides it, and reporting it as indeterminate would lose that.
+ */
+export function componentsForUnits(components, units) {
+    const changedUnits = new Set(units.changed);
+    const indeterminateUnits = new Set(units.indeterminate ?? []);
+    const changed = [];
+    const indeterminate = [];
+    const claimed = new Set();
+    for (const component of components) {
+        const names = deployUnits(component.deploy).map((u) => u.unit);
+        let touchesChanged = false;
+        let touchesIndeterminate = false;
+        for (const name of names) {
+            if (changedUnits.has(name)) {
+                touchesChanged = true;
+                claimed.add(name);
+            }
+            if (indeterminateUnits.has(name)) {
+                touchesIndeterminate = true;
+                claimed.add(name);
+            }
+        }
+        if (touchesChanged)
+            changed.push(component.name);
+        else if (touchesIndeterminate)
+            indeterminate.push(component.name);
+    }
+    const unclaimed = [...changedUnits, ...indeterminateUnits].filter((u) => !claimed.has(u));
+    return {
+        changed: changed.sort(),
+        indeterminate: indeterminate.sort(),
+        unclaimed: [...new Set(unclaimed)].sort(),
+    };
+}
+/**
+ * Components inside `within` that are transitively downstream of any of
+ * `roots`, each mapped to the **root** it was reached from rather than to its
+ * immediate parent — so a report names the one thing to fix instead of the
+ * nearest consequence of it.
+ *
+ * `roots` is sorted before the walk, so a component downstream of two separate
+ * roots always names the same one. Unsorted, the answer would depend on the
+ * order the caller listed them in, which is not a fact about anything.
+ *
+ * Shared by {@link remainingFanOut}, which needs it over a whole plan, and by
+ * the runner in ./fan-out-run.ts, which needs it as failures accumulate.
+ */
+export function downstreamWithin(components, within, roots) {
+    const inside = new Set(within);
+    const consumers = consumersOf(components);
+    const rootSet = new Set(roots);
+    const reached = new Map();
+    const queue = [...roots].sort();
+    while (queue.length > 0) {
+        const node = queue.shift();
+        const blamed = rootSet.has(node) ? node : reached.get(node);
+        for (const consumer of consumers.get(node) ?? []) {
+            if (!inside.has(consumer) || rootSet.has(consumer) || reached.has(consumer))
+                continue;
+            reached.set(consumer, blamed);
+            queue.push(consumer);
+        }
+    }
+    return reached;
+}
+/**
+ * Narrow a plan to what still has to run.
+ *
+ * **The digest does not change.** That is the whole point: an operator approved
+ * a fan-out, a component in the middle of it failed, and finishing the work
+ * they already approved must not ask them to approve it again. `remainingFanOut`
+ * returns the same `digest` the original derivation produced, so the standing
+ * resolution still satisfies the gate on the next attempt. Re-deriving with
+ * {@link planFanOut} would mint a new identity and invalidate the approval,
+ * which is why resume narrows a plan rather than recomputing one.
+ *
+ * **A component beneath a failure is `blocked`, never `failed`.** Nothing about
+ * it failed. It did not run because the value it would have read never landed,
+ * and the distinction is what makes the next attempt legible: an operator
+ * reading `blocked by "cluster-a"` knows to fix one thing, not fourteen.
+ *
+ * **Independent branches keep going.** The order was derived from the source,
+ * so a branch that shares no edge with the failure is *known* to be independent
+ * rather than assumed to be. Stopping it is the conservative-looking choice
+ * that throws away the reason for deriving the graph in the first place.
+ */
+export function remainingFanOut(plan, components, progress) {
+    const byName = new Map(components.map((c) => [c.name, c]));
+    const planned = new Set(plan.order);
+    const completed = new Set((progress.completed ?? []).filter((n) => planned.has(n)));
+    const failed = new Set((progress.failed ?? []).filter((n) => planned.has(n)));
+    const blockedBy = downstreamWithin(components, planned, [...failed]);
+    const runnable = new Set(plan.order.filter((n) => !completed.has(n) && !failed.has(n) && !blockedBy.has(n)));
+    // Re-layer what is left. A dependency that already applied is satisfied, so
+    // it does not hold its dependents back — the same rule the original
+    // derivation applies to a dependency outside the selection.
+    const remaining = new Set(runnable);
+    const deps = new Map([...runnable].map((n) => [n, new Set((byName.get(n)?.dependsOn ?? []).filter((d) => runnable.has(d)))]));
+    const waves = [];
+    while (remaining.size > 0) {
+        const wave = [...remaining].filter((n) => [...deps.get(n)].every((d) => !remaining.has(d))).sort();
+        for (const n of wave)
+            remaining.delete(n);
+        waves.push(wave);
+    }
+    const order = waves.flat();
+    // A completed component's outputs have to be seeded for a reference to
+    // resolve, exactly like a component that was never selected.
+    const seeds = [
+        ...new Set([
+            ...plan.seeds,
+            ...order.flatMap((n) => (byName.get(n)?.dependsOn ?? []).filter((d) => !runnable.has(d))),
+        ]),
+    ].sort();
+    const carried = plan.skipped.filter((s) => !runnable.has(s.component));
+    const skipped = [
+        ...carried,
+        ...[...completed].sort().map((component) => ({ component, reason: "already-applied" })),
+        ...[...blockedBy.entries()]
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([component, by]) => ({ component, reason: "blocked", blockedBy: by })),
+    ].sort((a, b) => a.component.localeCompare(b.component));
+    return { order, waves, skipped, seeds, indeterminate: plan.indeterminate, digest: plan.digest };
+}

package/dist/components/gate-plan.js

@@ -0,0 +1,41 @@
+/**
+ * The plan a component gate approval is bound to (#2574).
+ *
+ * An Op gate binds the digest of the change set its Plan phase produced
+ * (#2300). A component has no Plan phase: what it will do is its composition,
+ * run against one environment. So the digest is taken over that, with the
+ * same `computePlanDigest` Op gates use.
+ *
+ * ## What it covers
+ *
+ * - The environment. An approval for staging never answers prod.
+ * - The composition as this run executes it: `deploy` and `rollback` phases
+ *   with every step's authored input. A promote and a rollback run a
+ *   transformed composition (`./promote.ts`), and a rollback's pins the
+ *   recorded digest into it, so each differs from a plain deploy's.
+ * - The release being deployed, when the caller names one. A promote checks
+ *   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.
+ *
+ * ## What it leaves out
+ *
+ * Anything decided during the run: outputs of earlier phases (a fresh build's
+ * digest differs on every build that is not reproducible, and binding it
+ * would make an approval unusable by the run that consumes it) and outputs of
+ * upstream components. The run id and the time are left out for the reasons
+ * `../lifecycle/plan-digest.ts` gives.
+ */
+import { computePlanDigest } from "../lifecycle/plan-digest.js";
+/** The plan digest a component gate records and approves. */
+export function componentPlanDigest(plan) {
+    const { component } = plan;
+    return computePlanDigest("component-deploy", {
+        environment: plan.environment,
+        component: component.name,
+        deploy: component.deploy,
+        rollback: component.rollback ?? null,
+        vars: plan.vars ?? null,
+        release: plan.release ?? null,
+    });
+}

package/dist/components/gated-wave-pipeline.js

@@ -0,0 +1,46 @@
+/**
+ * The jobs of a generated gated-wave pipeline (#3049): one CI job per wave.
+ *
+ * The ruling in #3347 puts gated waves on forge CI by default, a job per
+ * wave, with approvals on `chant/lifecycle`. Each forge's generator (the
+ * gitlab and github lexicons) takes these jobs and adds its own transport;
+ * the commands and the order live here so the two cannot disagree.
+ *
+ * Job `wave-k` runs `chant components fan-out --wave-gate <gate> --wave k`.
+ * It derives the fan-out from the change, plans wave k against the outputs
+ * the record holds, decides that wave's gate and applies it. The attempt
+ * record (`--resume`) is the artifact handed from job to job: it says which
+ * components applied and what they exposed. A gate nobody approved exits 3,
+ * which fails the job; after `chant approve fan-out <gate>-wave-<k> --plan
+ * <digest>`, re-running that job carries on.
+ *
+ * How many jobs: the waves of the whole component graph, with the canary list
+ * in front. A change selects a subset, and a subset never layers deeper than
+ * the graph it came from, so a job past the change's last wave finds nothing
+ * to run and exits 0.
+ */
+import { layerWaves } from "../gated-waves.js";
+/** Where each wave job keeps the attempt record it hands the next one. */
+export const GATED_WAVE_RECORD = ".chant/fan-out.json";
+/** One job per possible wave, in order, each needing the one before. */
+export function gatedWaveJobs(components, env, options) {
+    const count = layerWaves(components.map((c) => ({ name: c.name, dependsOn: c.dependsOn ?? [] })), { ...(options.canary?.length ? { canary: options.canary } : {}) }).length;
+    const jobs = [];
+    for (let wave = 1; wave <= count; wave++) {
+        jobs.push({
+            wave,
+            jobName: `wave-${wave}`,
+            needs: wave > 1 ? [`wave-${wave - 1}`] : [],
+            command: [
+                "chant", "components", "fan-out",
+                "--base", options.base ?? "HEAD~1",
+                "--env", env,
+                "--wave-gate", options.gate,
+                ...(options.canary?.length ? ["--canary", options.canary.join(",")] : []),
+                "--wave", String(wave),
+                "--resume", GATED_WAVE_RECORD,
+            ],
+        });
+    }
+    return jobs;
+}

package/dist/components/index.js

@@ -0,0 +1,24 @@
+/**
+ * Component-native release orchestration — capability contract, starter verb
+ * set, and the thin interpret driver (epic #551, #554/#556). The pilot AWS
+ * leaves have real implementations over an injectable `CloudExecutor` (#557);
+ * every other verb remains a typed stub. See https://intentius.io/chant/components/orchestration/
+ */
+export { phase, gate, stackOutput, inferArchetype, projectToJson, isComponent, } from "./component.js";
+export { discoverComponents, } from "./discover.js";
+export { listComponents, describeComponent, computeComponentGraph, generateComponentsPipeline, runComponents, findComponentGate, resolveComponentTargets, } from "./cli-support.js";
+export { renderDriverHuman, renderDriverJson } from "./driver-output.js";
+export { CapabilityRegistry, CapabilityNotImplementedError, } from "./capability.js";
+export { createCapabilityRegistry, STARTER_VERB_FAMILIES } from "./registry.js";
+export { isCapabilityPlugin, } from "./capability-plugin.js";
+export { CapabilityManifestSchema, validateCapabilityManifest, } from "./capability-plugin-schema.js";
+export { loadCapabilityPlugin, loadCapabilityPlugins, registerCapabilityPlugins, buildCapabilityRegistry, MalformedCapabilityPluginError, DuplicateCapabilityKindError, } from "./capability-plugin-loader.js";
+export { starterCapabilityPlugin } from "./starter-plugin.js";
+export * from "./verbs/index.js";
+export * from "./builders.js";
+export { resolveComponentGraph, resolveWiring, resolveStepInput, collectComponentOutputs, accumulateComponentOutputs, runComponentDeploy, runInterpretDriver, DependencyCycleError, UnknownDependencyError, DriverRunFailure, } from "./driver.js";
+export { planFanOut, componentsForUnits, remainingFanOut, downstreamWithin, UnknownComponentError, } from "./fan-out.js";
+export { runFanOut, } from "./fan-out-run.js";
+export { renderFanOutPlan, renderFanOutHuman, renderFanOutJson, } from "./fan-out-output.js";
+export { deriveFanOut, fanOutRegistry, } from "./fan-out-support.js";
+export { EcsFargateComponent, LambdaComponent, SingleHostComposeComponent, } from "./presets/index.js";

package/dist/components/layers.js

@@ -0,0 +1,28 @@
+/**
+ * Kahn layering over a plain name graph: the wave computation
+ * `resolveComponentGraph` (./driver.ts) runs for `chant components fan-out`.
+ *
+ * It lives on its own, with no imports, so code that needs the same order
+ * without the driver can take it. The terraform lexicon's pin-bump rollout
+ * (#3189) orders roots with it, and that code has to bundle without the
+ * driver's gate and ledger modules (#3421).
+ */
+/**
+ * Split `deps` (name -> the names it depends on) into waves. A name is ready
+ * once every dependency it names has been placed in an earlier wave. Names in
+ * one wave are sorted. A dependency that is not a key of `deps` is the caller's
+ * to refuse or drop first: here it never becomes ready, so it reads as a cycle.
+ */
+export function kahnLayers(deps) {
+    const remaining = new Set(deps.keys());
+    const waves = [];
+    while (remaining.size > 0) {
+        const wave = [...remaining].filter((n) => [...deps.get(n)].every((d) => !remaining.has(d))).sort();
+        if (wave.length === 0)
+            return { cycle: [...remaining].sort() };
+        for (const n of wave)
+            remaining.delete(n);
+        waves.push(wave);
+    }
+    return { waves };
+}

package/dist/components/manifest-persistence.js

@@ -0,0 +1,108 @@
+/**
+ * Persist a component run's `BuildArchiveManifest` after a successful `chant
+ * run --components <name> --env <env>` (#609, epic #551 follow-up to
+ * #564/#568/#606/#613/#614). Mirrors ./auto-release.ts's shape exactly —
+ * same "extract from step records, then call a lifecycle-layer writer, then
+ * push, and never let a write failure fail an already-successful deploy"
+ * structure — because it is solving the same class of problem: the driver
+ * produces something worth recording durably, but the driver itself must
+ * stay capability-agnostic (../components/driver.ts takes no dependency on
+ * ../lifecycle/*), so the CLI performs the write as a post-run step.
+ *
+ * **Why here, not the driver.** Same reasoning as ./auto-release.ts's module
+ * doc: a manifest write is a git commit + push, a non-idempotent side effect
+ * with real-world I/O — exactly what `driver.ts` resists taking on (it is
+ * exercised in tests against a bare `CapabilityRegistry` with no lifecycle
+ * dependency at all). The CLI calls this after `runComponents` reports
+ * success, the same place `maybeRecordAutoRelease` is already called from
+ * (../cli/handlers/run.ts).
+ *
+ * **Extraction is duck-typed, not capability-specific.** `docker-build`,
+ * `generate-sbom`, `extract-config-bom`, and `addArchiveTemplate` (the
+ * build-family capabilities/helpers, ../components/verbs/build.ts,
+ * ./verbs/sbom.ts, ./verbs/config-bom.ts) all return `{ ..., manifest:
+ * BuildArchiveManifest }` — the accumulation convention documented on each of
+ * their inputs ("manifest to extend... same accumulation convention"). This
+ * module scans a run's step outputs for that shape, exactly the way
+ * ./auto-release.ts's `extractRunDigest` scans for a publish-shaped output,
+ * so a new build-family capability that follows the same `{ manifest }`
+ * output convention is picked up automatically — no branch here names a
+ * specific capability `kind`.
+ */
+import { persistBuildManifest } from "../lifecycle/build-ledger-store.js";
+import { pushLifecycle } from "../lifecycle/git.js";
+/** A step output shaped like it carries a `BuildArchiveManifest` — duck-typed the same way ./auto-release.ts's `isPublishShaped` detects a publish result. */
+function isManifestShaped(output) {
+    return (!!output &&
+        typeof output === "object" &&
+        "manifest" in output &&
+        !!output.manifest &&
+        typeof output.manifest === "object");
+}
+/**
+ * Find the most fully-accumulated `BuildArchiveManifest` a component run
+ * produced, by scanning its step records for the last manifest-bearing
+ * output — mirroring `extractRunDigest`'s "last wins" convention, which is
+ * also the correct one here: every build-family capability's `manifest`
+ * input/output accumulates onto whatever manifest came before it in the same
+ * phase (see ../components/verbs/build.ts's `DockerBuildInput.manifest`
+ * doc), so the *last* manifest-bearing step output in run order is always
+ * the fullest one — a template + SBOM + config-BOM composition's final step
+ * carries every earlier entry too, not just its own.
+ */
+export function extractRunManifest(records) {
+    let found;
+    for (const record of records) {
+        if (record.status !== "ok")
+            continue;
+        if (isManifestShaped(record.output)) {
+            found = record.output.manifest;
+        }
+    }
+    return found;
+}
+/**
+ * After a successful `chant run --components <name> --env <env>` (local
+ * executor), persist the run's accumulated `BuildArchiveManifest` (if any)
+ * to the durable build-manifest store (../lifecycle/build-ledger-store.ts)
+ * and push it — or explain, without throwing, why it didn't. Never called
+ * for a failed run, matching `maybeRecordAutoRelease`'s contract exactly.
+ *
+ * Skips (returns `{ persisted: false, reason }`, never throws):
+ *  - `options.disabled` — the opt-out flag/config was set.
+ *  - `run.success` false — defensive; callers should not reach here on
+ *    failure. A dry-run/failed deploy persists nothing, by construction —
+ *    this is also what makes a dry run safe: `chant run --components` never
+ *    calls this function at all unless the run actually completed.
+ *  - no manifest found in the run's records — a component with no
+ *    build-family step (an infra-only/apply-only component, or a
+ *    build-less `Publish`-only producer that reused a prior archive) has
+ *    nothing to persist. This is the expected common case for most deploys,
+ *    not an error.
+ *
+ * Write/push failures (any error `persistBuildManifest`/`pushLifecycle`
+ * throw) are reported as `{ persisted: false, reason: "error", error }`
+ * rather than propagated — same "never turn a successful deploy into a
+ * failing CLI invocation" contract `maybeRecordAutoRelease` already
+ * establishes for release records.
+ */
+export async function maybePersistBuildManifest(run, options = {}) {
+    if (options.disabled) {
+        return { persisted: false, reason: "opted-out" };
+    }
+    if (!run.success) {
+        return { persisted: false, reason: "run-not-successful" };
+    }
+    const manifest = run.manifest ?? extractRunManifest(run.records ?? []);
+    if (!manifest) {
+        return { persisted: false, reason: "no-manifest" };
+    }
+    try {
+        const { commit } = await persistBuildManifest(manifest, { cwd: options.cwd });
+        await pushLifecycle({ cwd: options.cwd });
+        return { persisted: true, commit, manifestDigest: manifest.manifestDigest };
+    }
+    catch (err) {
+        return { persisted: false, reason: "error", error: err instanceof Error ? err.message : String(err) };
+    }
+}

package/dist/components/pilots/alb-ecs.pilot.js

@@ -0,0 +1,59 @@
+/**
+ * Pilot: ALB/ECS target (#555, epic #551).
+ *
+ * Exercises the build + cross-stack axes: `docker-build` →
+ * `publish-image` (promote by digest, deploy-time) → `cfn-deploy` (importing
+ * the shared ALB's listener/cluster/subnets as cross-stack outputs, resolved
+ * by `chant graph --stacks` rather than a `describe-stacks | jq` pipeline
+ * step — see composition-and-wiring.mdx#cross-stack-outputs) →
+ * `ecs-update-service` → `wait-steady-state` + `health-gate`.
+ *
+ * This is the direct component-native replacement for the hand-rolled GitLab
+ * pipeline in `examples/gitlab-aws-alb-services/src/pipeline.ts`: the
+ * `describe-stacks`/`jq` glue in that pipeline's `deployServices` job is
+ * exactly the cross-stack `stackOutput()` wiring below, and its
+ * `docker build`/`docker push` steps are the `docker-build` + `publish-image`
+ * capabilities. `service` archetype: build → publish → apply → verify, the
+ * fullest of the three archetypes.
+ *
+ * It declares no component-level `rollback` phase (#2576). It used to declare
+ * one holding a `rollback-previous` step with only `service` and `cluster`,
+ * which the aws capability turned into an `aws ecs update-service` with no
+ * changes. Taking an environment back to an earlier recorded release is
+ * `chant components rollback` (#2531).
+ *
+ * The JSON projection of this pilot is authoritative at
+ * ../__fixtures__/alb-ecs-service.json (already schema-validated by
+ * component-schema.test.ts) — this module is the real typed `Component`
+ * authoring form (#560, ../component.ts) that composes to that same
+ * document; see ./pilots.test.ts, which asserts the two never diverge.
+ */
+import { phase, stackOutput } from "../component.js";
+/** The shared ALB stack's exported outputs this service imports — the cross-stack wiring axis. */
+const sharedAlbOutputs = {
+    listenerArn: stackOutput("shared-alb", "ListenerArn"),
+    clusterArn: stackOutput("shared-alb", "ClusterArn"),
+    subnets: stackOutput("shared-alb", "Subnets"),
+};
+export const searchService = {
+    name: "search-service",
+    archetype: "service",
+    dependsOn: ["shared-alb"],
+    build: { kind: "docker-build", context: ".", into: "archive" },
+    deploy: [
+        phase("Publish", [{ kind: "publish-image", from: "archive", to: "$env.registry" }]),
+        phase("Apply", [
+            {
+                kind: "cfn-deploy",
+                template: "archive:search.template.json",
+                imageRef: "@Publish.digest",
+                inputs: sharedAlbOutputs,
+            },
+            { kind: "ecs-update-service", cluster: "$env.cluster", service: "search" },
+        ]),
+        phase("Verify", [
+            { kind: "wait-steady-state", service: "search" },
+            { kind: "health-gate", path: "/healthz" },
+        ]),
+    ],
+};