@intentius/chant 0.124.52 → 0.124.54

package/src/ci-identity-targets.test.ts

@@ -62,6 +62,29 @@ const DECL: CloudIdentityDeclaration = {
 
 const ROOTS = ["envs/prod/net", "envs/staging/net", "shared/dns", "envs/prod/app"];
 
+describe("a target with several names takes the first rule any name matches (#4332)", () => {
+  // A Terraform root's key in `terraform.roots`, then its directory relative to the project.
+  const decl: CloudIdentityDeclaration = {
+    aws: {
+      rules: [
+        { targets: ["envs/prod/**"], plan: role("dir-plan"), apply: role("dir-apply") },
+        { targets: ["network"], plan: role("key-plan"), apply: role("key-apply") },
+        { plan: role("own-plan"), apply: role("own-apply") },
+      ],
+    },
+  };
+  const apply = (...names: string[]) => resolveTargetCloudIdentity(decl, "prod", undefined, names)!.apply.aws!.role;
+
+  test("the key matches", () => expect(apply("network", "infra/net")).toBe(role("key-apply")));
+  test("the directory matches", () => expect(apply("prod-net", "envs/prod/net")).toBe(role("dir-apply")));
+  test("both match different rules: the first declared rule wins", () => {
+    expect(apply("network", "envs/prod/net")).toBe(role("dir-apply"));
+    expect(apply("envs/prod/net", "network")).toBe(role("dir-apply"));
+  });
+  test("neither matches: the member's own rule", () => expect(apply("dns", "shared/dns")).toBe(role("own-apply")));
+  test("a single name resolves as before", () => expect(resolveTargetCloudIdentity(decl, "prod", undefined, "network")).toEqual(resolveTargetCloudIdentity(decl, "prod", undefined, ["network"])));
+});
+
 describe("which identity a target takes (#4332)", () => {
   test("the first rule that covers the environment, the member and the target wins, per cloud", () => {
     const prod = resolveTargetCloudIdentity(DECL, "prod", "infra", "envs/prod/net")!;

package/src/ci-identity.ts

@@ -207,14 +207,20 @@ function globBody(g: string, paths: boolean): string {
 
 const matches = (globs: readonly string[] | undefined, name: string | undefined): boolean => globs === undefined || (name !== undefined && globs.some((g) => nameGlobMatch(g, name)));
 
-const coversTarget = (r: CloudIdentityRule, target: string | undefined): boolean =>
-  r.targets === undefined || (target !== undefined && r.targets.some((g) => targetGlobMatch(g, target)));
+/** One target's names: a string, or the several names a tool knows it by, such as a Terraform root's key and its directory. */
+export type TargetNames = string | readonly string[];
+
+const coversTarget = (r: CloudIdentityRule, target: TargetNames | undefined): boolean =>
+  r.targets === undefined || (target !== undefined && (typeof target === "string" ? [target] : target).some((n) => r.targets!.some((g) => targetGlobMatch(g, n))));
 
 /**
  * The first rule that covers `env`, `member` and `target`, or undefined.
  * With no `target`, the first rule that names no targets: the pipeline's own.
+ * A `target` given as several names is covered by a rule when any one name
+ * matches a glob, and the first rule in declared order wins, whichever name
+ * it matched.
  */
-export function ruleFor(rules: readonly CloudIdentityRule[], env: string, member?: string, target?: string): CloudIdentityRule | undefined {
+export function ruleFor(rules: readonly CloudIdentityRule[], env: string, member?: string, target?: TargetNames): CloudIdentityRule | undefined {
   return rules.find((r) => matches(r.environments, env) && matches(r.members, member) && coversTarget(r, target));
 }
 
@@ -289,7 +295,7 @@ export function resolveCloudIdentity(decl: CloudIdentityDeclaration | undefined,
  * any cloud covers it. Each trade names one identity per cloud and no
  * `targets`.
  */
-export function resolveTargetCloudIdentity(decl: CloudIdentityDeclaration | undefined, env: string, member: string | undefined, target: string): PipelineCloudIdentity | undefined {
+export function resolveTargetCloudIdentity(decl: CloudIdentityDeclaration | undefined, env: string, member: string | undefined, target: TargetNames): PipelineCloudIdentity | undefined {
   if (!decl) return undefined;
   const plan: Record<string, unknown> = {};
   const apply: Record<string, unknown> = {};

package/src/cli/commands/import-index.test.ts

@@ -0,0 +1,117 @@
+/**
+ * #4524: `importFromIndex` end to end with a fake lexicon: it reads an index
+ * file, writes the generator's files and the report, gives byte-identical
+ * output for the same index and selection, and refuses an empty selection.
+ * No project is built (the declared entities are passed in) and nothing
+ * reaches a cloud.
+ */
+import { mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { afterAll, describe, expect, test } from "vitest";
+import { MASKED } from "../../deep-observation";
+import type { LexiconPlugin } from "../../lexicon";
+import { indexDocumentDigest, indexScopeKey, type CloudIndexScope, type IndexDocument } from "../../lifecycle/index-document";
+import { adoptionFileProblemsAgainst, type AdoptionFile } from "../../lifecycle/adoption-file";
+import { importFromIndex, INDEX_IMPORT_REPORT_FILE } from "./import-index";
+
+const dirs: string[] = [];
+const scratch = () => {
+  const d = mkdtempSync(join(tmpdir(), "chant-index-import-"));
+  dirs.push(d);
+  return d;
+};
+afterAll(() => {
+  for (const d of dirs) rmSync(d, { recursive: true, force: true });
+});
+
+const SCOPE: CloudIndexScope = { kind: "cloud", substrate: "aws", scopeId: "111", locations: ["r1"], types: "*" };
+const nodes = [
+  { id: "aws/111/r1/Fake::Net/net-1", kind: "Fake::Net", lexicon: "fake", attrs: { Cidr: "10.0.0.0/16" }, listedType: "Fake::Net", location: "r1", nativeId: "net-1" },
+  { id: "aws/111/r1/Fake::Db/db-1", kind: "Fake::Db", lexicon: "fake", attrs: { NetId: "net-1", Password: MASKED }, listedType: "Fake::Db", location: "r1", nativeId: "db-1" },
+];
+const edges = [{ from: nodes[1].id, to: nodes[0].id, kind: "ref" as const, origin: "derived" as const, rule: "fake:Fake::Db:NetId", viaAttr: "NetId" }];
+const graph = { version: 1 as const, nodes, edges, groups: {} };
+const DOC: IndexDocument = {
+  index: "v1",
+  stamp: { source: { kind: "cloud", name: "behold-lister" }, scope: SCOPE, scopeKey: indexScopeKey(SCOPE), observedAt: "2026-10-26T00:00:00.000Z", digest: indexDocumentDigest({ graph, coverage: [] }) },
+  coverage: [],
+  graph,
+};
+
+// The generator writes the IR as JSON, which is enough to see what it was given.
+const plugin = {
+  name: "fake",
+  indexImport: {
+    resource: (n: { kind: string; attrs: Record<string, unknown> }) => ({ type: n.kind, properties: n.attrs }),
+    reference: (v: string, t: { logicalId: string; node: { nativeId?: string } }) => (v === t.node.nativeId ? { ref: t.logicalId } : undefined),
+    secretParameter: (name: string) => ({ name, type: "String" }),
+    parameterReference: (name: string) => ({ param: name }),
+  },
+  templateGenerator: () => ({
+    ownsLayout: true,
+    generate: (ir: unknown) => [{ path: "main.ts", content: `export const ir = ${JSON.stringify(ir, null, 2)};\n` }],
+  }),
+} as unknown as LexiconPlugin;
+
+function indexFile(): string {
+  const p = join(scratch(), "index.json");
+  writeFileSync(p, JSON.stringify(DOC));
+  return p;
+}
+
+describe("importFromIndex", () => {
+  test("writes the generator's files with the header, and the report beside them", async () => {
+    const out = join(scratch(), "out");
+    const result = await importFromIndex({ index: indexFile(), selection: { all: true }, output: out, plugins: [plugin], declaredEntities: new Map() });
+    expect(result.success).toBe(true);
+    expect(readdirSync(out).sort()).toEqual([INDEX_IMPORT_REPORT_FILE, "main.ts"]);
+    const main = readFileSync(join(out, "main.ts"), "utf-8");
+    expect(main.startsWith("// Generated by chant import --index. Nothing was applied.")).toBe(true);
+    expect(main).not.toContain(MASKED);
+    expect(main).toContain('"ref": "Net1"');
+    const report = JSON.parse(readFileSync(join(out, INDEX_IMPORT_REPORT_FILE), "utf-8"));
+    expect(report.report).toBe("chant-index-import/v1");
+    expect(report.resources.map((r: { status: string }) => r.status)).toEqual(["imported", "imported"]);
+    expect(report.parameters).toEqual([{ name: "Db1Password", node: nodes[1].id, path: "Password", group: "" }]);
+  });
+
+  test("the same index and selection give byte-identical files", async () => {
+    const index = indexFile();
+    const a = join(scratch(), "a");
+    const b = join(scratch(), "b");
+    await importFromIndex({ index, selection: { all: true }, output: a, plugins: [plugin], declaredEntities: new Map() });
+    await importFromIndex({ index, selection: { all: true }, output: b, plugins: [plugin], declaredEntities: new Map() });
+    for (const f of ["main.ts", INDEX_IMPORT_REPORT_FILE]) {
+      expect(readFileSync(join(b, f), "utf-8")).toBe(readFileSync(join(a, f), "utf-8"));
+    }
+  });
+
+  test("an empty selection is refused before the index is read", async () => {
+    const result = await importFromIndex({ index: "does-not-exist", selection: {}, output: join(scratch(), "o"), plugins: [plugin] });
+    expect(result.success).toBe(false);
+    expect(result.error).toMatch(/name what to import/);
+  });
+
+  test("a file that is not an index is refused", async () => {
+    const p = join(scratch(), "not-index.json");
+    writeFileSync(p, JSON.stringify({ hello: 1 }));
+    const result = await importFromIndex({ index: p, selection: { all: true }, output: join(scratch(), "o"), plugins: [plugin], declaredEntities: new Map() });
+    expect(result.success).toBe(false);
+    expect(result.error).toMatch(/does not hold index documents/);
+  });
+
+  test("--adopt-out writes the adoption file for what was imported, valid against the index (#4536)", async () => {
+    const out = join(scratch(), "out");
+    const adoptOut = join(scratch(), "adopt.json");
+    const result = await importFromIndex({ index: indexFile(), selection: { all: true }, output: out, adoptOut, plugins: [plugin], declaredEntities: new Map() });
+    expect(result.success).toBe(true);
+    const adopt = JSON.parse(readFileSync(adoptOut, "utf-8")) as AdoptionFile;
+    expect(adopt.adopt).toBe("v1");
+    expect(adopt.select).toEqual([
+      { node: nodes[1].id, as: "Db1", type: "Fake::Db" },
+      { node: nodes[0].id, as: "Net1", type: "Fake::Net" },
+    ]);
+    expect(adoptionFileProblemsAgainst(adopt, DOC)).toEqual([]);
+  });
+});

package/src/cli/commands/import-index.ts

@@ -0,0 +1,265 @@
+/**
+ * `chant import --index <ref>` (#4524): typed source for indexed resources.
+ *
+ * Reads one index version (a file, or a version in the project's index
+ * store), selects nodes, and writes source through each lexicon's own
+ * template generator. Nothing is applied and nothing is written to the
+ * cloud. The pure part is ../../lifecycle/index-import.ts; this module reads
+ * the index, builds the project for the declared check, and writes files.
+ *
+ * The report (`chant-index-import.json` in the output directory, or
+ * `--report <path>`) names every selected resource's identity and cloud ids,
+ * what was imported, declared or unsupported, each reference and each
+ * parameter. The adoption step (INTENTIUS/choudoufu#2284) reads it.
+ * `--adopt-out <file>` also writes the adoption file (`adopt: v1`, #4536)
+ * that adopts every imported resource as its logical id.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join, relative, resolve } from "path";
+import type { GeneratedFile } from "../../import/generator";
+import type { LexiconPlugin } from "../../lexicon";
+import type { DeclaredEntity } from "../../lifecycle/identity-match";
+import { adoptionFileFromImportReport, adoptionFileJson } from "../../lifecycle/adoption-file";
+import type { IndexDocument } from "../../lifecycle/index-document";
+import {
+  declaredNodes,
+  indexImportHeader,
+  planIndexImport,
+  selectionIsEmpty,
+  type IndexImportPlan,
+  type IndexImportReport,
+  type IndexImportSelection,
+} from "../../lifecycle/index-import";
+import { generateOrganizedFiles, type ImportResult } from "./import";
+
+export const INDEX_IMPORT_REPORT_FILE = "chant-index-import.json";
+
+export interface IndexImportOptions {
+  /** A JSON file (one index document, or a list of the documents of one read), or `<scopeKey>[@<version>]` in the index store. */
+  index: string;
+  selection: IndexImportSelection;
+  /** Output directory (defaults to ./infra/). */
+  output?: string;
+  force?: boolean;
+  /** Where to write the report; defaults to `<output>/chant-index-import.json`. */
+  report?: string;
+  /** Where to write the adoption file for what was imported (`--adopt-out`, #4536). */
+  adoptOut?: string;
+  /** The project whose declared entities are checked (defaults to the current directory). */
+  projectDir?: string;
+  /** The project's source directory (`--src`; defaults to `sourceDir` from chant.config, then the project). */
+  src?: string;
+  /** Plugins to use instead of loading them (tests). */
+  plugins?: LexiconPlugin[];
+  /** Declared entities by lexicon instead of building the project (tests). */
+  declaredEntities?: ReadonlyMap<string, readonly DeclaredEntity[]>;
+}
+
+export interface IndexImportResult extends ImportResult {
+  report?: IndexImportReport;
+}
+
+function asDocuments(parsed: unknown, from: string): IndexDocument[] {
+  const list = Array.isArray(parsed)
+    ? parsed
+    : parsed && typeof parsed === "object" && Array.isArray((parsed as { documents?: unknown }).documents)
+      ? (parsed as { documents: unknown[] }).documents
+      : [parsed];
+  for (const d of list) {
+    if (!d || typeof d !== "object" || (d as { index?: unknown }).index !== "v1") {
+      throw new Error(`${from} does not hold index documents (index: "v1")`);
+    }
+  }
+  return list as IndexDocument[];
+}
+
+/**
+ * The documents an index ref names: a file path, or a store ref in the
+ * grammar `chant search --index` reads (`<scopeKey>[@latest|@<version>]`,
+ * ../../lifecycle/index-join.ts), from the store chant.config's `snapshots`
+ * picks (#4519).
+ */
+export async function loadIndexDocuments(ref: string, cwd: string): Promise<IndexDocument[]> {
+  const asFile = resolve(cwd, ref);
+  if (existsSync(asFile)) return asDocuments(JSON.parse(readFileSync(asFile, "utf-8")), ref);
+  const { parseIndexRef, readIndexRef } = await import("../../lifecycle/index-join");
+  const parsed = parseIndexRef(ref);
+  if ("error" in parsed) throw new Error(`no file of that name, and ${parsed.error}; ${parsed.hint}`);
+  const { resolveSnapshotStore } = await import("../../lifecycle/snapshot-store");
+  const store = await resolveSnapshotStore({ cwd });
+  await store.fetch();
+  const read = await readIndexRef(store, parsed);
+  if ("error" in read) throw new Error(read.hint ? `${read.error}; ${read.hint}` : read.error);
+  return [read.doc];
+}
+
+/**
+ * The files an import plan writes, through each lexicon's template
+ * generator, with the plan's header on each group's first file. Pure apart
+ * from the generators, so the same plan gives byte-identical files.
+ */
+export function renderIndexImport(
+  plan: IndexImportPlan,
+  plugins: readonly LexiconPlugin[],
+): { files: GeneratedFile[]; warnings: string[] } {
+  const files: GeneratedFile[] = [];
+  const warnings: string[] = [];
+  for (const group of plan.groups) {
+    const plugin = plugins.find((p) => p.name === group.lexicon);
+    if (!plugin?.templateGenerator) {
+      warnings.push(`the ${group.lexicon} lexicon has no template generator; ${group.ir.resources.length} resource(s) in ${group.dir || "."} were not written`);
+      continue;
+    }
+    const organized = generateOrganizedFiles(group.ir, plugin.templateGenerator());
+    warnings.push(...organized.warnings);
+    organized.files.forEach((f, i) => {
+      const path = group.dir ? `${group.dir}/${f.path}` : f.path;
+      files.push({ path, content: i === 0 ? indexImportHeader(plan, group) + f.content : f.content });
+    });
+  }
+  return { files, warnings };
+}
+
+/** The report as written: two-space JSON and a final newline. */
+export function indexImportReportJson(report: IndexImportReport): string {
+  return JSON.stringify(report, null, 2) + "\n";
+}
+
+/** The project's declared entities by lexicon, or why there are none to check. */
+async function projectEntities(
+  projectDir: string,
+  src: string | undefined,
+  plugins: readonly LexiconPlugin[],
+): Promise<{ entities: Map<string, DeclaredEntity[]>; warning?: string }> {
+  const entities = new Map<string, DeclaredEntity[]>();
+  try {
+    const { loadChantConfigUpward } = await import("../../config");
+    const { config, configPath } = await loadChantConfigUpward(projectDir);
+    if (!configPath) return { entities };
+    const projectPlugins = plugins.filter((p) => p.serializer);
+    if (projectPlugins.length === 0) return { entities };
+    const { build } = await import("../../build");
+    const { isObservableDeclarable } = await import("../../declarable");
+    const root = src ? resolve(src) : resolve(dirname(configPath), config.sourceDir ?? ".");
+    const result = await build(root, projectPlugins.map((p) => p.serializer), undefined, { config: config as unknown as Record<string, unknown> });
+    if (result.errors.length > 0) {
+      return { entities, warning: `the project at ${root} does not build, so no indexed resource was checked against its declarations` };
+    }
+    for (const [name, entity] of result.entities) {
+      if (!isObservableDeclarable(entity)) continue;
+      const list = entities.get(entity.lexicon) ?? entities.set(entity.lexicon, []).get(entity.lexicon)!;
+      list.push({ name, entityType: entity.entityType, props: (entity.props ?? {}) as Record<string, unknown> });
+    }
+    return { entities };
+  } catch (err) {
+    return { entities, warning: `the declared check did not run: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}
+
+/** The plugins for the index's lexicons and the project's, each loaded once; one that fails to load is left out. */
+async function pluginsFor(docs: readonly IndexDocument[], projectDir: string): Promise<LexiconPlugin[]> {
+  const { loadPlugin, resolveProjectLexicons } = await import("../plugins");
+  let names: string[] = [];
+  try {
+    names = await resolveProjectLexicons(projectDir);
+  } catch {
+    names = [];
+  }
+  for (const d of docs) for (const n of d.graph.nodes) if (!n.unmappedKind) names.push(n.lexicon);
+  const plugins: LexiconPlugin[] = [];
+  for (const name of [...new Set(names)].sort()) {
+    try {
+      const plugin = await loadPlugin(name);
+      await plugin.init?.();
+      plugins.push(plugin);
+    } catch {
+      // Not installed here: its nodes are reported as not loaded.
+    }
+  }
+  return plugins;
+}
+
+export async function importFromIndex(options: IndexImportOptions): Promise<IndexImportResult> {
+  const outputDir = resolve(options.output ?? "./infra/");
+  const projectDir = resolve(options.projectDir ?? (options.output ? dirname(outputDir) : "."));
+  const warnings: string[] = [];
+  const fail = (error: string): IndexImportResult => ({ success: false, generatedFiles: [], warnings, error });
+
+  if (selectionIsEmpty(options.selection)) {
+    return fail("name what to import: --type <type>, --name <native id>, --tag key=value, --select <file of node ids>, or --all");
+  }
+
+  let docs: IndexDocument[];
+  try {
+    docs = await loadIndexDocuments(options.index, process.cwd());
+  } catch (err) {
+    return fail(`could not read the index ${options.index}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  const plugins = options.plugins ?? (await pluginsFor(docs, projectDir));
+  let declared: Map<string, string> = new Map();
+  let entities: ReadonlyMap<string, readonly DeclaredEntity[]>;
+  if (options.declaredEntities) {
+    entities = options.declaredEntities;
+  } else {
+    const project = await projectEntities(projectDir, options.src, plugins);
+    if (project.warning) warnings.push(project.warning);
+    entities = project.entities;
+  }
+  try {
+    declared = declaredNodes(docs, entities, plugins);
+  } catch (err) {
+    warnings.push(`the declared check did not run: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  let plan: IndexImportPlan;
+  try {
+    plan = planIndexImport(docs, options.selection, plugins, { declared });
+  } catch (err) {
+    return fail(err instanceof Error ? err.message : String(err));
+  }
+  if (plan.report.resources.length === 0) return fail("the selection matches no node in the index");
+
+  const { files, warnings: renderWarnings } = renderIndexImport(plan, plugins);
+  warnings.push(...renderWarnings);
+  for (const r of plan.report.resources) {
+    if (r.status === "unsupported") warnings.push(`${r.node}: not imported, ${r.reason}`);
+  }
+
+  const reportPath = resolve(options.report ?? join(outputDir, INDEX_IMPORT_REPORT_FILE));
+  const generatedFiles: string[] = [];
+  const write = (path: string, content: string, shown: string) => {
+    if (existsSync(path) && !options.force) {
+      warnings.push(`File ${shown} already exists, skipping`);
+      return;
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+    generatedFiles.push(shown);
+  };
+  for (const file of files) write(join(outputDir, file.path), file.content, file.path);
+  write(reportPath, indexImportReportJson(plan.report), relative(outputDir, reportPath) || reportPath);
+  if (options.adoptOut) {
+    const adoptPath = resolve(options.adoptOut);
+    try {
+      write(adoptPath, adoptionFileJson(adoptionFileFromImportReport(plan.report)), relative(outputDir, adoptPath) || adoptPath);
+    } catch (err) {
+      return { success: false, generatedFiles, warnings, error: `no adoption file written: ${err instanceof Error ? err.message : String(err)}`, report: plan.report };
+    }
+  }
+
+  const lexicons = [...new Set(plan.groups.map((g) => g.lexicon))];
+  return {
+    success: true,
+    generatedFiles,
+    warnings,
+    ...(lexicons.length === 1 ? { lexicon: lexicons[0] } : {}),
+    report: plan.report,
+  };
+}
+
+/** One line per status: what was imported, declared and left out. */
+export function summarizeIndexImport(report: IndexImportReport): string {
+  const count = (s: string) => report.resources.filter((r) => r.status === s).length;
+  return `index import: ${count("imported")} imported, ${count("declared")} already declared, ${count("unsupported")} unsupported, ${report.parameters.length} parameter(s) to fill in`;
+}

package/src/cli/commands/lint.ts

@@ -9,7 +9,7 @@ import { findInfraFiles, detectLexicons } from "../../index";
 import { formatStylish, formatJson, formatSarif } from "../reporters/stylish";
 import { loadLocalRules } from "../../lint/rule-loader";
 import { loadCoreRules } from "../../lint/rules/index";
-import { loadComponentChecks } from "../../lint/rules/comp/index";
+import { loadComponentChecks, signalOnlyRootsOf } from "../../lint/rules/comp/index";
 import { runComponentChecks, type ComponentCheckDiagnostic } from "../../lint/component-checks";
 import { buildCapabilityRegistry } from "../../components/capability-plugin-loader";
 import type { RollbackPolicy } from "../../components/capability";
@@ -464,7 +464,9 @@ async function runComponentCheckDiagnostics(
   const allCheckIds = new Set(checks.map((c) => c.id));
 
   const registryContext = await resolveRegistryContext(infraPath);
-  const raw = await runComponentChecks(infraPath, checks, registryContext, sandbox, buildParams);
+  // COMP008 (#4490) reads the project's signalOnly terraform roots.
+  const signalOnlyRoots = await signalOnlyRootsOf(findProjectRoot(infraPath));
+  const raw = await runComponentChecks(infraPath, checks, { ...registryContext, signalOnlyRoots }, sandbox, buildParams);
 
   const fileDirectivesCache = new Map<string, ReturnType<typeof parseDisableComments>>();
   const fileLevelDisable = (

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

@@ -44,6 +44,15 @@ vi.mock("../../lifecycle/git", () => ({
   StaleLifecycleBranchError: class StaleLifecycleBranchError extends Error {},
 }));
 
+// The status baseline is read through the index store (#4519); this one hands the read to the mock above.
+vi.mock("../../lifecycle/snapshot-store", async () => {
+  const { fakeSnapshotStore } = await import("../../lifecycle/snapshot-store-fake");
+  const store = fakeSnapshotStore({
+    readLatest: async (environment, key) => (await readSnapshotMock(environment, key)) as string | null,
+  });
+  return { resolveSnapshotStore: async () => store };
+});
+
 vi.mock("../../lifecycle/build-ledger-store", () => ({
   findBuildManifestByArtifactDigest: (...args: unknown[]) => findBuildManifestByArtifactDigestMock(...args),
   readBuildManifest: (...args: unknown[]) => readBuildManifestMock(...args),

package/src/cli/handlers/components.ts

@@ -28,7 +28,8 @@
  */
 import { resolve, join, dirname } from "node:path";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { getHeadCommit, fetchLifecycle, pushLifecycle, readSnapshot, snapshotStorageKey, StaleLifecycleBranchError } from "../../lifecycle/git";
+import { getHeadCommit, fetchLifecycle, pushLifecycle, snapshotStorageKey, StaleLifecycleBranchError } from "../../lifecycle/git";
+import { resolveSnapshotStore } from "../../lifecycle/snapshot-store";
 import type { LifecycleSnapshot } from "../../lifecycle/types";
 import {
   appendReleaseRecord,
@@ -519,18 +520,27 @@ async function observeComponentStacks(
  * snapshot is no baseline, never an error: with none, nothing can have changed
  * since, and the status falls back to identity and presence.
  */
+/** Stores already fetched in this process, so a status over many lexicons fetches once. */
+const fetchedBaselineStores = new WeakSet<object>();
+
 async function readStatusBaseline(
   environment: string,
   lexicon: string,
   stacks: Array<string | undefined>,
 ): Promise<{ resources: Record<string, ResourceMetadata> | undefined; timestamps: Map<string, string> }> {
   const keys = [...new Set([...stacks.filter((s): s is string => !!s).map((s) => snapshotStorageKey(lexicon, s)), snapshotStorageKey(lexicon)])];
+  // Through the index store (#4519); a store that cannot be built is no baseline, like a missing snapshot.
+  const store = await resolveSnapshotStore().catch(() => null);
+  if (store && !fetchedBaselineStores.has(store)) {
+    fetchedBaselineStores.add(store);
+    await store.fetch();
+  }
   let resources: Record<string, ResourceMetadata> | undefined;
   const timestamps = new Map<string, string>();
   for (const key of keys) {
     let snap: LifecycleSnapshot | undefined;
     try {
-      const content = await readSnapshot(environment, key);
+      const content = store ? await store.readLatest(environment, key) : null;
       snap = content ? (JSON.parse(content) as LifecycleSnapshot) : undefined;
     } catch {
       snap = undefined;

package/src/cli/handlers/fan-out.ts

@@ -70,6 +70,8 @@ import { approveCommand, gateIsSealed } from "../../op/gate";
 import { getHeadCommit } from "../../lifecycle/git";
 import { remainingFanOut, type ChangedUnits, type FanOutProgress } from "../../components/fan-out";
 import { readDeployedOutputs } from "../../components/wave-plan";
+import { formRunGroups } from "../../components/groups";
+import { renderRunGroups, runGroupsReport } from "../../components/run-groups";
 import { deployContext, failedRunExitCode } from "../../components/driver";
 import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
 import { formatError, formatInfo, formatWarning } from "../format";
@@ -234,6 +236,8 @@ async function fanOut(ctx: CommandContext, projectPath: string, config: ChantCon
     return 1;
   }
 
+  // #4516: one registry finds the declared reads (a template's Fn::ImportValue) that order the fan-out and runs it.
+  const registry = await fanOutRegistry(projectPath, config);
   let derived;
   try {
     derived = await deriveFanOut({
@@ -242,6 +246,7 @@ async function fanOut(ctx: CommandContext, projectPath: string, config: ChantCon
       sandbox: args.sandbox,
       buildParams: paramsResolution.provenance,
       config,
+      registry,
       ...(args.canary?.length ? { canary: args.canary } : {}),
     });
   } catch (err) {
@@ -387,7 +392,6 @@ async function fanOut(ctx: CommandContext, projectPath: string, config: ChantCon
     }
   }
 
-  const registry = await fanOutRegistry(projectPath, config);
   const env = args.env ?? "local";
 
   // A completed component's recorded outputs win over a `--seed-outputs`
@@ -450,10 +454,15 @@ async function fanOut(ctx: CommandContext, projectPath: string, config: ChantCon
   const release = autoReleaseRun(`fan-out-${Date.now()}`);
   const events = await openCliRunEvents(args, { kind: "component", name: `fan-out ${derived.plan.order.join(",")}`, runId: release.runId, cwd: projectPath });
 
+  // ws-107 (#4465): the components a capability takes as one plan in their
+  // wave and apply as one group; under --wave-gate none forms (ruling 1).
+  const runPlan = await formRunGroups({ components: derived.components, plan: derived.plan, registry, env, ...(waveGate ? { waveGate: true } : {}) });
+
   let result;
   try {
-    result = await runFanOut(derived.plan, derived.components, registry, {
+    result = await runFanOut(runPlan, derived.components, registry, {
       env,
+      ...(runPlan.groups?.length ? { planGroupsAtWave: true } : {}),
       releaseIdentity: () => (revision ? { revision } : {}),
       componentOutputs,
       ...(targets ? { targets } : {}),
@@ -524,7 +533,12 @@ async function fanOut(ctx: CommandContext, projectPath: string, config: ChantCon
   recordAttempt();
 
   if (args.json) renderFanOutJson(result);
-  else renderFanOutHuman(result, { ...(gate ? { gate } : {}), ...(waveGate ? { waveGate } : {}) });
+  else {
+    renderFanOutHuman(result, { ...(gate ? { gate } : {}), ...(waveGate ? { waveGate } : {}) });
+    // #4465: the groups applied as one, and how each member ended.
+    const report = runGroupsReport({ grouped: result.plan.groups?.length || result.plan.fallbacks?.length ? result.plan : runPlan, ...(result.groupOutcomes ? { outcomes: result.groupOutcomes } : {}) });
+    for (const line of renderRunGroups(report, "the same fan-out with --resume")) console.error(formatInfo(line));
+  }
 
   // A wave whose set moved after its approval stops with both digests named
   // (#3049), the #2300 refusal on a set. Printed on stderr even under --json,

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

@@ -963,6 +963,48 @@ describe("runGraph", () => {
       expect(node?.physicalId).toBeUndefined();
     });
 
+    // #4452 — which read answered each root reaches the IR as the lexicon's
+    // structured report, so behold reads `rootReads` instead of matching the
+    // stderr notes. Asked the way behold asks for a plan read: `--overlay
+    // --detail 3`, whose overlay and detail passes each build a fresh IR.
+    test("a plan read's IR carries rootReads, a fallback with its reason", async () => {
+      resolveLexMock.mockResolvedValue(["terraform"]);
+      loadPluginsMock.mockResolvedValue([
+        { name: "terraform", serializer: {}, describeResources: () => Promise.resolve({}) },
+      ]);
+      discoverMock.mockResolvedValue({ entities: new Map(), errors: [], sourceFiles: [] });
+      const rootReads = {
+        "terraform.roots.app": { depth: "plan" },
+        "terraform.roots.edge": { depth: "plan", fellBackTo: "state", reason: "no-credentials" },
+      };
+      observeMock.mockResolvedValue({
+        observations: [{ lexicon: "terraform", resources: { "app/aws_s3_bucket.logs": { type: "aws_s3_bucket", status: "OK" } } }],
+        errors: [],
+        warnings: [],
+        sources: { "app/aws_s3_bucket.logs": "plan" },
+        rootReads,
+      });
+      const exit = await runGraph({ args: makeArgs({ format: "ir", live: true, overlay: true, env: "prod", detail: 3 }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      const ir = JSON.parse(stdoutBuf.join("\n")) as { version: number; rootReads?: unknown };
+      expect(ir.version).toBe(GRAPH_IR_VERSION);
+      expect(ir.rootReads).toEqual(rootReads);
+    });
+
+    test("an IR whose read reported no root reads has no rootReads", async () => {
+      resolveLexMock.mockResolvedValue(["aws"]);
+      loadPluginsMock.mockResolvedValue([
+        { name: "aws", serializer: {}, emulator: awsEmulatorStub, describeResources: () => Promise.resolve({}) },
+      ]);
+      observeMock.mockResolvedValue({
+        observations: [{ lexicon: "aws", resources: { "web-vpc": { type: "AWS::EC2::VPC", status: "OK" } } }],
+        errors: [],
+        warnings: [],
+      });
+      expect(await runGraph({ args: makeArgs({ format: "ir", live: true, env: "prod" }), plugins: [], serializers: [] })).toBe(0);
+      expect(JSON.parse(stdoutBuf.join("\n"))).not.toHaveProperty("rootReads");
+    });
+
     // #2377 — the overlay carries the prediction. behold's reader takes
     // `attrs._behaviour` per node and `meta._behaviour` on the graph, and
     // reads the absence of both as "not looked" rather than as a refusal, so