@intentius/chant-lexicon-terraform 0.124.45 → 0.124.46

package/src/capabilities.test.ts

@@ -0,0 +1,264 @@
+/**
+ * The capability catalog over Terraform's AWS provider (#4375).
+ *
+ * `__fixtures__/capabilities/` holds three roots:
+ *
+ *   ledger    the estate chant#4361 measured the rule language on, whose
+ *             answers were worked out by hand: identity reach 13 pairs,
+ *             exfiltration 3, blast radius 15 from three starts.
+ *   catalog   a case that holds and one that doesn't for each capability the
+ *             ledger leaves out (default VPC, unused things, public buckets,
+ *             SecureString, encryption, an explicit Deny).
+ *   findings  the -findings layer of choudoufu's terralith-gen, the estate
+ *             behold#912's step 6 asks about.
+ */
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { buildGraphIr, type GraphIR } from "@intentius/chant/graph-ir";
+import { CapabilityEngine } from "@intentius/chant/capabilities/matcher";
+import { buildView, displayName } from "@intentius/chant/capabilities/view";
+import { resolvePacks, shippedRules } from "@intentius/chant/capabilities/catalog";
+import { runSearch } from "@intentius/chant/cli/handlers/search";
+import { renderTerraformRoots } from "./hcl/roots";
+import { terraformPlugin } from "./plugin";
+import { terraformCapabilityPack } from "./capabilities/adapter";
+
+const FIXTURE = join(dirname(fileURLToPath(import.meta.url)), "__fixtures__", "capabilities");
+
+let engine: CapabilityEngine;
+let ir: GraphIR;
+
+beforeAll(async () => {
+  const rendered = await renderTerraformRoots({
+    projectRoot: FIXTURE,
+    roots: { ledger: { dir: "./ledger" }, catalog: { dir: "./catalog" }, findings: { dir: "./findings" } },
+  });
+  expect(rendered.warnings).toEqual([]);
+  ir = buildGraphIr(rendered.entities);
+  engine = new CapabilityEngine(buildView(ir, resolvePacks([terraformCapabilityPack])), shippedRules().rules);
+});
+
+const set = (name: string, args: unknown[] = [], root?: string) =>
+  [...engine.set(name, engine.bind(name, args as never)).keys()].filter((id) => !root || id.startsWith(`${root}/`)).map(displayName).sort();
+const pairs = (name: string, args: unknown[] = [], root = "ledger") =>
+  [...engine.relation(name, engine.bind(name, args as never)).out]
+    .filter(([a]) => a.startsWith(`${root}/`))
+    .flatMap(([a, m]) => [...m.keys()].map((b) => `${displayName(a)} ${displayName(b)}`))
+    .sort();
+
+describe("the ledger's three hand-checked answers (chant#4361)", () => {
+  it("identity reach: 13 (role, resource) pairs", () => {
+    expect(pairs("reaches")).toEqual([
+      "aws_iam_role.audit aws_dynamodb_table.orders",
+      "aws_iam_role.batch aws_dynamodb_table.orders",
+      "aws_iam_role.batch aws_iam_role.audit",
+      "aws_iam_role.deploy aws_s3_bucket.customer_data",
+      "aws_iam_role.deploy aws_secretsmanager_secret.db",
+      "aws_iam_role.reporter aws_s3_bucket.customer_data",
+      "aws_iam_role.web aws_iam_role.deploy",
+      "aws_iam_role.web aws_s3_bucket.assets",
+      "aws_iam_role.web aws_s3_bucket.customer_data",
+      "aws_iam_role.web aws_secretsmanager_secret.db",
+      "aws_iam_role.worker aws_dynamodb_table.orders",
+      "aws_iam_role.worker aws_s3_bucket.assets",
+      "aws_iam_role.worker aws_secretsmanager_secret.db",
+    ]);
+  });
+
+  it("exfiltration: 3 (compute, store) pairs", () => {
+    expect(pairs("exfiltrates")).toEqual([
+      "aws_instance.web aws_s3_bucket.customer_data",
+      "aws_instance.web aws_secretsmanager_secret.db",
+      "aws_lambda_function.reporter aws_s3_bucket.customer_data",
+    ]);
+  });
+
+  it("blast radius: 15 members from webServer, reporter and batch", () => {
+    const from = (start: string) => pairs("blast").filter((p) => p.startsWith(`${start} `)).map((p) => p.split(" ")[1]);
+    expect(from("aws_instance.web")).toEqual([
+      "aws_db_instance.customers",
+      "aws_dynamodb_table.orders",
+      "aws_iam_role.deploy",
+      "aws_iam_role.web",
+      "aws_iam_role.worker",
+      "aws_instance.admin_box",
+      "aws_instance.worker",
+      "aws_s3_bucket.assets",
+      "aws_s3_bucket.customer_data",
+      "aws_secretsmanager_secret.db",
+    ]);
+    expect(from("aws_lambda_function.reporter")).toEqual(["aws_iam_role.reporter", "aws_s3_bucket.customer_data"]);
+    expect(from("aws_lambda_function.batch")).toEqual(["aws_dynamodb_table.orders", "aws_iam_role.audit", "aws_iam_role.batch"]);
+  });
+
+  it("the exfiltration path includes the trust statement that makes the assume-role hop real", () => {
+    const ev = engine.relation("exfiltrates").out.get("ledger/aws_instance.web")!.get("ledger/aws_s3_bucket.customer_data")!;
+    const visited = ev.hops.flatMap((h) => [h.from, h.to]).map(displayName);
+    expect(visited).toContain("aws_iam_role.deploy#assume_role_policy[0].Statement[0]");
+    expect(visited.at(-1)).toBe("aws_s3_bucket.customer_data");
+    expect(ev.because.map((b) => b.capability)).toEqual(["internet-reachable", "holds-secret"]);
+    expect(ev.because[0].evidence.because.map((b) => b.capability)).toEqual(["internet-facing", "open-ingress"]);
+  });
+});
+
+describe("each capability on a fixture", () => {
+  it("internet-facing: a subnet routed to an internet gateway, by aws_route or by an inline route", () => {
+    expect(set("internet-facing", [], "ledger")).toEqual(["aws_instance.admin_box", "aws_instance.web"]);
+    expect(set("internet-facing", [], "findings")).toEqual(["aws_instance.bastion"]);
+  });
+
+  it("open-ingress: a world-open rule reached through a launch template, filtered by port and protocol", () => {
+    expect(set("open-ingress", [], "ledger")).toEqual(["aws_instance.web"]);
+    expect(set("open-ingress", [22], "ledger")).toEqual(["aws_instance.web"]);
+    expect(set("open-ingress", [8080], "ledger")).toEqual([]);
+    expect(set("open-ingress", [22, "udp"], "ledger")).toEqual([]);
+  });
+
+  it("internet-reachable: facing and open, or a function URL with no auth", () => {
+    expect(set("internet-reachable", [], "ledger")).toEqual(["aws_instance.web", "aws_lambda_function.reporter"]);
+    expect(set("internet-reachable", [22], "findings")).toEqual(["aws_instance.bastion"]);
+  });
+
+  it("attached-to-nothing: an unused group, an empty subnet, a policy no role holds", () => {
+    expect(set("attached-to-nothing", [], "catalog")).toEqual(["aws_iam_policy.orphan", "aws_security_group.unused", "aws_subnet.empty"]);
+  });
+
+  it("in-default-vpc: an instance in a subnet of aws_default_vpc, and the subnet", () => {
+    expect(set("in-default-vpc", [], "catalog")).toEqual(["aws_instance.legacy", "aws_subnet.legacy"]);
+  });
+
+  it("network: host to host through group-to-group ingress", () => {
+    expect(pairs("network")).toEqual([
+      "aws_instance.admin_box aws_db_instance.customers",
+      "aws_instance.web aws_instance.admin_box",
+      "aws_instance.web aws_instance.worker",
+      "aws_instance.worker aws_db_instance.customers",
+    ]);
+  });
+
+  it("stores-data and holds-secret: restricted by tag (through a local), a secret, a SecureString", () => {
+    expect(set("stores-data", [], "ledger")).toEqual([
+      "aws_db_instance.customers",
+      "aws_dynamodb_table.orders",
+      "aws_s3_bucket.assets",
+      "aws_s3_bucket.customer_data",
+      "aws_secretsmanager_secret.db",
+    ]);
+    expect(set("holds-secret", [], "ledger")).toEqual(["aws_db_instance.customers", "aws_s3_bucket.customer_data", "aws_secretsmanager_secret.db"]);
+    expect(set("holds-secret", [], "catalog")).toEqual(["aws_ssm_parameter.token"]);
+  });
+
+  it("encrypted-at-rest: by attribute for a database or file system, always for a bucket", () => {
+    const enc = set("encrypted-at-rest", [], "catalog");
+    expect(enc).toEqual(["aws_efs_file_system.shared", "aws_s3_bucket.blocked", "aws_s3_bucket.open"]);
+    expect(enc).not.toContain("aws_db_instance.plain");
+  });
+
+  it("publicly-readable: principal * with no public-access block in the way", () => {
+    expect(set("publicly-readable", [], "catalog")).toEqual(["aws_s3_bucket.open"]);
+  });
+
+  it("runs-as: through an instance profile, a launch template's profile, a Lambda role", () => {
+    expect(pairs("runs-as")).toEqual([
+      "aws_instance.admin_box aws_iam_role.worker",
+      "aws_instance.web aws_iam_role.web",
+      "aws_instance.worker aws_iam_role.worker",
+      "aws_lambda_function.batch aws_iam_role.batch",
+      "aws_lambda_function.reporter aws_iam_role.reporter",
+    ]);
+    expect(pairs("runs-as", [], "findings")).toEqual(["aws_instance.bastion aws_iam_role.app_data"]);
+  });
+
+  it("can-assume: by reference with a matching trust, and by ARN string naming a declared role", () => {
+    expect(pairs("can-assume")).toEqual(["aws_iam_role.batch aws_iam_role.audit", "aws_iam_role.web aws_iam_role.deploy"]);
+  });
+
+  it("grants: an action argument narrows it, and an explicit Deny on the same pair cancels it", () => {
+    expect(pairs("grants", ["sts:AssumeRole"])).toEqual(["aws_iam_role.batch aws_iam_role.audit", "aws_iam_role.web aws_iam_role.deploy"]);
+    expect(pairs("grants", ["s3:GetObject"], "catalog")).toEqual(["aws_iam_role.denied aws_s3_bucket.blocked"]);
+    expect(pairs("grants", [], "catalog")).toEqual(["aws_iam_role.denied aws_s3_bucket.blocked"]);
+  });
+});
+
+describe("behold#912 step 6: what the findings layer's role can reach", () => {
+  it("reaches the DynamoDB table and no other store, and leaves the wildcard roles to the not-evaluated note", () => {
+    const reached = [...engine.relation("reaches").out.get("findings/aws_iam_role.app_data")!.keys()].map(displayName);
+    expect(reached).toEqual(["aws_dynamodb_table.sessions"]);
+    expect(engine.relation("reaches").out.get("findings/aws_iam_role.team_0002_role")).toBeUndefined();
+  });
+});
+
+describe("chant search with capabilities", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  async function search(args: Record<string, unknown>): Promise<{ exit: number; out: string[]; err: string[] }> {
+    const out: string[] = [];
+    const err: string[] = [];
+    vi.spyOn(console, "log").mockImplementation((line: unknown) => void out.push(String(line)));
+    vi.spyOn(console, "error").mockImplementation((line: unknown) => void err.push(String(line)));
+    const cwd = process.cwd();
+    process.chdir(FIXTURE);
+    try {
+      const exit = await runSearch({ args: args as never, plugins: [terraformPlugin], serializers: [] });
+      return { exit, out, err };
+    } finally {
+      process.chdir(cwd);
+    }
+  }
+
+  it("step 6: the store the role reaches, with what the rule did not evaluate", async () => {
+    const { exit, out } = await search({ path: "cap:stores-data <-[cap=reaches]aws_iam_role.app_data" });
+    expect(exit).toBe(0);
+    expect(out[0]).toBe("findings/aws_dynamodb_table.sessions  aws_dynamodb_table");
+    expect(out[1]).toBe("— declared only · no observation · physical ids unavailable · stores-data, reaches derived from declared references");
+    expect(out[2]).toMatch(/^— reaches does not evaluate: IAM Condition keys; Resource "\*" \(2 statements here\);/);
+  });
+
+  it("--explain prints each match's path in #4359's hop format, and the sets it relied on", async () => {
+    const { out } = await search({ path: "kind:aws_instance cap:internet-reachable(22)", explain: true });
+    const lines = out.filter((l) => l.includes("bastion"));
+    expect(lines).toContain(
+      "  path findings/aws_instance.bastion cap:internet-reachable(22): (the node itself)",
+    );
+    expect(lines).toContain(
+      "    internet-facing findings/aws_instance.bastion: findings/aws_instance.bastion.subnet_id -> findings/aws_subnet.public.id; findings/aws_subnet.public.id <- findings/aws_route_table_association.public.subnet_id; findings/aws_route_table_association.public.route_table_id -> findings/aws_route_table.public.id; findings/aws_route_table.public.route -> findings/aws_route_table.public#route[0]; findings/aws_route_table.public#route[0].gateway_id -> findings/aws_internet_gateway.main.id",
+    );
+    expect(lines).toContain(
+      "    open-ingress findings/aws_instance.bastion: findings/aws_instance.bastion.launch_template -> findings/aws_launch_template.bastion.id; findings/aws_launch_template.bastion.vpc_security_group_ids -> findings/aws_security_group.bastion.id; findings/aws_security_group.bastion.id <- findings/aws_vpc_security_group_ingress_rule.bastion_ssh.security_group_id",
+    );
+  });
+
+  it("--explain prints an edge capability's path through the policy statement", async () => {
+    const { out } = await search({ path: "aws_iam_role.app_data ->[cap=reaches]cap:stores-data", explain: true });
+    expect(out).toContain(
+      "  path findings/aws_iam_role.app_data ->[cap=reaches]cap:stores-data: findings/aws_iam_role.app_data.name <- findings/aws_iam_role_policy_attachment.app_data.role; findings/aws_iam_role_policy_attachment.app_data.policy_arn -> findings/aws_iam_policy.app_data.arn; findings/aws_iam_policy.app_data.policy -> findings/aws_iam_policy.app_data#policy[0].Statement[0]; findings/aws_iam_policy.app_data#policy[0].Statement[0].Resource[0] -> findings/aws_dynamodb_table.sessions.arn",
+    );
+  });
+
+  it("--json carries the path, each hop's capability edge, and the not-evaluated list", async () => {
+    const { out } = await search({ path: "cap:exfiltrates", json: true });
+    const doc = JSON.parse(out[0]);
+    expect(doc.matches.map((m: { id: string }) => m.id)).toEqual(["ledger/aws_instance.web", "ledger/aws_lambda_function.reporter"]);
+    const path = doc.matches[0].paths[0];
+    expect(path.term).toBe("cap:exfiltrates");
+    expect(path.hops[0]).toEqual({ from: "ledger/aws_instance.web", fromAttr: "iam_instance_profile", to: "ledger/aws_iam_instance_profile.web", toAttr: "name", edge: "profile" });
+    expect(path.because.map((b: { capability: string }) => b.capability)).toContain("internet-facing");
+    expect(doc.capabilities).toEqual([
+      expect.objectContaining({ name: "exfiltrates", source: "declared", notEvaluated: expect.arrayContaining(["IAM Condition keys"]) }),
+    ]);
+  });
+
+  it("refuses an unknown capability, a set used as an edge, and the wrong arguments", async () => {
+    let r = await search({ path: "cap:reachable" });
+    expect(r.exit).toBe(1);
+    expect(r.err.join("\n")).toMatch(/no capability "reachable"/);
+    r = await search({ path: "->[cap=stores-data]kind:aws_s3_bucket" });
+    expect(r.exit).toBe(1);
+    expect(r.err.join("\n")).toMatch(/"stores-data" is a set, not an edge/);
+    r = await search({ path: "cap:open-ingress(22,tcp,3)" });
+    expect(r.exit).toBe(1);
+    expect(r.err.join("\n")).toMatch(/open-ingress takes at most 2 \(port, proto\)/);
+  });
+});

