@intentius/chant-lexicon-terraform 0.124.54 → 0.124.56

package/src/cone.ts

@@ -0,0 +1,138 @@
+/**
+ * choudoufu's cone plans (#4545, moved from terragucci's `cone.ts`): `plan
+ * -cone=<base>` plans only the blocks a change touches and every block that
+ * reads them.
+ *
+ * A wave that applies an open pull request plans a live root as the cone of
+ * its change since the pull request's base, as the plan note did. A wave
+ * that applies a merge commit and a drift run plan the whole estate, as do
+ * a root with no `live` block, an estate file (`estate.chdf.hcl`), whose
+ * form choudoufu refuses `-cone` on, and any binary but choudoufu.
+ *
+ * choudoufu's guard can plan the whole estate anyway (no base, a provider,
+ * terraform or live block or the lock file changed, a cone over 30% of the
+ * estate's blocks, and so on). It says why in a warning. A cone plan says
+ * its size in a warning too, and with `-out FILE` writes `FILE.cone.json`:
+ * the cone's base, the commit it named and the addresses it targets.
+ *
+ * The record's targets join the root's plan digest ({@link conePlanDigest}),
+ * so the digest an approval binds names the cone. A wave that plans again
+ * after its approval and finds another cone has another digest, and refuses
+ * as moved. choudoufu's `apply FILE` checks the same record again.
+ *
+ * Pure, apart from reading the record beside a plan file.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { computePlanDigest } from "@intentius/chant/lifecycle/plan-digest";
+
+/** The flags choudoufu refuses beside `-cone`, or plans in full with: a plan that carries one gets no `-cone`. */
+export const CONE_EXCLUDES = ["-target", "-exclude", "-destroy", "-refresh-only", "-json", "-estate"] as const;
+
+/** What choudoufu writes beside a saved cone plan, `FILE.cone.json`. */
+export interface ConeRecord {
+  base: string;
+  base_sha: string;
+  targets: string[];
+}
+
+/** What one root's cone plan did: planned the cone, or planned the whole estate for the guard's reason. */
+export interface PlanCone {
+  /** The revision the plan was asked to measure the change from. */
+  base: string;
+  /** With a cone: its blocks, and the estate's, as choudoufu counted them. Absent when it did not say. */
+  blocks?: number;
+  of?: number;
+  /** With a cone: the record beside the plan file. */
+  record?: ConeRecord;
+  /** The guard planned the whole estate: its kind and why. */
+  fallback?: { kind: string; reason: string };
+}
+
+/** Whether `binary` (a name or a path) is choudoufu. */
+export const isChoudoufu = (binary: string): boolean => basename(binary) === "choudoufu";
+
+/**
+ * The `-cone` argument a plan takes: `-cone=<base>` for choudoufu with a
+ * base, on a root that takes it (`live`), when none of `args` is a flag in
+ * {@link CONE_EXCLUDES}. Otherwise none, and the plan is full.
+ */
+export function coneArgs(binary: string, base: string | undefined, args: readonly string[], cone: boolean): string[] {
+  if (!base || !cone || !isChoudoufu(binary)) return [];
+  const excluded = args.some((a) => CONE_EXCLUDES.some((f) => a === f || a.startsWith(`${f}=`)));
+  return excluded ? [] : [`-cone=${base}`];
+}
+
+/** The path of the cone record beside a plan file. */
+export const coneRecordPath = (planFile: string): string => `${planFile}.cone.json`;
+
+/** The cone record beside `planFile`, or none when there is none or it does not read as one. */
+export function readConeRecord(planFile: string): ConeRecord | undefined {
+  const path = coneRecordPath(planFile);
+  if (!existsSync(path)) return undefined;
+  try {
+    const r = JSON.parse(readFileSync(path, "utf-8")) as Partial<ConeRecord> | null;
+    if (!r || typeof r.base !== "string" || !Array.isArray(r.targets) || !r.targets.every((t) => typeof t === "string")) return undefined;
+    return { base: r.base, base_sha: typeof r.base_sha === "string" ? r.base_sha : "", targets: [...r.targets].sort() };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The detail of the last warning with this summary in a plan's output, its
+ * lines joined. The binary prints a warning as `Warning: <summary>`, a blank
+ * line, and the detail up to the next blank line or the plan's summary; a box
+ * drawn around it with colour on is stripped.
+ */
+function warningDetail(text: string, summary: string): string | undefined {
+  const lines = text.replace(/\r\n/g, "\n").split("\n").map((l) => l.replace(/^[\s│╷╵]*/, "").trimEnd());
+  let found: string | undefined;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i] !== `Warning: ${summary}`) continue;
+    let j = i + 1;
+    while (j < lines.length && lines[j] === "") j++;
+    const detail: string[] = [];
+    for (; j < lines.length && lines[j] !== "" && !/^(Plan: |No changes\.|Changes to Outputs:)/.test(lines[j]!); j++) detail.push(lines[j]!);
+    found = detail.join(" ").replace(/\s+/g, " ").trim();
+  }
+  return found;
+}
+
+/**
+ * What a plan run with `-cone=<base>` did, from its output and the record
+ * beside `planFile`. A fallback warning means the whole estate was planned,
+ * even after a cone warning. With no fallback, the record is the cone. With
+ * neither, choudoufu said nothing this reads, and the plan counts as full.
+ */
+export function readPlanCone(output: string, planFile: string, base: string): PlanCone {
+  const fell = warningDetail(output, "Cone plan fell back to a full plan");
+  if (fell !== undefined) {
+    const m = /^This plan covers the whole estate \(guard ([^)]*)\): (.*?)\.?$/.exec(fell);
+    return { base, fallback: m ? { kind: m[1]!, reason: m[2]! } : { kind: "unknown", reason: fell } };
+  }
+  const record = readConeRecord(planFile);
+  if (!record) return { base, fallback: { kind: "unknown", reason: "choudoufu wrote no cone record beside the plan" } };
+  const size = /: (\d+) of the estate's (\d+) blocks/.exec(warningDetail(output, "Cone plan") ?? "");
+  return { base, ...(size ? { blocks: Number(size[1]), of: Number(size[2]) } : {}), record };
+}
+
+/** What a cone plan did, in words: its size, or why it planned the whole estate. */
+export function coneText(cone: PlanCone): string {
+  if (cone.fallback) return `the whole estate, since ${cone.fallback.reason} (guard ${cone.fallback.kind})`;
+  const n = cone.record?.targets.length ?? 0;
+  const size = cone.blocks !== undefined && cone.of !== undefined ? `${cone.blocks} of the estate's ${cone.of} blocks` : `${n} target${n === 1 ? "" : "s"}`;
+  return `the cone of the change since ${cone.base}, ${size}`;
+}
+
+/**
+ * A root's plan digest with its cone in it: the plan's own digest, unchanged,
+ * when the plan was full; with a cone, the digest over the plan's digest and
+ * the cone's targets, so an approval of one cone counts for no other. The
+ * digest's kind is terragucci's, so approvals recorded before the move still
+ * name the same digest.
+ */
+export function conePlanDigest(planDigest: string, cone: PlanCone | undefined): string {
+  if (!cone?.record) return planDigest;
+  return computePlanDigest("terragucci-cone-plan", { plan: planDigest, targets: [...cone.record.targets].sort() });
+}

