@intentius/chant 0.124.40 → 0.124.42

package/src/components/capability.ts

@@ -72,6 +72,14 @@ export interface DeployContext {
    * against missing values.
    */
   unresolvedInputs?: string[];
+  /**
+   * The addresses this component's steps narrow to (#4300), from
+   * `--target <component>:<address>`, sorted. A step's `plan` plans only
+   * these, and its `run` applies only these. Every capability step of the
+   * component must accept targets ({@link Capability.targets}), or the
+   * component refuses before anything plans or runs. Absent: the whole step.
+   */
+  targets?: string[];
 }
 
 /**
@@ -101,6 +109,14 @@ export interface CapabilityPlan {
    * applies.
    */
   outputs?: PlannedOutputs;
+  /**
+   * The targets this plan narrowed to (#4300), sorted. A plan made with
+   * `DeployContext.targets` gives them back, which says it planned only
+   * those. Planning binds them into the member's digest
+   * ({@link targetedPlanDigest} in ./wave-plan.ts), so an approval of a
+   * targeted plan covers that plan and no other.
+   */
+  targets?: string[];
 }
 
 /**
@@ -176,11 +192,44 @@ export interface Capability<In = unknown, Out = unknown> {
    * compensation gap. See ../lint/rules/comp/comp003-mutating-no-rollback.ts.
    */
   readonly rollbackPolicy?: RollbackPolicy;
+  /**
+   * Whether this verb narrows to `DeployContext.targets` (#4300). `"accept"`:
+   * its `plan` and `run` act on the targets alone, and its plan gives them
+   * back in {@link CapabilityPlan.targets}. `{ refuse }`: it can't, and says
+   * why. Unset refuses too, with a reason that names the verb.
+   */
+  readonly targets?: TargetSupport;
 }
 
 /** A capability's relationship to rollback — see `Capability.rollbackPolicy`. */
 export type RollbackPolicy = "native" | "none-by-design" | "needs-opt-out";
 
+/** Whether a capability accepts `DeployContext.targets` (#4300). See `Capability.targets`. */
+export type TargetSupport = "accept" | { refuse: string };
+
+/**
+ * A component was asked to narrow to targets (#4300) and one of its steps'
+ * capabilities refuses them. Nothing in the component plans or runs.
+ */
+export class TargetsRefusedError extends Error {
+  constructor(
+    readonly component: string,
+    readonly kind: string,
+    readonly reason: string,
+  ) {
+    super(`component "${component}": ${kind} refuses targets: ${reason}`);
+    this.name = "TargetsRefusedError";
+  }
+}
+
+/** Why `capability` refuses targets, or `undefined` when it accepts them (#4300). */
+export function targetRefusal(capability: Pick<Capability<never, unknown>, "kind" | "targets">): string | undefined {
+  const t = capability.targets;
+  if (t === "accept") return undefined;
+  if (t && typeof t === "object" && typeof t.refuse === "string") return t.refuse;
+  return `${capability.kind} does not say it can narrow to targets`;
+}
+
 /** Extract a capability's `In` type. */
 export type CapabilityInput<C> = C extends Capability<infer In, unknown> ? In : never;
 /** Extract a capability's `Out` type. */
@@ -257,3 +306,25 @@ export class CapabilityRegistry {
     return [...this.capabilities.keys()].sort();
   }
 }
+
+/**
+ * `--target <component>:<address>` values (#4300), grouped by component with
+ * each component's addresses sorted and unique. The address is everything
+ * after the first `:`, so it may hold colons of its own. Throws for a value
+ * with no component or no address, and, given `known`, for a component not
+ * among them.
+ */
+export function parseComponentTargets(values: readonly string[], known?: ReadonlySet<string>): Record<string, string[]> {
+  const out: Record<string, Set<string>> = {};
+  for (const value of values) {
+    const at = value.indexOf(":");
+    const component = at > 0 ? value.slice(0, at).trim() : "";
+    const address = at > 0 ? value.slice(at + 1).trim() : "";
+    if (component === "" || address === "") throw new Error(`--target needs a component and an address: --target <component>:<address>, got "${value}"`);
+    if (known && !known.has(component)) {
+      throw new Error(`--target ${value}: no component is named ${component} (components: ${[...known].sort().join(", ") || "none"})`);
+    }
+    (out[component] ??= new Set()).add(address);
+  }
+  return Object.fromEntries(Object.entries(out).sort(([a], [b]) => a.localeCompare(b)).map(([c, s]) => [c, [...s].sort()]));
+}

