@intentius/chant 0.41.20 → 0.44.1

package/src/cli/commands/build.ts

@@ -3,7 +3,7 @@ import { loadChantConfigUpward, resolveOwnershipMarker, resolveFoldEnabled, reso
 import { resolveCliBuildParams } from "../build-params-cli";
 import type { Serializer, SerializerResult } from "../../serializer";
 import type { LexiconPlugin } from "../../lexicon";
-import { resolveLexiconVersions } from "../plugins";
+import { resolveLexiconVersions, collectBuildRootContributors } from "../plugins";
 import { runPostSynthChecks } from "../../lint/post-synth";
 import { applyConfiguredSeverity } from "../../lint/config";
 import { loadPolicyChecks } from "../../lint/policy";
@@ -261,6 +261,14 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
     lexicons,
     lexiconVersions,
     buildParams: paramsResolution.provenance,
+    // #1548 piece 3 — config-declared build roots (kustomize dirs), rendered
+    // into entities by the owning lexicon's hook. Rooted at the config dir,
+    // not the (possibly sourceDir-scoped) infra path.
+    buildRoots: collectBuildRootContributors(
+      options.plugins,
+      config as unknown as Record<string, unknown>,
+      configDir,
+    ),
   });
 
   // #1022 — report per-file fold vs run so it's visible what still runs.

package/src/cli/commands/carve-apply.test.ts

@@ -4,6 +4,7 @@ import { tmpdir } from "os";
 import { join } from "path";
 import { carveApply, formatCarveApply } from "./carve-apply";
 import { loadHcl2json } from "../../terraform/parse";
+import { readCarveManifest, writeCarveManifest, type CarveManifest } from "../../terraform/manifest";
 
 let parserAvailable = false;
 try {
@@ -30,10 +31,101 @@ async function withEstate<T>(fn: (dir: string) => Promise<T>): Promise<T> {
   }
 }
 