package/src/cost-hold.ts

@@ -0,0 +1,29 @@
+/**
+ * The terraform lexicon's preset for an op wave's cost hold (#4545,
+ * `holds.cost` on the spec): infracost over each root's plan document, the
+ * `show -json` file `terraform-apply`'s plan names as `artifact.planJson`.
+ *
+ * ```ts
+ * const spec = { ..., step: { kind: "terraform-apply", root: "{target}" }, holds: { cost: terraformCostHold({ approveAbove: 100 }) } };
+ * ```
+ *
+ * The shape is core's `OpWaveCostHold`, written out here so the lexicon
+ * builds against a core without it.
+ */
+
+/** infracost's own command over one plan document. */
+export const INFRACOST_ARGV = ["infracost", "breakdown", "--path", "{planJson}", "--format", "json", "--log-level", "error"] as const;
+
+export interface TerraformCostHold {
+  command: string[];
+  approveAbove: number;
+  format: "infracost";
+  currency?: string;
+}
+
+/** A cost hold that prices each root with infracost, waiting over `approveAbove` a month. `command` replaces infracost's argv; it must name `{planJson}`. */
+export function terraformCostHold(options: { approveAbove: number; currency?: string; command?: string[] }): TerraformCostHold {
+  const command = options.command ?? [...INFRACOST_ARGV];
+  if (!command.some((a) => a.includes("{planJson}"))) throw new Error("terraformCostHold: the command must name {planJson}, the root's plan document");
+  return { command, approveAbove: options.approveAbove, format: "infracost", ...(options.currency ? { currency: options.currency } : {}) };
+}