package/src/components/cli-support.ts

@@ -390,6 +390,12 @@ export function findComponentGate(component: DriverComponent): { gate: string }
 export interface RunComponentsOptions {
   /** Target environment name, threaded into every capability's `DeployContext.env` (default: "local"). */
   env?: string;
+  /**
+   * The addresses each component's steps narrow to (#4300), by component
+   * (`--target <component>:<address>`). A name the run does not run refuses
+   * the run before anything starts.
+   */
+  targets?: Readonly<Record<string, readonly string[]>>;
   /**
    * chant #1051 — opt-in: discover `*.component.ts` files in a sandboxed
    * child process (`chant run --components <name|all> --sandbox`) instead of
@@ -664,6 +670,12 @@ export async function runComponents(
     return { success: false, selected: [], error: resolved.error };
   }
   const targets = resolved.targets;
+  const narrowed = options.targets ?? {};
+  const outside = Object.keys(narrowed).filter((name) => !targets.some((c) => c.name === name));
+  if (outside.length > 0) {
+    return { success: false, selected: [], error: `--target names ${outside.join(", ")}, which this run does not run` };
+  }
+  const targeted = Object.keys(narrowed).length > 0 ? { targets: narrowed } : {};
 
   // (#629) Resolve `chant.config.ts`'s `sbom`/`signing`/`vulnPolicy` sections
   // and fill their defaults into every recognized step (`generate-sbom`,
@@ -712,6 +724,7 @@ export async function runComponents(
       const run = await runInterpretDriver(resolvedTargets, registry, {
         env,
         releaseIdentity,
+        ...targeted,
         componentOutputs: seedOutputs,
         ...(emit ? { onRunEvent: emit } : {}),
         ...(gates ? { gates } : {}),
@@ -755,7 +768,7 @@ export async function runComponents(
     emit?.({ type: "component-start", wave: 1, component: componentName });
     const componentResult = await runComponentDeploy(
       resolvedTargets[0],
-      deployContext({ env, releaseIdentity }, componentName),
+      deployContext({ env, releaseIdentity, ...targeted }, componentName),
       registry,
       componentOutputs,
       undefined,

package/src/components/driver.ts

@@ -55,7 +55,7 @@ import { componentPlanDigest } from "./gate-plan";
 import { componentDeployInputs } from "./deploy-inputs";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import type { CapabilityRegistry, DeployContext } from "./capability";
-import { isPlanMovedError, PLAN_MOVED_EXIT_CODE } from "./capability";
+import { isPlanMovedError, PLAN_MOVED_EXIT_CODE, TargetsRefusedError, targetRefusal } from "./capability";
 import { isPromotedArtifact } from "./auto-release";
 import type { ReleaseIdentity } from "../telemetry-attribution";
 import type { RunProgressEvent } from "./run-progress";
@@ -889,6 +889,18 @@ export async function runComponentDeploy(
   onRunEvent?: RunEventSink,
 ): Promise<DriverComponentResult> {
   const emit = joinRunEventSinks(onRunEvent, progressSinkOf(onProgress));
+  // #4300: a component narrowed to targets runs only when every step can narrow.
+  try {
+    assertTargetsAccepted(component, registry, ctx);
+  } catch (err) {
+    if (!(err instanceof TargetsRefusedError)) throw err;
+    return {
+      component: component.name,
+      ok: false,
+      status: "fail",
+      records: [{ component: component.name, phase: "Targets", kind: err.kind, status: "fail", durationMs: 0, error: err.message }],
+    };
+  }
   // Each component tracks its own release: a digest one component promoted never stamps another's deploy.
   if (ctx.release) ctx = { ...ctx, release: { ...ctx.release } };
   const phaseOutputs: Record<string, Record<string, unknown>> = {};
@@ -908,6 +920,7 @@ export async function runComponentDeploy(
         component,
         ...(ctx.vars ? { vars: ctx.vars } : {}),
         ...(release !== undefined ? { release } : {}),
+        ...(ctx.targets ? { targets: ctx.targets } : {}),
         // #4155: the files the steps deploy from, read where the steps read
         // them. Only a gate reads the digest, so a run with none skips the hashing.
         ...(hasGateStep(component) ? { inputs: componentDeployInputs(component.deploy, process.cwd()).inputs } : {}),
@@ -1121,6 +1134,8 @@ export interface InterpretRunOptions {
    * step promotes an artifact. Absent: no deploy step sees a release.
    */
   releaseIdentity?: (component: string) => ReleaseIdentity | undefined;
+  /** The addresses each component narrows to (#4300), by component: its `DeployContext.targets`. */
+  targets?: Readonly<Record<string, readonly string[]>>;
 }
 
 /**
@@ -1144,11 +1159,47 @@ export interface InterpretRunOptions {
  */
 /** A component's `DeployContext` for a run: its env, vars and, when the caller knows it, its release. */
 export function deployContext(
-  options: { env: string; vars?: Record<string, unknown>; releaseIdentity?: (component: string) => ReleaseIdentity | undefined },
+  options: {
+    env: string;
+    vars?: Record<string, unknown>;
+    releaseIdentity?: (component: string) => ReleaseIdentity | undefined;
+    targets?: Readonly<Record<string, readonly string[]>>;
+  },
   component: string,
 ): DeployContext {
   const release = options.releaseIdentity?.(component);
-  return { env: options.env, component, ...(options.vars ? { vars: options.vars } : {}), ...(release ? { release: { ...release } } : {}) };
+  const targets = options.targets?.[component];
+  return {
+    env: options.env,
+    component,
+    ...(options.vars ? { vars: options.vars } : {}),
+    ...(release ? { release: { ...release } } : {}),
+    ...(targets && targets.length > 0 ? { targets: [...new Set(targets)].sort() } : {}),
+  };
+}
+
+/**
+ * Refuse a component asked to narrow to `ctx.targets` (#4300) when one of its
+ * capability steps can't: throws {@link TargetsRefusedError} naming the first
+ * such verb, in composition order. A step whose kind is not registered
+ * refuses too. Does nothing when `ctx.targets` is absent.
+ */
+export function assertTargetsAccepted(component: DriverComponent, registry: CapabilityRegistry, ctx: DeployContext): void {
+  if (!ctx.targets || ctx.targets.length === 0) return;
+  const walk = (steps: DriverPhase["steps"]): void => {
+    for (const step of steps) {
+      if (typeof (step as DriverPhase).phase === "string" && Array.isArray((step as DriverPhase).steps)) {
+        walk((step as DriverPhase).steps);
+        continue;
+      }
+      const kind = (step as { kind?: unknown }).kind;
+      if (kind === "gate" || typeof kind !== "string") continue;
+      if (!registry.has(kind)) throw new TargetsRefusedError(component.name, kind, `no capability is registered for ${kind}`);
+      const reason = targetRefusal(registry.resolve(kind));
+      if (reason !== undefined) throw new TargetsRefusedError(component.name, kind, reason);
+    }
+  };
+  for (const phase of component.deploy) walk(phase.steps);
 }
 
 export async function runInterpretDriver(

package/src/components/fan-out-run.ts

@@ -54,6 +54,7 @@ import type { CapabilityRegistry } from "./capability";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import type { DeployContext } from "./capability";
 import { planWaveComponent, type WaveComponentPlan } from "./wave-plan";
+import { computePlanDigest } from "../lifecycle/plan-digest";
 import { decideWaveGate, runWaveLoop, waveGateName, waveSetDigest, type WaveMember, type WaveRecord } from "../wave-engine";
 
 /** The sink a fan-out emits to: run events, and the older stream through them. */
@@ -129,6 +130,19 @@ export interface FanOutWaveGate {
    * do not exist yet. A later wave is left for its own job.
    */
   only?: number;
+  /**
+   * With `only` (#4291): members of earlier waves the record says failed to
+   * plan or to apply. Each blocks its dependents in this wave and names
+   * itself as what blocked them; the rest of the wave runs. An earlier
+   * member that neither applied nor failed still refuses the run.
+   */
+  failedEarlier?: readonly string[];
+  /**
+   * With `only` (#4291): earlier waves the record says stopped at their gate.
+   * A member left in one of them stops this wave too ({@link EarlierWaveWaitingError}),
+   * since a gate nobody approved stops every wave after it.
+   */
+  waitingEarlier?: ReadonlyArray<{ wave: number; gate: string; components: readonly string[] }>;
 }
 
 /** Thrown when `FanOutWaveGate.only` names a wave whose predecessors have not all applied. */
@@ -146,6 +160,22 @@ export class EarlierWaveNotAppliedError extends Error {
   }
 }
 
