@intentius/chant 0.124.51 → 0.124.54

package/src/cli/handlers/graph.ts

@@ -2,7 +2,7 @@ import { isAbsolute, relative, resolve } from "node:path";
 import { discoverOps } from "../../op/discover";
 import { discover } from "../../discovery/index";
 import { partitionByLexicon, computeStackGraph, build } from "../../build";
-import { applyLexiconOutputs, buildGraphIr, buildLiveGraphIr, collectUnobserved, overlayGraphs, sourceOverlayGraphs, GRAPH_IR_VERSION, type GraphIR, type IRPipeline, type LexiconWorkspaceOutputs, type LiveObservation } from "../../graph-ir";
+import { applyLexiconOutputs, buildGraphIr, buildLiveGraphIr, collectUnobserved, overlayGraphs, sourceOverlayGraphs, withInstanceNodes, GRAPH_IR_VERSION, type GraphIR, type IRPipeline, type LexiconWorkspaceOutputs, type LiveObservation } from "../../graph-ir";
 import { behaviourOverlay } from "../../behaviour-overlay";
 import type { SerializerResult } from "../../serializer";
 import { applyBehaviourOverlay, behaviourRequestFromIr } from "../../behaviour-graph";
@@ -10,6 +10,7 @@ import { buildDeclaredPerStack } from "../../graph-declared";
 import { mergeProjectOps } from "../../graph-ops";
 import { reconstructEdges, mergeCatalogs, containmentGroups, type ReferenceCatalog, type ContainmentPair } from "../../graph-refs";
 import { carryAnnotations, observeResources } from "../../lifecycle/observe";
+import type { RootRead } from "../../observation";
 import { withLiveReadSession } from "../../live-read-session";
 import { replaySnapshots, hasSnapshot } from "../../lifecycle/replay";
 import { loadChantConfig, environmentNames, matchesDeclaredEnvironment, loadChantConfigUpward, type ChantConfig } from "../../config";
@@ -293,6 +294,8 @@ async function runGraphLive(
     let observations: LiveObservation[];
     // Facts about absent entities (#4372), carried onto the overlay's nodes.
     let annotations: Record<string, Record<string, unknown>> | undefined;
+    // Which read answered each root (#4452), carried onto the IR as written.
+    let rootReads: Record<string, RootRead> | undefined;
     // A replay is a graph of what was recorded, so it must not reach the provider
     // at all — not for observation and not for enrichment. Anything that quietly
     // called out would make `--at` a live read with an older label on it.
@@ -322,6 +325,7 @@ async function runGraphLive(
       });
       observations = observeResult.observations;
       annotations = observeResult.annotations;
+      rootReads = observeResult.rootReads;
       const { errors, warnings, notes = [] } = observeResult;
       for (const e of errors) console.error(formatWarning({ message: e }));
       // Unobserved entities (#1089) arrive as warnings — a node missing from the
@@ -383,7 +387,13 @@ async function runGraphLive(
   let containment: ContainmentPair[] = [];
   if (catalogs.length > 0) {
     const reconstructed = reconstructEdges(ir.nodes, mergeCatalogs(catalogs));
-    ir = { ...ir, edges: reconstructed.edges };
+    // Merge, never replace, as `search --live` does (#1273). An observation
+    // can carry edges of its own (terraform's state dependencies, #4520's
+    // engine facts), and a catalog on one observing lexicon used to wipe every
+    // lexicon's: the reason terraform's catalog stayed off its plugin until
+    // #4535.
+    const seen = new Set(ir.edges.map((e) => `${e.from}|${e.to}|${e.viaAttr ?? ""}`));
+    ir = { ...ir, edges: [...ir.edges, ...reconstructed.edges.filter((e) => !seen.has(`${e.from}|${e.to}|${e.viaAttr ?? ""}`))] };
     containment = reconstructed.containment;
   }
 
@@ -427,7 +437,12 @@ async function runGraphLive(
         console.error(formatWarning({ message: "overlay: a build root failed to render — showing the provisioned graph without the declared overlay" }));
       } else {
         await mergeGraphOps(declared.entities, declared.sourceFiles, projectPath);
-        const declaredIr = withLexiconEdges(buildGraphIr(declared.entities, projectPath), plugins, declared.entities);
+        // Instance nodes (#4454) on the declared side too, so a live instance
+        // meets its declared node and an unread one is painted alone.
+        const declaredIr = withInstanceNodes(
+          withLexiconEdges(buildGraphIr(declared.entities, projectPath), plugins, declared.entities),
+          declared.entities,
+        );
         ir =
           args.overlayAnchor === "live"
             ? overlayGraphs(ir, declaredIr, overlayOpts)
@@ -484,6 +499,11 @@ async function runGraphLive(
     }
   }
 
+  // The structured read report (#4452) goes on last, past the overlay, lens
+  // and detail passes that each build a fresh IR, so it is in every format's
+  // IR whatever those kept.
+  if (rootReads && Object.keys(rootReads).length > 0) ir = { ...ir, rootReads };
+
   return emitIr(ir, ctx, format);
 }
 
