@intentius/chant 0.124.51 → 0.124.54

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 } : {}) }] }],
+  };
+}

package/src/components/wave-plan.ts

@@ -27,6 +27,7 @@
  * `@<component>.publish.*`) resolves.
  */
 
+import type { PlanShape } from "./covered-round";
 import { assertTargetsAccepted, resolveStepInput, unresolvedWiringSources, type DriverComponent, type DriverPhase, type DriverStep } from "./driver";
 import { componentPlanDigest } from "./gate-plan";
 import { componentDeployInputs, type ComponentDeployInputs } from "./deploy-inputs";
@@ -44,7 +45,7 @@ import type { ChangeSetPart } from "../change-set";
  * merges a run's outputs; absent when no step's plan says.
  */
 export type WaveComponentPlan =
-  | { component: string; members: WaveMember[]; plans: Record<string, unknown>; parts: ChangeSetPart[]; outputs?: PlannedOutputs }
+  | { component: string; members: WaveMember[]; plans: Record<string, unknown>; parts: ChangeSetPart[]; outputs?: PlannedOutputs; shapes?: Record<string, PlanShape> }
   | { component: string; error: string };
 
 /** A part with no entries, for a member whose planner describes no changes. `unbound` steps become its holes (#4155). */
@@ -101,6 +102,7 @@ export async function planWaveComponent(
     const plans: Record<string, unknown> = {};
     const parts: ChangeSetPart[] = [];
     let outputs: PlannedOutputs | undefined;
+    const shapes: Record<string, PlanShape> = {};
     assertTargetsAccepted(component, registry, ctx);
     for (const step of capabilitySteps(component.deploy)) {
       const capability = registry.resolve(step.kind);
@@ -112,6 +114,7 @@ export async function planWaveComponent(
       members.push(member);
       parts.push(planned.changeSet ?? emptyPart(member));
       if (planned.artifact !== undefined) plans[planned.member] = planned.artifact;
+      if (planned.shape) shapes[planned.member] = { ...planned.shape, member: planned.member };
       if (planned.outputs) outputs = mergePlannedOutputs(outputs, planned.outputs);
     }
     // #4155: the steps without a plan, which no member above covers.
@@ -141,7 +144,7 @@ export async function planWaveComponent(
         parts.push(emptyPart(member, read.unbound));
       }
     }
-    return { component: component.name, members, plans, parts, ...(outputs ? { outputs } : {}) };
+    return { component: component.name, members, plans, parts, ...(outputs ? { outputs } : {}), ...(Object.keys(shapes).length > 0 ? { shapes } : {}) };
   } catch (err) {
     return { component: component.name, error: err instanceof Error ? err.message : String(err) };
   }

package/src/config.ts

@@ -34,6 +34,20 @@ export {
 } from "./config-environments";
 import { EXECUTOR_FORGES, isOwnershipParamRef, resolveOwnershipStack, type EnvironmentDeclaration, type OwnershipEnv } from "./config-environments";
 
+/** An s3 index store's settings (#4519, ./lifecycle/snapshot-store-s3.ts). */
+const S3StoreSettingsShape = {
+  bucket: z.string().min(1),
+  prefix: z.string().optional(),
+  region: z.string().min(1).optional(),
+  endpoint: z.string().url().optional(),
+  forcePathStyle: z.boolean().optional(),
+  credentials: z.object({
+    accessKeyId: z.string().min(1),
+    secretAccessKey: z.string().min(1),
+    sessionToken: z.string().min(1).optional(),
+  }).strict().optional(),
+};
+
 /**
  * Zod schema for ChantConfig validation.
  */
