@intentius/chant 0.124.52 → 0.124.54

package/src/components/run-groups.ts

@@ -0,0 +1,113 @@
+/**
+ * What a promote under a release, `components fan-out` and `run --components`
+ * say about the groups they applied as one (ws-107, #4465), as `pr-report`
+ * says it for a pull request since #4446: each group with its members, the
+ * wave it ran in, its digest and the reads its apply computes, how each
+ * member ended, and why each component that could have grouped did not.
+ */
+
+import type { ChangeSetDocument } from "../change-set";
+import type { GroupMemberStatus } from "./capability";
+import type { FanOutGroup, FanOutGroupFallback, FanOutPlan } from "./fan-out";
+
+/** One group a run applied as one. */
+export interface RunGroupReport {
+  /** The kind of the capability every member's one step names. */
+  capability: string;
+  /** The members, in apply order: upstreams first. */
+  components: string[];
+  /** The 1-based wave of the grouped fan-out it ran in. */
+  wave: number;
+  /** The group digest folded into each member's `planDigest`; `null` when it failed to plan. Absent when the run planned it in its wave. */
+  digest?: string | null;
+  /** Why the group failed to plan. */
+  error?: string;
+  /** Each read of another member its plan did not know, by change-set member, which the group's apply computes. Absent when none. */
+  reads?: Array<{ member: string; ref: string }>;
+  /** How each member's part ended, as the capability said. Absent when the group did not run. */
+  outcomes?: Record<string, GroupMemberStatus>;
+}
+
+export interface RunGroupsReport {
+  groups?: RunGroupReport[];
+  fallbacks?: FanOutGroupFallback[];
+}
+
+/**
+ * The report of `grouped`'s groups. `planned` are the groups a release gate's
+ * plan planned (`ReleasePlan.groups`), with their digests; `doc` is the
+ * change set they are in, which names each member's reads; `outcomes` is the
+ * run's `groupOutcomes`.
+ */
+export function runGroupsReport(input: {
+  grouped: FanOutPlan | undefined;
+  planned?: ReadonlyArray<FanOutGroup & { digest: string | null; error?: string }>;
+  doc?: ChangeSetDocument;
+  outcomes?: Record<string, GroupMemberStatus>;
+}): RunGroupsReport {
+  const waves = input.grouped?.waves ?? [];
+  const waveOf = new Map(waves.flatMap((w, i) => w.map((name) => [name, i + 1] as const)));
+  const groups: Array<FanOutGroup & { digest?: string | null; error?: string }> = input.planned?.length ? [...input.planned] : [...(input.grouped?.groups ?? [])];
+  const out: RunGroupReport[] = groups.map((g) => {
+    const reads = g.digest
+      ? (input.doc?.members ?? []).filter((m) => m.group?.digest === g.digest).flatMap((m) => m.group!.reads.map((ref) => ({ member: m.member, ref })))
+      : [];
+    const outcomes = Object.fromEntries(g.components.filter((c) => input.outcomes?.[c] !== undefined).map((c) => [c, input.outcomes![c]!]));
+    return {
+      capability: g.capability,
+      components: [...g.components],
+      wave: waveOf.get(g.components[0]!) ?? 0,
+      ...(g.digest !== undefined ? { digest: g.digest } : {}),
+      ...(g.error !== undefined ? { error: g.error } : {}),
+      ...(reads.length > 0 ? { reads } : {}),
+      ...(Object.keys(outcomes).length > 0 ? { outcomes } : {}),
+    };
+  });
+  const fallbacks = input.grouped?.fallbacks ?? [];
+  return { ...(out.length > 0 ? { groups: out } : {}), ...(fallbacks.length > 0 ? { fallbacks: [...fallbacks] } : {}) };
+}
+
+/** `a`, `b` and `c`. */
+const listed = (items: string[]): string => (items.length > 1 ? `${items.slice(0, -1).join(", ")} and ${items.at(-1)}` : (items[0] ?? ""));
+
+const OUTCOME_WORDS: Record<GroupMemberStatus, string> = {
+  applied: "applied",
+  "no-changes": "had no changes",
+  partial: "applied in part, and what applied stays",
+  failed: "failed",
+  "not-started": "did not start",
+};
+
+/**
+ * The report as lines for a person: one per group naming its members, wave,
+ * digest and the reads its apply computes, then how each member ended, and,
+ * when the apply stopped part way, what `again` (the command to run again)
+ * plans next. Then why the components that could have grouped did not; a
+ * fallback of kind `off` is not printed.
+ */
+export function renderRunGroups(report: RunGroupsReport, again: string): string[] {
+  const out: string[] = [];
+  for (const g of report.groups ?? []) {
+    const reads = (g.reads ?? []).map((r) => `${r.member} reads ${r.ref}`);
+    out.push(
+      `${listed(g.components)} plan and apply as one (${g.capability}, wave ${g.wave}${g.digest ? `, group ${g.digest}` : ""})` +
+        (g.error ? `; the group failed to plan, so nothing of it applied: ${g.error}` : reads.length > 0 ? `; ${listed(reads)}, known when the group applies` : ""),
+    );
+    const outcomes = g.outcomes ?? {};
+    const ran = g.components.filter((c) => outcomes[c] !== undefined);
+    if (ran.length === 0) continue;
+    out.push(`  ${ran.map((c) => `${c} ${OUTCOME_WORDS[outcomes[c]!]}`).join("; ")}`);
+    const left = ran.filter((c) => outcomes[c] !== "applied" && outcomes[c] !== "no-changes");
+    if (left.length > 0) {
+      out.push(`  the group's apply stopped part way and nothing that applied is undone; ${again} plans ${listed(left)} again, as one group where they still join`);
+    }
+  }
+  const byWhy = new Map<string, string[]>();
+  for (const f of report.fallbacks ?? []) {
+    if (f.kind === "off") continue;
+    const why = `(${f.kind}): ${f.reason}`;
+    byWhy.set(why, [...(byWhy.get(why) ?? []), f.component]);
+  }
+  for (const [why, names] of byWhy) out.push(`planned one by one, not as a group: ${names.join(", ")} ${why}`);
+  return out;
+}