@@ -938,7 +958,9 @@ async function runGraphView(
 
   // Build the base IR, focus with a lens (declarable-level, most precise), then
   // apply the detail tier — so e.g. blast:<resource> works before any collapse.
-  let ir: GraphIR = buildGraphIr(result.entities, projectPath);
+  // Instance nodes (#4454) go on here, not in `buildGraphIr`, so search and
+  // the other readers of the base IR still count one node per block.
+  let ir: GraphIR = withInstanceNodes(buildGraphIr(result.entities, projectPath), result.entities);
 
   // The declared half of the epic's delta (#2355): this path predicts the
   // file, the live path predicts the account. Same helper, so the two shapes

package/src/cli/handlers/index-cloud.ts

@@ -0,0 +1,32 @@
+/**
+ * `chant index <substrate>` as a registry command (chant#4532).
+ *
+ * At the terminal, main() hands `index`'s raw argv straight to
+ * `runCloudIndex` (../../lifecycle/cloud-index.ts), because its flags are its
+ * own. This entry is for a caller that has already parsed a command line
+ * with core's parser (the ACP server asks the registry whether a word is a
+ * verb): it rebuilds the words that parser keeps (the substrate, `--json`,
+ * `--help`), and refuses when the parsed line carried an action flag core's
+ * parser knows, so the read-only rule holds on this path too.
+ */
+import type { CommandContext } from "../registry";
+
+export async function runIndexCommand(ctx: CommandContext): Promise<number> {
+  const { runCloudIndex } = await import("../../lifecycle/cloud-index");
+  const a = ctx.args;
+  const action = a.fix ? "--fix" : a.live ? "--live" : a.write ? "--write" : a.yes ? "--yes" : a.op ? "--op" : undefined;
+  const words = [...(a.positionals ?? (a.path && a.path !== "." ? [a.path] : []))];
+  if (words[0] === "diff") {
+    // #4533 — `chant index diff <a> [<b>]` reads two stored versions; it takes no action flag either.
+    if (action) {
+      process.stderr.write(`chant index diff: refused ${action}: the diff only reads the store\n`);
+      return 2;
+    }
+    const { runIndexDiff } = await import("./index-diff");
+    return runIndexDiff([...words.slice(1), ...(a.json ? ["--json"] : []), ...(a.help ? ["--help"] : [])]);
+  }
+  if (action) words.push(action);
+  if (a.json) words.push("--json");
+  if (a.help) words.push("--help");
+  return runCloudIndex(words);
+}

package/src/cli/handlers/index-diff.test.ts

@@ -0,0 +1,68 @@
+// #4533: `chant index diff <a> [<b>]` over a local store holding the two fixture versions of
+// ../../lifecycle/__fixtures__/index-diff/, read through --store local:<dir> as chant index writes it.
+import { copyFileSync, mkdirSync, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { runIndexDiff } from "./index-diff";
+
+const FIXTURES = join(import.meta.dirname, "..", "..", "lifecycle", "__fixtures__", "index-diff");
+const V1 = "20261026T120000Z-aaaaaaaaaaaa.json";
+const V2 = "20261026T130000Z-bbbbbbbbbbbb.json";
+const V3 = "20261026T140000Z-cccccccccccc.json";
+const SCOPE = "cloud/aws/000000000000/5c1f0e2a9b7d";
+const OTHER = "cloud/aws/000000000000/0123456789ab";
+
+/** A scratch dir (no chant project) with a local store: SCOPE holds V1 and V2, OTHER holds V1's document as V3. */
+function scratch() {
+  const cwd = mkdtempSync(join(tmpdir(), "chant-index-diff-"));
+  for (const [scope, file, as] of [[SCOPE, V1, V1], [SCOPE, V2, V2], [OTHER, V1, V3]] as const) {
+    const dir = join(cwd, "store", "index", ...scope.split("/"));
+    mkdirSync(dir, { recursive: true });
+    copyFileSync(join(FIXTURES, file), join(dir, as));
+  }
+  return cwd;
+}
+
+async function run(argv: string[]) {
+  const cwd = scratch();
+  let out = "";
+  let err = "";
+  const code = await runIndexDiff([...argv, "--store", "local:store"], {
+    cwd,
+    env: { XDG_DATA_HOME: join(cwd, "none") },
+    stdout: (s) => void (out += s),
+    stderr: (s) => void (err += s),
+  });
+  return { code, out, err };
+}
+
+describe("chant index diff", () => {
+  it("prints the diff of two named versions as JSON", async () => {
+    const r = await run([`${SCOPE}/${V1}`, V2, "--json"]);
+    expect(r.code).toBe(0);
+    expect(JSON.parse(r.out)).toMatchObject({ diff: "v1", scopeKey: SCOPE, from: { version: V1 }, to: { version: V2 }, counts: { properties: 1, added: 1, removed: 1 } });
+  });
+
+  it("a scope alone diffs its last two versions, as text", async () => {
+    const r = await run([SCOPE]);
+    expect(r.code).toBe(0);
+    expect(r.out).toContain(`Index diff: ${SCOPE}`);
+    expect(r.out).toContain('attrs.VersioningConfiguration.Status: "Suspended" -> "Enabled"');
+    expect(r.out).toContain("(not observed in the to read: read-failed, ListResources returned ThrottlingException)");
+  });
+
+  it("refuses two scopes by name", async () => {
+    const r = await run([`${SCOPE}/${V1}`, `${OTHER}/${V3}`, "--json"]);
+    expect(r.code).toBe(1);
+    expect(JSON.parse(r.out)).toMatchObject({ error: "index-scope-mismatch", fromScopeKey: SCOPE, toScopeKey: OTHER });
+    expect(r.err).toContain("different scopes");
+  });
+
+  it("usage errors: no version, an unknown flag", async () => {
+    expect((await run([])).code).toBe(2);
+    const r = await run([SCOPE, "--apply"]);
+    expect(r.code).toBe(2);
+    expect(r.err).toContain("unknown flag --apply");
+  });
+});

package/src/cli/handlers/index-diff.ts

@@ -0,0 +1,146 @@
+/**
+ * `chant index diff <a> [<b>] [--store <spec>] [--json]` (#4533): what
+ * changed between two versions of one index scope.
+ *
+ * `<a>` is `<scopeKey>/<version>`, or `<scopeKey>` alone. `<b>` is
+ * `<scopeKey>/<version>`, or a version name in `<a>`'s scope. With no `<b>`,
+ * the version before `<a>` is diffed against `<a>`, and a scope alone diffs
+ * its last two versions.
+ *
+ * Versions are read through #4519's store API, from the store `chant index`
+ * writes to (#4532's {@link planIndexStore}: `--store <spec>`, else the
+ * project's store, else the per-user one), so a git-ref, local or s3 store
+ * diffs the same way. Nothing is built, no lexicon is loaded and no cloud is
+ * queried. The computation is ../../lifecycle/index-diff.ts.
+ */
+import { homedir } from "node:os";
+import { chantUserStoreDir, IndexUsageError, planIndexStore, type StorePlan } from "../../lifecycle/cloud-index";
+import { diffIndexVersionRefs, IndexScopeMismatch, NotAnIndexVersion, parseIndexVersionRef, type IndexDiff } from "../../lifecycle/index-diff";
+import { createSnapshotStore, resolveSnapshotStore, snapshotStoreConfig, type SnapshotStore } from "../../lifecycle/snapshot-store";
+
+export const INDEX_DIFF_USAGE = `chant index diff <a> [<b>] [--store <spec>] [--json]
+
+What changed between two versions of one index scope: nodes added and
+removed, properties changed, edges added and removed. A node is removed only
+where the later read listed its type and location; elsewhere it is not
+observed. Two versions of different scopes are refused.
+
+  <a>              <scopeKey>/<version>, or <scopeKey> for its latest version
+  <b>              <scopeKey>/<version>, or a version name in <a>'s scope.
+                   Absent: the version before <a> against <a> (a scope alone:
+                   its last two versions)
+  --store <spec>   the store to read, as chant index takes it (local,
+                   local:<dir>, git-ref, git-ref:<ref>, s3,
+                   s3://<bucket>[/<prefix>]). Default: the project's store,
+                   else chant's per-user store
+  --json           the diff as JSON
+`;
+
+export interface IndexDiffRunOptions {
+  cwd?: string;
+  env?: Record<string, string | undefined>;
+  home?: string;
+  stdout?: (s: string) => void;
+  stderr?: (s: string) => void;
+  /** Open the planned store; tests pass a fake. */
+  openStore?: (plan: StorePlan, cwd: string) => Promise<Pick<SnapshotStore, "kind" | "listIndex" | "readIndexAt" | "fetch">>;
+}
+
+async function openReadStore(plan: StorePlan, cwd: string): Promise<SnapshotStore> {
+  switch (plan.kind) {
+    case "user":
+      return createSnapshotStore({ store: "local", dir: plan.dir }, { cwd });
+    case "project":
+      return resolveSnapshotStore({ cwd: plan.projectDir });
+    case "spec":
+      return createSnapshotStore(snapshotStoreConfig(plan.configured, plan.env), { cwd, env: plan.env });
+  }
+}
+
+const show = (v: unknown) => (v === undefined ? "(absent)" : JSON.stringify(v));
+
+/** The diff as text, one line per change. */
+export function renderIndexDiff(d: IndexDiff): string {
+  const lines: string[] = [];
+  lines.push(`Index diff: ${d.scopeKey}`);
+  lines.push(`  from ${d.from.version ?? d.from.digest.slice(0, 12)} (observed ${d.from.observedAt})`);
+  lines.push(`  to   ${d.to.version ?? d.to.digest.slice(0, 12)} (observed ${d.to.observedAt})`);
+  if (d.unchanged) {
+    lines.push("", "Same digest: nothing changed.");
+    return `${lines.join("\n")}\n`;
+  }
+  const c = d.counts;
+  lines.push(
+    "",
+    `${c.added} added, ${c.removed} removed, ${c.changed} changed (${c.properties} properties), ${c.notObserved} not observed; edges ${c.edgesAdded} added, ${c.edgesRemoved} removed, ${c.edgesNotObserved} not observed`,
+  );
+  for (const n of d.nodes.added) lines.push(`  + ${n.key}`);
+  for (const n of d.nodes.removed) lines.push(`  - ${n.key}`);
+  for (const n of d.nodes.changed) {
+    lines.push(`  ~ ${n.key}`);
+    for (const p of n.properties) lines.push(`      ${p.path}: ${show(p.before)} -> ${show(p.after)}`);
+  }
+  for (const n of d.nodes.notObserved) lines.push(`  ? ${n.key} (not observed in the ${n.side} read: ${n.verdict}${n.detail ? `, ${n.detail}` : ""})`);
+  for (const e of d.edges.added) lines.push(`  + edge ${e.from} -> ${e.to}${e.viaAttr ? ` via ${e.viaAttr}` : ""}`);
+  for (const e of d.edges.removed) lines.push(`  - edge ${e.from} -> ${e.to}${e.viaAttr ? ` via ${e.viaAttr}` : ""}`);
+  for (const e of d.edges.notObserved) lines.push(`  ? edge ${e.from} -> ${e.to} (${e.unobservedEnd} not observed in the ${e.side} read: ${e.verdict})`);
+  for (const v of d.coverage) lines.push(`  coverage ${v.listedType} @ ${v.location}: ${v.before ?? "(none)"} -> ${v.after ?? "(none)"}`);
+  return `${lines.join("\n")}\n`;
+}
+
+/** `chant index diff`'s argv (the words after `diff`). Exit 0 on a diff, 1 on a refusal, 2 on a usage error. */
+export async function runIndexDiff(argv: readonly string[], o: IndexDiffRunOptions = {}): Promise<number> {
+  const out = o.stdout ?? ((s: string) => void process.stdout.write(s));
+  const err = o.stderr ?? ((s: string) => void process.stderr.write(s));
+  const cwd = o.cwd ?? process.cwd();
+  const env = o.env ?? process.env;
+  if (argv.includes("-h") || argv.includes("--help")) {
+    out(INDEX_DIFF_USAGE);
+    return 0;
+  }
+  const refs: string[] = [];
+  let store: string | undefined;
+  let json = false;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "--json") json = true;
+    else if (a === "--store") {
+      store = argv[++i];
+      if (!store || store.startsWith("-")) {
+        err(`chant index diff: --store needs a store spec\n\n${INDEX_DIFF_USAGE}`);
+        return 2;
+      }
+    } else if (a.startsWith("--store=")) store = a.slice("--store=".length);
+    else if (a.startsWith("-")) {
+      err(`chant index diff: unknown flag ${a}\n\n${INDEX_DIFF_USAGE}`);
+      return 2;
+    } else refs.push(a);
+  }
+  if (refs.length < 1 || refs.length > 2) {
+    err(`chant index diff: name one or two index versions\n\n${INDEX_DIFF_USAGE}`);
+    return 2;
+  }
+
+  let d: IndexDiff;
+  try {
+    const from = parseIndexVersionRef(refs[0]!);
+    const to = refs[1] ? parseIndexVersionRef(refs[1], from.scopeKey) : undefined;
+    const plan = planIndexStore({ store, cwd, env, defaultStoreDir: () => chantUserStoreDir(env, o.home ?? homedir()), command: "chant index diff" });
+    const s = await (o.openStore ?? openReadStore)(plan, cwd);
+    await s.fetch();
+    d = await diffIndexVersionRefs(s, from, to);
+  } catch (e) {
+    if (e instanceof IndexUsageError) {
+      err(`${e.message}\n`);
+      return 2;
+    }
+    if (e instanceof IndexScopeMismatch || e instanceof NotAnIndexVersion) {
+      if (json) out(`${JSON.stringify({ error: e.code, message: e.message, ...(e instanceof IndexScopeMismatch ? { fromScopeKey: e.fromScopeKey, toScopeKey: e.toScopeKey } : {}) }, null, 2)}\n`);
+      err(`chant index diff: ${e.message}\n`);
+      return 1;
+    }
+    throw e;
+  }
+  out(json ? `${JSON.stringify(d, null, 2)}\n` : renderIndexDiff(d));
+  return 0;
+}