package/src/describe-resources.engine-facts.test.ts

@@ -38,7 +38,6 @@ import { normalizeObservation } from "@intentius/chant/observation";
 import type { Declarable } from "@intentius/chant/declarable";
 import { buildLiveGraphIr } from "@intentius/chant/graph-ir";
 import { ENGINE_FACTS_FLOOR } from "@intentius/chant/engine-facts";
-import { NEXT_RELEASE } from "@intentius/chant/release-floors";
 import {
   describeResources,
   readEngineGraph,
@@ -406,7 +405,7 @@ describe("the floors (#4528)", () => {
     expect(isOlderVersion(MIN_CHOUDOUFU_VERSION, MIN_CHOUDOUFU_GRAPH_VERSION)).toBe(true);
   });
 
-  it("the chant floor for writing facts is the next release", () => {
-    expect(ENGINE_FACTS_FLOOR).toBe(NEXT_RELEASE);
+  it("the chant floor for writing facts shipped in 0.124.54", () => {
+    expect(ENGINE_FACTS_FLOOR).toBe("0.124.54");
   });
 });

package/src/drift-rows.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Drift rows (#4580) over two hand-written plans: a stock root's
+ * refresh-only plan with drift and a create row, and a full plan of a root
+ * under live resource markers. The count and names are checked against a
+ * copy of terragucci's own rules (packages/terragucci/src/report/drift.ts
+ * at integration/ci-products), so a product that moves onto these rows
+ * reports the same numbers.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { terraformPlanDriftCount, terraformPlanDriftNames, terraformPlanDriftRows } from "./drift-rows";
+
+const FIX = join(import.meta.dirname, "__fixtures__", "drift-rows");
+const read = (name: string): unknown => JSON.parse(readFileSync(join(FIX, name), "utf-8"));
+
+// ── terragucci's rules, copied as they are, for the parity checks ─────────────
+
+type Json = Record<string, unknown>;
+const FLIP: Record<string, string> = { create: "delete", delete: "create" };
+
+function liveDrift(plan: unknown): unknown {
+  if (plan === null || typeof plan !== "object" || Array.isArray(plan)) return plan;
+  const p = plan as Json;
+  const changes = Array.isArray(p.resource_changes) ? (p.resource_changes as Json[]) : [];
+  const resource_drift = changes
+    .filter((r) => r.mode !== "data")
+    .flatMap((r) => {
+      const ch = (r.change ?? {}) as Json;
+      const actions = Array.isArray(ch.actions) ? (ch.actions as string[]) : [];
+      if (actions.length === 0 || actions.every((a) => a === "no-op" || a === "read")) return [];
+      const action = actions.length === 1 ? (FLIP[actions[0]!] ?? actions[0]!) : "update";
+      const live = (ch.before ?? null) as Json | null;
+      let code = (ch.after ?? null) as Json | null;
+      const unknown = ch.after_unknown !== null && typeof ch.after_unknown === "object" ? (ch.after_unknown as Json) : {};
+      if (code && live) code = { ...code, ...Object.fromEntries(Object.keys(unknown).filter((k) => unknown[k] === true && k in live).map((k) => [k, live[k]])) };
+      return [{
+        ...r,
+        change: { actions: [action], before: code, after: live, before_sensitive: ch.after_sensitive ?? false, after_sensitive: ch.before_sensitive ?? false },
+      }];
+    });
+  return { ...p, resource_drift };
+}
+
+function driftCount(plan: unknown): number {
+  const list = plan !== null && typeof plan === "object" ? (plan as Json).resource_drift : undefined;
+  return Array.isArray(list) ? list.length : 0;
+}
+
+function driftNames(plan: unknown): Map<string, string> {
+  const out = new Map<string, string>();
+  const list = plan !== null && typeof plan === "object" ? (plan as Json).resource_drift : undefined;
+  if (!Array.isArray(list)) return out;
+  for (const r of list as Json[]) {
+    const ch = (r.change ?? {}) as Json;
+    const values = [ch.after, ch.before].filter((v): v is Json => v !== null && typeof v === "object");
+    for (const key of ["name", "id", "bucket", "function_name", "arn"]) {
+      const v = values.map((x) => x[key]).find((x) => typeof x === "string" && x !== "");
+      if (typeof v === "string") {
+        out.set(String(r.address), v);
+        break;
+      }
+    }
+  }
+  return out;
+}
+
+// ── the rows ──────────────────────────────────────────────────────────────────
+
+describe("a stock root's refresh-only plan", () => {
+  const plan = read("refresh-plan.json");
+  const rows = terraformPlanDriftRows(plan);
+
+  test("every resource_drift entry is a row, creates and data blocks included", () => {
+    expect(rows).toEqual([
+      { address: "aws_s3_bucket.logs", action: "update", type: "aws_s3_bucket", name: "acme-logs" },
+      { address: "aws_lambda_function.worker", action: "delete", type: "aws_lambda_function", name: "acme-worker" },
+      { address: "aws_sqs_queue.jobs", action: "create", type: "aws_sqs_queue", name: "acme-jobs" },
+      { address: "aws_iam_role.runner", action: "update", type: "aws_iam_role", name: "arn:aws:iam::000000000000:role/acme-runner" },
+      { address: "data.aws_caller_identity.me", action: "update", type: "aws_caller_identity" },
+    ]);
+  });
+
+  test("rows carry no attribute values", () => {
+    for (const row of rows) expect(Object.keys(row).every((k) => ["address", "action", "type", "name"].includes(k))).toBe(true);
+  });
+
+  test("the count and names match terragucci's report", () => {
+    expect(terraformPlanDriftCount(plan)).toBe(driftCount(plan));
+    expect(terraformPlanDriftCount(plan)).toBe(5);
+    expect(terraformPlanDriftNames(plan)).toEqual(driftNames(plan));
+  });
+
+  test("a delete-and-create pair is a replace", () => {
+    const pair = { resource_drift: [{ address: "a.b", change: { actions: ["delete", "create"], before: { id: "x" }, after: { id: "y" } } }] };
+    expect(terraformPlanDriftRows(pair)).toEqual([{ address: "a.b", action: "replace", name: "y" }]);
+  });
+});
+
+describe("a live root's full plan", () => {
+  const plan = read("live-root-plan.json");
+  const rows = terraformPlanDriftRows(plan, { live: true });
+
+  test("changes read as drift from the other side, data, no-op and resource_drift left out", () => {
+    expect(rows).toEqual([
+      { address: "aws_s3_bucket.assets", action: "delete", type: "aws_s3_bucket", name: "acme-assets" },
+      { address: "aws_sqs_queue.stray", action: "create", type: "aws_sqs_queue", name: "acme-stray" },
+      { address: "aws_lambda_function.api", action: "update", type: "aws_lambda_function", name: "acme-api" },
+      { address: "aws_iam_role.deployer", action: "update", type: "aws_iam_role", name: "acme-deployer-old" },
+      { address: "aws_security_group.edge", action: "update", type: "aws_security_group", name: "sg-0001" },
+    ]);
+  });
+
+  test("the count and names match terragucci's report after liveDrift", () => {
+    const drifted = liveDrift(plan);
+    expect(terraformPlanDriftCount(plan, { live: true })).toBe(driftCount(drifted));
+    expect(terraformPlanDriftCount(plan, { live: true })).toBe(5);
+    expect(terraformPlanDriftNames(plan, { live: true })).toEqual(driftNames(drifted));
+  });
+
+  test("read as a stock plan, the same document counts only its resource_drift", () => {
+    expect(terraformPlanDriftCount(plan)).toBe(1);
+  });
+});
+
+describe("documents with nothing to read", () => {
+  test("a missing or malformed plan has no rows", () => {
+    for (const plan of [undefined, null, "plan", [], {}, { resource_drift: "x" }]) {
+      expect(terraformPlanDriftRows(plan)).toEqual([]);
+      expect(terraformPlanDriftRows(plan, { live: true })).toEqual([]);
+      expect(terraformPlanDriftCount(plan)).toBe(driftCount(plan));
+    }
+  });
+});

package/src/drift-rows.ts

@@ -0,0 +1,137 @@
+/**
+ * Drift rows (#4580): one row per object a plan found drifted, by address,
+ * with its action and the object's real name, counted the way a product's
+ * drift report counts. `./drift-record.ts` answers a different question (the
+ * status of each instance the plan names), so it skips create rows, carries
+ * no names and stays as it is.
+ *
+ * A stock root's refresh-only plan reports drift as `resource_drift`, and
+ * every entry there is one row, data blocks and creates included. A full
+ * plan of a root under live resource markers (`live: true`) reads drift from
+ * `resource_changes` instead, seen from the other side: a create there is an
+ * object that no longer exists (delete), a delete one that exists outside
+ * the code (create), a replacement or any other pair of actions an update.
+ * Data blocks, no-op and read entries are not drift.
+ *
+ * These are terragucci's rules (packages/terragucci/src/report/drift.ts:
+ * `liveDrift`, `driftCount`, `driftNames`), so a row count here equals the
+ * count its report gives for the same plan.
+ *
+ * A row carries no attribute values. Its `name` is the first non-empty
+ * string among `name`, `id`, `bucket`, `function_name` and `arn`, read from
+ * the object as found and then as the code has it; a deleted object has no
+ * other place its name survives.
+ *
+ * The module imports nothing, so a product can load it behind a
+ * feature-detect without pulling the lexicon's entry point.
+ */
+
+type Json = Record<string, unknown>;
+
+const isObject = (v: unknown): v is Json => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/** One drifted object. */
+export interface TerraformDriftRow {
+  /** The resource address, `""` when the plan's entry has none. */
+  address: string;
+  /**
+   * What happened outside the code: `update`, `delete` (the object is gone),
+   * `create` (an object exists that state or code does not hold), or on a
+   * stock root whatever single action the plan's entry names. On a stock
+   * root a delete-and-create pair is `replace`, and any other pair `update`.
+   */
+  action: string;
+  /** The resource type, when the entry names one. */
+  type?: string;
+  /** The object's real name, by the rule in this module's header. */
+  name?: string;
+}
+
+export interface TerraformPlanDriftRowsOptions {
+  /**
+   * The plan is a full plan of a root under live resource markers, whose
+   * changes are its drift. Default false: a refresh-only plan's
+   * `resource_drift`.
+   */
+  live?: boolean;
+}
+
+const FLIP: Record<string, string> = { create: "delete", delete: "create" };
+const NAME_KEYS = ["name", "id", "bucket", "function_name", "arn"] as const;
+
+function nameOf(values: readonly unknown[]): string | undefined {
+  const objects = values.filter(isObject);
+  for (const key of NAME_KEYS) {
+    const v = objects.map((x) => x[key]).find((x) => typeof x === "string" && x !== "");
+    if (typeof v === "string") return v;
+  }
+  return undefined;
+}
+
+function rowOf(entry: unknown, action: string, values: readonly unknown[]): TerraformDriftRow {
+  const r = isObject(entry) ? entry : {};
+  const name = nameOf(values);
+  return {
+    address: typeof r.address === "string" ? r.address : "",
+    action,
+    ...(typeof r.type === "string" && r.type !== "" ? { type: r.type } : {}),
+    ...(name !== undefined ? { name } : {}),
+  };
+}
+
+function stockAction(actions: readonly string[]): string {
+  if (actions.length === 1) return actions[0]!;
+  if (actions.length === 2 && actions.includes("delete") && actions.includes("create")) return "replace";
+  return "update";
+}
+
+/** A refresh-only plan's `resource_drift`, one row per entry. */
+function stockRows(doc: Json): TerraformDriftRow[] {
+  const list = Array.isArray(doc.resource_drift) ? doc.resource_drift : [];
+  return list.map((entry) => {
+    const ch = isObject(entry) && isObject(entry.change) ? entry.change : {};
+    const actions = Array.isArray(ch.actions) ? ch.actions.map(String) : [];
+    return rowOf(entry, stockAction(actions), [ch.after, ch.before]);
+  });
+}
+
+/** A live root's full plan, its changes read as drift. */
+function liveRows(doc: Json): TerraformDriftRow[] {
+  const list = Array.isArray(doc.resource_changes) ? doc.resource_changes : [];
+  const out: TerraformDriftRow[] = [];
+  for (const entry of list) {
+    if (!isObject(entry) || entry.mode === "data") continue;
+    const ch = isObject(entry.change) ? entry.change : {};
+    const actions = Array.isArray(ch.actions) ? ch.actions.map(String) : [];
+    if (actions.length === 0 || actions.every((a) => a === "no-op" || a === "read")) continue;
+    const action = actions.length === 1 ? (FLIP[actions[0]!] ?? actions[0]!) : "update";
+    const live = isObject(ch.before) ? ch.before : null;
+    let code = isObject(ch.after) ? ch.after : null;
+    // A value the plan knows only after the apply is not a difference: the live one stands for it.
+    const unknown = isObject(ch.after_unknown) ? ch.after_unknown : {};
+    if (code && live) code = { ...code, ...Object.fromEntries(Object.keys(unknown).filter((k) => unknown[k] === true && k in live).map((k) => [k, live[k]])) };
+    out.push(rowOf(entry, action, [live, code]));
+  }
+  return out;
+}
+
+/**
+ * The drift a plan (`show -json`, parsed) found, one row per drifted object
+ * in the plan's order. Its length is the drift count.
+ */
+export function terraformPlanDriftRows(plan: unknown, options: TerraformPlanDriftRowsOptions = {}): TerraformDriftRow[] {
+  if (!isObject(plan)) return [];
+  return options.live ? liveRows(plan) : stockRows(plan);
+}
+
+/** How many objects a plan found drifted: `terraformPlanDriftRows(plan, options).length`. */
+export function terraformPlanDriftCount(plan: unknown, options: TerraformPlanDriftRowsOptions = {}): number {
+  return terraformPlanDriftRows(plan, options).length;
+}
+
+/** Each drifted object's real name by address, for the rows that have one. */
+export function terraformPlanDriftNames(plan: unknown, options: TerraformPlanDriftRowsOptions = {}): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const row of terraformPlanDriftRows(plan, options)) if (row.name !== undefined) out.set(row.address, row.name);
+  return out;
+}