@@ -139,6 +153,20 @@ export const ChantConfigSchema = z.object({
   exclude: z.array(z.string().min(1)).optional(),
   include: z.array(z.string().min(1)).optional(),
   rootOnly: z.boolean().optional(),
+  // Strict: a misspelt key would send snapshots somewhere nobody looks (#4519).
+  snapshots: z.discriminatedUnion("store", [
+    z.object({ store: z.literal("git-ref"), ref: z.string().regex(/^refs\/chant\//).optional(), readOrphanBranch: z.boolean().optional() }).strict(),
+    z.object({ store: z.literal("orphan-branch") }).strict(),
+    z.object({ store: z.literal("local"), dir: z.string().min(1).optional() }).strict(),
+    z.object({ store: z.literal("s3"), ...S3StoreSettingsShape }).strict(),
+    z.object({ store: z.literal("none") }).strict(),
+  ]).optional(),
+  observationBaseline: z.object({
+    store: z.enum(["file", "git-ref", "s3", "none"]),
+    dir: z.string().min(1).optional(),
+    ref: z.string().regex(/^refs\/chant\//).optional(),
+    s3: z.object(S3StoreSettingsShape).strict().optional(),
+  }).strict().optional(),
 }).passthrough();
 
 /**
@@ -504,6 +532,22 @@ export interface ChantConfig {
    * in a project with no `chant.workspace.json`.
    */
   rootOnly?: boolean;
+
+  /**
+   * Where snapshots and every other index are kept (#4519): `git-ref`
+   * (default, `refs/chant/snapshots`, still reading `chant/lifecycle` for
+   * snapshots written before), `local` (a directory), `s3` (a bucket under a
+   * prefix), `none`, or `orphan-branch` (read-only). `CHANT_SNAPSHOT_STORE`
+   * and its companions override it. See `./lifecycle/snapshot-store.ts`.
+   */
+  snapshots?: import("./lifecycle/snapshot-store").SnapshotStoreConfig;
+
+  /**
+   * Where accepted observation deviations are kept (#4519): `file` (default,
+   * `.chant/observation-baseline/<env>.json`, committed and reviewed),
+   * `git-ref`, `s3` or `none`. See `./lifecycle/observation-baseline.ts`.
+   */
+  observationBaseline?: import("./lifecycle/observation-baseline").ObservationBaselineStoreConfig;
 }
 
 /**

package/src/deep-observation.ts

@@ -45,6 +45,7 @@
 
 import type { UnobservedEntity } from "./observation";
 import { isHeldElsewhere, isNormalizedHeldElsewhere, normalizeHeldElsewhere } from "./held-elsewhere";
+import { isSensitiveKey } from "./sensitive-key";
 
 /**
  * A live property tree for one declared entity, already normalized by the
@@ -203,29 +204,10 @@ export const UNRESOLVED = "<chant:unresolved>";
 /** Value a masked (secret-bearing) property takes. Matches the thin path's convention. */
 export const MASKED = "[REDACTED]";
 
-/**
- * Property-name patterns that mark a value secret-bearing. Deliberately narrow
- * and key-name based: broadening this to e.g. `/key/i` would mask an AWS tag's
- * `Key` field and every `*KeyName` reference, which is how masking turns into
- * its own drift signal.
- *
- * Shared with the thin snapshot path (`./lifecycle/snapshot.ts`), which warns
- * on the same names — one list, so the two paths cannot disagree about what
- * counts as a secret.
- */
-export const SENSITIVE_KEY_PATTERNS: readonly RegExp[] = [
-  /password/i,
-  /secret/i,
-  /token/i,
-  /private.?key/i,
-  /credential/i,
-  /connection.?string/i,
-];
-
-/** True when a property name looks secret-bearing (see {@link SENSITIVE_KEY_PATTERNS}). */
-export function isSensitiveKey(key: string): boolean {
-  return SENSITIVE_KEY_PATTERNS.some((p) => p.test(key));
-}
+// The secret-key list lives in `./sensitive-key.ts` so the drift record
+// (`./drift-record.ts`) can redact with it inside the change-set bundle,
+// which may not import this module's normalization code.
+export { SENSITIVE_KEY_PATTERNS, isSensitiveKey } from "./sensitive-key";
 
 /** Which tree a hook is being invoked on. */
 export type DeepSide = "declared" | "live";