package/src/cli/handlers/ledger-root-member.test.ts

@@ -0,0 +1,161 @@
+/**
+ * #4482 (B4 of #4477): a local `chant run` of a TerraformApplyOp lands on the
+ * Op run ledger of the member that declares the Op, and `chant ledger runs`
+ * names the member whose directory holds the root it applied in
+ * `root_member`. That is the read behold's member run card takes for a
+ * choudoufu member applied from a chant one.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, beforeEach, describe, expect, it } from "vitest";
+import type { ActivityFn, ActivityProfile } from "../../op/activity-registry";
+import { OpRunFailure, runOpLocally } from "../../op/local-executor";
+import { withKnownOutputs } from "../../op/activity-failure";
+import type { OpConfig } from "../../op/types";
+import { clearMemberLedgerCache } from "../../lifecycle/member-ledger";
+import { readLedgerTable } from "../../lifecycle/ledger-read";
+import { queryLedgers } from "./query";
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+beforeEach(() => clearMemberLedgerCache());
+
+function git(args: string[], cwd: string): void {
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
+  if (r.status !== 0) throw new Error(`git ${args.join(" ")}: ${r.stderr}`);
+}
+
+function workspace(): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-root-member-")));
+  scratch.push(root);
+  const files: Record<string, string> = {
+    "chant.workspace.json": JSON.stringify({
+      name: "estate",
+      schema: 1,
+      members: [
+        { name: "app", dir: "app", kind: "chant" },
+        { name: "aws", dir: "estates/aws", kind: "choudoufu" },
+      ],
+    }),
+    "app/chant.config.json": JSON.stringify({ lexicons: ["terraform"], terraform: { roots: { aws: { dir: "../estates/aws" } } } }),
+    "estates/aws/main.tf": "",
+  };
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), text);
+  }
+  git(["init", "-q", "-b", "main"], root);
+  git(["config", "user.email", "test@chant.dev"], root);
+  git(["config", "user.name", "Test"], root);
+  git(["add", "-A"], root);
+  git(["commit", "-q", "-m", "init"], root);
+  return root;
+}
+
+const PROFILES: Record<string, ActivityProfile> = { single: { timeout: "5m", retry: { maximumAttempts: 1 } } };
+
+// The phases TerraformApplyOp builds with `gate: "never"`, with the Init step's #4482 outcome.
+const config: OpConfig = {
+  name: "aws-apply",
+  overview: "",
+  labels: { Apply: "true", TerraformRoot: "aws" },
+  phases: [
+    { name: "Init", steps: [{ kind: "activity", fn: "terraformInit", args: { root: "aws" }, outcomeAttribute: { name: "TerraformRootPath", from: "rootPath" } }] },
+    { name: "Plan", steps: [{ kind: "activity", fn: "terraformPlan", args: { root: "aws" } }] },
+    { name: "Apply", steps: [{ kind: "activity", fn: "terraformApply", args: { root: "aws" } }] },
+  ],
+};
+
+describe("chant ledger runs: root_member (#4482)", () => {
+  it("lists a local TerraformApplyOp run under the member whose root it applied", async () => {
+    const root = workspace();
+    const activities = new Map<string, ActivityFn>([
+      // terraformInit's own result: the root's directory relative to the workspace.
+      ["terraformInit", async () => ({ dir: join(root, "estates/aws"), rootPath: "estates/aws" })],
+      ["terraformPlan", async () => ({ changed: true })],
+      ["terraformApply", async () => ({ applied: true })],
+    ]);
+    const result = await runOpLocally(config, activities, PROFILES, undefined, { ledger: { cwd: join(root, "app") } });
+    expect(result.status).toBe("ok");
+
+    const doc = await readLedgerTable("runs", () => queryLedgers(root), { where: ["root_member=aws"] });
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.rows).toHaveLength(1);
+    expect(doc.rows[0]).toMatchObject({
+      member: "app",
+      op: "aws-apply",
+      status: "ok",
+      root_member: "aws",
+      labels: { Apply: "true", TerraformRoot: "aws" },
+      outcomes: { TerraformRootPath: "estates/aws" },
+    });
+  });
+
+  it("leaves root_member null for a run with no root path", async () => {
+    const root = workspace();
+    const plain: OpConfig = { name: "plain", overview: "", phases: [{ name: "Only", steps: [{ kind: "activity", fn: "noop" }] }] };
+    await runOpLocally(plain, new Map<string, ActivityFn>([["noop", async () => undefined]]), PROFILES, undefined, { ledger: { cwd: join(root, "app") } });
+    const doc = await readLedgerTable("runs", () => queryLedgers(root), {});
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.rows.map((r) => [r.op, r.root_member])).toEqual([["plain", null]]);
+  });
+
+  it("names root_member on a failed run when Init knew the root before it failed (#4512)", async () => {
+    const root = workspace();
+    const activities = new Map<string, ActivityFn>([
+      // What terraformInit throws when `terraform init` itself fails: the root resolved first.
+      ["terraformInit", async () => {
+        throw withKnownOutputs(new Error("terraform init: backend unreachable"), { dir: join(root, "estates/aws"), rootPath: "estates/aws" });
+      }],
+      ["terraformPlan", async () => ({ changed: true })],
+      ["terraformApply", async () => ({ applied: true })],
+    ]);
+    const failure = await runOpLocally(config, activities, PROFILES, undefined, { ledger: { cwd: join(root, "app") } }).then(
+      () => undefined,
+      (err: unknown) => err,
+    );
+    expect(failure).toBeInstanceOf(OpRunFailure);
+    expect((failure as OpRunFailure).result.status).toBe("fail");
+
+    const doc = await readLedgerTable("runs", () => queryLedgers(root), { where: ["root_member=aws"] });
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.rows).toHaveLength(1);
+    expect(doc.rows[0]).toMatchObject({
+      member: "app",
+      op: "aws-apply",
+      status: "fail",
+      root_member: "aws",
+      labels: { Apply: "true", TerraformRoot: "aws" },
+      outcomes: { TerraformRootPath: "estates/aws" },
+    });
+  });
+
+  it("leaves root_member null, meaning unknown, when Init fails before it knows the root, with the declared root key in labels (#4508)", async () => {
+    const root = workspace();
+    const activities = new Map<string, ActivityFn>([
+      // Failing before the root resolved (a chant.config.ts that throws), so no known outputs.
+      ["terraformInit", async () => {
+        throw new Error("chant.config.ts: evaluation failed");
+      }],
+      ["terraformPlan", async () => ({ changed: true })],
+      ["terraformApply", async () => ({ applied: true })],
+    ]);
+    // A failed run throws OpRunFailure, carrying the result; the ledger row is written first.
+    const failure = await runOpLocally(config, activities, PROFILES, undefined, { ledger: { cwd: join(root, "app") } }).then(
+      () => undefined,
+      (err: unknown) => err,
+    );
+    expect(failure).toBeInstanceOf(OpRunFailure);
+    expect((failure as OpRunFailure).result.status).not.toBe("ok");
+
+    const doc = await readLedgerTable("runs", () => queryLedgers(root), {});
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.rows).toHaveLength(1);
+    expect(doc.rows[0]).toMatchObject({ member: "app", op: "aws-apply", root_member: null, labels: { Apply: "true", TerraformRoot: "aws" } });
+    expect(doc.rows[0].outcomes).not.toHaveProperty("TerraformRootPath");
+  });
+});

package/src/cli/handlers/lifecycle-drift.ts

@@ -0,0 +1,68 @@
+/**
+ * `chant lifecycle drift [--member <name>] [--read <read>] [--resource <addr>]`
+ * (behold#995): the project's drift, as each lexicon's own engine reads it,
+ * printed as the drift-record NDJSON stream (`../../drift-record.ts`).
+ *
+ * This is the member half of `chant workspace drift`. A `terraform` or
+ * `choudoufu` member has no chant config of its own, so the workspace writes
+ * it a reader project (`../../workspace/kind-readers.ts`) and runs this
+ * command there, under the member's own toolchain, the way `workspace graph`
+ * runs `chant graph`. Every lexicon with a `readDrift` is asked; the lines
+ * are printed in the order they came, one JSON object per line. chant core
+ * never imports a lexicon to read drift.
+ *
+ * `--member` names the workspace member the records are for; it defaults to
+ * the project directory's name. A lexicon that refuses the read (a read its
+ * engine has not got, or one resource on an engine that cannot read one on
+ * its own) makes the command print `{"refused": {code, message}}` as its
+ * only stdout line and exit 3, so the workspace command can name the
+ * refusal. No lexicon with a drift read is the refusal `no-drift-read`.
+ */
+
+import { basename, resolve } from "node:path";
+import { loadChantConfig } from "../../config";
+import { DRIFT_READS, encodeDriftLine, type DriftLine, type DriftRead, type ReadDriftRefusalCode } from "../../drift-record";
+import { formatError } from "../format";
+import type { CommandContext } from "../registry";
+
+/** The exit status of a refused read. */
+export const DRIFT_REFUSED_EXIT = 3;
+
+const USAGE = "chant lifecycle drift [--member <name>] [--read <state|plan|refresh|live-read|ownership>] [--resource <addr>]";
+
+function refuse(code: ReadDriftRefusalCode, message: string): number {
+  console.log(JSON.stringify({ refused: { code, message } }));
+  return DRIFT_REFUSED_EXIT;
+}
+
+export async function runLifecycleDrift(ctx: CommandContext): Promise<number> {
+  const { args, plugins } = ctx;
+  const read = args.driftRead;
+  if (read !== undefined && !(DRIFT_READS as readonly string[]).includes(read)) {
+    console.error(formatError({ message: `--read ${read} is not a drift read; the reads are ${DRIFT_READS.join(", ")}`, hint: USAGE }));
+    return 1;
+  }
+  const projectRoot = resolve(".");
+  const { config } = await loadChantConfig(projectRoot);
+  const member = args.members?.[0] ?? basename(projectRoot);
+  const readers = plugins.filter((p) => typeof p.readDrift === "function");
+  if (readers.length === 0) {
+    return refuse("no-drift-read", `no lexicon this project declares (${plugins.map((p) => p.name).join(", ") || "none"}) has a drift read`);
+  }
+  const observedAt = new Date().toISOString();
+  const lines: DriftLine[] = [];
+  for (const plugin of readers) {
+    const answer = await plugin.readDrift!({
+      member,
+      projectRoot,
+      config: config as Record<string, unknown>,
+      ...(read !== undefined ? { read: read as DriftRead } : {}),
+      ...(args.resource !== undefined ? { resource: args.resource } : {}),
+      observedAt,
+    });
+    if ("refused" in answer) return refuse(answer.refused.code, `${plugin.name}: ${answer.refused.message}`);
+    lines.push(...answer.lines);
+  }
+  for (const line of lines) process.stdout.write(encodeDriftLine(line));
+  return 0;
+}

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