package/src/exit-codes.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, test } from "vitest";
+import { CHANT_EXIT } from "@intentius/chant/exit-codes";
+import { terraformExitOf, terraformPlanMoved } from "./exit-codes";
+
+describe("terraform, tofu and choudoufu exit statuses on chant's table (#4553)", () => {
+  test("choudoufu's refusals of a moved plan are chant's moved code", () => {
+    expect(terraformExitOf({ command: "live-wave-apply", code: 3 })).toBe(CHANT_EXIT.moved);
+    expect(terraformExitOf({ command: "apply", code: 3, refusal: "approval-mismatch" })).toBe(CHANT_EXIT.moved);
+    expect(terraformPlanMoved({ command: "live-wave-apply", code: 3 })).toBe(true);
+  });
+
+  test("a plan made against another estate is a failure, and so is a root that failed", () => {
+    expect(terraformExitOf({ command: "apply", code: 3, refusal: "wrong-estate" })).toBe(CHANT_EXIT.failed);
+    expect(terraformExitOf({ command: "live-wave-apply", code: 4 })).toBe(CHANT_EXIT.failed);
+    expect(terraformExitOf({ command: "live-plan-set", code: 4 })).toBe(CHANT_EXIT.failed);
+  });
+
+  test("a plan's 2 is drift only under a drift check", () => {
+    expect(terraformExitOf({ command: "plan", code: 2 })).toBe(CHANT_EXIT.done);
+    expect(terraformExitOf({ command: "plan", code: 2, drift: true })).toBe(CHANT_EXIT.drift);
+    expect(terraformExitOf({ command: "plan", code: 1 })).toBe(CHANT_EXIT.failed);
+  });
+});

