infraweaver 0.1.0

package/src/mcp/terraform/refactor.ts

@@ -0,0 +1,879 @@
+/**
+ * Refactor equivalence proof (Phase A — the "safe floor").
+ *
+ * The `refactor` verb relocates resources behind a module boundary and asserts
+ * behaviour is unchanged. The PROOF that backs that assertion has two layers:
+ *
+ *   - the keys-free STATIC proof in this file (no cloud creds): same managed
+ *     resource set, identical per-resource argument names, and — the highest-risk
+ *     invariant — EVERY relocated address covered by a `moved {}` block, plus
+ *     `terraform validate` and `terraform fmt -check` clean. `computeEquivalence`
+ *     hard-fails on a single uncovered move: a missed `moved {}` is a silent
+ *     destroy/create on live infrastructure (a sin of commission), so the gate
+ *     must refuse rather than warn.
+ *   - the OPTIONAL stronger proof (cloud creds present): a real `terraform plan`
+ *     that is a pure-move plan (`isPureMovePlan` in plan.ts). That is corroboration
+ *     layered on top of this floor, never a substitute for it.
+ *
+ * Everything here is pure parsing + set arithmetic over file contents — the tool
+ * wrapper supplies the before-tree (via `git show <base>:<path>`) and the
+ * after-tree (the working tree on disk), mirroring moduleExtraction.ts.
+ *
+ * `moved {}` semantics anchor:
+ * https://developer.hashicorp.com/terraform/language/modules/develop/refactoring
+ *   moved { from = aws_instance.example  to = module.ec2.aws_instance.example }
+ */
+
+import { readFileSync } from "node:fs";
+import { join, posix } from "node:path";
+import { type } from "arktype";
+import { PRODUCT_NAME } from "#app/brand";
+import type { LocalToolContext } from "#app/mcp/localContext";
+import {
+  type ModuleSourceKind,
+  parseModuleBlocks,
+  walkTfFiles,
+} from "#app/mcp/modules";
+import { execute, tool, toolOk, toolSkip } from "#app/mcp/shared";
+import { scanSessionOf } from "#app/mcp/terraform/scanSession";
+import { scanFmt, scanValidate } from "#app/mcp/terraform/scanners";
+import { run } from "#app/mcp/terraform/subprocess";
+import { log } from "#app/utils/cli";
+import { resolveModuleCredentialEnv } from "#app/utils/registryAuth";
+
+// --- resource parsing with argument names (pure) -----------------------------
+
+export interface ResourceRef {
+  /** full Terraform address, module-prefixed: `module.x.aws_s3_bucket.logs`. */
+  address: string;
+  /** the resource's logical identity, module-path-independent: `aws_s3_bucket.logs`. */
+  key: string;
+  type: string;
+  name: string;
+  /** sorted top-level argument names (attributes + nested block labels). */
+  argNames: string[];
+}
+
+export interface MovedBlock {
+  from: string;
+  to: string;
+}
+
+export interface SourceFile {
+  /** repo-relative path, posix-separated. */
+  path: string;
+  hcl: string;
+}
+
+// Meta-arguments are valid on every resource and never describe behaviour we
+// compare for equivalence; mirrors RESOURCE_META_ARGUMENTS in scanners.ts.
+const META_ARGUMENTS: ReadonlySet<string> = new Set([
+  "count",
+  "for_each",
+  "provider",
+  "depends_on",
+  "lifecycle",
+  "provisioner",
+  "connection",
+]);
+
+/** strip a `"…"` string, `#`/`//` comment, or `<<EOF` heredoc starting at `i`;
+ * returns the index of the span's last char, or null when `i` isn't a span start.
+ * A compact local copy of scanners.ts's skipNonCode (not exported there) so the
+ * brace/argument scan can't be fooled by an interpolation brace or a commented `}`. */
+function skipNonCode(s: string, i: number): number | null {
+  const ch = s[i];
+  if (ch === '"') {
+    let j = i + 1;
+    while (j < s.length && s[j] !== '"') {
+      if (s[j] === "\\") j++;
+      j++;
+    }
+    return j;
+  }
+  if (ch === "<" && s[i + 1] === "<") {
+    const m = /^<<[-~]?([A-Za-z_][A-Za-z0-9_]*)/.exec(s.slice(i, i + 80));
+    if (m) {
+      const openNl = s.indexOf("\n", i);
+      if (openNl === -1) return s.length - 1;
+      const cm = new RegExp(`\\n[ \\t]*${m[1]}[ \\t]*(?=\\n|$)`).exec(
+        s.slice(openNl),
+      );
+      return cm ? openNl + cm.index + cm[0].length - 1 : s.length - 1;
+    }
+  }
+  if (ch === "#" || (ch === "/" && s[i + 1] === "/")) {
+    const nl = s.indexOf("\n", i);
+    return nl === -1 ? s.length - 1 : nl;
+  }
+  return null;
+}
+
+/** brace-match the body opened at `open`, string/comment/heredoc-aware. */
+function matchBraceBody(
+  hcl: string,
+  open: number,
+): { text: string; end: number } | null {
+  let depth = 0;
+  for (let i = open; i < hcl.length; i++) {
+    const span = skipNonCode(hcl, i);
+    if (span !== null) {
+      i = span;
+      continue;
+    }
+    const ch = hcl[i];
+    if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) return { text: hcl.slice(open + 1, i), end: i };
+    }
+  }
+  return null;
+}
+
+/** depth-0 argument names of a resource body (attributes `name =`, nested blocks
+ * `name {`, and a `dynamic "x"` block's generated label `x`), excluding
+ * meta-arguments. String/comment/heredoc-aware so an interpolation or comment
+ * can't fabricate a name. Returned sorted for stable comparison. */
+function topLevelArgNames(body: string): string[] {
+  const names = new Set<string>();
+  let depth = 0;
+  let atStmtStart = true;
+  for (let i = 0; i < body.length; i++) {
+    const span = skipNonCode(body, i);
+    if (span !== null) {
+      // a comment/heredoc ends the line; a string does not. Approximate by
+      // checking whether the span consumed a newline.
+      atStmtStart = body.slice(i, span + 1).includes("\n");
+      i = span;
+      continue;
+    }
+    const ch = body[i]!;
+    if (ch === "{") {
+      depth++;
+      atStmtStart = false;
+      continue;
+    }
+    if (ch === "}") {
+      depth--;
+      atStmtStart = false;
+      continue;
+    }
+    if (ch === "\n") {
+      atStmtStart = true;
+      continue;
+    }
+    if (ch === " " || ch === "\t" || ch === "\r") continue;
+    if (depth === 0 && atStmtStart && /[A-Za-z_]/.test(ch)) {
+      let j = i;
+      while (j < body.length && /[A-Za-z0-9_-]/.test(body[j]!)) j++;
+      const ident = body.slice(i, j);
+      let k = j;
+      while (k < body.length && (body[k] === " " || body[k] === "\t")) k++;
+      const next = body[k];
+      if (next === "=" && body[k + 1] !== "=") {
+        if (!META_ARGUMENTS.has(ident)) names.add(ident);
+      } else if (next === "{") {
+        if (!META_ARGUMENTS.has(ident)) names.add(ident);
+      } else if (next === '"' && ident === "dynamic") {
+        const labelEnd = body.indexOf('"', k + 1);
+        if (labelEnd !== -1) names.add(body.slice(k + 1, labelEnd));
+      }
+      i = j - 1;
+      atStmtStart = false;
+      continue;
+    }
+    atStmtStart = false;
+  }
+  return [...names].sort();
+}
+
+/** parse every `resource "<type>" "<name>" { … }` block's type, name, and
+ * top-level argument names from one file. */
+function parseResourcesWithArgs(
+  hcl: string,
+): { type: string; name: string; argNames: string[] }[] {
+  const out: { type: string; name: string; argNames: string[] }[] = [];
+  const re = /(?:^|\n)\s*resource\s+"([^"]+)"\s+"([^"]+)"\s*\{/g;
+  let m: RegExpExecArray | null;
+  // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex-exec iteration
+  while ((m = re.exec(hcl)) !== null) {
+    const [, resourceType = "", name = ""] = m;
+    const braceStart = hcl.indexOf("{", m.index);
+    if (braceStart === -1) break;
+    const body = matchBraceBody(hcl, braceStart);
+    if (!body) break;
+    re.lastIndex = body.end + 1;
+    out.push({
+      type: resourceType,
+      name,
+      argNames: topLevelArgNames(body.text),
+    });
+  }
+  return out;
+}
+
+// --- moved {} block parsing (pure) -------------------------------------------
+
+/**
+ * Parse every top-level `moved { from = <addr>  to = <addr> }` block from HCL.
+ * Addresses are unquoted Terraform traversals (`module.x.aws_s3_bucket.logs`,
+ * `aws_instance.example[0]`), so the value is captured raw up to the line end or
+ * a trailing comment. Brace-matched so a stray `{}` in a comment can't fool it.
+ * A block missing either `from` or `to` is skipped (incomplete, not a relocation).
+ */
+export function parseMovedBlocks(hcl: string): MovedBlock[] {
+  const out: MovedBlock[] = [];
+  const re = /(?:^|\n)\s*moved\s*\{/g;
+  let m: RegExpExecArray | null;
+  // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex-exec iteration
+  while ((m = re.exec(hcl)) !== null) {
+    const braceStart = hcl.indexOf("{", m.index);
+    if (braceStart === -1) break;
+    const body = matchBraceBody(hcl, braceStart);
+    if (!body) break;
+    re.lastIndex = body.end + 1;
+    // capture the address TOKEN after `from =` / `to =` — a run of address
+    // characters terminated by whitespace, `}`, or a comment. Token-based (not
+    // line-based) so a single-line `moved { from = a  to = b }` parses as well as
+    // the multi-line form. `\bfrom\b`/`\bto\b` anchor on the keyword, not a
+    // substring of an address.
+    const from = body.text.match(/\bfrom\b\s*=\s*([^\s}#]+)/)?.[1];
+    const to = body.text.match(/\bto\b\s*=\s*([^\s}#]+)/)?.[1];
+    if (from && to)
+      out.push({ from: normaliseAddress(from), to: normaliseAddress(to) });
+  }
+  return out;
+}
+
+/** collapse incidental whitespace so two spellings of the same address compare
+ * equal (`module.x . aws_s3_bucket.logs` is not valid HCL, but defensive). */
+export function normaliseAddress(addr: string): string {
+  return addr
+    .trim()
+    .replace(/\s*\.\s*/g, ".")
+    .replace(/\s+/g, " ");
+}
+
+// --- module attribution (pure) -----------------------------------------------
+
+/** the leaf `<type>.<name>` of an address, stripping leading `module.X.` hops and
+ * any `[index]`/`["key"]` instance suffix. `module.db.aws_db_instance.main[0]`
+ * → `aws_db_instance.main`. */
+export function addressKey(address: string): string {
+  const noModules = address.replace(/^(?:module\.[^.]+\.)+/, "");
+  return noModules.replace(/\[[^\]]*\]$/, "");
+}
+
+interface ModuleCall {
+  /** repo-relative posix dir the local module's source resolves to. */
+  dir: string;
+  callName: string;
+}
+
+/** resolve every `module "<name>" { source = "./local/path" }` call to the dir
+ * its `.tf` files live in (local sources only — registry/git modules have no
+ * in-tree files to attribute). */
+function localModuleCalls(files: SourceFile[]): ModuleCall[] {
+  const calls: ModuleCall[] = [];
+  for (const f of files) {
+    for (const block of parseModuleBlocks(f.hcl)) {
+      if (block.kind !== "local") continue;
+      const dir = posix
+        .normalize(posix.join(posix.dirname(f.path), block.source))
+        .replace(/\/+$/, "");
+      calls.push({ dir, callName: block.name });
+    }
+  }
+  return calls;
+}
+
+/** true when `file` lives inside module `dir` (or a nested file under it). */
+function fileInDir(file: string, dir: string): boolean {
+  return dir === "."
+    ? !file.includes("/")
+    : file === dir || file.startsWith(`${dir}/`);
+}
+
+/**
+ * Attribute every resource in a file tree to its full Terraform address.
+ * A resource in a file under a single-caller local module dir is prefixed
+ * `module.<caller>.`; a resource at root keeps its bare `<type>.<name>`. A module
+ * dir with MULTIPLE callers (instantiated more than once) or NESTED module dirs
+ * can't be attributed to one address deterministically — those resources are
+ * returned in `ambiguous` so the caller degrades honestly rather than asserting a
+ * false address. Pure.
+ */
+export function attributeAddresses(files: SourceFile[]): {
+  resources: ResourceRef[];
+  ambiguous: string[];
+} {
+  const calls = localModuleCalls(files);
+  const callersByDir = new Map<string, string[]>();
+  for (const c of calls) {
+    callersByDir.set(c.dir, [...(callersByDir.get(c.dir) ?? []), c.callName]);
+  }
+  const resources: ResourceRef[] = [];
+  const ambiguous: string[] = [];
+  for (const f of files) {
+    // the longest module dir that contains this file (handles `modules/x` vs
+    // `modules/x/sub` — the deepest wins).
+    const owningDirs = [...callersByDir.keys()]
+      .filter((dir) => fileInDir(f.path, dir))
+      .sort((a, b) => b.length - a.length);
+    const owningDir = owningDirs[0];
+    for (const r of parseResourcesWithArgs(f.hcl)) {
+      const key = `${r.type}.${r.name}`;
+      if (!owningDir) {
+        resources.push({
+          address: key,
+          key,
+          type: r.type,
+          name: r.name,
+          argNames: r.argNames,
+        });
+        continue;
+      }
+      const callers = callersByDir.get(owningDir) ?? [];
+      // a nested module dir (file owned by a dir that is itself under another
+      // module dir) or a multi-instantiated module yields >1 viable prefix.
+      if (callers.length !== 1 || owningDirs.length > 1) {
+        ambiguous.push(`${owningDir}:${key}`);
+        continue;
+      }
+      const address = `module.${callers[0]}.${key}`;
+      resources.push({
+        address,
+        key,
+        type: r.type,
+        name: r.name,
+        argNames: r.argNames,
+      });
+    }
+  }
+  return { resources, ambiguous };
+}
+
+// --- the equivalence computation (pure) --------------------------------------
+
+export interface EquivalenceResult {
+  /** the overall keys-free verdict: all sub-checks below passed. The push
+   * guardrail hard-blocks when this is false. */
+  equivalent: boolean;
+  /** same multiset of `<type>.<name>` across the whole tree before and after. */
+  resource_set_equivalent: boolean;
+  /** identical top-level argument names for every resource present in both. */
+  arg_names_equivalent: boolean;
+  /** every relocated address is covered by a `moved {}` block (zero uncovered).
+   * THE highest-risk invariant — a false here means a silent destroy/create. */
+  moves_exhaustive: boolean;
+  /** count of address relocations detected between before and after. */
+  moves_detected: number;
+  /** the relocations we detected (the authoritative move set). */
+  expected_moves: MovedBlock[];
+  /** relocations with NO matching `moved {}` block — the hard-fail set. */
+  uncovered_moves: MovedBlock[];
+  /** `moved {}` blocks that match no detected relocation (likely a typo'd
+   * `to`/`from` — surfaced, but not on its own a hard-fail). */
+  spurious_moved_blocks: MovedBlock[];
+  /** logical keys added / removed between before and after (must be empty for
+   * an equivalence-preserving refactor; a non-empty `added` is the b.4 "adopting
+   * a module adds a KMS key" signal — that's an ALTERING change, not equivalence). */
+  resource_set_diff: { added: string[]; removed: string[] };
+  /** per-resource argument-name drift. */
+  arg_diffs: { resource: string; added: string[]; removed: string[] }[];
+  /** addresses that couldn't be attributed deterministically (multi-instantiated
+   * or nested modules) — equivalence is reported but flagged incomplete. */
+  ambiguous: string[];
+  /** human-readable reasons the verdict is what it is. */
+  reasons: string[];
+}
+
+/** multiset of a list of keys → Map<key, count>. */
+function multiset(keys: string[]): Map<string, number> {
+  const m = new Map<string, number>();
+  for (const k of keys) m.set(k, (m.get(k) ?? 0) + 1);
+  return m;
+}
+
+/**
+ * Compute the keys-free equivalence verdict from the before/after resource
+ * address sets and the `moved {}` blocks present in the after tree. Validate/fmt
+ * results are merged in by the tool wrapper (they need a subprocess); this pure
+ * core proves the three static invariants — resource-set preservation, argument
+ * preservation, and moved-block exhaustiveness.
+ */
+export function computeEquivalence(
+  before: ResourceRef[],
+  after: ResourceRef[],
+  movedBlocks: MovedBlock[],
+  ambiguous: string[] = [],
+): EquivalenceResult {
+  const reasons: string[] = [];
+
+  // 1. resource-set preservation (multiset of logical keys).
+  const beforeKeys = multiset(before.map((r) => r.key));
+  const afterKeys = multiset(after.map((r) => r.key));
+  const added: string[] = [];
+  const removed: string[] = [];
+  for (const [k, n] of afterKeys)
+    if (n > (beforeKeys.get(k) ?? 0)) added.push(k);
+  for (const [k, n] of beforeKeys)
+    if (n > (afterKeys.get(k) ?? 0)) removed.push(k);
+  added.sort();
+  removed.sort();
+  const resourceSetEquivalent = added.length === 0 && removed.length === 0;
+  if (added.length > 0)
+    reasons.push(
+      `resource set GAINED ${added.length} resource(s): ${added.join(", ")}`,
+    );
+  if (removed.length > 0)
+    reasons.push(
+      `resource set LOST ${removed.length} resource(s): ${removed.join(", ")}`,
+    );
+
+  // 2. argument-name preservation per logical key (compare the union of
+  // arg-name sets for each key — robust to count>1 without false drift).
+  const argDiffs: EquivalenceResult["arg_diffs"] = [];
+  const argsByKey = (refs: ResourceRef[]) => {
+    const m = new Map<string, Set<string>>();
+    for (const r of refs) {
+      const set = m.get(r.key) ?? new Set<string>();
+      for (const a of r.argNames) set.add(a);
+      m.set(r.key, set);
+    }
+    return m;
+  };
+  const beforeArgs = argsByKey(before);
+  const afterArgs = argsByKey(after);
+  for (const key of new Set([...beforeArgs.keys(), ...afterArgs.keys()])) {
+    const b = beforeArgs.get(key) ?? new Set<string>();
+    const a = afterArgs.get(key) ?? new Set<string>();
+    const gained = [...a].filter((x) => !b.has(x)).sort();
+    const lost = [...b].filter((x) => !a.has(x)).sort();
+    if (gained.length > 0 || lost.length > 0)
+      argDiffs.push({ resource: key, added: gained, removed: lost });
+  }
+  const argNamesEquivalent = argDiffs.length === 0;
+  if (argDiffs.length > 0)
+    reasons.push(
+      `argument drift on ${argDiffs.length} resource(s): ${argDiffs.map((d) => d.resource).join(", ")}`,
+    );
+
+  // 3. moved-block exhaustiveness — pair each logical key's before/after
+  // addresses; a key whose address changed is a relocation that MUST be covered.
+  const addrsByKey = (refs: ResourceRef[]) => {
+    const m = new Map<string, string[]>();
+    for (const r of refs) m.set(r.key, [...(m.get(r.key) ?? []), r.address]);
+    return m;
+  };
+  const beforeAddrs = addrsByKey(before);
+  const afterAddrs = addrsByKey(after);
+  const expected: MovedBlock[] = [];
+  for (const [key, bAddrs] of beforeAddrs) {
+    const aAddrs = afterAddrs.get(key) ?? [];
+    // froms = before addresses not still present after; tos = new addresses.
+    const froms = bAddrs.filter((x) => !aAddrs.includes(x));
+    const tos = aAddrs.filter((x) => !bAddrs.includes(x));
+    // pair positionally (the 1:1 mechanical-extraction case is exact); any
+    // surplus on either side is an ambiguous relocation flagged below.
+    const pairs = Math.min(froms.length, tos.length);
+    for (let i = 0; i < pairs; i++)
+      expected.push({ from: froms[i]!, to: tos[i]! });
+    if (froms.length !== tos.length)
+      reasons.push(
+        `ambiguous relocation for ${key} (${froms.length} from / ${tos.length} to)`,
+      );
+  }
+  const moveKey = (mv: MovedBlock) => `${mv.from}=>${mv.to}`;
+  const movedSet = new Set(movedBlocks.map(moveKey));
+  const expectedSet = new Set(expected.map(moveKey));
+  const uncovered = expected.filter((mv) => !movedSet.has(moveKey(mv)));
+  const spurious = movedBlocks.filter((mv) => !expectedSet.has(moveKey(mv)));
+  const movesExhaustive = uncovered.length === 0;
+  if (uncovered.length > 0)
+    reasons.push(
+      `${uncovered.length} relocated resource(s) have NO \`moved {}\` block — ` +
+        `this would DESTROY and RECREATE them on apply: ${uncovered.map((u) => u.from).join(", ")}`,
+    );
+  if (spurious.length > 0)
+    reasons.push(
+      `${spurious.length} \`moved {}\` block(s) match no detected relocation (check from/to): ${spurious.map(moveKey).join(", ")}`,
+    );
+  if (ambiguous.length > 0)
+    reasons.push(
+      `${ambiguous.length} resource(s) in multi-instantiated/nested modules couldn't be attributed — equivalence is incomplete for: ${ambiguous.join(", ")}`,
+    );
+
+  const equivalent =
+    resourceSetEquivalent &&
+    argNamesEquivalent &&
+    movesExhaustive &&
+    ambiguous.length === 0;
+
+  return {
+    equivalent,
+    resource_set_equivalent: resourceSetEquivalent,
+    arg_names_equivalent: argNamesEquivalent,
+    moves_exhaustive: movesExhaustive,
+    moves_detected: expected.length,
+    expected_moves: expected,
+    uncovered_moves: uncovered,
+    spurious_moved_blocks: spurious,
+    resource_set_diff: { added, removed },
+    arg_diffs: argDiffs,
+    ambiguous,
+    reasons,
+  };
+}
+
+// --- moved {} block generation (pure) — A2 -----------------------------------
+
+/**
+ * Generate one `moved {}` block per resource being relocated under a module call,
+ * and the authoritative `expected_moves` list (the denominator
+ * `computeEquivalence` checks coverage against). Each input address keeps its
+ * leaf `<type>.<name>[index]`; the new address prefixes it with `module.<to_module>.`.
+ * Works for root→module and module→module — the
+ * leaf is taken after stripping any existing `module.X.` hops.
+ */
+export function generateMovedBlocks(
+  addresses: string[],
+  toModule: string,
+): { hcl: string; expected_moves: MovedBlock[] } {
+  const moves: MovedBlock[] = [];
+  for (const raw of addresses) {
+    const from = normaliseAddress(raw);
+    if (!from) continue;
+    const leaf = from.replace(/^(?:module\.[^.]+\.)+/, "");
+    moves.push({ from, to: `module.${toModule}.${leaf}` });
+  }
+  const hcl = moves
+    .map((mv) => `moved {\n  from = ${mv.from}\n  to   = ${mv.to}\n}`)
+    .join("\n\n");
+  return { hcl, expected_moves: moves };
+}
+
+// --- module provenance (pure) — C3 -------------------------------------------
+
+export interface ModuleProvenance {
+  /** the local `module "<name>"` call name. */
+  name: string;
+  source: string;
+  /** the pinned version (registry `version`, or a git `?ref=`), or null. */
+  version: string | null;
+  kind: ModuleSourceKind;
+  /** true when the source is pinned to an exact version/ref — the provenance
+   * discipline for adopting a third-party module (the analog to a SHA-pinned
+   * action). An unpinned external module is a supply-chain risk to flag. */
+  pinned: boolean;
+}
+
+/**
+ * Record the provenance of every EXTERNAL module the config calls (registry /
+ * git / remote — local modules have in-tree code, no provenance to record).
+ * Used by the refactor b.4 evidence: "adopted `<source>` at `<version>`",
+ * with `pinned` flagging an unpinned adoption. Pure over the file tree.
+ */
+export function collectModuleProvenance(
+  files: SourceFile[],
+): ModuleProvenance[] {
+  const out: ModuleProvenance[] = [];
+  const seen = new Set<string>();
+  for (const f of files) {
+    for (const b of parseModuleBlocks(f.hcl)) {
+      if (b.kind === "local") continue;
+      const key = `${b.name}|${b.source}|${b.version ?? ""}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push({
+        name: b.name,
+        source: b.source,
+        version: b.version,
+        kind: b.kind,
+        pinned: b.version !== null,
+      });
+    }
+  }
+  return out;
+}
+
+/** read the workspace's `.tf`/`.tfvars` tree and record external-module
+ * provenance (the impure wrapper the evidence bundle calls). */
+export function collectWorkspaceProvenance(cwd: string): ModuleProvenance[] {
+  return collectModuleProvenance(readWorkingTree(cwd));
+}
+
+// --- the `proposed — unproven` honesty primitive — C4 ------------------------
+
+/** the GitHub label an UNPROVEN b.4 change carries so it is never mistaken for a
+ * proven one. Applied to the PR and surfaced in the evidence bundle. */
+export const PROPOSED_UNPROVEN_LABEL = "proposed-unproven";
+
+/**
+ * The unmissable PR-body banner for a behaviour-ALTERING b.4 change that ran
+ * WITHOUT opt-in read creds (the default): Infraweaver proposes the change but
+ * proves nothing about its runtime effect. It must never silently read as a
+ * proven/equivalence change. Used verbatim at the top of such a PR's body and
+ * mirrored as the `proposed_unproven` marker in the evidence bundle.
+ */
+export const PROPOSED_UNPROVEN_BANNER =
+  "> [!CAUTION]\n" +
+  "> **proposed — unproven.** This change adopts a third-party module: it ALTERS behaviour " +
+  "(it can change defaults and add or remove resources), so equivalence is false and is NOT claimed. " +
+  `No \`terraform plan\` was run (no read-only state was supplied), so ${PRODUCT_NAME} asserts nothing about ` +
+  "its runtime effect — **review the plan yourself before merging.**";
+
+// --- tool wiring -------------------------------------------------------------
+
+/** read the `.tf`/`.tfvars` tree at a git ref into memory (the before-state).
+ * Returns null when the ref or git is unavailable (degrade to "no baseline"). */
+function readTreeAtRef(cwd: string, ref: string): SourceFile[] | null {
+  const list = run("git", ["ls-tree", "-r", "--name-only", ref], cwd);
+  if (list.status !== 0) return null;
+  const files: SourceFile[] = [];
+  for (const raw of list.stdout.split("\n")) {
+    const path = raw.trim().replace(/\\/g, "/");
+    if (!path.endsWith(".tf") && !path.endsWith(".tfvars")) continue;
+    const show = run("git", ["show", `${ref}:${path}`], cwd);
+    if (show.status === 0) files.push({ path, hcl: show.stdout });
+  }
+  return files;
+}
+
+/** read the working-tree `.tf`/`.tfvars` files on disk (the after-state) —
+ * the working tree, including the agent's uncommitted edits. */
+function readWorkingTree(cwd: string): SourceFile[] {
+  const files: SourceFile[] = [];
+  for (const rel of walkTfFiles(cwd)) {
+    if (!rel.endsWith(".tf") && !rel.endsWith(".tfvars")) continue;
+    try {
+      files.push({
+        path: rel.replace(/\\/g, "/"),
+        hcl: readFileSync(join(cwd, rel), "utf8"),
+      });
+    } catch {
+      /* skip unreadable file */
+    }
+  }
+  return files;
+}
+
+/** the mode that remediates AND refactors on one branch — its refactor half is
+ * measured against the COMMITTED fix, not the run-start commit (see below). */
+const REMEDIATE_AND_REFACTOR_MODE = "RemediateAndRefactor";
+
+/** resolve the commit the refactor's equivalence is measured against. Normally
+ * the run-start commit (mirrors guardrails.runStartSha), so the before-tree is
+ * exactly the state this run began from. In the combined Remediate+Refactor mode
+ * the remediation fix is COMMITTED before the refactor begins, so the baseline is
+ * that post-fix commit (the current HEAD): the fix's argument changes are the
+ * refactor's starting point and must NOT be counted against its equivalence. */
+function resolveBaseSha(ctx: LocalToolContext, cwd: string): string | null {
+  if (ctx.toolState.selectedMode === REMEDIATE_AND_REFACTOR_MODE) {
+    const r = run("git", ["rev-parse", "HEAD"], cwd);
+    return r.status === 0 && r.stdout.trim() ? r.stdout.trim() : null;
+  }
+  const head = ctx.toolState.initialHead;
+  if (!head) return null;
+  const ref = head.kind === "branch" ? head.name : head.sha;
+  const r = run("git", ["rev-parse", ref], cwd);
+  return r.status === 0 && r.stdout.trim() ? r.stdout.trim() : null;
+}
+
+export const TerraformEquivalenceCheckParams = type({});
+
+export function TerraformEquivalenceCheckTool(ctx: LocalToolContext) {
+  return tool({
+    name: "terraform_equivalence_check",
+    description:
+      "Keys-free EQUIVALENCE PROOF for a `refactor` PR (no cloud credentials). Compares the working tree " +
+      "against the run-start commit and proves the refactor preserved behaviour: (1) the same multiset of " +
+      "managed resources, (2) identical top-level argument names per resource, and (3) — the highest-risk " +
+      "invariant — that EVERY relocated address is covered by a `moved {}` block (zero uncovered moves), " +
+      "then runs `terraform validate` + `terraform fmt -check`. Returns `equivalent` (the overall verdict; " +
+      "the push guardrail HARD-BLOCKS when false), plus `uncovered_moves` (a missed `moved {}` = a silent " +
+      "destroy/recreate on apply — fix before pushing), `expected_moves`, `resource_set_diff`, and " +
+      "`arg_diffs`. For a behaviour-ALTERING change (b.4, adopting a third-party module) equivalence is " +
+      "expected to be false — do not claim it. Optional stronger proof: a real `terraform_plan` that is a " +
+      "pure-move plan (`refactor_safe: true`) corroborates this floor when cloud creds are present.",
+    parameters: TerraformEquivalenceCheckParams,
+    execute: execute(async () => {
+      const cwd = ctx.payload.cwd ?? process.cwd();
+      const base = resolveBaseSha(ctx, cwd);
+      if (!base) {
+        return toolSkip(
+          "no_baseline",
+          "could not resolve the run-start commit — an equivalence proof needs the before-state to diff against. Ensure the run started from a clean git checkout.",
+        );
+      }
+      // Combined Remediate+Refactor: the baseline is the COMMITTED fix, so the
+      // refactor edits must still be UNCOMMITTED for this to measure anything. A
+      // clean working tree here means the refactor wasn't made yet, or was
+      // committed before proving — either way diffing the baseline against an
+      // identical working tree would vacuously report `equivalent: true`. Refuse
+      // that false positive rather than emit a proof of nothing.
+      if (
+        ctx.toolState.selectedMode === REMEDIATE_AND_REFACTOR_MODE &&
+        changedFilesSinceBase(cwd, base).length === 0
+      ) {
+        return toolSkip(
+          "refactor_uncommitted_required",
+          "combined Remediate+Refactor: the equivalence proof diffs the working tree against the COMMITTED fix, but the working tree has no uncommitted changes. Commit the fix first, then make the refactor edits, then run this check BEFORE committing them.",
+        );
+      }
+      const beforeFiles = readTreeAtRef(cwd, base);
+      if (!beforeFiles) {
+        return toolSkip(
+          "no_baseline",
+          `could not read the Terraform tree at ${base.slice(0, 8)} — equivalence cannot be proven without the before-state.`,
+        );
+      }
+      const afterFiles = readWorkingTree(cwd);
+
+      const before = attributeAddresses(beforeFiles);
+      const after = attributeAddresses(afterFiles);
+      // `moved {}` blocks live in ROOT files (a module can't relocate its own
+      // caller's addresses), so collect them from after files NOT inside a module.
+      const afterCalls = new Set(
+        afterFiles.flatMap((f) =>
+          parseModuleBlocks(f.hcl)
+            .filter((b) => b.kind === "local")
+            .map((b) =>
+              posix
+                .normalize(posix.join(posix.dirname(f.path), b.source))
+                .replace(/\/+$/, ""),
+            ),
+        ),
+      );
+      const rootFiles = afterFiles.filter(
+        (f) => ![...afterCalls].some((dir) => fileInDir(f.path, dir)),
+      );
+      const movedBlocks = rootFiles.flatMap((f) => parseMovedBlocks(f.hcl));
+
+      const result = computeEquivalence(
+        before.resources,
+        after.resources,
+        movedBlocks,
+        [...new Set([...before.ambiguous, ...after.ambiguous])],
+      );
+
+      // validate + fmt (the keys-free proof's correctness gates). The credentials
+      // let a private cross-repo `git::` module or a private-registry module
+      // resolve during init, mirroring validate.
+      const terraformEnv = resolveModuleCredentialEnv(ctx.payload, {
+        sshKeyDir: ctx.tmpdir,
+      });
+      const fmtOutcome = scanFmt(cwd);
+      const validateOutcome = scanValidate(cwd, terraformEnv);
+      const validateRan = validateOutcome.ran;
+      const validatePassed =
+        validateRan &&
+        validateOutcome.concerns.length === 0 &&
+        (validateOutcome.unvalidated ?? 0) === 0;
+      // fmt-clean is scoped to the files this run changed — pre-existing drift in
+      // untouched files is not the refactor's to fix and must not fail its proof.
+      const changed = new Set(changedFilesSinceBase(cwd, base));
+      const fmtDriftFiles = [
+        ...new Set(
+          fmtOutcome.concerns
+            .map((c) => c.location.file)
+            .filter((f) => changed.size === 0 || changed.has(f)),
+        ),
+      ];
+      const fmtClean = fmtOutcome.ran && fmtDriftFiles.length === 0;
+
+      const reasons = [...result.reasons];
+      if (!validatePassed)
+        reasons.push(
+          validateRan
+            ? "`terraform validate` did not pass"
+            : "`terraform validate` did not run (terraform not installed) — the equivalence proof is incomplete",
+        );
+      if (!fmtClean && fmtOutcome.ran && fmtDriftFiles.length > 0)
+        reasons.push(
+          `\`terraform fmt\` reports drift in changed file(s): ${fmtDriftFiles.join(", ")}`,
+        );
+
+      const equivalent = result.equivalent && validatePassed && fmtClean;
+
+      // record for the push-time hard-fail guardrail (read in guardrails.ts) and
+      // the evidence bundle (read in terraform_emit_evidence).
+      scanSessionOf(ctx.toolState).refactorEquivalence = {
+        equivalent,
+        resource_set_equivalent: result.resource_set_equivalent,
+        arg_names_equivalent: result.arg_names_equivalent,
+        moves_exhaustive: result.moves_exhaustive,
+        moves_detected: result.moves_detected,
+        validate_passed: validatePassed,
+        fmt_clean: fmtClean,
+        uncovered_moves: result.uncovered_moves,
+        reasons,
+      };
+
+      log.info(
+        `» terraform_equivalence_check: equivalent=${equivalent} (moves ${result.expected_moves.length}, uncovered ${result.uncovered_moves.length}, resource-set ${result.resource_set_equivalent}, args ${result.arg_names_equivalent}, validate ${validatePassed}, fmt ${fmtClean})`,
+      );
+
+      return toolOk({
+        ...result,
+        equivalent,
+        validate_passed: validatePassed,
+        validate_ran: validateRan,
+        fmt_clean: fmtClean,
+        fmt_drift_files: fmtDriftFiles,
+        base: base.slice(0, 8),
+        reasons,
+        note: equivalent
+          ? "behaviour-preserving refactor PROVEN (keys-free). For the stronger proof, run terraform_plan — refactor_safe:true corroborates it."
+          : "NOT equivalent — the push will be blocked. Fix the issues in `reasons` (an uncovered move is the dangerous one — add the missing `moved {}` block).",
+      });
+    }),
+  });
+}
+
+/** files changed (tracked) between the base commit and the working tree. */
+function changedFilesSinceBase(cwd: string, base: string): string[] {
+  const r = run("git", ["diff", "--name-only", base], cwd);
+  if (r.status !== 0) return [];
+  return r.stdout
+    .split("\n")
+    .map((l) => l.trim().replace(/\\/g, "/"))
+    .filter(Boolean);
+}
+
+export const TerraformGenerateMovedParams = type({
+  resources: type.string
+    .array()
+    .describe(
+      "the CURRENT addresses of the resources being relocated, e.g. ['aws_s3_bucket.logs', 'aws_s3_bucket_policy.logs'] (root) or ['module.old.aws_vpc.main'] (module→module).",
+    ),
+  to_module: type.string.describe(
+    'the local name of the `module "<name>"` call the resources are moving INTO (the new address prefix).',
+  ),
+});
+
+export function TerraformGenerateMovedTool(ctx: LocalToolContext) {
+  return tool({
+    name: "terraform_generate_moved",
+    description:
+      "Generate the EXHAUSTIVE `moved {}` blocks for a resources→module refactor — one per relocated " +
+      "address (old → `module.<to_module>.<leaf>`), so the move set is complete by construction. Returns " +
+      "the ready-to-paste `hcl` (put it in a ROOT file) and `expected_moves` (the authoritative mapping " +
+      "`terraform_equivalence_check` verifies coverage against). A missing `moved {}` block is the single " +
+      "highest-risk refactor defect (a silent destroy/recreate) — generate them here rather than hand-" +
+      "writing so none is forgotten.",
+    parameters: TerraformGenerateMovedParams,
+    // pure string generation — no state change, safe for subagents.
+    execute: execute(async ({ resources, to_module }) => {
+      void ctx;
+      const { hcl, expected_moves } = generateMovedBlocks(resources, to_module);
+      return toolOk({
+        count: expected_moves.length,
+        expected_moves,
+        hcl,
+        note: "paste `hcl` into a root .tf file, then prove the refactor with terraform_equivalence_check (and terraform_plan when cloud creds are available).",
+      });
+    }),
+  });
+}