@@ -45,6 +45,27 @@ vi.mock("../../lifecycle/git", () => ({
   readBlobFromPath: (...args: unknown[]) => readBlobFromPathMock(...args),
   writeBlobToPath: (...args: unknown[]) => writeBlobToPathMock(...args),
 }));
+// Snapshots are read through the index store (#4519); this one hands each read to the mocks 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,
+    list: async (opts) => ((await listSnapshotsMock(opts)) as Array<{ commit: string; date: string; message: string }>).map((e) => ({ version: e.commit, date: e.date, message: e.message })),
+    fetch: async () => {
+      await fetchLifecycleMock();
+    },
+  });
+  return {
+    resolveSnapshotStore: async () => store,
+    readEnvironmentSnapshotsFrom: async (_store: unknown, environment: string) => readEnvironmentSnapshotsMock(environment),
+  };
+});
+// The baseline is a file under .chant/ (#4519); the write is mocked so a test never writes into the checkout.
+const saveObservationBaselineMock = vi.fn();
+vi.mock("../../lifecycle/observation-baseline", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../../lifecycle/observation-baseline")>()),
+  saveObservationBaseline: (...args: unknown[]) => saveObservationBaselineMock(...args),
+}));
 vi.mock("../../lifecycle/snapshot", () => ({
   takeSnapshot: (...args: unknown[]) => takeSnapshotMock(...args),
 }));