package/src/exit-codes.ts

@@ -0,0 +1,59 @@
+/**
+ * OpenTofu, Terraform and choudoufu outcomes mapped onto chant's exit-code
+ * table (#4553, `CHANT_EXIT` in `@intentius/chant/exit-codes`).
+ *
+ * The lexicon never picks the process's exit code itself: for a moved plan it
+ * throws an error core marks as moved (`planMoved: true`, read by
+ * `isPlanMovedError`), and core exits `CHANT_EXIT.moved`. This mapping says
+ * which engine outcome is which row of the table, so the throw sites and the
+ * reference page agree.
+ *
+ * | Engine outcome | Table |
+ * |---|---|
+ * | `plan -detailed-exitcode` 0 or 2 | not an exit: the plan's answer. 2 under a drift check is `drift` |
+ * | any 1 | `failed` |
+ * | choudoufu `apply <planfile>` 3, approval mismatch | `moved` |
+ * | choudoufu `apply <planfile>` 3, plan made against another estate | `failed`: the pipeline handed the wrong file, and no approval fixes that |
+ * | choudoufu `live-wave-apply` 3, set moved | `moved` |
+ * | choudoufu `live-wave-apply` 4 or `live-plan-set` 4, a root failed | `failed` |
+ * | a composed plan that moved | `moved` |
+ * | `live-affected` 2, `live-cone` 2 | planner answers, never a job's exit |
+ */
+import { CHANT_EXIT, type ChantExitCode } from "@intentius/chant/exit-codes";
+import { CHOUDOUFU_APPROVAL_EXIT_CODE, CHOUDOUFU_WAVE_EXIT, type TerraformApprovalRefusal } from "./op/activities/terraform";
+
+/** The command whose exit status is mapped. */
+export type TerraformExitSource =
+  /** `terraform|tofu|choudoufu plan -detailed-exitcode`; `drift` says a drift check asked for it. */
+  | { command: "plan"; code: number; drift?: boolean }
+  /** `choudoufu apply <planfile>` on a live root; `refusal` is `classifyApprovalRefusal`'s answer for its output. */
+  | { command: "apply"; code: number; refusal?: TerraformApprovalRefusal }
+  /** `choudoufu live-wave-apply`. */
+  | { command: "live-wave-apply"; code: number }
+  /** `choudoufu live-plan-set`. */
+  | { command: "live-plan-set"; code: number };
+
+/**
+ * The table's code for a terraform, tofu or choudoufu exit status. A plan's
+ * 0 and 2 are both `done` unless a drift check asked, when 2 is `drift`.
+ */
+export function terraformExitOf(source: TerraformExitSource): ChantExitCode {
+  const { code } = source;
+  if (code === 0) return CHANT_EXIT.done;
+  switch (source.command) {
+    case "plan":
+      if (code === 2) return source.drift ? CHANT_EXIT.drift : CHANT_EXIT.done;
+      return CHANT_EXIT.failed;
+    case "apply":
+      return code === CHOUDOUFU_APPROVAL_EXIT_CODE && source.refusal === "approval-mismatch" ? CHANT_EXIT.moved : CHANT_EXIT.failed;
+    case "live-wave-apply":
+      return code === CHOUDOUFU_WAVE_EXIT.setMoved ? CHANT_EXIT.moved : CHANT_EXIT.failed;
+    case "live-plan-set":
+      return code === 2 ? CHANT_EXIT.done : CHANT_EXIT.failed;
+  }
+}
+
+/** Whether `source` is a plan that moved since its approval: the outcomes the lexicon throws a `planMoved` error for. */
+export function terraformPlanMoved(source: TerraformExitSource): boolean {
+  return terraformExitOf(source) === CHANT_EXIT.moved;
+}

