@intentius/chant 0.124.51 → 0.124.54

package/src/cli/handlers/promote.test.ts

@@ -18,6 +18,9 @@ const readReleaseLedgerMock = vi.fn();
 const pushLifecycleMock = vi.fn();
 const resolveTargetsMock = vi.fn();
 const ran: string[] = [];
+/** #4516: the reads the fake `import-apply` declares, and the order its steps ran in. */
+let importReads: Array<{ reader: string; upstream: string; output: string; at: string }> = [];
+const importApplied: Array<{ component: string; input: unknown }> = [];
 const stepInputs: Array<{ kind: string; input: unknown }> = [];
 let releaseFixture: { release: import("../../lifecycle/release-store").Release; label: string | null } | null = null;
 let storedTemplate: string | null = null;
@@ -64,6 +67,15 @@ vi.mock("../../components/fan-out-support", () => ({
       if (ctx.component === failApplyFor) throw applyError ?? new Error("apply failed");
       return {};
     });
+    // #4516: a stack step whose template imports another component's export, found by `declaredReads`.
+    registry.register({
+      kind: "import-apply",
+      declaredReads: (_ctx: unknown, members: ReadonlyArray<{ component: string }>) => importReads.filter((r) => members.some((m) => m.component === r.reader)),
+      async run(ctx: DeployContext, input: unknown) {
+        importApplied.push({ component: ctx.component, input });
+        return { outputs: { VpcId: `${ctx.component}-vpc` } };
+      },
+    } as never);
     // #4045: a planner whose member is provisional.
     registry.register({
       kind: "plan-provisional",
@@ -226,6 +238,8 @@ beforeEach(() => {
   removedTemplates.length = 0;
   ran.length = 0;
   stepInputs.length = 0;
+  importReads = [];
+  importApplied.length = 0;
   writtenTemplates.length = 0;
   releaseFixture = null;
   storedTemplate = null;
@@ -429,6 +443,56 @@ describe("chant components promote", () => {
   });
 });
 
+describe("chant components promote orders an importer after its exporter (#4516)", () => {
+  /** A component that publishes its image and applies one stack. */
+  const stackComponent = (name: string): DriverComponent => ({
+    name,
+    deploy: [
+      { phase: "Build", steps: [{ kind: "docker-build", context: ".", into: "api.tar" }] },
+      { phase: "Publish", steps: [{ kind: "publish-image", from: "archive:api.tar" }] },
+      { phase: "Apply", steps: [{ kind: "import-apply", stack: name }] },
+    ],
+  });
+  // Discovered importer first, so only the read can put network ahead of it.
+  const app = stackComponent("app");
+  const network = stackComponent("network");
+  const read = { reader: "app", upstream: "network", output: "VpcId", at: "/imports/Net-VpcId" };
+
+  beforeEach(() => {
+    readReleaseLedgerMock.mockResolvedValue({ records: [{ ...staging, component: "app" }, { ...staging, component: "network" }], malformed: 0 });
+    resolveTargetsMock.mockResolvedValue({ success: true, targets: [app, network] });
+  });
+
+  test("a template's Fn::ImportValue of another promoted component's export deploys the exporter first and hands the importer its output", async () => {
+    importReads = [read];
+    expect(await runComponentsPromote(ctx({}))).toBe(0);
+    expect(importApplied.map((a) => a.component)).toEqual(["network", "app"]);
+    expect(importApplied[1]!.input).toMatchObject({ stack: "app", imports: { "Net-VpcId": "network-vpc" } });
+    expect(appendReleaseRecordMock).toHaveBeenCalledTimes(2);
+  });
+
+  test("with no declared read the two deploy as one wave and the importer gets no imports", async () => {
+    expect(await runComponentsPromote(ctx({}))).toBe(0);
+    expect(importApplied.map((a) => a.component).sort()).toEqual(["app", "network"]);
+    expect((importApplied.find((a) => a.component === "app")!.input as Record<string, unknown>).imports).toBeUndefined();
+  });
+
+  test("a read of a component this promote does not deploy is left out: the importer deploys alone", async () => {
+    importReads = [read];
+    resolveTargetsMock.mockResolvedValue({ success: true, targets: [app] });
+    expect(await runComponentsPromote(ctx({ component: "app" }))).toBe(0);
+    expect(importApplied.map((a) => a.component)).toEqual(["app"]);
+    expect((importApplied[0]!.input as Record<string, unknown>).imports).toBeUndefined();
+  });
+
+  test("--dry-run with a declared read still deploys nothing", async () => {
+    importReads = [read];
+    expect(await runComponentsPromote(ctx({ dryRun: true, json: true }))).toBe(0);
+    expect(importApplied).toEqual([]);
+    expect(appendReleaseRecordMock).not.toHaveBeenCalled();
+  });
+});
+
 describe("chant components promote --release (#4026)", () => {
   const prodTemplate = `{"env":"prod"}\n`;
   const withTemplate: DriverComponent = {

package/src/cli/handlers/promote.ts

@@ -39,6 +39,7 @@ import {
 } from "../../lifecycle/release-ledger";
 import { isComponentList, resolveComponentTargets } from "../../components/cli-support";
 import { applyConfigDefaults } from "../../components/config-defaults";
+import { withDeclaredReads } from "../../components/declared-reads";
 import { fanOutRegistry } from "../../components/fan-out-support";
 import { renderDriverHuman } from "../../components/driver-output";
 import { ndjsonProgressSink } from "../../components/run-progress";
@@ -172,6 +173,9 @@ interface BoundReleaseGate {
   unknownInputs?: Record<string, string[]>;
   /** The approval a resume record carried on, when it still covers what is left. */
   resumedFrom?: string;
+  /** The groups the plan planned as one (#4465), and the components that could have grouped and did not. */
+  groups?: import("../../components/release-gate").ReleasePlanGroup[];
+  fallbacks?: import("../../components/fan-out").FanOutGroupFallback[];
   replan: (only: ReadonlySet<string>, outputs: Record<string, Record<string, unknown>>) => Promise<ChangeSetDocument>;
   bind: (doc: ChangeSetDocument, gates: string[]) => Promise<ReleaseGateBinding>;
 }
@@ -200,6 +204,10 @@ async function bindReleaseGate(input: {
   projectPath: string;
   head: string | undefined;
   resume?: import("../../components/promote-rounds").PromoteResume;
+  /** The grouped fan-out (#4465): its groups plan as one. */
+  grouped?: import("../../components/fan-out").FanOutPlan;
+  /** Each group plan this binding makes is added here, the newest first, for the run to apply. */
+  groupRuns: import("../../components/capability").GroupRun[];
 }): Promise<BoundReleaseGate | number | undefined> {
   const { plan, under, port } = input;
   const gate = await import("../../components/release-gate");
@@ -230,8 +238,8 @@ async function bindReleaseGate(input: {
   }
 
   const digests = new Map(plan.items.map((i) => [i.component, i.digest]));
-  const planSet = (only: ReadonlySet<string> | undefined, outputs: Record<string, Record<string, unknown>>) =>
-    gate.planReleaseSet({
+  const planSet = async (only: ReadonlySet<string> | undefined, outputs: Record<string, Record<string, unknown>>) => {
+    const planned = await gate.planReleaseSet({
       release: under.release,
       env,
       components: input.prepared,
@@ -241,7 +249,13 @@ async function bindReleaseGate(input: {
       unsettled,
       seededOutputs: outputs,
       ...(only ? { only } : {}),
+      ...(input.grouped ? { grouped: input.grouped } : {}),
     });
+    // #4465: the run applies the plan the gate bound, the newest one for a group planned again.
+    for (const g of planned.groups ?? []) if (g.run) input.groupRuns.unshift(g.run);
+    return planned;
+  };
+  const groupsOf = (p: Awaited<ReturnType<typeof planSet>>) => ({ ...(p.groups ? { groups: p.groups } : {}), ...(p.fallbacks ? { fallbacks: p.fallbacks } : {}) });
 
   const { storeGateChangeSet } = await import("../../lifecycle/gate-change-set");
   const { readStoredChangeSet } = await import("../../lifecycle/change-set-store");
@@ -322,6 +336,7 @@ async function bindReleaseGate(input: {
           binding: { op: gate.RELEASE_GATE_OP, planDigest: stored.document.digest, releaseDigest, verifyEmpty },
           reads: fresh.reads,
           resumedFrom: stored.document.digest,
+          ...groupsOf(fresh),
           ...(fresh.plannedOutputs ? { plannedOutputs: fresh.plannedOutputs } : {}),
           ...(fresh.unknownInputs ? { unknownInputs: fresh.unknownInputs } : {}),
           ...later,
@@ -331,7 +346,7 @@ async function bindReleaseGate(input: {
     }
     const bound = await bindDoc(fresh.doc, gates, "change set");
     if (typeof bound === "number") return bound;
-    return { doc: fresh.doc, ...bound, reads: fresh.reads, ...(fresh.plannedOutputs ? { plannedOutputs: fresh.plannedOutputs } : {}), ...(fresh.unknownInputs ? { unknownInputs: fresh.unknownInputs } : {}), ...later };
+    return { doc: fresh.doc, ...bound, reads: fresh.reads, ...groupsOf(fresh), ...(fresh.plannedOutputs ? { plannedOutputs: fresh.plannedOutputs } : {}), ...(fresh.unknownInputs ? { unknownInputs: fresh.unknownInputs } : {}), ...later };
   }
 
   const first = await planSet(undefined, input.seededOutputs);
@@ -340,7 +355,7 @@ async function bindReleaseGate(input: {
   for (const [component, refs] of Object.entries(first.unknownInputs ?? {})) {
     console.error(formatInfo(`${component} reads ${refs.join(", ")}, known only once its upstream applies; it is planned again then, and needs its own approval if its plan moves`));
   }
-  return { doc: first.doc, ...bound, reads: first.reads, ...(first.plannedOutputs ? { plannedOutputs: first.plannedOutputs } : {}), ...(first.unknownInputs ? { unknownInputs: first.unknownInputs } : {}), ...later };
+  return { doc: first.doc, ...bound, reads: first.reads, ...groupsOf(first), ...(first.plannedOutputs ? { plannedOutputs: first.plannedOutputs } : {}), ...(first.unknownInputs ? { unknownInputs: first.unknownInputs } : {}), ...later };
 }
 
 /** A later round's or wave's plan was refused (provisional or failed members); the refusal is already printed. */
@@ -518,6 +533,12 @@ async function deployPlanIn(
   }
 
   const registry = await fanOutRegistry(project.projectPath, project.config);
+  // #4516: the reads a capability finds in its steps' files (a template's
+  // Fn::ImportValue) order the promote as `deriveFanOut` orders a fan-out, so
+  // an importer deploys after the exporter it reads. Read once the release's
+  // templates are written, so they are the files read; a read of a component
+  // this promote does not deploy is left out.
+  prepared.splice(0, prepared.length, ...(await withDeclaredReads(prepared, registry, project.projectPath)));
   const port = gitGateLedgerPort();
   // #4045: under a release, every gate binds the release's change set for this environment.
   let releaseGate: ReleaseGateBinding | undefined;
@@ -536,10 +557,51 @@ async function deployPlanIn(
       console.error(formatWarning({ message: `could not read the resume record ${resumePath}: ${err instanceof Error ? err.message : String(err)}` }));
     }
   }
+  // ws-107 (#4465): under a release, the components a capability takes as one
+  // plan and apply as one group; under --wave-gate none forms (ruling 1).
+  // A resume groups again what is left of each group.
+  let grouped: import("../../components/fan-out").FanOutPlan | undefined;
+  const groupRuns: import("../../components/capability").GroupRun[] = [];
+  if (under) {
+    const groups = await import("../../components/groups");
+    const whole = await groups.formRunGroups({
+      components: prepared,
+      plan: groups.componentSetFanOut(prepared),
+      registry,
+      env: plan.to,
+      ...(args.waveGate !== undefined ? { waveGate: true } : {}),
+    });
+    if (resume && whole.groups?.length) {
+      const { remainingFanOut } = await import("../../components/fan-out");
+      grouped = await groups.regroupRemaining({
+        components: prepared,
+        plan: remainingFanOut(whole, prepared, { completed: resume.completed }),
+        registry,
+        env: plan.to,
+        groups: whole.groups,
+        ...(whole.fallbacks ? { fallbacks: whole.fallbacks } : {}),
+      });
+    } else {
+      grouped = whole;
+    }
+  }
   let pullRequests: Array<import("../../lifecycle/merge-record").MergeRecord> = [];
   if (under) {
     try {
-      const result = await bindReleaseGate({ plan, prepared, under, registry, port, seededOutputs, actor: actor!, projectPath: project.projectPath, head, ...(resume ? { resume } : {}) });
+      const result = await bindReleaseGate({
+        plan,
+        prepared,
+        under,
+        registry,
+        port,
+        seededOutputs,
+        actor: actor!,
+        projectPath: project.projectPath,
+        head,
+        ...(resume ? { resume } : {}),
+        ...(grouped ? { grouped } : {}),
+        groupRuns,
+      });
       if (typeof result === "number") {
         tidy();
         return result;
@@ -594,6 +656,7 @@ async function deployPlanIn(
         ...(args.waveGate ? { waveGate: args.waveGate } : {}),
         replan: bound.replan,
         bind: bound.bind,
+        ...(grouped?.groups?.length ? { grouped } : {}),
         run: (components, outputs, binding) =>
           runPromotion({
             plan: { ...plan, items: plan.items.filter((i) => components.some((c) => c.name === i.component)) },
@@ -602,6 +665,7 @@ async function deployPlanIn(
             componentOutputs: outputs,
             gates: port,
             releaseGate: binding,
+            ...(grouped?.groups?.length ? { grouped, groupRuns } : {}),
             ...(args.progressJson ? { onProgress: ndjsonProgressSink() } : {}),
             ...(events ? { onRunEvent: events.emit } : {}),
           }),
@@ -615,6 +679,8 @@ async function deployPlanIn(
         componentOutputs: seededOutputs,
         gates: port,
         ...(releaseGate ? { releaseGate } : {}),
+        // #4465: with no release gate to bind, nothing planned the groups beforehand, so each plans in its wave.
+        ...(grouped?.groups?.length ? { grouped, groupRuns, planGroupsAtWave: bound === undefined } : {}),
         ...(args.progressJson ? { onProgress: ndjsonProgressSink() } : {}),
         ...(events ? { onRunEvent: events.emit } : {}),
       });
@@ -653,6 +719,15 @@ async function deployPlanIn(
       console.error(formatInfo(`resume record: ${resumePath}; the same promote carries on from here`));
     }
   }
+  // #4465: the groups applied as one, and how each member ended, as pr-report says it.
+  const { runGroupsReport, renderRunGroups } = await import("../../components/run-groups");
+  const groupsReport = runGroupsReport({
+    grouped,
+    ...(bound?.groups ? { planned: bound.groups } : {}),
+    ...(bound ? { doc: bound.doc } : {}),
+    ...(run.groupOutcomes ? { outcomes: run.groupOutcomes } : {}),
+  });
+  if (!args.json) for (const line of renderRunGroups(groupsReport, `the same ${verb}`)) console.error(formatInfo(line));
   // The driver settles the stream; this only ends one it left open.
   events?.settle(run.status === "fail" ? "failed" : run.status);
   if (!args.json) renderDriverHuman(run);
@@ -690,7 +765,7 @@ async function deployPlanIn(
     const withChangeSet = under && changeSetJson ? { release: { ...releaseJson.release!, ...changeSetJson } } : releaseJson;
     const stagedJson = staged ? { stages: staged.stages, ...(bound?.plannedOutputs ? { plannedOutputs: bound.plannedOutputs } : {}), ...(bound?.unknownInputs ? { unknownInputs: bound.unknownInputs } : {}) } : {};
     const prJson = pullRequests.length > 0 ? { pullRequests: pullRequests.map((r) => ({ commit: r.commit, source: r.source, plan: r.plan, digest: r.digest, approvedBy: r.approvedBy, ...(r.authorApproved ? { authorApproved: r.authorApproved } : {}) })) } : {};
-    console.log(JSON.stringify({ ...planJson(plan, removed), ...withChangeSet, ...stagedJson, ...prJson, run, recorded, ...(outcome ? { outcome } : {}) }, null, 2));
+    console.log(JSON.stringify({ ...planJson(plan, removed), ...withChangeSet, ...stagedJson, ...prJson, ...groupsReport, run, recorded, ...(outcome ? { outcome } : {}) }, null, 2));
   } else {
     for (const r of recorded) {
       console.error(formatSuccess(

package/src/cli/handlers/query.ts

@@ -1,7 +1,8 @@
 /**
  * `chant query "<sql>" [dir] [--member <name>] [--json]` (#4297): one
- * read-only SQL statement over the snapshots, Op runs, gates, deploys and
- * releases on the local `chant/lifecycle` branch. The tables and the engine
+ * read-only SQL statement over the snapshots in the index store (#4519) and
+ * the Op runs, gates, deploys and releases on the local `chant/lifecycle`
+ * branch. The tables and the engine
  * live in `../../lifecycle/query.ts`; this reads the ledgers and prints.
  *
  * Inside a workspace every member's ledger is read, each row naming its
@@ -34,7 +35,11 @@ export async function queryLedgers(cwd: string, members?: readonly string[], at?
     const commit = resolveLedgerRevision(repo, at);
     return (member: string | null) => revisionLedgerReadPort(repo, commit, member === null ? "" : memberLedgerPrefix([member]));
   })();
-  if (!found) return [{ member: null, port: atPort ? atPort(null) : gitLedgerReadPort({ cwd }) }];
+  // Snapshots come from the index store (#4519). `--at` names a commit of
+  // chant/lifecycle, so it reads that commit's snapshots as before.
+  const { resolveSnapshotStore, snapshotReadPort } = await import("../../lifecycle/snapshot-store");
+  const store = at === undefined ? await resolveSnapshotStore({ cwd: found?.dir ?? cwd }) : undefined;
+  if (!found) return [{ member: null, port: atPort ? atPort(null) : gitLedgerReadPort({ cwd }), ...(store ? { snapshots: snapshotReadPort(store, { cwd }) } : {}) }];
   // Workspace code loads only when there is a workspace, so a level-0 project never pays for it.
   const { readDeclaration, WorkspaceReadError } = await import("../../workspace/declaration");
   const { workingTree } = await import("../../workspace/tree");
@@ -51,9 +56,27 @@ export async function queryLedgers(cwd: string, members?: readonly string[], at?
     const unknown = [...wanted].filter((n) => !declaration.members.some((m) => m.name === n));
     if (unknown.length > 0) throw new QueryError(`--member ${unknown.join(", ")} names no member of the workspace`);
   }
+  // #4482: a TerraformApplyOp run names its root's directory; the member that holds it is `root_member`.
+  const { ownerOf, resolveGroups } = await import("../../workspace/declaration");
+  const groups = (() => {
+    try {
+      return resolveGroups(declaration, workingTree(found.dir));
+    } catch {
+      return [];
+    }
+  })();
+  const ownerOfPath = (path: string): string | null => {
+    const owner = ownerOf(declaration, groups, path);
+    return owner && "member" in owner ? owner.member.name : null;
+  };
   return declaration.members
     .filter((m) => !wanted || wanted.has(m.name))
-    .map((m) => ({ member: m.name, port: atPort ? atPort(m.dir === "." ? null : m.name) : gitLedgerReadPort({ cwd: found.dir, member: m.dir === "." ? "." : m.name }) }));
+    .map((m) => ({
+      member: m.name,
+      port: atPort ? atPort(m.dir === "." ? null : m.name) : gitLedgerReadPort({ cwd: found.dir, member: m.dir === "." ? "." : m.name }),
+      ...(store ? { snapshots: snapshotReadPort(store, { cwd: found.dir, member: m.dir === "." ? "." : m.name }) } : {}),
+      ownerOfPath,
+    }));
 }
 
 export async function runQueryCommand(ctx: CommandContext): Promise<number> {

package/src/cli/handlers/run-declared-reads-cli.test.ts

@@ -0,0 +1,187 @@
+/**
+ * `chant run --components` and `chant components fan-out` order an importer
+ * after its exporter when the read is one a capability declares (chant#4516):
+ * a template's `Fn::ImportValue` of another component's export, which
+ * `declaredReads` (#4466a) finds and core writes into the reader's step as a
+ * `stackOutput()` plus a `dependsOn`. Driven through the CLI handlers, as
+ * run-groups-cli.test.ts drives group formation (chant#4505).
+ *
+ * Discovery, config, the capability registry and the gate ledger are fakes.
+ * app is discovered first and declares no `dependsOn`, so only the declared
+ * read can put network ahead of it. edge reads nothing.
+ */
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import type { Component } from "../../components/component";
+import type { ParsedArgs } from "../registry";
+
+const affectedStacksMock = vi.fn();
+const discoverComponentsMock = vi.fn();
+const buildCapabilityRegistryMock = vi.fn();
+
+vi.mock("../../lifecycle/affected", () => ({
+  affectedStacks: (...args: unknown[]) => affectedStacksMock(...args),
+}));
+
+vi.mock("../../components/discover", () => ({
+  discoverComponents: (...args: unknown[]) => discoverComponentsMock(...args),
+}));
+
+vi.mock("../../config", async () => {
+  const actual = await vi.importActual<typeof import("../../config")>("../../config");
+  return { ...actual, loadChantConfig: async () => ({ config: { lexicons: ["aws"] } }) };
+});
+
+vi.mock("../../components/capability-plugin-loader", () => ({
+  buildCapabilityRegistry: (...args: unknown[]) => buildCapabilityRegistryMock(...args),
+}));
+
+/** The real gate ledger is this repository's `chant/lifecycle` branch; a test never appends to it. */
+vi.mock("../../op/gate", async () => {
+  const actual = await vi.importActual<typeof import("../../op/gate")>("../../op/gate");
+  return { ...actual, gitGateLedgerPort: () => actual.memoryGateLedgerPort(), gateIsSealed: async () => false };
+});
+
+/** The release ledger, for the same reason. */
+vi.mock("../../components/auto-release", async () => {
+  const actual = await vi.importActual<typeof import("../../components/auto-release")>("../../components/auto-release");
+  return { ...actual, maybeRecordAutoRelease: async () => ({ recorded: false, reason: "opted-out" }) };
+});
+
+/** `run --components` on the local runtime: the real `runComponents`, with the test's registry. */
+vi.mock("../../op/runtimes/local", async () => {
+  const { runComponents } = await import("../../components/cli-support");
+  const { memoryGateLedgerPort } = await import("../../op/gate");
+  return {
+    createLocalOpRuntime: () => ({
+      name: "local",
+      runComponents: async (path: string, selector: string, options: object) =>
+        runComponents(path, selector, { ...options, registry: await buildCapabilityRegistryMock(), config: {}, revision: null, gates: memoryGateLedgerPort() }),
+    }),
+  };
+});
+
+const { CapabilityRegistry } = await import("../../components/capability");
+const { computePlanDigest } = await import("../../lifecycle/plan-digest");
+const { runComponentsFanOut } = await import("./fan-out");
+const { runOpComponents } = await import("./run");
+
+interface StackInput {
+  stack: string;
+  imports?: Record<string, unknown>;
+}
+
+const stack = (name: string): Component => ({
+  name,
+  dependsOn: [],
+  deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", stack: name, template: `${name}.template.json` }] }],
+});
+const COMPONENTS = [stack("app"), stack("network"), stack("edge")];
+/** app's template imports `Net-VpcId`, which network's template exports from its `VpcId` output. */
+const READ = { reader: "app", index: 0, upstream: "network", output: "VpcId", at: "/imports/Net-VpcId" };
+
+let declares = true;
+let applied: Array<{ stack: string; imports?: Record<string, unknown> }> = [];
+let stderrLines: string[] = [];
+
+function registry() {
+  const r = new CapabilityRegistry();
+  r.register({
+    kind: "cfn-deploy",
+    async plan(_ctx: unknown, input: StackInput) {
+      const planDigest = computePlanDigest("cfn-deploy", { stack: input.stack, imports: input.imports ?? null });
+      return {
+        member: input.stack,
+        planDigest,
+        artifact: { planDigest },
+        outputs: { known: {}, unknown: ["VpcId"] },
+        changeSet: {
+          member: { member: input.stack, lexicon: "aws", planner: "tofu" as const, status: "planned" as const, planDigest, holes: [] },
+          entries: [{ member: input.stack, lexicon: "aws", planner: "tofu" as const, address: "res.x", type: "res", action: "create" as const, attributes: [] }],
+        },
+      };
+    },
+    async run(_ctx: unknown, input: StackInput) {
+      applied.push({ stack: input.stack, ...(input.imports ? { imports: input.imports } : {}) });
+      return { outputs: { VpcId: `${input.stack}-vpc` } };
+    },
+    ...(declares
+      ? {
+          declaredReads(_ctx: unknown, members: ReadonlyArray<{ component: string }>) {
+            return members.some((m) => m.component === READ.reader) ? [READ] : [];
+          },
+        }
+      : {}),
+  } as never);
+  return r;
+}
+
+const baseArgs = { format: "", fix: false, watch: false, verbose: false, help: false, live: false };
+const fanOutCtx = (overrides: Partial<ParsedArgs> = {}) => ({ args: { command: "components", path: "fan-out", ...baseArgs, ...overrides } as ParsedArgs, plugins: [], serializers: [] }) as never;
+const runCtx = (selector: string) => ({ args: { command: "run", path: selector, components: true, on: "local", ...baseArgs } as ParsedArgs, plugins: [] }) as never;
+const stderr = () => stderrLines.join("\n");
+const order = () => applied.map((a) => a.stack);
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  declares = true;
+  applied = [];
+  stderrLines = [];
+  discoverComponentsMock.mockResolvedValue({
+    components: new Map(COMPONENTS.map((c) => [c.name, { component: c, exportName: c.name, filePath: `${c.name}.component.ts` }])),
+    sourceFiles: [],
+    errors: [],
+  });
+  buildCapabilityRegistryMock.mockImplementation(async () => registry());
+  affectedStacksMock.mockResolvedValue({ changed: ["network"], dependents: [], indeterminate: [] });
+  vi.spyOn(console, "error").mockImplementation((...args: unknown[]) => {
+    stderrLines.push(args.map(String).join(" "));
+  });
+  vi.spyOn(console, "log").mockImplementation(() => {});
+  vi.spyOn(process.stderr, "write").mockImplementation((chunk: unknown) => {
+    stderrLines.push(String(chunk));
+    return true;
+  });
+  vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("chant run --components orders an importer after its exporter (chant#4516)", () => {
+  test("all: network applies before app, and app's step gets network's output under imports", async () => {
+    expect(await runOpComponents(runCtx("all"))).toBe(0);
+    expect(order().indexOf("network")).toBeLessThan(order().indexOf("app"));
+    expect(applied.find((a) => a.stack === "app")).toEqual({ stack: "app", imports: { "Net-VpcId": "network-vpc" } });
+    expect(order().sort()).toEqual(["app", "edge", "network"]);
+  });
+
+  test("a list naming the importer pulls in its exporter, says so, and runs it first", async () => {
+    expect(await runOpComponents(runCtx("app,edge"))).toBe(0);
+    expect(stderr()).toContain("added as dependencies: network");
+    expect(stderr()).toMatch(/run order: .*network.*, then app/);
+    expect(order().indexOf("network")).toBeLessThan(order().indexOf("app"));
+    expect(applied.find((a) => a.stack === "app")?.imports).toEqual({ "Net-VpcId": "network-vpc" });
+  });
+
+  test("a single name runs that component alone; a read of a component outside the run is left out", async () => {
+    expect(await runOpComponents(runCtx("app"))).toBe(0);
+    expect(applied).toEqual([{ stack: "app" }]);
+  });
+
+  test("without declaredReads a list adds nothing and app gets no imports, as before", async () => {
+    declares = false;
+    expect(await runOpComponents(runCtx("app,edge"))).toBe(0);
+    expect(stderr()).not.toContain("added as dependencies");
+    expect(order().sort()).toEqual(["app", "edge"]);
+    expect(applied.find((a) => a.stack === "app")?.imports).toBeUndefined();
+  });
+});
+
+describe("chant components fan-out orders an importer after its exporter (chant#4516)", () => {
+  test("a changed network pulls in app, which applies after it with network's output", async () => {
+    expect(await runComponentsFanOut(fanOutCtx({ base: "main" }))).toBe(0);
+    expect(order()).toEqual(["network", "app"]);
+    expect(applied[1]).toEqual({ stack: "app", imports: { "Net-VpcId": "network-vpc" } });
+  });
+});