@intentius/chant-lexicon-terraform 0.124.52 → 0.124.54

package/src/drift-read.ts

@@ -0,0 +1,284 @@
+/**
+ * The terraform lexicon's drift read (behold#995): `LexiconPlugin.readDrift`,
+ * which `chant lifecycle drift` calls, and which `chant workspace drift` runs
+ * in a `terraform` or `choudoufu` member's reader project. It runs the
+ * engine's own reads, one root at a time, and hands each document to the
+ * drift-record adapters in `./drift-record.ts` (#4451), so the records say
+ * exactly what those adapters say.
+ *
+ * | root | `--read` | reads | adapter |
+ * |---|---|---|---|
+ * | stock | `state` (default) | `show -json` over state | `terraformStateDriftRecords` |
+ * | stock | `plan` | `plan -input=false -lock=false -out=<tmp>`, `show -json` | `terraformPlanDriftRecords` |
+ * | live | `ownership` (default) | `choudoufu live-plan -json`, `live-ls -json` | `choudoufuLiveDriftRecords` |
+ * | live | `plan` | live-plan, then the same plan read | `choudoufuLivePlusPlanDriftRecords` |
+ * | live | `--resource <addr>` | `choudoufu live-plan -resource=<addr>` | its own stream, decoded by `decodeDriftLines` |
+ *
+ * Nothing is written in the root. `init` is never run, as on the plan read
+ * (`terraformPlanRead`): a root that was never initialised reads
+ * not-observed with the init line in the detail. A plan read that fails
+ * falls back one depth (the plan to state, live+plan to ownership) and the
+ * records carry `fellBackFrom`. A live-ls that fails is left out: it only
+ * adds what the estate holds and nothing declares.
+ *
+ * Each root's records go out as one stream: a `drift-start` whose `expected`
+ * is every address the read answered, the records, and a `drift-settle`.
+ * `node` stays null; `chant workspace drift` places each record on the
+ * member's graph. A pulumi member (`pulumiMember`) is refused: its drift is
+ * the pulumi lexicon's (chant#4453).
+ */
+
+import { spawn } from "node:child_process";
+import { resolve } from "node:path";
+import {
+  decodeDriftLines,
+  driftRecord,
+  driftRecordLine,
+  driftSettle,
+  driftStart,
+  type DriftEngine,
+  type DriftLine,
+  type DriftRead,
+  type DriftRecord,
+  type ReadDriftOptions,
+  type ReadDriftResult,
+} from "@intentius/chant/drift-record";
+import { ownRoots, type TerraformConfig, type TerraformRootConfig } from "./config";
+import { declaredOf } from "./describe-resources";
+import {
+  choudoufuLivePlusPlanDriftRecords,
+  choudoufuLiveDriftRecords,
+  terraformPlanDriftRecords,
+  terraformStateDriftRecords,
+} from "./drift-record";
+import { RESOURCE_TYPE } from "./hcl/parse";
+import { renderTerraformRoots } from "./hcl/roots";
+import { readsAsCredentials } from "./live-plan-reasons";
+import { detectLiveEstate } from "./op/activities/live-detect";
+import {
+  choudoufuLiveLs,
+  choudoufuLivePlanDocument,
+  rootIsInitialised,
+  terraformBinary,
+  terraformEnvironment,
+  terraformInitLine,
+  terraformPlanRead,
+  terraformShow,
+} from "./op/activities/terraform";
+
+const firstLine = (err: unknown): string => (err instanceof Error ? err.message : String(err)).split("\n")[0];
+
+/** The reads a root answers, the first its default. */
+const ROOT_READS: Record<"stock" | "live", readonly DriftRead[]> = { stock: ["state", "plan"], live: ["ownership", "plan"] };
+
+interface RootContext {
+  options: ReadDriftOptions;
+  name: string;
+  root: TerraformRootConfig;
+  binary: string;
+  dir: string;
+  engine: DriftEngine;
+  /** Every declared managed resource's address. */
+  declared: string[];
+  where: { root: string; cwd: string };
+}
+
+/** One root's records as a stream: start, records, settle. */
+function asStream(ctx: RootContext, read: DriftRead, records: DriftRecord[], extra: { fellBackFrom?: string; resource?: string } = {}): DriftLine[] {
+  const start = driftStart({
+    member: ctx.options.member,
+    engine: ctx.engine,
+    read,
+    ...extra,
+    at: ctx.options.observedAt,
+    expected: records.map((r) => r.address),
+    evidence: { tool: ctx.engine },
+  });
+  const settled = driftSettle(start, records, ctx.options.observedAt);
+  return [start, ...settled.records.map(driftRecordLine), settled.line];
+}
+
+/** Every declared address not-observed, for a read that could not run at all. */
+function unobservedAll(ctx: RootContext, read: DriftRead, err: unknown, command: string): DriftRecord[] {
+  const detail = firstLine(err);
+  return ctx.declared.map((address) =>
+    driftRecord({
+      member: ctx.options.member,
+      engine: ctx.engine,
+      address,
+      node: null,
+      observedAt: ctx.options.observedAt,
+      read,
+      status: "not-observed",
+      unobserved: { reason: readsAsCredentials(detail) ? "no-credentials" : "read-failed", detail },
+      evidence: { tool: ctx.engine, command },
+    }),
+  );
+}
+
+/** A stock root's state read. Never runs init. */
+async function stateRecords(ctx: RootContext, fellBackFrom?: string): Promise<DriftRecord[]> {
+  const base = { member: ctx.options.member, observedAt: ctx.options.observedAt, engine: ctx.engine as "terraform" | "tofu", declared: ctx.declared, ...(fellBackFrom ? { fellBackFrom } : {}) };
+  const env = { ...process.env, ...terraformEnvironment(ctx.root) };
+  if (!rootIsInitialised(ctx.dir, env)) {
+    const line = terraformInitLine({
+      binary: ctx.binary,
+      dir: ctx.dir,
+      ...(ctx.root.backendConfig ? { backendConfig: ctx.root.backendConfig } : {}),
+      ...(ctx.root.backendConfigFiles ? { backendConfigFiles: ctx.root.backendConfigFiles } : {}),
+    });
+    return terraformStateDriftRecords({ ...base, failed: { reason: "read-failed", detail: `${ctx.dir} has never been initialised: run \`${line}\` first; chant never runs init on a read` } });
+  }
+  try {
+    const shown = await terraformShow(ctx.where);
+    return terraformStateDriftRecords({ ...base, state: shown.json });
+  } catch (err) {
+    const detail = firstLine(err);
+    return terraformStateDriftRecords({ ...base, failed: { reason: readsAsCredentials(detail) ? "no-credentials" : "read-failed", detail } });
+  }
+}
+
+async function stockRoot(ctx: RootContext, read: DriftRead): Promise<DriftLine[]> {
+  if (read === "state") return asStream(ctx, "state", await stateRecords(ctx));
+  try {
+    const plan = await terraformPlanRead(ctx.where);
+    return asStream(ctx, "plan", terraformPlanDriftRecords({ member: ctx.options.member, observedAt: ctx.options.observedAt, engine: ctx.engine as "terraform" | "tofu", plan: plan.json }));
+  } catch (err) {
+    // One depth down: what the last apply recorded, said as such.
+    process.stderr.write(`terraform.roots.${ctx.name}: the plan read failed (${firstLine(err)}), so the state read answered\n`);
+    return asStream(ctx, "state", await stateRecords(ctx, "plan"), { fellBackFrom: "plan" });
+  }
+}
+
+async function liveOwnership(ctx: RootContext, fellBackFrom?: string): Promise<{ records: DriftRecord[]; livePlan?: unknown; liveLs?: unknown }> {
+  let livePlan: unknown;
+  try {
+    livePlan = (await choudoufuLivePlanDocument(ctx.where)).json;
+  } catch (err) {
+    return { records: unobservedAll(ctx, "ownership", err, "choudoufu live-plan -json") };
+  }
+  let liveLs: unknown;
+  try {
+    liveLs = (await choudoufuLiveLs({ ...ctx.where, consistent: true })).json;
+  } catch (err) {
+    process.stderr.write(`terraform.roots.${ctx.name}: live-ls failed (${firstLine(err)}); what the estate holds and nothing declares is left out\n`);
+  }
+  const base = { member: ctx.options.member, observedAt: ctx.options.observedAt, livePlan, ...(liveLs !== undefined ? { liveLs } : {}), ...(fellBackFrom ? { fellBackFrom } : {}) };
+  return { records: choudoufuLiveDriftRecords(base), livePlan, liveLs };
+}
+
+async function liveRoot(ctx: RootContext, read: DriftRead): Promise<DriftLine[]> {
+  if (read === "ownership") return asStream(ctx, "ownership", (await liveOwnership(ctx)).records);
+  const owned = await liveOwnership(ctx);
+  if (owned.livePlan === undefined) return asStream(ctx, "ownership", owned.records, { fellBackFrom: "live+plan" });
+  try {
+    const plan = await terraformPlanRead(ctx.where);
+    const records = choudoufuLivePlusPlanDriftRecords({
+      member: ctx.options.member,
+      observedAt: ctx.options.observedAt,
+      livePlan: owned.livePlan,
+      plan: plan.json,
+      ...(owned.liveLs !== undefined ? { liveLs: owned.liveLs } : {}),
+    });
+    return asStream(ctx, "plan", records);
+  } catch (err) {
+    process.stderr.write(`terraform.roots.${ctx.name}: the plan read failed (${firstLine(err)}), so live-plan alone answered\n`);
+    const fell = choudoufuLiveDriftRecords({
+      member: ctx.options.member,
+      observedAt: ctx.options.observedAt,
+      livePlan: owned.livePlan,
+      ...(owned.liveLs !== undefined ? { liveLs: owned.liveLs } : {}),
+      fellBackFrom: "live+plan",
+    });
+    return asStream(ctx, "ownership", fell, { fellBackFrom: "live+plan" });
+  }
+}
+
+/** `choudoufu live-plan -resource=<addr>`'s own stream (choudoufu#2245), decoded, with the workspace member's name on every line. */
+async function liveResource(ctx: RootContext, address: string): Promise<DriftLine[]> {
+  // `-estate` only for a root that names its estate in chant.config and not in its HCL: choudoufu refuses the flag beside a declaration.
+  const estateFlag = ctx.root.estate !== undefined && detectLiveEstate(ctx.dir) === undefined ? [`-estate=${ctx.root.estate}`] : [];
+  const argv = ["live-plan", ...estateFlag, `-resource=${address}`];
+  const command = `${ctx.binary} ${argv.join(" ")}`;
+  const ran = await new Promise<{ code: number | null; stdout: string; stderr: string; error?: Error }>((done) => {
+    const child = spawn(ctx.binary, argv, { cwd: ctx.dir, env: { ...process.env, ...terraformEnvironment(ctx.root) }, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (d) => (stdout += String(d)));
+    child.stderr.on("data", (d) => (stderr += String(d)));
+    child.on("error", (error) => done({ code: null, stdout, stderr, error }));
+    child.on("close", (code) => done({ code, stdout, stderr }));
+  });
+  if (ran.stderr.trim()) process.stderr.write(ran.stderr.endsWith("\n") ? ran.stderr : `${ran.stderr}\n`);
+  // 2 is live-plan's "changes present" under -detailed-exitcode; the stream is what answers.
+  if (ran.error === undefined && (ran.code === 0 || ran.code === 2) && ran.stdout.trim()) {
+    try {
+      return decodeDriftLines(ran.stdout).map((line) => ({ ...line, member: ctx.options.member }));
+    } catch (err) {
+      return asStream(ctx, "plan", [unobservedOne(ctx, address, `${command} printed a line that is not drift: ${firstLine(err)}`, command)], { resource: address });
+    }
+  }
+  const why = ran.error?.message ?? (ran.stderr.trim().split("\n").pop() || `exit ${ran.code}`);
+  return asStream(ctx, "plan", [unobservedOne(ctx, address, `${command} failed: ${why}`, command)], { resource: address });
+}
+
+function unobservedOne(ctx: RootContext, address: string, detail: string, command: string): DriftRecord {
+  return driftRecord({
+    member: ctx.options.member,
+    engine: "choudoufu",
+    address,
+    node: null,
+    observedAt: ctx.options.observedAt,
+    read: "plan",
+    status: "not-observed",
+    unobserved: { reason: readsAsCredentials(detail) ? "no-credentials" : "read-failed", detail },
+    evidence: { tool: "choudoufu", command },
+  });
+}
+
+/** `LexiconPlugin.readDrift` for the terraform lexicon. */
+export async function readTerraformDrift(options: ReadDriftOptions): Promise<ReadDriftResult> {
+  const namespace = (options.config as { terraform?: TerraformConfig }).terraform;
+  // A `signalOnly` root (#4484) is not this project's to read.
+  const roots = Object.entries(ownRoots(namespace?.roots));
+  if (roots.length === 0) return { refused: { code: "no-drift-read", message: "terraform.roots declares no root of its own" } };
+  const binary = terraformBinary(namespace);
+  const live = (root: TerraformRootConfig, dir: string) => binary === "choudoufu" && (detectLiveEstate(dir) !== undefined || root.estate !== undefined);
+
+  const contexts: Array<RootContext & { live: boolean }> = [];
+  for (const [name, root] of roots) {
+    const dir = resolve(options.projectRoot, root.dir);
+    const rendered = await renderTerraformRoots({
+      projectRoot: options.projectRoot,
+      roots: { [name]: root },
+      binary: namespace?.binary,
+      callModuleType: namespace?.callModuleType,
+      moduleRoot: namespace?.moduleRoot,
+    });
+    const declared = [...rendered.entities.entries()]
+      .map(([key, entity]) => declaredOf(key, entity as unknown as { entityType: string; props: Record<string, unknown> }))
+      .filter((d) => d.type === RESOURCE_TYPE)
+      .map((d) => d.address);
+    const isLive = live(root, dir);
+    contexts.push({ options, name, root, binary, dir, engine: isLive ? "choudoufu" : binary === "tofu" ? "tofu" : "terraform", declared: [...new Set(declared)].sort(), where: { root: name, cwd: options.projectRoot }, live: isLive });
+  }
+
+  for (const ctx of contexts) {
+    const reads = ROOT_READS[ctx.live ? "live" : "stock"];
+    if (options.read !== undefined && !reads.includes(options.read)) {
+      return { refused: { code: "read-unsupported", message: `terraform.roots.${ctx.name} is a ${ctx.live ? "live (choudoufu)" : "stock"} root, which answers ${reads.join(" or ")}, not ${options.read}` } };
+    }
+    if (options.resource !== undefined && !ctx.live) {
+      return { refused: { code: "resource-unsupported", message: `terraform.roots.${ctx.name} is a stock root; one resource is read through choudoufu live-plan -resource, on a live root` } };
+    }
+  }
+
+  const lines: DriftLine[] = [];
+  for (const ctx of contexts) {
+    const read = options.read ?? ROOT_READS[ctx.live ? "live" : "stock"][0];
+    if (options.resource !== undefined) lines.push(...(await liveResource(ctx, options.resource)));
+    else if (ctx.live) lines.push(...(await liveRoot(ctx, read)));
+    else lines.push(...(await stockRoot(ctx, read)));
+  }
+  return { lines };
+}

package/src/drift-record.test.ts

@@ -0,0 +1,223 @@
+/**
+ * The terraform-family drift adapters (#4451) over recorded and hand-written
+ * fixtures: a stock root's state and plan, and a choudoufu live root's
+ * live-plan, live-ls and plan. Every adapter's records round-trip through
+ * the document reader, and no state read yields in-sync or drifted.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { driftDocument, parseDriftDocument, STATE_READ_STATUSES, type DriftRecord } from "@intentius/chant/drift-record";
+import {
+  choudoufuLiveDriftRecords,
+  choudoufuLiveLsDriftRecords,
+  choudoufuLivePlanDriftRecords,
+  choudoufuLivePlusPlanDriftRecords,
+  terraformPlanDriftRecords,
+  terraformStateDriftRecords,
+} from "./drift-record";
+
+const FIX = join(import.meta.dirname, "__fixtures__");
+const read = (...path: string[]): unknown => JSON.parse(readFileSync(join(FIX, ...path), "utf-8"));
+const AT = "2026-10-25T12:00:00Z";
+const statusOf = (records: DriftRecord[]) => Object.fromEntries(records.map((r) => [r.address, r.status]));
+const at = (records: DriftRecord[], address: string) => records.find((r) => r.address === address)!;
+
+function roundTrip(records: DriftRecord[]): void {
+  const doc = driftDocument(records);
+  expect(parseDriftDocument(JSON.parse(JSON.stringify(doc)))).toEqual(doc);
+}
+
+describe("a stock root's state", () => {
+  const records = terraformStateDriftRecords({
+    member: "app",
+    observedAt: AT,
+    state: read("show-state.json"),
+    declared: ["null_resource.first", "null_resource.second", "module.cdn.null_resource.edge", "null_resource.never_applied"],
+  });
+
+  test("is recorded where state has it and pending where it does not", () => {
+    expect(statusOf(records)).toEqual({
+      "module.cdn.null_resource.edge": "recorded",
+      "null_resource.first": "recorded",
+      "null_resource.never_applied": "pending",
+      "null_resource.second": "recorded",
+    });
+    expect(at(records, "null_resource.first").ownership).toEqual({ verdict: "owned", by: "state" });
+    roundTrip(records);
+  });
+
+  test("never yields in-sync or drifted, a failed read included", () => {
+    const failed = terraformStateDriftRecords({ member: "app", observedAt: AT, declared: ["null_resource.first"], failed: { reason: "read-failed", detail: "init failed" } });
+    expect(statusOf(failed)).toEqual({ "null_resource.first": "not-observed" });
+    for (const r of [...records, ...failed]) {
+      expect(r.read).toBe("state");
+      expect(STATE_READ_STATUSES).toContain(r.status);
+      expect(r.status).not.toBe("in-sync");
+      expect(r.status).not.toBe("drifted");
+    }
+    roundTrip(failed);
+  });
+});
+
+describe("a stock root's plan", () => {
+  const records = terraformPlanDriftRecords({ member: "app", observedAt: AT, plan: read("show-plan.json") });
+
+  test("drift rows decide, and a configuration change is not drift", () => {
+    expect(statusOf(records)).toEqual({
+      "shell_script.conf": "drifted",
+      "terraform_data.downstream": "in-sync",
+      "terraform_data.reader": "in-sync",
+      "terraform_data.replaced": "in-sync",
+      "terraform_data.updated": "in-sync",
+    });
+    const conf = at(records, "shell_script.conf");
+    expect(conf.read).toBe("plan");
+    expect(conf.evidence).toMatchObject({ tool: "terraform", version: "1.15.8" });
+    expect(conf.attributes).toContainEqual({ path: "dirty", before: false, after: true });
+    roundTrip(records);
+  });
+
+  test("a drift delete is missing, a create with no prior row pending, a dropped block undeclared", () => {
+    const plan = {
+      terraform_version: "1.9.0",
+      prior_state: { values: { root_module: { resources: [{ address: "aws_s3_bucket.gone", mode: "managed", type: "aws_s3_bucket" }, { address: "aws_s3_bucket.dropped", mode: "managed", type: "aws_s3_bucket" }] } } },
+      resource_drift: [{ address: "aws_s3_bucket.gone", type: "aws_s3_bucket", change: { actions: ["delete"], before: { bucket: "gone" }, after: null } }],
+      resource_changes: [
+        { address: "aws_s3_bucket.gone", mode: "managed", type: "aws_s3_bucket", change: { actions: ["create"], before: null, after: { bucket: "gone" } } },
+        { address: "aws_s3_bucket.new", mode: "managed", type: "aws_s3_bucket", change: { actions: ["create"], before: null, after: { bucket: "new" } } },
+        { address: "aws_s3_bucket.dropped", mode: "managed", type: "aws_s3_bucket", change: { actions: ["delete"], before: { bucket: "dropped" }, after: null } },
+        { address: "data.aws_caller_identity.me", mode: "data", type: "aws_caller_identity", change: { actions: ["read"] } },
+      ],
+    };
+    const out = terraformPlanDriftRecords({ member: "app", engine: "tofu", observedAt: AT, plan });
+    expect(statusOf(out)).toEqual({ "aws_s3_bucket.dropped": "undeclared", "aws_s3_bucket.gone": "missing", "aws_s3_bucket.new": "pending" });
+    expect(out.every((r) => r.engine === "tofu" && r.resourceType === "aws_s3_bucket")).toBe(true);
+    roundTrip(out);
+  });
+});
+
+describe("choudoufu live-plan", () => {
+  const records = choudoufuLivePlanDriftRecords({ member: "estate", observedAt: AT, livePlan: read("live-plan.json") });
+
+  test("maps bound, unowned, adoptable and omissions", () => {
+    expect(statusOf(records)).toEqual({
+      "aws_cloudwatch_log_group.adoptable": "unclaimed",
+      "aws_cloudwatch_log_group.app": "in-sync",
+      "aws_cloudwatch_log_group.held_elsewhere": "unclaimed",
+      "aws_cloudwatch_log_group.never_applied": "pending",
+      "aws_eip.pool[0]": "in-sync",
+      "aws_eip.pool[1]": "in-sync",
+      "aws_security_group.main": "in-sync",
+      "aws_security_group_rule.https": "pending",
+      "aws_subnet.app": "in-sync",
+      "aws_vpc.adoptable": "unclaimed",
+      "aws_vpc.main": "in-sync",
+    });
+    expect(records.every((r) => r.read === "ownership" && r.engine === "choudoufu")).toBe(true);
+    expect(at(records, "aws_eip.pool[0]").ownership).toEqual({ verdict: "owned", by: "marker", markerOnObject: true });
+    expect(at(records, "aws_cloudwatch_log_group.app").ownership).toEqual({ verdict: "owned", by: "derived", markerOnObject: false });
+    expect(at(records, "aws_cloudwatch_log_group.adoptable").ownership).toMatchObject({ verdict: "adoptable", adopt: "aws_cloudwatch_log_group.adoptable" });
+    expect(at(records, "aws_cloudwatch_log_group.held_elsewhere").ownership).toEqual({ verdict: "foreign", by: "marker", markerOnObject: true, ownedBy: "other-estate" });
+    expect(at(records, "aws_cloudwatch_log_group.held_elsewhere").evidence.engineCode).toBe("UNOWNED");
+    expect(at(records, "aws_vpc.adoptable").evidence.engineCode).toBe("NEEDS_DISCOVERY");
+    expect(at(records, "aws_cloudwatch_log_group.never_applied").evidence.engineCode).toBe("ABSENT");
+    expect(at(records, "aws_eip.pool[0]").evidence.version).toBe("v0.15.0");
+    roundTrip(records);
+  });
+
+  test("foreign, controller_held, the new omission reasons and an UNOWNED with no row", () => {
+    const out = choudoufuLivePlanDriftRecords({ member: "estate", observedAt: AT, livePlan: read("drift-record", "live-plan-sections.json") });
+    expect(statusOf(out)).toEqual({
+      "arn:aws:s3:::ack-made": "runtime",
+      "arn:aws:s3:::someone-elses": "undeclared",
+      "aws_cloudwatch_log_group.orphan_unowned": "not-observed",
+      "aws_iam_role.app": "in-sync",
+      "aws_instance.verified": "not-observed",
+      "aws_lambda_function.fn": "not-observed",
+      "aws_s3_bucket.records": "in-sync",
+      "aws_sqs_queue.later": "not-observed",
+      "https://sqs.us-east-1.amazonaws.com/000000000000/loose": "undeclared",
+      "kubernetes_deployment.legacy": "runtime",
+      "kubernetes_manifest.issuer": "not-observed",
+    });
+    const reason = (a: string) => [at(out, a).unobserved?.reason, at(out, a).evidence.engineCode];
+    expect(reason("aws_cloudwatch_log_group.orphan_unowned")).toEqual(["read-failed", "UNOWNED"]);
+    expect(reason("aws_instance.verified")).toEqual(["read-failed", "VERIFIED_NOT_IMPORTABLE"]);
+    expect(reason("kubernetes_manifest.issuer")).toEqual(["filtered", "OUT_OF_SCOPE"]);
+    expect(reason("aws_lambda_function.fn")).toEqual(["no-credentials", "FAILED"]);
+    expect(reason("aws_sqs_queue.later")).toEqual(["read-failed", "SOMETHING_NEW"]);
+    expect(at(out, "arn:aws:s3:::someone-elses").ownership).toEqual({ verdict: "foreign", by: "marker", markerOnObject: true, ownedBy: "other-estate" });
+    expect(at(out, "https://sqs.us-east-1.amazonaws.com/000000000000/loose").ownership).toEqual({ verdict: "foreign", markerOnObject: false });
+    expect(at(out, "kubernetes_deployment.legacy").ownership).toEqual({ verdict: "foreign", by: "label", ownedBy: "Helm release web" });
+    expect(at(out, "aws_s3_bucket.records").ownership).toEqual({ verdict: "owned", by: "record", markerOnObject: false });
+    roundTrip(out);
+  });
+
+  test("a graph places instances on their instance nodes", () => {
+    const placed = choudoufuLivePlanDriftRecords({
+      member: "estate",
+      observedAt: AT,
+      livePlan: read("live-plan.json"),
+      graph: { member: null, at: null, ids: ["estate/aws_eip.pool", "estate/aws_vpc.main"] },
+    });
+    expect(at(placed, "aws_eip.pool[1]")).toMatchObject({ node: "estate/aws_eip.pool[1]", instanceOf: "estate/aws_eip.pool" });
+    expect(at(placed, "aws_vpc.main").node).toBe("estate/aws_vpc.main");
+    expect(at(placed, "aws_subnet.app").node).toBeNull();
+    roundTrip(placed);
+  });
+});
+
+describe("choudoufu live-ls", () => {
+  test("an undeclared item is undeclared, and a gap live-plan answered is left out", () => {
+    const alone = choudoufuLiveLsDriftRecords({ member: "estate", observedAt: AT, liveLs: read("live-ls.json") });
+    expect(statusOf(alone)).toEqual({ "aws_s3_bucket.data": "undeclared", "aws_security_group_rule.https": "not-observed" });
+    expect(at(alone, "aws_s3_bucket.data").ownership).toEqual({ verdict: "owned", by: "marker", markerOnObject: true });
+    expect(at(alone, "aws_security_group_rule.https").evidence.engineCode).toBe("declaration-carried");
+    roundTrip(alone);
+
+    const both = choudoufuLiveDriftRecords({ member: "estate", observedAt: AT, livePlan: read("live-plan.json"), liveLs: read("live-ls.json") });
+    expect(at(both, "aws_s3_bucket.data").status).toBe("undeclared");
+    expect(at(both, "aws_security_group_rule.https").status).toBe("pending");
+    roundTrip(both);
+  });
+});
+
+describe("choudoufu live+plan", () => {
+  test("a bound instance with a planned update is drifted, declared before and live after", () => {
+    const records = choudoufuLivePlusPlanDriftRecords({
+      member: "estate",
+      observedAt: AT,
+      livePlan: read("live-plan-depth", "live-plan.json"),
+      plan: read("live-plan-depth", "show-plan.json"),
+    });
+    const app = at(records, "aws_cloudwatch_log_group.app");
+    expect(app.read).toBe("plan");
+    expect(app.status).toBe("drifted");
+    expect(app.attributes).toContainEqual({ path: "retention_in_days", before: 1, after: 3 });
+    expect(app.ownership).toEqual({ verdict: "owned", by: "derived", markerOnObject: false });
+    const vpc = at(records, "aws_vpc.main");
+    expect(vpc.status).toBe("drifted");
+    expect(vpc.attributes).toContainEqual({ path: "tags.drifted", after: "yes" });
+    expect(at(records, "aws_eip.pool[0]")).toMatchObject({ read: "plan", status: "in-sync" });
+    // Not bound: the plan does not say who holds it, so live-plan's record stands.
+    expect(at(records, "aws_cloudwatch_log_group.never_applied")).toMatchObject({ read: "ownership", status: "pending" });
+    roundTrip(records);
+  });
+
+  test("a sensitive value never leaves, on either side", () => {
+    const records = choudoufuLivePlusPlanDriftRecords({
+      member: "estate",
+      observedAt: AT,
+      livePlan: read("live-plan-depth", "live-plan.json"),
+      plan: read("live-plan-depth", "show-plan-sensitive.json"),
+    });
+    const vpc = at(records, "aws_vpc.main");
+    expect(vpc.attributes).toContainEqual({ path: "tags.token", sensitive: true });
+    const text = JSON.stringify(driftDocument(records));
+    expect(text).not.toContain("hunter2");
+    expect(text).not.toContain("hunter3");
+    roundTrip(records);
+  });
+});