package/src/index.ts

@@ -66,6 +66,7 @@ export {
 
 // The plan shape of a `show -json` plan (#4436), for core's `coveredRound`.
 export { terraformPlanShape, type TerraformPlanShapeOptions } from "./plan-shape";
+export { terraformLockRows, terraformLockRowsFromPart, terraformDefaultLockGrain, terraformLockGrainRefusal } from "./lock-rows";
 
 // Composed runs (#4419, #4438): which roots compose, in what order, and why
 // the others fall back. Off unless `terraform.compose.enabled` is set.
@@ -208,3 +209,5 @@ export {
   type TerraformLiveRead,
   type TerraformPredictOptions,
 } from "./behaviour";
+// terraform, tofu and choudoufu exit statuses on chant's exit-code table (#4553).
+export { terraformExitOf, terraformPlanMoved, type TerraformExitSource } from "./exit-codes";

package/src/lint/audit-catalog.ts

@@ -88,10 +88,11 @@ export const terraformAuditCatalog: Record<string, RuleMeta> = {
     tier: "merge-worthy",
     fixKind: "guidance",
     category: "correctness",
-    title: "Live root declares a backend or cloud block, which choudoufu refuses",
+    title: "Live root declares a backend or cloud block, which choudoufu ignores",
     remediation:
-      "Remove the `backend`/`cloud` block from the live root's terraform block; a live root's prior " +
-      "state is a projection rebuilt from the live system every run, so there is no state to store.",
+      "Keep a `backend` block if other roots read this estate's outputs or the record store should be " +
+      "derived from its bucket; declare `record_store` to put records elsewhere. Remove a `cloud` block, " +
+      "which choudoufu drops entirely, or swap it for a `backend` block.",
     yamlBased: false,
   },
   TF025: {
@@ -551,6 +552,31 @@ export const terraformAuditCatalog: Record<string, RuleMeta> = {
       'Set `terragrunt_version_constraint = ">= 1.1.0"` in the root config. Off by default; judged only across the configs scanned.',
     yamlBased: false,
   },
+  TF046: {
+    id: "TF046",
+    tier: "report-only",
+    fixKind: "guidance",
+    category: "correctness",
+    title: "Live root resolves to the local record store in a CI run",
+    remediation:
+      "Keep or add a `backend` block of type s3, gcs or azurerm with a literal bucket, so choudoufu " +
+      "derives the record store from it, or declare `record_store` in the live block or `estate.chdf.hcl`. " +
+      "The rule is off by default and terragucci turns it on for its users; an emulator or test lane " +
+      "that keeps the local store on purpose sets `CHANT_ALLOW_LOCAL_RECORD_STORE=1`.",
+    yamlBased: false,
+  },
+  TF047: {
+    id: "TF047",
+    tier: "report-only",
+    fixKind: "guidance",
+    category: "correctness",
+    title: "Live root pins a module version the known-module catalog has no row for, or one with refusals",
+    remediation:
+      "Run `choudoufu live-check` on the root to see each refused site, or pin a version whose examples are clear in " +
+      "the static tier of choudoufu's module table (https://intentius.io/choudoufu/aws/compatibility/#modules). " +
+      "Off by default; terragucci turns it on for its users.",
+    yamlBased: false,
+  },
 };
 
 // Prior art credits, if any, live beside the rules in ./audit-lineage.ts (see

package/src/lint/audit-lineage.ts

@@ -76,8 +76,8 @@
  *
  * TF024 (#2103, live root declares a backend/cloud block) credits choudoufu's
  * own `RuleStateBackend`, `internal/live/lint/issue.go` of
- * github.com/INTENTIUS/choudoufu: the identical condition, checked the same
- * way this fork checks it at `init` before any command runs. TF025 (a live
+ * github.com/INTENTIUS/choudoufu: the same condition, which choudoufu has
+ * reported as a warning since its #2213 (the block is ignored, not refused). TF025 (a live
  * root's non-default `terraform.workspace`) has no entry: its workspace half
  * is refused at the CLI argument-parsing layer there
  * (`internal/command/live_mode.go`), not by a dedicated lint rule under
@@ -110,6 +110,18 @@
  * a root's mode, and no surveyed tool has an Op model to read: choudoufu lints
  * HCL, and every tflint ruleset, tfsec/trivy-checks and the Sentinel policies
  * do the same. There is nothing upstream to credit.
+ *
+ * TF046 (chant#4561, a live root on the local record store in a CI run) has
+ * no entry. choudoufu prints where records go on every run and reports a
+ * `record_store.note` in `live-check -json` (INTENTIUS/choudoufu#2293), but
+ * it has no `internal/live/lint` rule for the local store, and no surveyed
+ * tool knows about record stores. TF044 is the nearest neighbour, for a
+ * Terragrunt state backend.
+ *
+ * TF047 (chant#4560, a live root pins a module version the known-module
+ * catalog has no row for, or one with refusals) has no entry. Its data is
+ * choudoufu's own module table (choudoufu#2292), vendored; no surveyed tool
+ * checks a module pin against a measured compatibility table.
  */
 import type { Lineage } from "@intentius/chant/audit/catalog";
 

package/src/lint/post-synth/fixtures/TF024/live-with-record-store/main.tf

@@ -0,0 +1,18 @@
+terraform {
+  required_version = ">= 1.5.0"
+
+  live {
+    estate = "fixture-estate"
+
+    record_store "s3" {
+      bucket = "fixture-records"
+    }
+  }
+
+  backend "s3" {
+    bucket = "tfstate"
+    key    = "fixture/terraform.tfstate"
+  }
+}
+
+resource "null_resource" "first" {}

package/src/lint/post-synth/fixtures/TF024/sidecar-with-backend/estate.chdf.hcl

@@ -0,0 +1 @@
+estate = "fixture-estate"