@@ -138,6 +159,8 @@ describe("runLifecycleDiff --live", () => {
     readBlobFromPathMock.mockResolvedValue(null); // no accepted baseline recorded
     writeBlobToPathMock.mockReset();
     writeBlobToPathMock.mockResolvedValue("sha");
+    saveObservationBaselineMock.mockReset();
+    saveObservationBaselineMock.mockResolvedValue({ where: ".chant/observation-baseline/prod.json", published: "file" });
     pushLifecycleMock.mockReset();
     pushLifecycleMock.mockResolvedValue(true);
   });
@@ -715,27 +738,26 @@ describe("runLifecycleDiff --live", () => {
       expect(output).toContain("could not be observed — that part of the estate is unknown, not clean");
     });
 
-    test("--update-baseline writes what was reported and pushes it", async () => {
+    test("--update-baseline writes what was reported to the baseline file", async () => {
       await runDiff([withDeep()], { updateBaseline: true });
-      expect(writeBlobToPathMock).toHaveBeenCalledTimes(1);
-      const [environment, filename, content] = writeBlobToPathMock.mock.calls[0] as [string, string, string];
-      expect(environment).toBe("prod");
-      expect(filename).toBe("observation-baseline.json");
-      const written = JSON.parse(content) as {
-        lexicons: { aws: { bucket: { accepted: Array<{ path: string; value: unknown }> } } };
-      };
+      expect(saveObservationBaselineMock).toHaveBeenCalledTimes(1);
+      const [written] = saveObservationBaselineMock.mock.calls[0] as [
+        { environment: string; lexicons: { aws: { bucket: { accepted: Array<{ path: string; value: unknown }> } } } },
+      ];
+      expect(written.environment).toBe("prod");
       // Only drift is accepted. A held field needs no acceptance: it was never
       // reported as a deviation to begin with (#2160).
       expect(written.lexicons.aws.bucket.accepted.map((a) => a.path)).toEqual(["Versioning"]);
-      expect(pushLifecycleMock).toHaveBeenCalled();
-      expect(stderrBuf.join("\n")).toContain("accepted 1 deviation(s)");
+      // Never on the orphan branch again (#4519).
+      expect(writeBlobToPathMock).not.toHaveBeenCalled();
+      expect(stderrBuf.join("\n")).toContain("accepted 1 deviation(s) into .chant/observation-baseline/prod.json");
     });
 
     test("--update-baseline with nothing reported writes nothing", async () => {
       await runDiff([
         withDeep({ observeResourcesDeep: staticDeepObservation({}) }),
       ], { updateBaseline: true });
-      expect(writeBlobToPathMock).not.toHaveBeenCalled();
+      expect(saveObservationBaselineMock).not.toHaveBeenCalled();
       expect(stderrBuf.join("\n")).toContain("nothing to accept");
     });
   });