package/src/components/starter-plugin.ts

@@ -47,6 +47,7 @@ import {
   wranglerDeployCapability,
   wranglerVersionsPromoteCapability,
   r2SyncCapability,
+  memberOutputsStarterCapability,
 } from "./verbs/index";
 import { ownPackageVersion, type CapabilityPlugin } from "./capability-plugin";
 
@@ -82,6 +83,10 @@ export const STARTER_VERB_FAMILIES = {
   // there is no cloudflare lexicon for these three verbs to live in. Revisit
   // if/when the zone-plane lexicon (#1294) lands.
   cloudflare: ["wrangler-deploy", "wrangler-versions-promote", "r2-sync"],
+  // Another workspace member's outputs, read through the engine it runs on
+  // (#4455). One agnostic verb; each engine's lexicon contributes a source
+  // (`CapabilityPlugin.engineOutputSources`).
+  engineOutputs: ["member-outputs"],
 } as const;
 
 /**
@@ -112,6 +117,7 @@ function starterCapabilities(): Array<Capability<never, unknown>> {
     wranglerDeployCapability,
     wranglerVersionsPromoteCapability,
     r2SyncCapability,
+    memberOutputsStarterCapability,
   ] as unknown as Array<Capability<never, unknown>>;
 }
 

package/src/components/verbs/index.ts

@@ -53,6 +53,7 @@ export * from "./verify";
 export * from "./run-agent";
 export * from "./wrangler";
 export * from "./r2-sync";
+export * from "./member-outputs";
 export * from "./vuln-scan";
 export * from "./vex";
 export * from "./license-policy";

package/src/components/verbs/member-outputs.test.ts

@@ -0,0 +1,205 @@
+/**
+ * `member-outputs` (#4455): a chant member's parameter planned against
+ * another workspace member's output, read through that member's engine.
+ *
+ * The estate is the three-cloud demo's: `dns` reads `azureEndpoint`, which
+ * the `azure` member publishes. `azure` is a choudoufu member, read through
+ * a fake engine source standing in for the terraform lexicon's
+ * `choudoufuOutputSource`; `records` is dns's deploy, a fake step that
+ * plans its parameters the way `cfn-deploy` does (a hole when an input is
+ * not known yet).
+ */
+
+import { describe, expect, test } from "vitest";
+import { CapabilityRegistry, type DeployContext } from "../capability";
+import { registerCapabilityPlugins } from "../capability-plugin-loader";
+import type { CapabilityPlugin } from "../capability-plugin";
+import { starterCapabilityPlugin } from "../starter-plugin";
+import { planFanOut } from "../fan-out";
+import { applyPrSet, approvalOf, decidePrGate, planPrSet, readOnlyLedger, type PrPlanSet } from "../pr-run";
+import { memoryGateLedgerPort } from "../../op/gate";
+import { computePlanDigest } from "../../lifecycle/plan-digest";
+import { deployUnits } from "../deploy-units";
+import type { DriverComponent } from "../driver";
+import {
+  EngineOutputSourceMissingError,
+  MEMBER_OUTPUTS_KIND,
+  memberOutputsCapability,
+  memberOutputsComponent,
+  memberOutputsMemberName,
+  MemberOutputsPendingError,
+  type EngineMemberRef,
+  type EngineOutputSource,
+  type EnginePlannedOutputs,
+} from "./member-outputs";
+
+interface RecordsInput {
+  inputs: Record<string, unknown>;
+}
+
+/** dns's two components: the azure member's outputs, and the records reading `azureEndpoint`. */
+const ESTATE: DriverComponent[] = [
+  memberOutputsComponent("azure") as unknown as DriverComponent,
+  {
+    name: "records",
+    dependsOn: ["azure"],
+    deploy: [{ phase: "Apply", steps: [{ kind: "fake-records", inputs: { azureEndpoint: { stackOutput: { stack: "azure", name: "azureEndpoint" } } } }] }],
+  },
+];
+
+const WORKSPACE = "/ws";
+const lookup = async (_cwd: string, member: string): Promise<EngineMemberRef> => {
+  if (member !== "azure") throw new Error(`no member ${member}`);
+  return { member, kind: "choudoufu", dir: `${WORKSPACE}/azure`, workspaceRoot: WORKSPACE };
+};
+
+function world() {
+  const w = {
+    /** What the azure estate's outputs are now. */
+    applied: { azureEndpoint: "web.old.azurecontainerapps.io" } as Record<string, unknown>,
+    /** What azure's plan says. */
+    plan: { known: { azureEndpoint: "web.old.azurecontainerapps.io" }, unknown: [] as string[], planDigest: "sha256:azure-plan", changes: false } as EnginePlannedOutputs,
+    /** What each plan of records saw. */
+    recordsPlanned: [] as Array<{ inputs: Record<string, unknown>; unresolved?: string[] }>,
+    recordsRan: [] as Array<Record<string, unknown>>,
+    refs: [] as EngineMemberRef[],
+  };
+  const source: EngineOutputSource = {
+    kinds: ["choudoufu"],
+    async applied(_ctx, ref) {
+      w.refs.push(ref);
+      return { ...w.applied };
+    },
+    async planned(_ctx, ref) {
+      w.refs.push(ref);
+      return { ...w.plan, known: { ...w.plan.known }, unknown: [...w.plan.unknown] };
+    },
+  };
+  const plugin: CapabilityPlugin = {
+    name: "fake-dns",
+    version: "0.0.0",
+    capabilities: () =>
+      [
+        {
+          kind: "fake-records",
+          async plan(ctx: DeployContext, input: RecordsInput) {
+            w.recordsPlanned.push({ inputs: { ...input.inputs }, ...(ctx.unresolvedInputs ? { unresolved: [...ctx.unresolvedInputs] } : {}) });
+            const planDigest = computePlanDigest("fake-records", { inputs: input.inputs, unresolved: ctx.unresolvedInputs ?? [] });
+            const holes = ctx.unresolvedInputs?.length ? [{ address: "records", reason: `inputs from ${ctx.unresolvedInputs.join(", ")}; re-checked on apply` }] : [];
+            return {
+              member: "records",
+              planDigest,
+              artifact: { planDigest },
+              changeSet: { member: { member: "records", lexicon: "aws", planner: "chant", status: "planned", planDigest, holes }, entries: [] },
+            };
+          },
+          async run(_ctx: DeployContext, input: RecordsInput) {
+            w.recordsRan.push({ ...input.inputs });
+            return {};
+          },
+        },
+      ] as never,
+    engineOutputSources: () => [source],
+  };
+  // The registry the CLI builds: the starter set, whose member-outputs gets the plugins' sources bound.
+  const starter = { ...starterCapabilityPlugin, capabilities: () => starterCapabilityPlugin.capabilities().filter((c) => c.kind !== MEMBER_OUTPUTS_KIND).concat([memberOutputsCapability({ lookup }) as never]) };
+  const registry = registerCapabilityPlugins(new CapabilityRegistry(), [starter as CapabilityPlugin, plugin]);
+  return { registry, state: w };
+}
+
+const NOW = "2026-10-25T00:00:00Z";
+
+describe("member-outputs", () => {
+  test("is in the starter set, and a registry built without a source for the member's kind refuses by name", async () => {
+    expect(starterCapabilityPlugin.capabilities().map((c) => c.kind)).toContain(MEMBER_OUTPUTS_KIND);
+    const bare = memberOutputsCapability({ lookup });
+    await expect(bare.outputs!({ env: "prod", component: "azure" }, { member: "azure" })).rejects.toBeInstanceOf(EngineOutputSourceMissingError);
+    await expect(bare.outputs!({ env: "prod", component: "azure" }, { member: "azure" })).rejects.toThrow(/member "azure" is kind choudoufu.*Add "terraform"/);
+  });
+
+  test("the component is a deploy unit named after the member", () => {
+    expect(deployUnits(memberOutputsComponent("azure").deploy)).toEqual([{ unit: "azure", lexicon: "workspace" }]);
+  });
+
+  test("an applied output feeds dns's parameter when the change does not touch the member", async () => {
+    const w = world();
+    const plan = planFanOut({ components: ESTATE, changed: ["records"] });
+    const set = await planPrSet({ components: ESTATE, plan, registry: w.registry, env: "prod" });
+    expect(set.failed).toBe(false);
+    expect(w.state.recordsPlanned).toEqual([{ inputs: { azureEndpoint: "web.old.azurecontainerapps.io" } }]);
+    expect(set.deployedOutputs).toEqual({ azure: ["azureEndpoint"] });
+    expect(w.state.refs[0]).toEqual({ member: "azure", kind: "choudoufu", dir: "/ws/azure", workspaceRoot: "/ws" });
+    const records = set.members.find((m) => m.member === "records")!;
+    expect(records.unknownInputs).toBeUndefined();
+    expect(records.reads).toEqual([{ upstream: "azure", outputs: ["azureEndpoint"] }]);
+  });
+
+  test("a planned output the member's plan knows feeds dns's parameter when the change touches the member", async () => {
+    const w = world();
+    w.state.plan = { known: { azureEndpoint: "web.new.azurecontainerapps.io" }, unknown: [], planDigest: "sha256:azure-v2", changes: true };
+    const plan = planFanOut({ components: ESTATE, changed: ["azure"] });
+    const set = await planPrSet({ components: ESTATE, plan, registry: w.registry, env: "prod" });
+    expect(w.state.recordsPlanned).toEqual([{ inputs: { azureEndpoint: "web.new.azurecontainerapps.io" } }]);
+    expect(set.plannedOutputs).toEqual({ azure: ["azureEndpoint"] });
+    const azure = set.doc.members.find((m) => m.member === memberOutputsMemberName("azure"))!;
+    expect(azure.holes).toEqual([]);
+    // The approval binds the member's plan: another plan of azure moves the set's digest.
+    const moved = world();
+    moved.state.plan = { ...w.state.plan, planDigest: "sha256:azure-v3" };
+    const again = await planPrSet({ components: ESTATE, plan, registry: moved.registry, env: "prod" });
+    expect(again.doc.digest).not.toBe(set.doc.digest);
+  });
+
+  test("an unknown upstream output holds dns back, naming the member and the output", async () => {
+    const w = world();
+    w.state.plan = { known: {}, unknown: ["azureEndpoint"], planDigest: "sha256:azure-new-app", changes: true };
+    const plan = planFanOut({ components: ESTATE, changed: ["azure"] });
+    const set = await planPrSet({ components: ESTATE, plan, registry: w.registry, env: "prod" });
+    expect(set.failed).toBe(false);
+
+    // records was planned without the value, told whose output it waits on.
+    expect(w.state.recordsPlanned).toEqual([{ inputs: {}, unresolved: ["azure"] }]);
+    const records = set.members.find((m) => m.member === "records")!;
+    expect(records.unknownInputs).toEqual(["azure.azureEndpoint"]);
+    expect(records.reads).toEqual([{ upstream: "azure", outputs: ["azureEndpoint"], unknown: ["azureEndpoint"] }]);
+    expect(set.doc.members.find((m) => m.member === "records")!.holes).toEqual([{ address: "records", reason: "inputs from azure; re-checked on apply" }]);
+    // The member's own part names the output.
+    expect(set.doc.members.find((m) => m.member === memberOutputsMemberName("azure"))!.holes).toEqual([
+      { address: "azure.azureEndpoint", type: "output", reason: "azure.azureEndpoint is known only after azure applies; what reads it is planned again then" },
+    ]);
+
+    // On merge, before azure's own pipeline applied: the read refuses, so records is blocked behind it and nothing reads a stale value.
+    const early = await applyPrSet({ components: ESTATE, plan, registry: w.registry, env: "prod", set });
+    expect(early.members.find((m) => m.member === "records")).toMatchObject({ status: "blocked", blockedBy: "azure" });
+    expect(w.state.recordsRan).toEqual([]);
+
+    // Once azure applied: records is held back with the reason, and planned again against the value azure applied as.
+    w.state.applied = { azureEndpoint: "web.new.azurecontainerapps.io" };
+    w.state.plan = { known: { azureEndpoint: "web.new.azurecontainerapps.io" }, unknown: [], planDigest: "sha256:azure-applied", changes: false };
+    const decideNothing = async ({ gate, set: round }: { gate: string; set: PrPlanSet }) => {
+      const check = await decidePrGate(readOnlyLedger(memoryGateLedgerPort()), { op: "pr-12", gate, digest: round.doc.digest, now: NOW });
+      return { satisfied: check.satisfied, approval: approvalOf(check) };
+    };
+    const held = await applyPrSet({ components: ESTATE, plan, registry: w.registry, env: "prod", set, decideRound: decideNothing });
+    expect(held.status).toBe("waiting");
+    expect(held.members.find((m) => m.member === "records")).toMatchObject({
+      status: "waiting",
+      round: 2,
+      held: "its plan read azure.azureEndpoint before that output applied as another value",
+    });
+    expect(w.state.recordsPlanned.at(-1)).toEqual({ inputs: { azureEndpoint: "web.new.azurecontainerapps.io" } });
+    expect(w.state.recordsRan).toEqual([]);
+  });
+
+  test("run reads and never applies: a member with changes left refuses, one without answers its applied outputs", async () => {
+    const w = world();
+    const capability = w.registry.resolve(MEMBER_OUTPUTS_KIND);
+    w.state.plan = { ...w.state.plan, changes: true };
+    await expect(capability.run({ env: "prod", component: "azure" }, { member: "azure" } as never)).rejects.toBeInstanceOf(MemberOutputsPendingError);
+    w.state.plan = { ...w.state.plan, changes: false };
+    await expect(capability.run({ env: "prod", component: "azure" }, { member: "azure" } as never)).resolves.toEqual({
+      member: "azure",
+      outputs: { azureEndpoint: "web.old.azurecontainerapps.io" },
+    });
+  });
+});