package/src/config.ts

@@ -48,6 +48,14 @@ export type TerraformDeleteMode = z.infer<typeof terraformDeleteModeSchema>;
  * strict, and a root entry is exactly where a typo (`varfiles`) would
  * otherwise land silently.
  */
+/**
+ * How deep a root is observed (#4358): `"state"` reads state, `"plan"`
+ * reads a saved plan. See {@link TerraformRootConfig.observe}.
+ */
+export const terraformObserveDepthSchema = z.enum(["state", "plan"]);
+
+export type TerraformObserveDepth = z.infer<typeof terraformObserveDepthSchema>;
+
 export const terraformRootSchema = z.strictObject({
   /** Root module directory, relative to the project root (where `chant.config.*` lives). */
   dir: z.string(),
@@ -85,6 +93,22 @@ export const terraformRootSchema = z.strictObject({
   estate: z.string().optional(),
   /** This root's declared delete mode. See {@link terraformDeleteModeSchema}. */
   delete: terraformDeleteModeSchema.optional(),
+  /**
+   * How deep `describeResources` reads this root (#4358). `"state"`, the
+   * default, is `terraform show -json` over state: what the last apply
+   * recorded. `"plan"` is a saved plan, `plan -lock=false -out=<tmp>` then
+   * `show -json`: what the next apply would do, with replace reasons,
+   * values unknown until apply and drift. It needs provider credentials and
+   * an initialised root, and falls back to the state read, then to declared
+   * only, saying which read answered. A live choudoufu root keeps its
+   * `live-plan -json` read for ownership at either depth; at `"plan"` the
+   * plan read runs beside it and its attributes go on the blocks `live-plan`
+   * bound (#4371).
+   *
+   * The `CHANT_TERRAFORM_OBSERVE` environment variable overrides it for
+   * every root, for one run.
+   */
+  observe: terraformObserveDepthSchema.optional(),
 });
 
 export const terraformConfigSchema = z.strictObject({
@@ -119,6 +143,8 @@ export const terraformConfigSchema = z.strictObject({
    * project does not own.
    */
   moduleRoot: z.string().optional(),
+  /** The default {@link TerraformRootConfig.observe} for every root that sets none (#4358). */
+  observe: terraformObserveDepthSchema.optional(),
   /** Named root modules. The name is the entity-key prefix, so keep it stable. */
   roots: z.record(z.string(), terraformRootSchema),
 });

package/src/describe-resources.live-plan.test.ts

@@ -0,0 +1,302 @@
+/**
+ * The plan depth on a live choudoufu root (#4371): `live-plan -json` for
+ * ownership, the plan read for the attributes, merged per block.
+ *
+ * The declared side is `src/__fixtures__/live-estate/`, rendered as
+ * `buildRoots()` renders it. The read side is
+ * `src/__fixtures__/live-plan-depth/`: a `live-plan -json` document and two
+ * `show -json <planfile>` documents recorded from that configuration by the
+ * choudoufu v0.30.0 release binary against the pinned floci emulator, with
+ * drift made out of band (`live-plan-depth/README.md` is the log).
+ *
+ * Nothing here runs choudoufu: the activities are injected. The real binary
+ * is `live-plan-depth.acceptance.test.ts`.
+ */
+
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { normalizeObservation } from "@intentius/chant/observation";
+import type { Declarable } from "@intentius/chant/declarable";
+import { buildLiveGraphIr } from "@intentius/chant/graph-ir";
+import { __searchInternals } from "@intentius/chant/cli/handlers/search";
+import { describeResources, livePlanDocumentFile, TERRAFORM_LIVE_PLAN_DIR_ENV, type TerraformReadDeps } from "./describe-resources";
+import { TerraformPlanReadError } from "./op/activities/terraform";
+import { PLAN_ATTRIBUTE_NAMES, SENSITIVE_VALUE } from "./plan-observation";
+import { renderTerraformRoots } from "./hcl/roots";
+
+const fixtures = join(dirname(fileURLToPath(import.meta.url)), "__fixtures__");
+const RECORDED = join(fixtures, "live-plan-depth");
+const ROOT_DIR = join(fixtures, "live-estate");
+const LIVE_PLAN: unknown = JSON.parse(readFileSync(join(RECORDED, "live-plan.json"), "utf-8"));
+const PLAN: unknown = JSON.parse(readFileSync(join(RECORDED, "show-plan.json"), "utf-8"));
+const PLAN_SENSITIVE: unknown = JSON.parse(readFileSync(join(RECORDED, "show-plan-sensitive.json"), "utf-8"));
+const ESTATE = "stateless-e2e-block";
+
+type Entities = Map<string, { entityType: string; props: Record<string, unknown> }>;
+
+/** The fixture root rendered under `binary`: `"choudoufu"` makes it live, `"terraform"` stock. */
+async function declaredEntities(binary: "choudoufu" | "terraform"): Promise<Entities> {
+  const { entities } = await renderTerraformRoots({
+    projectRoot: fixtures,
+    roots: { estate: { dir: "./live-estate" } },
+    binary,
+  });
+  const out: Entities = new Map();
+  for (const [key, entity] of entities) {
+    out.set(key, { entityType: entity.entityType, props: (entity as Declarable & { props: Record<string, unknown> }).props });
+  }
+  return out;
+}
+
+async function options(binary: "choudoufu" | "terraform" = "choudoufu", depth: "plan" | "state" = "plan") {
+  const entities = await declaredEntities(binary);
+  return { environment: "prod", buildOutput: "", entityNames: [...entities.keys()].sort(), entities, depth };
+}
+
+const never = ((args: { root: string }) => {
+  throw new Error(`unexpected activity for root "${args.root}"`);
+}) as never;
+
+const COMMAND = "choudoufu plan -input=false -lock=false -out=/tmp/chant-terraform-plan-x/plan.tfplan";
+
+function deps(overrides?: Partial<TerraformReadDeps>, plan: unknown = PLAN): TerraformReadDeps {
+  return {
+    init: never,
+    show: never,
+    liveLs: never,
+    livePlan: (async () => ({ json: LIVE_PLAN, dir: ROOT_DIR, estate: ESTATE })) as unknown as TerraformReadDeps["livePlan"],
+    planRead: (async () => ({ json: plan, dir: ROOT_DIR, planDir: "/tmp/chant-terraform-plan-x", command: COMMAND })) as TerraformReadDeps["planRead"],
+    ...overrides,
+  };
+}
+
+const planOnly = (attributes: Record<string, unknown> | undefined): Record<string, unknown> =>
+  Object.fromEntries(Object.entries(attributes ?? {}).filter(([k]) => k.startsWith("plan")));
+
+const BOUND = [
+  "estate/aws_cloudwatch_log_group.app",
+  "estate/aws_eip.pool",
+  "estate/aws_security_group.main",
+  "estate/aws_subnet.app",
+  "estate/aws_vpc.main",
+];
+
+describe("a live root at the plan depth carries the plan's attributes on bound blocks (#4371)", () => {
+  it("drift made out of band is the planned update, live value before, declared value after", async () => {
+    const result = normalizeObservation(await describeResources(await options(), deps()));
+    const attrs = (name: string) => result.resources[`estate/${name}`]!.attributes as Record<string, unknown>;
+
+    expect(attrs("aws_cloudwatch_log_group.app")).toMatchObject({
+      planAction: "update",
+      planChanges: [{ path: "retention_in_days", before: 3, after: 1 }],
+    });
+    expect(attrs("aws_vpc.main").planAction).toBe("update");
+    expect(attrs("aws_vpc.main").planChanges).toEqual(
+      expect.arrayContaining([
+        { path: "tags.drifted", before: "yes", after: null },
+        { path: "tags_all.drifted", before: "yes", after: null },
+      ]),
+    );
+    expect(attrs("aws_eip.pool")).toMatchObject({
+      planAction: "no-op",
+      planActions: { "aws_eip.pool[0]": ["no-op"], "aws_eip.pool[1]": ["no-op"] },
+    });
+    // choudoufu rebuilds prior state from the account, so there is no
+    // recorded state for `resource_drift` to compare against.
+    for (const name of BOUND) expect(result.resources[name]!.attributes).not.toHaveProperty("planDrift");
+  });
+
+  it("ownership still comes from live-plan's markers, unchanged by the plan read", async () => {
+    const atPlan = normalizeObservation(await describeResources(await options(), deps()));
+    const atDefault = normalizeObservation(await describeResources(await options("choudoufu", "state"), deps({ planRead: never })));
+    expect(Object.keys(atPlan.resources).sort()).toEqual(Object.keys(atDefault.resources).sort());
+    expect(Object.keys(atPlan.unobserved).sort()).toEqual(Object.keys(atDefault.unobserved).sort());
+    for (const [name, meta] of Object.entries(atDefault.resources)) {
+      const merged = atPlan.resources[name]!;
+      expect({ ...merged, attributes: undefined }).toEqual({ ...meta, attributes: undefined });
+      const rest = Object.fromEntries(Object.entries(merged.attributes ?? {}).filter(([k]) => !k.startsWith("plan")));
+      expect(rest, name).toEqual(meta.attributes);
+    }
+    expect(atPlan.resources["estate/aws_vpc.main"]!.marker).toEqual({ stack: ESTATE });
+  });
+
+  it("the plan attributes on a bound block are the ones a stock root gets from the same plan", async () => {
+    const live = normalizeObservation(await describeResources(await options("choudoufu"), deps()));
+    const stock = normalizeObservation(await describeResources(await options("terraform"), deps()));
+    expect(new Set(Object.values(stock.sources))).toEqual(new Set(["plan"]));
+    for (const name of BOUND) {
+      const attrs = planOnly(live.resources[name]!.attributes);
+      expect(Object.keys(attrs).length, name).toBeGreaterThan(0);
+      expect(attrs, name).toEqual(planOnly(stock.resources[name]!.attributes));
+      for (const key of Object.keys(attrs)) expect((PLAN_ATTRIBUTE_NAMES as readonly string[]).includes(key), key).toBe(true);
+    }
+  });
+
+  it("a foreign or adoptable block gets no plan attributes, and a planned create stays absent", async () => {
+    const result = normalizeObservation(await describeResources(await options(), deps()));
+    const held = result.resources["estate/aws_cloudwatch_log_group.held_elsewhere"]!;
+    const adoptable = result.resources["estate/aws_cloudwatch_log_group.adoptable"]!;
+    expect(held.ownership).toBe("foreign");
+    expect(adoptable.ownership).toBe("unknown");
+    expect(planOnly(held.attributes)).toEqual({});
+    expect(planOnly(adoptable.attributes)).toEqual({});
+    expect(result.resources["estate/aws_cloudwatch_log_group.never_applied"]).toBeUndefined();
+    expect(result.unobserved["estate/aws_cloudwatch_log_group.never_applied"]).toBeUndefined();
+  });
+
+  it("chant search matches the plan attributes on a live root", async () => {
+    const result = normalizeObservation(await describeResources(await options(), deps()));
+    const ir = buildLiveGraphIr([{ lexicon: "terraform", resources: result.resources }]);
+    const { parseQuery, matchTerm } = __searchInternals;
+    const search = (query: string) =>
+      ir.nodes
+        .filter((n) => parseQuery(query).every((t) => matchTerm(n, t, ir)))
+        .map((n) => n.id)
+        .sort();
+    expect(search("attr:planAction=update")).toEqual(["estate/aws_cloudwatch_log_group.app", "estate/aws_vpc.main"]);
+  });
+});
+
+describe("which reads answered is on the wire: \"live+plan\" (#4371)", () => {
+  it("every entity of the root reads \"live+plan\", and the note names both reads", async () => {
+    const opts = await options();
+    const result = normalizeObservation(await describeResources(opts, deps()));
+    expect(Object.keys(result.sources).sort()).toEqual([...opts.entityNames].sort());
+    expect(new Set(Object.values(result.sources))).toEqual(new Set(["live+plan"]));
+    expect(result.rootReads).toEqual({ "terraform.roots.estate": { depth: "live+plan" } });
+    expect(result.notes.join("\n")).toContain(
+      "terraform.roots.estate: the plan read answered (`choudoufu plan -input=false -lock=false -out=<tmp>/plan.tfplan`), beside `live-plan -json`, which answered presence and ownership",
+    );
+    expect(result.queried["estate/aws_vpc.main"]).toMatch(/^choudoufu live-plan -json .*; choudoufu plan -input=false -lock=false .* \+ show -json <planfile>$/);
+  });
+
+  it("the default depth on a live root never calls the plan read and still reads \"live\"", async () => {
+    const result = normalizeObservation(await describeResources(await options("choudoufu", "state"), deps({ planRead: never })));
+    expect(new Set(Object.values(result.sources))).toEqual(new Set(["live"]));
+    expect(planOnly(result.resources["estate/aws_vpc.main"]!.attributes)).toEqual({});
+  });
+});
+
+describe("a live root falls back to live-plan alone, and says so (#4371)", () => {
+  it("a plan read without provider credentials leaves live-plan's answer, reading \"live\"", async () => {
+    const planRead = (async () => {
+      throw new TerraformPlanReadError("plan", "choudoufu plan failed in /x: Error: No valid credential sources found", ROOT_DIR);
+    }) as TerraformReadDeps["planRead"];
+    const result = normalizeObservation(await describeResources(await options(), deps({ planRead })));
+    const vpc = result.resources["estate/aws_vpc.main"]!;
+    expect(vpc.ownership).toBe("owned");
+    expect(planOnly(vpc.attributes)).toEqual({});
+    expect(new Set(Object.values(result.sources))).toEqual(new Set(["live"]));
+    expect(result.notes.join("\n")).toMatch(
+      /terraform\.roots\.estate: the plan read failed \(no provider credentials: .*No valid credential sources found\), so `live-plan -json` alone answered; plan attributes are absent/,
+    );
+    expect(result.rootReads).toEqual({ "terraform.roots.estate": { depth: "live+plan", fellBackTo: "live", reason: "no-credentials" } });
+  });
+
+  it("a root that needs init says so, and live-plan's answer stands", async () => {
+    const planRead = (async () => {
+      throw new TerraformPlanReadError("not-initialised", "terraform.roots.estate (/x) needs init (Error: Required plugins are not installed)", ROOT_DIR);
+    }) as TerraformReadDeps["planRead"];
+    const result = normalizeObservation(await describeResources(await options(), deps({ planRead })));
+    expect(result.resources["estate/aws_vpc.main"]!.ownership).toBe("owned");
+    expect(result.notes.join("\n")).toMatch(/the plan read failed \(the root needs init, which chant never runs: /);
+    expect(result.rootReads).toEqual({ "terraform.roots.estate": { depth: "live+plan", fellBackTo: "live", reason: "needs-init" } });
+  });
+
+  it("a plan read that cannot reach the backend, or fails otherwise, gets its own reason", async () => {
+    const failing = (kind: "backend" | "plan", message: string) =>
+      (async () => {
+        throw new TerraformPlanReadError(kind, message, ROOT_DIR);
+      }) as TerraformReadDeps["planRead"];
+    const backend = normalizeObservation(await describeResources(await options(), deps({ planRead: failing("backend", "Error: Failed to get existing workspaces") })));
+    expect(backend.rootReads).toEqual({ "terraform.roots.estate": { depth: "live+plan", fellBackTo: "live", reason: "backend-unreachable" } });
+    const plain = normalizeObservation(await describeResources(await options(), deps({ planRead: failing("plan", "Error: Invalid count argument") })));
+    expect(plain.rootReads).toEqual({ "terraform.roots.estate": { depth: "live+plan", fellBackTo: "live", reason: "plan-failed" } });
+  });
+
+  it("a failed live-plan leaves the root not observed and never tries the plan read", async () => {
+    const livePlan = (async () => {
+      throw new Error("choudoufu live-plan failed in /x (exit 1)\nError: Provider unavailable for marker discovery");
+    }) as unknown as TerraformReadDeps["livePlan"];
+    const result = normalizeObservation(await describeResources(await options(), deps({ livePlan, planRead: never })));
+    expect(Object.keys(result.resources)).toEqual([]);
+    expect(result.unobserved["estate/aws_vpc.main"]!.reason).toBe("read-failed");
+    expect(new Set(Object.values(result.sources))).toEqual(new Set(["live"]));
+    expect(result.notes.join("\n")).toMatch(/terraform\.roots\.estate: no read answered \(`live-plan -json` failed, so the plan read was not tried\)/);
+    expect(result.rootReads).toBeUndefined();
+  });
+});
+
+describe("sensitive values on a live root (#4371)", () => {
+  it("a secret is redacted on both sides, though choudoufu flags only the declared side", async () => {
+    // Recorded: the tag was applied as "hunter2", then the variable changed to
+    // "hunter3". The live value in `before` is the old secret, and the
+    // document flags `after` only.
+    const raw = readFileSync(join(RECORDED, "show-plan-sensitive.json"), "utf-8");
+    expect(raw).toContain("hunter2");
+    expect(raw).toContain("hunter3");
+    const vpcChange = (PLAN_SENSITIVE as { resource_changes: Array<{ address: string; change: Record<string, unknown> }> }).resource_changes.find(
+      (r) => r.address === "aws_vpc.main",
+    )!.change;
+    expect(vpcChange.before_sensitive).toEqual({ tags: {}, tags_all: {} });
+    expect(vpcChange.after_sensitive).toEqual({ tags: { token: true }, tags_all: {} });
+
+    const result = await describeResources(await options(), deps(undefined, PLAN_SENSITIVE));
+    expect(JSON.stringify(result)).not.toMatch(/hunter[23]/);
+    const vpc = normalizeObservation(result).resources["estate/aws_vpc.main"]!.attributes as Record<string, unknown>;
+    expect(vpc.planChanges).toEqual(
+      expect.arrayContaining([
+        { path: "tags.token", before: SENSITIVE_VALUE, after: SENSITIVE_VALUE },
+        // Unflagged on both sides; redacted because it equals a flagged value.
+        { path: "tags_all.token", before: SENSITIVE_VALUE, after: SENSITIVE_VALUE },
+      ]),
+    );
+  });
+});
+
+describe("the live-plan document, handed to a caller that asks (behold#924)", () => {
+  const withEnv = async <T>(value: string | undefined, fn: () => Promise<T>): Promise<T> => {
+    const before = process.env[TERRAFORM_LIVE_PLAN_DIR_ENV];
+    if (value === undefined) delete process.env[TERRAFORM_LIVE_PLAN_DIR_ENV];
+    else process.env[TERRAFORM_LIVE_PLAN_DIR_ENV] = value;
+    try {
+      return await fn();
+    } finally {
+      if (before === undefined) delete process.env[TERRAFORM_LIVE_PLAN_DIR_ENV];
+      else process.env[TERRAFORM_LIVE_PLAN_DIR_ENV] = before;
+    }
+  };
+
+  it("writes the document the verdicts came from, at either depth, as <root>.live-plan.json", async () => {
+    for (const depth of ["plan", "state"] as const) {
+      const out = mkdtempSync(join(tmpdir(), "chant-live-plan-dir-"));
+      try {
+        const result = await withEnv(out, async () => describeResources(await options("choudoufu", depth), deps()));
+        expect(normalizeObservation(result).resources["estate/aws_vpc.main"]!.ownership).toBe("owned");
+        expect(readdirSync(out)).toEqual([livePlanDocumentFile("estate")]);
+        expect(JSON.parse(readFileSync(join(out, "estate.live-plan.json"), "utf-8"))).toEqual(LIVE_PLAN);
+      } finally {
+        rmSync(out, { recursive: true, force: true });
+      }
+    }
+  });
+
+  it("writes nothing unless asked, and nothing for a relative path", async () => {
+    const out = mkdtempSync(join(tmpdir(), "chant-live-plan-dir-"));
+    try {
+      await withEnv(undefined, async () => describeResources(await options(), deps()));
+      await withEnv("relative/dir", async () => describeResources(await options(), deps()));
+      expect(readdirSync(out)).toEqual([]);
+      expect(existsSync(join(ROOT_DIR, "relative"))).toBe(false);
+    } finally {
+      rmSync(out, { recursive: true, force: true });
+    }
+  });
+
+  it("a root name that is not a file name is made one", () => {
+    expect(livePlanDocumentFile("app/prod")).toBe("app_prod.live-plan.json");
+  });
+});