+/**
+ * Thrown when `FanOutWaveGate.only` names a wave after one that waits at its
+ * gate (#4291): nothing in this wave runs until that gate is approved and
+ * its job runs again. The CLI exits 3, as the waiting wave's job does.
+ */
+export class EarlierWaveWaitingError extends Error {
+  constructor(
+    readonly wave: number,
+    readonly earlier: number,
+    readonly gate: string,
+  ) {
+    super(`wave ${wave} does not run yet: wave ${earlier} waits at its gate ${gate}. Approve it and run wave ${earlier} again, then this wave.`);
+    this.name = "EarlierWaveWaitingError";
+  }
+}
+
 /** The single gate over a whole fan-out. Omit it to run without one. */
 export interface FanOutGate {
   /** The name `chant approve <op> <gate>` takes — the fan-out's name, not a component's. */
@@ -158,6 +188,8 @@ export interface FanOutGate {
 export interface FanOutRunOptions {
   env: string;
   vars?: Record<string, unknown>;
+  /** The addresses each component narrows to (#4300), by component: its steps' `DeployContext.targets`. */
+  targets?: Readonly<Record<string, readonly string[]>>;
   /** Outputs of components this run is not running: the ones the plan lists in `seeds`. */
   componentOutputs?: Record<string, Record<string, unknown>>;
   onProgress?: (event: RunProgressEvent) => void;
@@ -290,7 +322,7 @@ export async function runFanOut(
       evaluateGate(gates.port, {
         op: gate.op,
         gate: gate.gate,
-        planDigest: active.digest,
+        planDigest: fanOutGateDigest(active.digest, options.targets),
         ...(gate.description ? { description: gate.description } : {}),
         ...(gate.timeout ? { timeout: gate.timeout } : {}),
         ...(options.now ? { now: options.now } : {}),
@@ -426,6 +458,21 @@ export async function runFanOut(
   };
 }
 
+/**
+ * The digest a gate over the whole set binds: the derivation's digest, and,
+ * when the run narrows components to targets (#4300), the digest over it and
+ * every component's sorted targets. An approval of the whole set then covers
+ * no narrowed run, and one narrowed run's approval covers no other.
+ */
+export function fanOutGateDigest(digest: string, targets: FanOutRunOptions["targets"]): string {
+  const narrowed = Object.entries(targets ?? {})
+    .filter(([, t]) => t.length > 0)
+    .map(([component, t]) => [component, [...new Set(t)].sort()] as const)
+    .sort(([a], [b]) => a.localeCompare(b));
+  if (narrowed.length === 0) return digest;
+  return computePlanDigest("fan-out-targets", { plan: digest, targets: Object.fromEntries(narrowed) });
+}
+
 /** The run's `deployContext`, with the carried state and the carry callback (#3459) when the caller gave them. */
 function fanOutContext(options: FanOutRunOptions, component: string): DeployContext {
   return {
@@ -518,7 +565,13 @@ async function runGatedWaves(
       if (!wave) return { end: "stop" };
       const runnable = wave.filter((name) => left.has(name) && !blockedBy.has(name));
       if (waveGate.only !== undefined && waveNum < waveGate.only) {
-        if (runnable.length > 0) throw new EarlierWaveNotAppliedError(waveGate.only, waveNum, runnable);
+        // #4291: an earlier member that failed blocks only its dependents; one that waits at its gate stops this wave.
+        const failedBefore = new Set(waveGate.failedEarlier ?? []);
+        const open = runnable.filter((name) => !failedBefore.has(name));
+        const waiting = waveGate.waitingEarlier?.find((w) => w.wave === waveNum && open.some((name) => w.components.includes(name)));
+        if (waiting) throw new EarlierWaveWaitingError(waveGate.only, waveNum, waiting.gate);
+        if (open.length > 0) throw new EarlierWaveNotAppliedError(waveGate.only, waveNum, open);
+        for (const name of runnable) markBlocked(name);
         return { end: "next" };
       }
       if (waveGate.only !== undefined && waveNum > waveGate.only) return { end: "stop" };
@@ -664,7 +717,9 @@ async function runGatedWaves(
     .sort(([a], [b]) => a.localeCompare(b))
     .map(([component, by]) => ({ component, reason: "blocked" as const, blockedBy: by }));
 
-  const status: FanOutRunResult["status"] = failed.length > 0 ? "fail" : gatedFact ? "gated" : "ok";
+  // #4291: a member of this job's wave that an earlier job's failure blocked fails the job, though the rest of the wave applied.
+  const blockedHere = waveGate.only !== undefined && (plan.waves[waveGate.only - 1] ?? []).some((name) => blockedBy.has(name));
+  const status: FanOutRunResult["status"] = failed.length > 0 || blockedHere ? "fail" : gatedFact ? "gated" : "ok";
   emit?.({ type: "run-settle", status: status === "fail" ? "failed" : status, durationMs: null });
 
   return {

package/src/components/fan-out-waves.test.ts

@@ -11,7 +11,7 @@ import { describe, expect, test } from "vitest";
 import { CapabilityRegistry, type DeployContext } from "./capability";
 import { memoryGateLedgerPort } from "../op/gate";
 import { planFanOut } from "./fan-out";
-import { EarlierWaveNotAppliedError, runFanOut, type FanOutRunOptions } from "./fan-out-run";
+import { EarlierWaveNotAppliedError, EarlierWaveWaitingError, runFanOut, type FanOutRunOptions } from "./fan-out-run";
 import { computePlanDigest } from "../lifecycle/plan-digest";
 import type { DriverComponent } from "./driver";
 import type { GateResolutionRecord, PendingGateRecord } from "../lifecycle/gate-ledger";
@@ -354,6 +354,50 @@ describe("one wave per CI job", () => {
   });
 });
 
+describe("a failed member blocks only its dependents across wave jobs (#4291)", () => {
+  /** net, then a and b, then app (reads a) and web (reads b). */
+  const WIDE: DriverComponent[] = [...ESTATE, root("web", ["b"])];
+
+  test("wave 3's job blocks what an earlier job's failure holds, and plans the rest", async () => {
+    const w = world();
+    const plan = planFanOut({ components: WIDE, changed: ["net"] });
+    const result = await runFanOut(plan, WIDE, w.registry, {
+      ...waveOptions(ledger()),
+      waveGate: { op: "fan-out", gate: "release", only: 3, failedEarlier: ["a"] },
+      progress: { completed: ["net", "b"] },
+    });
+    expect(result.blocked).toEqual([{ component: "app", reason: "blocked", blockedBy: "a" }]);
+    expect(w.planned.map((p) => p.root)).toEqual(["web"]);
+    // A member of the job's own wave was blocked, so the job fails though web went on to its gate.
+    expect(result.status).toBe("fail");
+  });
+
+  test("an earlier member that neither applied nor failed still refuses the job", async () => {
+    const w = world();
+    const plan = planFanOut({ components: WIDE, changed: ["net"] });
+    await expect(
+      runFanOut(plan, WIDE, w.registry, {
+        ...waveOptions(ledger()),
+        waveGate: { op: "fan-out", gate: "release", only: 3, failedEarlier: ["a"] },
+        progress: { completed: ["net"] },
+      }),
+    ).rejects.toThrow(EarlierWaveNotAppliedError);
+  });
+
+  test("an earlier wave that waits at its gate stops the job", async () => {
+    const w = world();
+    const plan = planFanOut({ components: WIDE, changed: ["net"] });
+    await expect(
+      runFanOut(plan, WIDE, w.registry, {
+        ...waveOptions(ledger()),
+        waveGate: { op: "fan-out", gate: "release", only: 3, waitingEarlier: [{ wave: 2, gate: "release-wave-2", components: ["a", "b"] }] },
+        progress: { completed: ["net"] },
+      }),
+    ).rejects.toThrow(EarlierWaveWaitingError);
+    expect(w.planned).toEqual([]);
+  });
+});
+
 describe("both modes", () => {
   test("a run takes one gate over the set or one per wave, not both", async () => {
     const w = world();

package/src/components/gate-plan.ts

@@ -45,6 +45,8 @@ export interface ComponentGatePlan {
   release?: string;
   /** What the steps deploy from (`componentDeployInputs`), when the caller read it. */
   inputs?: readonly DeployInputDigest[];
+  /** The addresses the component narrows to (#4300), sorted. A gate's approval then covers that narrowing alone. */
+  targets?: readonly string[];
 }
 
 /** The plan digest a component gate records and approves. */
@@ -58,5 +60,6 @@ export function componentPlanDigest(plan: ComponentGatePlan): string {
     vars: plan.vars ?? null,
     release: plan.release ?? null,
     ...(plan.inputs && plan.inputs.length > 0 ? { inputs: plan.inputs } : {}),
+    ...(plan.targets && plan.targets.length > 0 ? { targets: [...plan.targets].sort() } : {}),
   });
 }