package/src/components/verbs/member-outputs.ts

@@ -0,0 +1,308 @@
+/**
+ * `member-outputs`: another workspace member's outputs, read through the
+ * engine that member runs on, so a chant member's parameters can be planned
+ * against them (#4455, design record choudoufu#2258 lane T6).
+ *
+ * In `behold/example-three-cloud`, `dns` (a chant member) reads each cloud's
+ * endpoint as a parameter of the same name as the output the cloud's member
+ * publishes. When the Azure site is a choudoufu estate, `azureEndpoint` is a
+ * Terraform root output, and when the AWS site is a Pulumi stack it is a
+ * stack output. Neither is a chant component, so there is nothing for a
+ * `stackOutput()` reference to read. This verb is that something: a
+ * component in the consumer's project whose one step names the upstream
+ * member, and whose capability answers the two questions the components
+ * machinery already asks of an upstream:
+ *
+ * - `outputs` (applied): what the member exposes now. A pull request that
+ *   does not touch the member plans the consumer against these
+ *   (`deployedOutputs`, #4104).
+ * - `plan` (planned): what the member will expose once its own plan applies,
+ *   with the outputs known only after apply named (`PlannedOutputs`, #3999).
+ *   A pull request that touches the member plans the consumer against the
+ *   known ones. A reference to an unknown one is unresolved, so the
+ *   consumer's step is planned with `DeployContext.unresolvedInputs` naming
+ *   the member, the pull request's report lists `<member>.<output>` under the
+ *   consumer's `unknownInputs`, and the apply holds the consumer back until
+ *   the member applied, then plans it again (`pr-run.ts`, "Planning again
+ *   once an upstream applied"). That is the hold chant already puts on a
+ *   root waiting on another root's unknown output; nothing here adds a
+ *   second one.
+ *
+ * The consumer writes it as two components:
+ *
+ * ```ts
+ * export const azure = memberOutputsComponent("azure");
+ * export const records: Component = {
+ *   name: "records",
+ *   dependsOn: ["azure"],
+ *   deploy: [phase("Apply", [{ kind: "cfn-deploy", template: "dist/dns.json",
+ *     inputs: { azureEndpoint: stackOutput("azure", "azureEndpoint") } }])],
+ * };
+ * ```
+ *
+ * ## Engines: the seam
+ *
+ * The member is looked up in the workspace declaration (`chant.workspace.json`)
+ * by name, and its `kind` picks the {@link EngineOutputSource} that reads it.
+ * Sources are not capabilities: each lexicon that drives an engine
+ * contributes one through `CapabilityPlugin.engineOutputSources()`, the way
+ * the cloud lexicons contribute registry logins to `publish-image`, and the
+ * registry binds them into this one verb when it is built
+ * (`registerCapabilityPlugins`). So two engines never register the same
+ * kind, and a consumer's step does not change when the member moves between
+ * engines.
+ *
+ * - `choudoufu` (the terraform lexicon, `choudoufuOutputSource`): applied
+ *   values from `choudoufu output -json` in the member's directory, which in
+ *   live mode reads the estate's record store; planned values from
+ *   `live-plan-set -json` over the member's root, its plan's
+ *   `planned_values.outputs` with every output whose `output_changes` entry
+ *   marks any part `after_unknown` named unknown (`terraformPlannedOutputs`).
+ * - `pulumi` (the pulumi lexicon, `pulumiOutputSource`): applied values
+ *   from `pulumi stack output --json --show-secrets=false`, or from the
+ *   member's checked-in `stack-export.json` when chant must not run pulumi
+ *   (`CHANT_PULUMI_APPLIED_OUTPUTS=export`); planned values from `pulumi
+ *   preview --json`, the stack step's outputs, where an output holding
+ *   Pulumi's unknown sentinel is unknown. Secret outputs are left out of
+ *   both. A member on plunge runs the same commands under `plunge`.
+ *   Nothing in this module or in the consumer changes for it.
+ *
+ * ## Run reads, it never applies
+ *
+ * The member applies through its own pipeline. `run` checks that the
+ * member's plan has nothing left to apply (`changes` false) and answers its
+ * applied outputs; a member with changes still to apply refuses the run
+ * with {@link MemberOutputsPendingError}, so the consumer is blocked behind
+ * it and never applies against values from before the member's change. A
+ * workspace orders the member's own run before the consumer's (members that
+ * link to a producer run after it, `chant workspace run`).
+ *
+ * ## Which changes reach the member
+ *
+ * The component is a deploy unit named after the member (`DEPLOY_UNIT_RULES`),
+ * so a change signal that names the member as a changed unit puts it in the
+ * change. The terraform lexicon names it when the consumer's
+ * `terraform.roots` has an entry of that name whose files changed;
+ * `--from-affected` can name it too.
+ */
+
+import type { Capability, CapabilityPlan, DeployContext, PlannedOutputs } from "../capability";
+import type { ChangeSetHole, ChangeSetPart } from "../../change-set";
+import { computePlanDigest } from "../../lifecycle/plan-digest";
+import type { Component } from "../component";
+
+/** The step kind. */
+export const MEMBER_OUTPUTS_KIND = "member-outputs";
+
+/** The `member-outputs` step's input. */
+export interface MemberOutputsInput {
+  /** The upstream member's name in the workspace declaration. Also the component's name, by convention. */
+  member: string;
+  /**
+   * Where the declaration search starts. Default: the current directory,
+   * which is the consumer's project root under `chant run`.
+   */
+  cwd?: string;
+}
+
+/** What `run` returns: the member's applied outputs, under `outputs`, where the driver collects a stack's outputs from. */
+export interface MemberOutputsOutput {
+  member: string;
+  outputs: Record<string, unknown>;
+}
+
+/** The upstream member a source reads, as the workspace declares it. */
+export interface EngineMemberRef {
+  /** The member's name. */
+  member: string;
+  /** Its declared kind, which picked the source: `choudoufu`, `pulumi`. */
+  kind: string;
+  /** Its directory, absolute. */
+  dir: string;
+  /** The workspace root, absolute. A source that must run from above the member's directory runs from here. */
+  workspaceRoot: string;
+}
+
+/** What a source's plan of the member says about its outputs. */
+export interface EnginePlannedOutputs extends PlannedOutputs {
+  /**
+   * A digest of the member's plan, the engine's own or chant's over it. The
+   * consumer's approval binds it, so a plan of the member that moves after
+   * review moves the consumer's digest too.
+   */
+  planDigest: string;
+  /** Whether the member's plan has anything to apply. `run` refuses while it does. */
+  changes: boolean;
+}
+
+/**
+ * Reads one engine's member outputs (#4455). One per engine, contributed by
+ * the lexicon that drives it through `CapabilityPlugin.engineOutputSources()`.
+ */
+export interface EngineOutputSource {
+  /** The member kinds this source reads, as declared in `chant.workspace.json`. */
+  readonly kinds: readonly string[];
+  /** The member's outputs as applied now, by name. */
+  applied(ctx: DeployContext, ref: EngineMemberRef): Promise<Record<string, unknown>>;
+  /** The member's outputs once its current plan applies, the ones known only after apply named. */
+  planned(ctx: DeployContext, ref: EngineMemberRef): Promise<EnginePlannedOutputs>;
+}
+
+/** Finds a member in the workspace above `cwd`: its kind and directory. */
+export type MemberLookup = (cwd: string, member: string) => Promise<EngineMemberRef>;
+
+/** No source for the member's kind is loaded. */
+export class EngineOutputSourceMissingError extends Error {
+  constructor(
+    readonly member: string,
+    readonly kind: string,
+    readonly available: readonly string[],
+  ) {
+    super(
+      `${MEMBER_OUTPUTS_KIND}: member "${member}" is kind ${kind}, and no loaded lexicon reads that engine's outputs` +
+        (available.length > 0 ? ` (loaded: ${available.join(", ")})` : "") +
+        `. ${kind === "choudoufu" ? 'Add "terraform" to the project\'s lexicons.' : kind === "pulumi" ? 'Add "pulumi" to the project\'s lexicons.' : "Load the lexicon that drives it."}`,
+    );
+    this.name = "EngineOutputSourceMissingError";
+  }
+}
+
+/** The member's plan has changes its own pipeline has not applied. Nothing was read. */
+export class MemberOutputsPendingError extends Error {
+  constructor(readonly member: string) {
+    super(
+      `${MEMBER_OUTPUTS_KIND}: member "${member}" has changes its own pipeline has not applied yet, ` +
+        `so its outputs are still the ones from before them. Apply ${member} first; whatever reads its outputs runs after it.`,
+    );
+    this.name = "MemberOutputsPendingError";
+  }
+}
+
+/** The member a {@link MemberOutputsInput} reads plans as, in the consumer's change set. */
+export const memberOutputsMemberName = (member: string): string => `${member}#outputs`;
+
+/**
+ * The member's name in the declaration above `cwd`, with its kind and
+ * directory. Reads the working tree. Imported lazily: the verb set is
+ * loaded where the workspace reader's dependencies may not be.
+ */
+export const workspaceMemberLookup: MemberLookup = async (cwd, member) => {
+  const { locateWorkspace } = await import("../../workspace/which-chant");
+  const { readDeclaration } = await import("../../workspace/declaration");
+  const { join } = await import("node:path");
+  const located = locateWorkspace(cwd);
+  const declaration = readDeclaration(located.tree);
+  const found = declaration.members.find((m) => m.name === member);
+  if (!found) {
+    const names = declaration.members.map((m) => m.name).sort();
+    throw new Error(`${MEMBER_OUTPUTS_KIND}: the workspace at ${located.rootOnDisk} declares no member "${member}" (members: ${names.join(", ")})`);
+  }
+  return {
+    member: found.name,
+    kind: found.kind,
+    dir: found.dir === "." ? located.rootOnDisk : join(located.rootOnDisk, ...found.dir.split("/")),
+    workspaceRoot: located.rootOnDisk,
+  };
+};
+
+function requireMember(input: MemberOutputsInput): void {
+  if (typeof input?.member !== "string" || input.member === "") {
+    throw new Error(`${MEMBER_OUTPUTS_KIND}: "member" is required and names a member of the workspace`);
+  }
+}
+
+/** Implemented by a capability that wants the plugins' engine output sources injected when a registry is built. */
+export interface EngineOutputSourceConsumer {
+  withEngineOutputSources(sources: readonly EngineOutputSource[]): Capability<never, unknown>;
+}
+
+export function isEngineOutputSourceConsumer(value: unknown): value is EngineOutputSourceConsumer {
+  return typeof value === "object" && value !== null && typeof (value as EngineOutputSourceConsumer).withEngineOutputSources === "function";
+}
+
+/**
+ * The member's part of the consumer's change set: no entries, since the
+ * member's own pipeline plans and applies its changes, and a hole per output
+ * known only after apply, naming the member and the output.
+ */
+function outputsPart(member: string, planDigest: string, unknown: readonly string[]): ChangeSetPart {
+  const holes: ChangeSetHole[] = unknown.map((name) => ({
+    address: `${member}.${name}`,
+    type: "output",
+    reason: `${member}.${name} is known only after ${member} applies; what reads it is planned again then`,
+  }));
+  return {
+    member: { member: memberOutputsMemberName(member), lexicon: "chant", planner: "chant", status: "planned", planDigest, holes },
+    entries: [],
+  };
+}
+
+export interface MemberOutputsCapabilityOptions {
+  /** The engines' sources. Bound by the registry from the loaded plugins; empty until then. */
+  sources?: readonly EngineOutputSource[];
+  /** How a member is found. Default: {@link workspaceMemberLookup}. */
+  lookup?: MemberLookup;
+}
+
+/** `member-outputs` over the given sources. */
+export function memberOutputsCapability(
+  options: MemberOutputsCapabilityOptions = {},
+): Capability<MemberOutputsInput, MemberOutputsOutput> & EngineOutputSourceConsumer {
+  const sources = options.sources ?? [];
+  const lookup = options.lookup ?? workspaceMemberLookup;
+
+  async function resolve(input: MemberOutputsInput): Promise<{ ref: EngineMemberRef; source: EngineOutputSource }> {
+    requireMember(input);
+    const ref = await lookup(input.cwd ?? process.cwd(), input.member);
+    const source = sources.find((s) => s.kinds.includes(ref.kind));
+    if (!source) throw new EngineOutputSourceMissingError(ref.member, ref.kind, [...new Set(sources.flatMap((s) => s.kinds))].sort());
+    return { ref, source };
+  }
+
+  return {
+    kind: MEMBER_OUTPUTS_KIND,
+    // It reads; the member's own pipeline applies. Nothing to compensate.
+    rollbackPolicy: "none-by-design",
+    targets: { refuse: "it reads another member's outputs; narrow that member's own plan instead" },
+    async plan(ctx: DeployContext, input: MemberOutputsInput): Promise<CapabilityPlan> {
+      const { ref, source } = await resolve(input);
+      const planned = await source.planned(ctx, ref);
+      const unknown = [...new Set(planned.unknown)].sort();
+      const known = Object.fromEntries(Object.entries(planned.known).filter(([name]) => !unknown.includes(name)));
+      const member = memberOutputsMemberName(ref.member);
+      const planDigest = computePlanDigest(MEMBER_OUTPUTS_KIND, { env: ctx.env, member: ref.member, kind: ref.kind, plan: planned.planDigest, known, unknown });
+      return { member, planDigest, changeSet: outputsPart(ref.member, planDigest, unknown), outputs: { known, unknown } };
+    },
+    async outputs(ctx: DeployContext, input: MemberOutputsInput): Promise<Record<string, unknown>> {
+      const { ref, source } = await resolve(input);
+      return source.applied(ctx, ref);
+    },
+    async run(ctx: DeployContext, input: MemberOutputsInput): Promise<MemberOutputsOutput> {
+      const { ref, source } = await resolve(input);
+      const now = await source.planned(ctx, ref);
+      if (now.changes) throw new MemberOutputsPendingError(ref.member);
+      return { member: ref.member, outputs: await source.applied(ctx, ref) };
+    },
+    withEngineOutputSources(next: readonly EngineOutputSource[]) {
+      return memberOutputsCapability({ ...options, sources: next }) as unknown as Capability<never, unknown>;
+    },
+  };
+}
+
+/** The starter set's `member-outputs`, with no sources until a registry binds the loaded plugins' ones. */
+export const memberOutputsStarterCapability = memberOutputsCapability();
+
+/**
+ * A component in the consumer's project that stands for workspace member
+ * `member` (#4455): one step reading its outputs. Named after the member, so
+ * `stackOutput(member, "<output>")` reads them and `dependsOn: [member]`
+ * orders the consumer after it.
+ */
+export function memberOutputsComponent(member: string, options: { cwd?: string } = {}): Component {
+  return {
+    name: member,
+    archetype: "infra",
+    dependsOn: [],
+    deploy: [{ phase: "Outputs", steps: [{ kind: MEMBER_OUTPUTS_KIND, member, ...(options.cwd ? { cwd: options.cwd } : {}) }] }],
+  };
+}