+function manifestFor(target: string, dir: string): CarveManifest {
+  return {
+    version: 1,
+    target,
+    from: dir,
+    boundary: {
+      target,
+      carveSet: [{ address: target, type: target.split(".")[0] }],
+      peelability: 90,
+      inbound: [],
+      outbound: [],
+      reversible: true,
+      diagnostics: [],
+    },
+  };
+}
+
 describe("carveApply", () => {
-  test("requires --from and --select", async () => {
+  test("requires --from; without --select it needs a carve manifest", async () => {
     expect((await carveApply({})).error).toContain("--from");
-    expect((await carveApply({ from: "/x" })).error).toContain("--select");
+    await withEstate(async (dir) => {
+      const res = await carveApply({ from: dir });
+      expect(res.ok).toBe(false);
+      expect(res.error).toContain("--select");
+    });
+  });
+
+  test("composes with the carve manifest: target resolved without --select, graduation recorded", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const out = join(dir, "carveout");
+      writeCarveManifest(out, manifestFor("aws_s3_bucket.assets", dir));
+
+      const res = await carveApply({ from: dir, output: out, env: "prod", stack: "assets" });
+      expect(res.ok).toBe(true);
+      expect(res.selectFromManifest).toBe(true);
+      expect(formatCarveApply(res)).toContain("target from the carve manifest");
+
+      const m = readCarveManifest(res.manifestPath!)!;
+      expect(m.apply!.marker).toEqual({ stack: "assets", env: "prod" });
+      expect(m.apply!.ownershipTags["chant:managed-by"]).toBe("chant");
+    });
+  });
+
+  test("--write-source stamps the ownership marker into the emitted source and records it", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const out = join(dir, "carveout");
+      const emitted = join(out, "assets.ts");
+      const manifest = manifestFor("aws_s3_bucket.assets", dir);
+      manifest.emit = { source: "tfstate", files: [emitted], at: "t" };
+      writeCarveManifest(out, manifest);
+      writeFileSync(emitted, 'export const assets = new Bucket({\n  BucketName: "myapp-assets-prod",\n});\n');
+
+      const res = await carveApply({ from: dir, output: out, env: "prod", stack: "assets", writeSource: true });
+      expect(res.ok).toBe(true);
+      expect(res.stamped).toEqual([emitted]);
+
+      const stamped = readFileSync(emitted, "utf-8");
+      expect(stamped).toContain('{"Key":"chant:managed-by","Value":"chant"}');
+      expect(stamped).toContain('{"Key":"chant:stack","Value":"assets"}');
+      expect(stamped).toContain('{"Key":"chant:env","Value":"prod"}');
+
+      const m = readCarveManifest(res.manifestPath!)!;
+      expect(m.apply!.stampedFiles).toEqual([emitted]);
+      expect(formatCarveApply(res)).toContain("Stamped the ownership marker into");
+
+      // Idempotent: a second graduation leaves the source stable.
+      const again = await carveApply({ from: dir, output: out, env: "prod", stack: "assets", writeSource: true });
+      expect(again.ok).toBe(true);
+      expect(readFileSync(emitted, "utf-8")).toBe(stamped);
+    });
+  });
+
+  test("--write-source without an emit record in the manifest is a clear error", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const out = join(dir, "carveout");
+      writeCarveManifest(out, manifestFor("aws_s3_bucket.assets", dir));
+      const res = await carveApply({ from: dir, output: out, env: "prod", writeSource: true });
+      expect(res.ok).toBe(false);
+      expect(res.error).toContain("carve emit");
+    });
+  });
+
+  test("falls back to the manifest's persisted boundary when the block is already excised", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const out = join(dir, "carveout");
+      writeCarveManifest(out, manifestFor("aws_s3_bucket.gone", dir));
+
+      const res = await carveApply({ from: dir, output: out, env: "prod" });
+      expect(res.ok).toBe(true);
+      expect(res.plan!.target).toBe("aws_s3_bucket.gone");
+    });
   });
 
   test("plans graduation with ownership marker; writes nothing by default", async () => {

package/src/cli/commands/carve-apply.ts

@@ -9,14 +9,16 @@
  * lifecycle you brought.
  */
 
-import { existsSync, statSync, mkdirSync, writeFileSync } from "fs";
+import { existsSync, statSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { join } from "path";
 import { parseTerraformDir, Hcl2JsonNotInstalled } from "../../terraform/parse";
 import { boundaryReport } from "../../terraform/carve";
-import { graduationPlan, type GraduationPlan } from "../../terraform/graduate";
+import { graduationPlan, stampOwnershipIntoSource, type GraduationPlan } from "../../terraform/graduate";
+import { resolveCarveManifest, updateCarveManifest } from "../../terraform/manifest";
 
 export interface CarveApplyOptions {
   from?: string;
+  /** Optional when the output dir holds a single carve manifest from `carve emit`. */
   select?: string;
   env?: string;
   stack?: string;
@@ -24,6 +26,8 @@ export interface CarveApplyOptions {
   output?: string;
   /** Write the graduation doc to the output dir. */
   write?: boolean;
+  /** Stamp the ownership marker into the emitted chant source. */
+  writeSource?: boolean;
 }
 
 export interface CarveApplyResult {
@@ -31,36 +35,77 @@ export interface CarveApplyResult {
   error?: string;
   plan?: GraduationPlan;
   written?: string;
+  /** Emitted source files the ownership marker was stamped into. */
+  stamped?: string[];
+  /** The carve state manifest this graduation was recorded into. */
+  manifestPath?: string;
+  /** True when the target came from the manifest, not --select. */
+  selectFromManifest?: boolean;
 }
 
 export async function carveApply(opts: CarveApplyOptions): Promise<CarveApplyResult> {
   if (!opts.from) return { ok: false, error: "chant carve apply requires --from <terraform-dir>" };
-  if (!opts.select) return { ok: false, error: "chant carve apply requires --select <tf-address>" };
   if (!existsSync(opts.from) || !statSync(opts.from).isDirectory()) {
     return { ok: false, error: `Not a directory: ${opts.from}` };
   }
 
+  // Compose with the manifest emit/bridge persisted: it supplies the target
+  // (and tfstate) when --select is absent, and its persisted boundary stands in
+  // when the carved block is already excised from the estate.
+  const outDir = opts.output ?? join(opts.from, "carveout");
+  const resolved = resolveCarveManifest(outDir, opts.select);
+  if (!opts.select && resolved.error) return { ok: false, error: resolved.error };
+  const select = opts.select ?? resolved.manifest!.target;
+  const statePath = opts.statePath ?? resolved.manifest?.statePath;
+
   let plan: GraduationPlan;
   try {
-    const graph = await parseTerraformDir(opts.from, { statePath: opts.statePath });
-    const report = boundaryReport(graph, opts.select);
-    if (!report) return { ok: false, error: `${opts.select} not found in ${opts.from}` };
+    const graph = await parseTerraformDir(opts.from, { statePath });
+    const report = boundaryReport(graph, select) ?? resolved.manifest?.boundary ?? null;
+    if (!report) return { ok: false, error: `${select} not found in ${opts.from}` };
     plan = graduationPlan(report, { stack: opts.stack, env: opts.env });
   } catch (err) {
     if (err instanceof Hcl2JsonNotInstalled) return { ok: false, error: err.message };
     return { ok: false, error: `Failed to plan graduation: ${err instanceof Error ? err.message : String(err)}` };
   }
 
+  // Stamp the marker into the emitted source (`--write-source`) — the emitted
+  // files are known from the manifest, so the tags the plan promises are the
+  // tags the source actually carries into the apply.
+  let stamped: string[] | undefined;
+  if (opts.writeSource) {
+    const files = resolved.manifest?.emit?.files ?? [];
+    if (files.length === 0) {
+      return {
+        ok: false,
+        error: "--write-source needs the emitted source recorded in the carve manifest — run `chant carve emit` first.",
+      };
+    }
+    stamped = [];
+    for (const file of files) {
+      if (!existsSync(file)) return { ok: false, error: `Emitted source not found: ${file}` };
+      const result = stampOwnershipIntoSource(readFileSync(file, "utf-8"), plan.ownershipTags);
+      if (!result) return { ok: false, error: `No constructor to stamp in ${file}.` };
+      if (result.changed) writeFileSync(file, result.content);
+      stamped.push(file);
+    }
+  }
+
   let written: string | undefined;
   if (opts.write) {
-    const outDir = opts.output ?? join(opts.from, "carveout");
     mkdirSync(outDir, { recursive: true });
-    const slug = opts.select.replace(/[^A-Za-z0-9_]+/g, "-");
+    const slug = select.replace(/[^A-Za-z0-9_]+/g, "-");
     written = join(outDir, `${slug}-graduation.md`);
     writeFileSync(written, renderGraduationDoc(plan) + "\n");
   }
 
-  return { ok: true, plan, written };
+  // Record the graduation into an existing manifest; never create one here —
+  // plan-only stays plan-only unless a carve flow is already in progress.
+  const manifestPath = updateCarveManifest(outDir, select, {
+    apply: { marker: plan.marker, ownershipTags: plan.ownershipTags, stampedFiles: stamped, at: new Date().toISOString() },
+  });
+
+  return { ok: true, plan, written, stamped, manifestPath, selectFromManifest: !opts.select };
 }
 
 function renderGraduationDoc(plan: GraduationPlan): string {
@@ -86,7 +131,7 @@ export function formatCarveApply(result: CarveApplyResult): string {
   if (!result.ok || !result.plan) return result.error ?? "carve apply failed";
   const p = result.plan;
   const L: string[] = [];
-  L.push(`Apply graduation for ${p.target} (dial-turn: observe → apply).`);
+  L.push(`Apply graduation for ${p.target} (dial-turn: observe → apply)${result.selectFromManifest ? " — target from the carve manifest" : ""}.`);
   L.push(`  Ownership marker: stack=${p.marker.stack}${p.marker.env ? `, env=${p.marker.env}` : ""}`);
   L.push("  Ownership tags (stamped on apply):");
   for (const [k, v] of Object.entries(p.ownershipTags)) L.push(`    ${k} = ${v}`);
@@ -97,10 +142,16 @@ export function formatCarveApply(result: CarveApplyResult): string {
     for (const w of p.warnings) L.push(`  ! ${w}`);
   }
   L.push("");
+  if (result.stamped?.length) {
+    L.push(`Stamped the ownership marker into: ${result.stamped.join(", ")}`);
+  }
   if (result.written) {
     L.push(`Wrote graduation doc: ${result.written}`);
-  } else {
+  } else if (!result.stamped?.length) {
     L.push("Plan only — no cloud call, nothing written. The apply is your lifecycle (BYOL). Add --write to save this as a doc.");
   }
+  if (result.manifestPath) {
+    L.push(`Recorded in the carve manifest: ${result.manifestPath}`);
+  }
   return L.join("\n");
 }

package/src/cli/commands/carve-bridge.test.ts

@@ -1,9 +1,11 @@
 import { describe, test, expect } from "vitest";
+import { execFileSync } from "child_process";
 import { mkdtempSync, writeFileSync, rmSync, readFileSync, existsSync } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
 import { carveBridge, formatCarveBridge } from "./carve-bridge";
 import { loadHcl2json } from "../../terraform/parse";
+import { readCarveManifest, writeCarveManifest, type CarveManifest } from "../../terraform/manifest";
 
 let parserAvailable = false;
 try {
@@ -39,10 +41,52 @@ async function withEstate<T>(fn: (dir: string) => Promise<T>): Promise<T> {
   }
 }
 
+function manifestFor(target: string, dir: string): CarveManifest {
+  return {
+    version: 1,
+    target,
+    from: dir,
+    boundary: {
+      target,
+      carveSet: [{ address: target, type: target.split(".")[0] }],
+      peelability: 90,
+      inbound: [],
+      outbound: [],
+      reversible: true,
+      diagnostics: [],
+    },
+  };
+}
+
 describe("carveBridge", () => {
-  test("requires --from and --select", async () => {
+  test("requires --from; without --select it needs a carve manifest", async () => {
     expect((await carveBridge({})).error).toContain("--from");
-    expect((await carveBridge({ from: "/x" })).error).toContain("--select");
+    await withEstate(async (dir) => {
+      const res = await carveBridge({ from: dir });
+      expect(res.ok).toBe(false);
+      expect(res.error).toContain("--select");
+      expect(res.error).toContain("carve emit");
+    });
+  });
+
+  test("composes with the carve manifest: target resolved without --select, bridge recorded", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const out = join(dir, "carveout");
+      writeCarveManifest(out, manifestFor("aws_s3_bucket.assets", dir));
+
+      const res = await carveBridge({ from: dir, output: out });
+      expect(res.ok).toBe(true);
+      expect(res.selectFromManifest).toBe(true);
+      expect(res.plan!.target).toBe("aws_s3_bucket.assets");
+      expect(formatCarveBridge(res)).toContain("target from the carve manifest");
+
+      const m = readCarveManifest(res.manifestPath!)!;
+      expect(m.bridge!.written.length).toBeGreaterThan(0);
+      expect(m.bridge!.appliedInPlace).toBe(false);
+      // The boundary is refreshed from the estate, not left as the stub.
+      expect(m.boundary.inbound.map((e) => e.survivor)).toEqual(["aws_lambda_function.api"]);
+    });
   });
 
   test("dry-run: writes runbook + data sources + proposed survivor, touches no .tf in place", async () => {
@@ -65,6 +109,39 @@ describe("carveBridge", () => {
     });
   });
 
+  test("emits one git-applyable patch carrying the whole survivor edit", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const out = join(dir, "carveout");
+      const res = await carveBridge({ from: dir, select: "aws_s3_bucket.assets", output: out });
+      expect(res.ok).toBe(true);
+      expect(res.patchPath).toBe(join(out, "aws_s3_bucket-assets-bridge.patch"));
+      expect(res.written).toContain(res.patchPath);
+
+      const patch = readFileSync(res.patchPath!, "utf-8");
+      expect(patch).toContain("diff --git a/aws_s3_bucket-assets-datasources.tf b/aws_s3_bucket-assets-datasources.tf");
+      expect(patch).toContain("new file mode 100644");
+      expect(patch).toContain("diff --git a/api.tf b/api.tf");
+      expect(patch).toContain("-      ASSETS_BUCKET = aws_s3_bucket.assets.bucket");
+      expect(patch).toContain("+      ASSETS_BUCKET = data.aws_s3_bucket.assets.bucket");
+
+      const m = readCarveManifest(res.manifestPath!)!;
+      expect(m.bridge!.patch).toBe(res.patchPath);
+      expect(formatCarveBridge(res)).toContain("git apply");
+
+      // The patch really applies: `git apply` from the estate reproduces the
+      // rewired survivor and the new data-source file.
+      try {
+        execFileSync("git", ["apply", res.patchPath!], { cwd: dir });
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") return; // no git on this machine
+        throw err;
+      }
+      expect(readFileSync(join(dir, "api.tf"), "utf-8")).toContain("data.aws_s3_bucket.assets.bucket");
+      expect(readFileSync(join(dir, "aws_s3_bucket-assets-datasources.tf"), "utf-8")).toContain('data "aws_s3_bucket" "assets"');
+    });
+  });
+
   test("--apply-rewrites edits the survivor .tf in place", async () => {
     if (!parserAvailable) return;
     await withEstate(async (dir) => {
@@ -77,10 +154,11 @@ describe("carveBridge", () => {
       expect(res.ok).toBe(true);
       expect(res.appliedInPlace).toBe(true);
 
-      // api.tf rewritten in place; bucket.tf (the carved declaration) untouched.
+      // api.tf rewritten in place; bucket.tf's carved declaration excised
+      // (#998 — after `terraform state rm`, the block would re-create it).
       const api = readFileSync(join(dir, "api.tf"), "utf-8");
       expect(api).toContain("data.aws_s3_bucket.assets.bucket");
-      expect(readFileSync(join(dir, "bucket.tf"), "utf-8")).toBe(BUCKET_TF);
+      expect(readFileSync(join(dir, "bucket.tf"), "utf-8")).not.toContain('resource "aws_s3_bucket" "assets"');
     });
   });
 

package/src/cli/commands/carve-bridge.ts

@@ -10,14 +10,17 @@
  */
 
 import { existsSync, statSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "fs";
-import { join, basename } from "path";
+import { join, basename, relative, resolve } from "path";
 import { parseTerraformDir, Hcl2JsonNotInstalled } from "../../terraform/parse";
-import { boundaryReport } from "../../terraform/carve";
+import { boundaryReport, type CarveReport } from "../../terraform/carve";
 import { generateBridge, type BridgePlan, type CarvedIdentity } from "../../terraform/bridge";
 import { IDENTITY_ATTR } from "../../terraform/tier-map";
+import { resolveCarveManifest, writeCarveManifest, type CarveManifest } from "../../terraform/manifest";
+import { newFileDiff, unifiedDiff } from "../../terraform/unified-diff";
 
 export interface CarveBridgeOptions {
   from?: string;
+  /** Optional when the output dir holds a single carve manifest from `carve emit`. */
   select?: string;
   statePath?: string;
   /** Output directory for proposed files (default `<from>/carveout`). */
@@ -34,6 +37,12 @@ export interface CarveBridgeResult {
   written?: string[];
   /** True if survivor files were edited in place. */
   appliedInPlace?: boolean;
+  /** The git-applyable `.patch` carrying the whole survivor edit. */
+  patchPath?: string;
+  /** The carve state manifest this bridge composed with / recorded into. */
+  manifestPath?: string;
+  /** True when the target came from the manifest, not --select. */
+  selectFromManifest?: boolean;
 }
 
 function listTfFiles(dir: string): string[] {
@@ -45,16 +54,25 @@ function listTfFiles(dir: string): string[] {
 
 export async function carveBridge(opts: CarveBridgeOptions): Promise<CarveBridgeResult> {
   if (!opts.from) return { ok: false, error: "chant carve bridge requires --from <terraform-dir>" };
-  if (!opts.select) return { ok: false, error: "chant carve bridge requires --select <tf-address>" };
   if (!existsSync(opts.from) || !statSync(opts.from).isDirectory()) {
     return { ok: false, error: `Not a directory: ${opts.from}` };
   }
 
+  // Compose with the carve state manifest `carve emit` persisted: without
+  // --select it supplies the target (and tfstate), with it it is updated below.
+  const outDir = opts.output ?? join(opts.from, "carveout");
+  const resolved = resolveCarveManifest(outDir, opts.select);
+  if (!opts.select && resolved.error) return { ok: false, error: resolved.error };
+  const select = opts.select ?? resolved.manifest!.target;
+  const statePath = opts.statePath ?? resolved.manifest?.statePath;
+
   let plan: BridgePlan;
+  let report: CarveReport;
   try {
-    const graph = await parseTerraformDir(opts.from, { statePath: opts.statePath });
-    const report = boundaryReport(graph, opts.select);
-    if (!report) return { ok: false, error: `${opts.select} not found in ${opts.from}` };
+    const graph = await parseTerraformDir(opts.from, { statePath });
+    const found = boundaryReport(graph, select);
+    if (!found) return { ok: false, error: `${select} not found in ${opts.from}` };
+    report = found;
 
     // Physical identities for the carved resources, for the data sources.
     const identities = new Map<string, CarvedIdentity>();
@@ -71,8 +89,7 @@ export async function carveBridge(opts: CarveBridgeOptions): Promise<CarveBridge
     return { ok: false, error: `Failed to build the bridge: ${err instanceof Error ? err.message : String(err)}` };
   }
 
-  const slug = opts.select.replace(/[^A-Za-z0-9_]+/g, "-");
-  const outDir = opts.output ?? join(opts.from, "carveout");
+  const slug = select.replace(/[^A-Za-z0-9_]+/g, "-");
   mkdirSync(outDir, { recursive: true });
   const written: string[] = [];
 
@@ -101,19 +118,66 @@ export async function carveBridge(opts: CarveBridgeOptions): Promise<CarveBridge
     }
   }
 
-  return { ok: true, plan, written, appliedInPlace: opts.applyRewrites && changed.length > 0 };
+  // The whole survivor edit as one git-applyable patch: the data-source file as
+  // a new file, plus the rewired references — `cd <from> && git apply <patch>`.
+  let patchPath: string | undefined;
+  if (plan.dataSources.length || changed.length) {
+    const chunks: string[] = [];
+    if (plan.dataSources.length) {
+      chunks.push(newFileDiff(`${slug}-datasources.tf`, plan.dataSources.map((d) => d.hcl).join("\n\n") + "\n"));
+    }
+    for (const r of changed) {
+      chunks.push(unifiedDiff(relative(opts.from, r.path), r.original, r.rewritten));
+    }
+    patchPath = join(outDir, `${slug}-bridge.patch`);
+    writeFileSync(patchPath, chunks.join(""));
+    written.push(patchPath);
+  }
+
+  // Record the bridge into the manifest (create one on a standalone bridge),
+  // so `carve apply` composes with this step too.
+  const applied = Boolean(opts.applyRewrites) && changed.length > 0;
+  const manifest: CarveManifest = resolved.manifest ?? {
+    version: 1,
+    target: select,
+    from: resolve(opts.from),
+    statePath: statePath ? resolve(statePath) : undefined,
+    boundary: report,
+  };
+  manifest.boundary = report;
+  manifest.bridge = {
+    written: written.map((w) => resolve(w)),
+    appliedInPlace: applied,
+    patch: patchPath ? resolve(patchPath) : undefined,
+    excised: plan.excised.length ? plan.excised : undefined,
+    at: new Date().toISOString(),
+  };
+  const manifestPath = writeCarveManifest(outDir, manifest);
+
+  return {
+    ok: true,
+    plan,
+    written,
+    appliedInPlace: applied,
+    patchPath,
+    manifestPath,
+    selectFromManifest: !opts.select,
+  };
 }
 
 export function formatCarveBridge(result: CarveBridgeResult): string {
   if (!result.ok || !result.plan) return result.error ?? "carve bridge failed";
   const p = result.plan;
   const L: string[] = [];
-  L.push(`Boundary bridge for ${p.target}:`);
+  L.push(`Boundary bridge for ${p.target}${result.selectFromManifest ? " (target from the carve manifest)" : ""}:`);
   if (p.dataSources.length) {
     L.push(`  ${p.dataSources.length} data source(s) for survivors to read:`);
     for (const d of p.dataSources) L.push(`    data.${d.type}.${d.name}  (was ${d.address})`);
   } else {
-    L.push("  no inbound edges — no survivor patch needed.");
+    L.push("  no inbound edges — nothing reads the carved resource, no data source needed.");
+  }
+  if (p.excised.length) {
+    L.push(`  carved block(s) excised from the survivor source: ${p.excised.join(", ")}`);
   }
   const changed = p.rewrites.filter((r) => r.changed);
   if (changed.length) {
@@ -124,6 +188,10 @@ export function formatCarveBridge(result: CarveBridgeResult): string {
     for (const d of p.deferredInputs) L.push(`    - ${d.note}`);
   }
   L.push("");
+  if (result.patchPath && !result.appliedInPlace) {
+    L.push(`One git-applyable patch carries the whole edit: git apply --directory=<terraform-dir> ${resolve(result.patchPath)}`);
+    L.push("  (--directory is the Terraform dir relative to your repo root; plain `git apply` from the dir works outside a repo.)");
+  }
   if (result.appliedInPlace) {
     L.push("Rewritten survivor Terraform in place. Review with `git diff`, then `terraform plan`.");
   } else {