@intentius/chant 0.41.19 → 0.42.1

package/src/terraform/adopt-state.ts

@@ -10,17 +10,47 @@
  * AWS carve-out table (`aws-resources.ts`) — the same table the advisor's tier
  * map derives from, so every AWS type advise ranks can be emitted. Attributes
  * without a mapping are preserved in a reference comment, never dropped.
+ *
+ * Deferred outbound inputs (#998): an attribute whose value the Terraform
+ * source read from a survivor (`vpc_id = aws_vpc.main.id`) is not a fact of
+ * the carved resource — it is a deploy-time input. Those props are emitted as
+ * `params.<name>` references instead of frozen literals, with the state's
+ * resolved value as the declared default (see `carve-emit.ts`'s scaffold).
  */
 
 import { AWS_CARVE_TYPES, AWS_LEXICON_IMPORT, awsCarveType, applyAwsMapper } from "./aws-resources";
 import type { StateResource } from "./state";
 
+/** The core subpath the emitted source reads build parameters from. */
+export const PARAMS_IMPORT = "@intentius/chant/params";
+
+/**
+ * One deferred outbound input turned into a build parameter (#998). Derived
+ * from the boundary report's outbound edges + the state's resolved attributes
+ * in `carve-emit.ts`; consumed here (source substitution) and by the scaffold
+ * (`chant.config.ts` `buildParams` declaration).
+ */
+export interface DeferredParam {
+  /** Build-parameter name, source-referenceable (`params.<name>`). */
+  name: string;
+  /** The carved resource's own Terraform attribute the value enters through. */
+  tfAttr: string;
+  /** The survivor the Terraform source read, e.g. `aws_vpc.main`. */
+  survivor: string;
+  /** Survivor attribute(s) read, e.g. `["id"]`. */
+  attrs: string[];
+  /** The state-resolved value — the parameter's declared default. */
+  default?: string | number | boolean;
+}
+
 export interface AdoptedSource {
   fileName: string;
   content: string;
   /** True when at least one attribute was mapped to a native prop. */
   mapped: boolean;
   nativeType: string;
+  /** Deferred params actually substituted into the emitted props (#998). */
+  parameterized: string[];
 }
 
 /** Is this Terraform type adoptable from state (has a native constructor)? */
@@ -33,16 +63,41 @@ export function supportedStateAdoptionTypes(): string[] {
   return AWS_CARVE_TYPES.map((t) => t.tfType).sort();
 }
 
+/** Marker for a prop whose value is a `params.<name>` reference, not a literal. */
+class ParamRef {
+  constructor(
+    readonly name: string,
+    readonly type: "string" | "number" | "boolean",
+  ) {}
+}
+
 /**
  * Render chant source for a state-adopted resource. Emits the native
  * constructor with mapped properties, plus a reference comment listing the
  * Terraform attributes that were not mapped so nothing is silently dropped.
+ *
+ * A mapped attribute named by a `DeferredParam` renders as a `params.<name>`
+ * reference (a real chant build parameter) instead of the state literal —
+ * the value came from a survivor, so it stays overridable per build.
  */
-export function adoptFromState(resource: StateResource): AdoptedSource | null {
+export function adoptFromState(resource: StateResource, params: DeferredParam[] = []): AdoptedSource | null {
   const entry = awsCarveType(resource.type);
   if (!entry) return null;
 
   const { props, mappedKeys } = applyAwsMapper(entry, resource.attributes);
+
+  // Substitute deferred inputs: only plain (untransformed) field mappings can
+  // carry a parameter reference — a transform ran against the literal at emit
+  // time and cannot re-run at build. Everything else keeps the state literal.
+  const parameterized: string[] = [];
+  for (const param of params) {
+    const spec = entry.fields[param.tfAttr];
+    if (typeof spec !== "string" || !(spec in props)) continue;
+    const type = typeof param.default === "number" ? "number" : typeof param.default === "boolean" ? "boolean" : "string";
+    props[spec] = new ParamRef(param.name, type);
+    parameterized.push(param.name);
+  }
+
   const unmapped: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(resource.attributes)) {
     if (!mappedKeys.includes(k)) unmapped[k] = v;
@@ -52,6 +107,10 @@ export function adoptFromState(resource: StateResource): AdoptedSource | null {
   L.push(`// Adopted from Terraform state: ${resource.type}.${resource.name} -> ${entry.nativeType}`);
   L.push(`// Properties mapped from Terraform attributes (CloudFormation PascalCase).`);
   L.push(`import { ${entry.ctor} } from "${AWS_LEXICON_IMPORT}";`);
+  if (parameterized.length) {
+    L.push(`// Deferred deploy-time input(s) — declared in chant.config.ts's buildParams.`);
+    L.push(`import { params } from "${PARAMS_IMPORT}";`);
+  }
   L.push("");
   L.push(`export const ${resource.name} = new ${entry.ctor}(${renderObject(props, 2)});`);
   if (Object.keys(unmapped).length) {
@@ -66,6 +125,7 @@ export function adoptFromState(resource: StateResource): AdoptedSource | null {
     content: L.join("\n") + "\n",
     mapped: Object.keys(props).length > 0,
     nativeType: entry.nativeType,
+    parameterized,
   };
 }
 
@@ -74,6 +134,13 @@ function renderObject(obj: Record<string, unknown>, indent: number): string {
   const keys = Object.keys(obj);
   if (keys.length === 0) return "{}";
   const pad = " ".repeat(indent);
-  const body = keys.map((k) => `${pad}${k}: ${JSON.stringify(obj[k])},`).join("\n");
+  const body = keys
+    .map((k) => `${pad}${k}: ${renderValue(obj[k])},`)
+    .join("\n");
   return `{\n${body}\n}`;
 }
+
+/** A prop value: a `params.<name>` reference (cast keeps the project tsc-clean) or a literal. */
+function renderValue(value: unknown): string {
+  return value instanceof ParamRef ? `params.${value.name} as ${value.type}` : JSON.stringify(value);
+}

package/src/terraform/bridge.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from "vitest";
-import { buildGraph } from "./graph";
+import { buildFixtureGraph } from "./__fixtures__/build-graph";
 import { boundaryReport } from "./carve";
 import { generateBridge, type CarvedIdentity } from "./bridge";
 import type { Hcl2JsonTree } from "./types";
@@ -41,7 +41,7 @@ const identities = new Map<string, CarvedIdentity>([
 
 describe("generateBridge — inbound (data-source rewrite)", () => {
   test("adds a data source for the carved bucket", () => {
-    const report = boundaryReport(buildGraph(workedExample), "aws_s3_bucket.assets")!;
+    const report = boundaryReport(buildFixtureGraph(workedExample), "aws_s3_bucket.assets")!;
     const plan = generateBridge(report, [{ path: "api.tf", content: API_TF }], identities);
 
     expect(plan.dataSources).toHaveLength(1);
@@ -52,7 +52,7 @@ describe("generateBridge — inbound (data-source rewrite)", () => {
   });
 
   test("rewrites survivor references to the data source", () => {
-    const report = boundaryReport(buildGraph(workedExample), "aws_s3_bucket.assets")!;
+    const report = boundaryReport(buildFixtureGraph(workedExample), "aws_s3_bucket.assets")!;
     const plan = generateBridge(report, [{ path: "api.tf", content: API_TF }], identities);
 
     const rewrite = plan.rewrites.find((r) => r.path === "api.tf")!;
@@ -64,7 +64,7 @@ describe("generateBridge — inbound (data-source rewrite)", () => {
   });
 
   test("does not double-prefix an already-rewritten reference (idempotent)", () => {
-    const report = boundaryReport(buildGraph(workedExample), "aws_s3_bucket.assets")!;
+    const report = boundaryReport(buildFixtureGraph(workedExample), "aws_s3_bucket.assets")!;
     const already = API_TF.replace(/aws_s3_bucket\.assets/g, "data.aws_s3_bucket.assets");
     const plan = generateBridge(report, [{ path: "api.tf", content: already }], identities);
     const rewrite = plan.rewrites.find((r) => r.path === "api.tf")!;
@@ -72,19 +72,39 @@ describe("generateBridge — inbound (data-source rewrite)", () => {
     expect(rewrite.rewritten).not.toContain("data.data.aws_s3_bucket");
   });
 
-  test("does not touch the carved resource's own declaration (quoted labels)", () => {
-    const report = boundaryReport(buildGraph(workedExample), "aws_s3_bucket.assets")!;
-    const decl = `resource "aws_s3_bucket" "assets" {\n  bucket = "myapp-assets-prod"\n}\n`;
+  test("excises the carved resource's own declaration (#998 — the data source replaces it)", () => {
+    const report = boundaryReport(buildFixtureGraph(workedExample), "aws_s3_bucket.assets")!;
+    const decl = `resource "aws_s3_bucket" "assets" {\n  bucket = "myapp-assets-prod"\n}\n\nresource "aws_sns_topic" "alerts" {\n  name = "a"\n}\n`;
     const plan = generateBridge(report, [{ path: "bucket.tf", content: decl }], identities);
     const rewrite = plan.rewrites.find((r) => r.path === "bucket.tf")!;
-    // `resource "aws_s3_bucket" "assets"` uses quoted labels, not the dotted
-    // token, so it is left alone.
-    expect(rewrite.rewritten).toContain('resource "aws_s3_bucket" "assets"');
-    expect(rewrite.changed).toBe(false);
+    // After `terraform state rm`, a block left behind would re-create the
+    // resource on the next apply — so the bridge removes it.
+    expect(rewrite.changed).toBe(true);
+    expect(rewrite.excised).toEqual(["aws_s3_bucket.assets"]);
+    expect(rewrite.rewritten).not.toContain('resource "aws_s3_bucket" "assets"');
+    expect(rewrite.rewritten).toContain('resource "aws_sns_topic" "alerts"');
+    expect(plan.excised).toEqual(["aws_s3_bucket.assets"]);
+    expect(plan.runbook).toContain("removes the carved block(s): aws_s3_bucket.assets");
+  });
+
+  test("a folded sub-resource's block is excised along with its parent", () => {
+    const withVersioning: Hcl2JsonTree = {
+      resource: {
+        ...workedExample.resource,
+        aws_s3_bucket_versioning: {
+          assets: [{ bucket: "${aws_s3_bucket.assets.id}", versioning_configuration: { status: "Enabled" } }],
+        },
+      },
+    };
+    const report = boundaryReport(buildFixtureGraph(withVersioning), "aws_s3_bucket.assets")!;
+    const decl = `resource "aws_s3_bucket" "assets" {\n  bucket = "b"\n}\n\nresource "aws_s3_bucket_versioning" "assets" {\n  bucket = aws_s3_bucket.assets.id\n}\n`;
+    const plan = generateBridge(report, [{ path: "bucket.tf", content: decl }], identities);
+    expect(plan.excised).toEqual(["aws_s3_bucket.assets", "aws_s3_bucket_versioning.assets"]);
+    expect(plan.rewrites[0].rewritten.trim()).toBe("");
   });
 
   test("unknown identity emits a TODO data source instead of a wrong value", () => {
-    const report = boundaryReport(buildGraph(workedExample), "aws_s3_bucket.assets")!;
+    const report = boundaryReport(buildFixtureGraph(workedExample), "aws_s3_bucket.assets")!;
     const plan = generateBridge(report, [{ path: "api.tf", content: API_TF }], new Map());
     expect(plan.dataSources[0].hcl).toContain("# TODO");
   });
@@ -98,17 +118,21 @@ describe("generateBridge — outbound (deferred inputs)", () => {
         aws_sqs_queue: { dlq: [{ name: "d", redrive: "${aws_sns_topic.alerts.arn}" }] },
       },
     };
-    const report = boundaryReport(buildGraph(tree), "aws_sqs_queue.dlq")!;
+    const report = boundaryReport(buildFixtureGraph(tree), "aws_sqs_queue.dlq")!;
     const plan = generateBridge(report, [], new Map());
     expect(plan.dataSources).toEqual([]); // no inbound → no survivor patch
     expect(plan.deferredInputs).toHaveLength(1);
     expect(plan.deferredInputs[0]).toMatchObject({ survivor: "aws_sns_topic.alerts", carved: "aws_sqs_queue.dlq" });
+    // The deferred input names the build param emit declares for it (#998).
+    expect(plan.deferredInputs[0].params).toEqual(["redrive"]);
+    expect(plan.deferredInputs[0].note).toContain("build param `redrive`");
+    expect(plan.deferredInputs[0].note).toContain("--param");
   });
 });
 
 describe("generateBridge — runbook", () => {
   test("is reversible and observe-first, with the state-rm and import steps", () => {
-    const report = boundaryReport(buildGraph(workedExample), "aws_s3_bucket.assets")!;
+    const report = boundaryReport(buildFixtureGraph(workedExample), "aws_s3_bucket.assets")!;
     const plan = generateBridge(report, [{ path: "api.tf", content: API_TF }], identities);
     expect(plan.runbook).toContain("terraform state rm aws_s3_bucket.assets");
     expect(plan.runbook).toContain("does NOT destroy");

package/src/terraform/bridge.ts

@@ -19,7 +19,8 @@
  * is reversible via `terraform import`.
  */
 
-import type { CarveReport } from "./carve";
+import { deferredParamName, type CarveReport } from "./carve";
+import { exciseResourceBlocks, type ExciseTarget } from "./excise";
 
 export interface CarvedIdentity {
   /** The HCL identity attribute, e.g. `bucket` or `name`. */
@@ -41,12 +42,16 @@ export interface FileRewrite {
   original: string;
   rewritten: string;
   changed: boolean;
+  /** Carved addresses whose own `resource` block was removed from this file (#998). */
+  excised: string[];
 }
 
 export interface DeferredInput {
   survivor: string;
   carved: string;
   attrs: string[];
+  /** Build-parameter name(s) the input becomes in the emitted project (#998). */
+  params: string[];
   note: string;
 }
 
@@ -55,6 +60,8 @@ export interface BridgePlan {
   dataSources: DataSourceBlock[];
   rewrites: FileRewrite[];
   deferredInputs: DeferredInput[];
+  /** Every carved address whose own block the rewrites remove, across files. */
+  excised: string[];
   runbook: string;
 }
 
@@ -99,33 +106,56 @@ export function generateBridge(
     hcl: dataSourceHcl(type, name, identities.get(address) ?? {}),
   }));
 
-  // Rewrite every survivor reference to the carved resources into a data ref.
+  // Excise the carve set's own blocks (#998): after `terraform state rm`, a
+  // block left behind would re-create the resource on the next apply. Then
+  // rewrite every remaining survivor reference into a data ref.
+  const exciseTargets: ExciseTarget[] = report.carveSet
+    .filter((m) => !m.address.startsWith("module."))
+    .map((m) => {
+      const [type, ...rest] = m.address.split(".");
+      return { address: m.address, type, name: rest.join(".") };
+    });
   const rewrites: FileRewrite[] = files.map(({ path, content }) => {
-    let rewritten = content;
+    const excision = exciseResourceBlocks(content, exciseTargets);
+    let rewritten = excision.content;
     for (const address of carvedWithInbound.keys()) {
       rewritten = rewritten.replace(referenceRegex(address), `data.${address}`);
     }
-    return { path, original: content, rewritten, changed: rewritten !== content };
+    return { path, original: content, rewritten, changed: rewritten !== content, excised: excision.excised };
   });
+  const excised = rewrites.flatMap((r) => r.excised);
 
-  const deferredInputs: DeferredInput[] = report.outbound.map((e) => ({
-    survivor: e.survivor,
-    carved: e.carved,
-    attrs: e.attrs,
-    note: `${e.carved} reads ${e.survivor}.${e.attrs.join(", ")} — supply this as a deploy-time input to the carved component at apply.`,
-  }));
+  const deferredInputs: DeferredInput[] = report.outbound.map((e) => {
+    const params = (e.via ?? []).map(deferredParamName);
+    const wiring = params.length
+      ? `emit declares it as build param ${params.map((p) => `\`${p}\``).join(", ")} — override with --param at build`
+      : "supply this as a deploy-time input to the carved component at apply";
+    return {
+      survivor: e.survivor,
+      carved: e.carved,
+      attrs: e.attrs,
+      params,
+      note: `${e.carved} reads ${e.survivor}.${e.attrs.join(", ")} — ${wiring}.`,
+    };
+  });
 
   return {
     target: report.target,
     dataSources,
     rewrites,
     deferredInputs,
-    runbook: buildRunbook(report, dataSources, deferredInputs),
+    excised,
+    runbook: buildRunbook(report, dataSources, deferredInputs, excised),
   };
 }
 
 /** The reversible, observe-first handoff runbook (#197). */
-function buildRunbook(report: CarveReport, dataSources: DataSourceBlock[], deferred: DeferredInput[]): string {
+function buildRunbook(
+  report: CarveReport,
+  dataSources: DataSourceBlock[],
+  deferred: DeferredInput[],
+  excised: string[],
+): string {
   const carvedAddrs = report.carveSet.map((m) => m.address);
   const L: string[] = [];
   L.push(`# Carve-out: ${report.target} → chant   [observe-first, reversible]`);
@@ -140,10 +170,14 @@ function buildRunbook(report: CarveReport, dataSources: DataSourceBlock[], defer
   L.push("");
   L.push("## 3. Confirm no destroy, then patch the survivors");
   L.push("    terraform plan   # expect 0 to destroy; refs to the carved resource now error");
+  if (excised.length) {
+    L.push(`    # the generated bridge patch removes the carved block(s): ${excised.join(", ")}`);
+    L.push("    #   (without this, the next apply would re-create what state rm released)");
+  }
   if (dataSources.length) {
-    L.push("    # apply the generated bridge patch — it adds these data sources and rewires references:");
+    L.push("    # it also adds these data sources and rewires references:");
     for (const ds of dataSources) L.push(`    #   data.${ds.type}.${ds.name}  (for ${ds.address})`);
-  } else {
+  } else if (!excised.length) {
     L.push("    # no inbound edges — no survivor patch needed.");
   }
   L.push("    terraform plan   # expect: in-place updates to the survivors only");

package/src/terraform/carve.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from "vitest";
-import { buildGraph } from "./graph";
+import { buildFixtureGraph } from "./__fixtures__/build-graph";
 import { resolveCarveSet, boundaryReport } from "./carve";
 import type { Hcl2JsonTree } from "./types";
 
@@ -27,7 +27,7 @@ const workedExample: Hcl2JsonTree = {
 
 describe("resolveCarveSet", () => {
   test("selected node plus its folded sub-resources", () => {
-    const set = resolveCarveSet(buildGraph(workedExample), "aws_s3_bucket.assets");
+    const set = resolveCarveSet(buildFixtureGraph(workedExample), "aws_s3_bucket.assets");
     expect(set.map((m) => m.address).sort()).toEqual([
       "aws_s3_bucket.assets",
       "aws_s3_bucket_versioning.assets",
@@ -37,13 +37,13 @@ describe("resolveCarveSet", () => {
   });
 
   test("empty for an unknown address", () => {
-    expect(resolveCarveSet(buildGraph(workedExample), "aws_s3_bucket.nope")).toEqual([]);
+    expect(resolveCarveSet(buildFixtureGraph(workedExample), "aws_s3_bucket.nope")).toEqual([]);
   });
 });
 
 describe("boundaryReport", () => {
   test("classifies the Lambda inbound edge; folds the versioning internal edge away", () => {
-    const report = boundaryReport(buildGraph(workedExample), "aws_s3_bucket.assets")!;
+    const report = boundaryReport(buildFixtureGraph(workedExample), "aws_s3_bucket.assets")!;
     expect(report.target).toBe("aws_s3_bucket.assets");
     expect(report.peelability).toBe(88);
     expect(report.reversible).toBe(true);
@@ -56,6 +56,7 @@ describe("boundaryReport", () => {
         survivor: "aws_lambda_function.api",
         carved: "aws_s3_bucket.assets",
         attrs: ["arn", "bucket"],
+        via: ["environment"],
         bridge: "tf-data-source",
         required: "immediately",
       },
@@ -71,7 +72,7 @@ describe("boundaryReport", () => {
       },
     };
     // Carve the queue: it depends on the topic (a survivor) → outbound/deferred.
-    const report = boundaryReport(buildGraph(tree), "aws_sqs_queue.dlq")!;
+    const report = boundaryReport(buildFixtureGraph(tree), "aws_sqs_queue.dlq")!;
     expect(report.inbound).toEqual([]);
     expect(report.outbound).toEqual([
       {
@@ -79,6 +80,7 @@ describe("boundaryReport", () => {
         survivor: "aws_sns_topic.alerts",
         carved: "aws_sqs_queue.dlq",
         attrs: ["arn"],
+        via: ["redrive"],
         bridge: "deferred-input",
         required: "at-apply",
       },
@@ -87,11 +89,11 @@ describe("boundaryReport", () => {
 
   test("unsupported type is flagged in diagnostics", () => {
     const tree: Hcl2JsonTree = { resource: { random_pet: { n: [{ length: 2 }] } } };
-    const report = boundaryReport(buildGraph(tree), "random_pet.n")!;
+    const report = boundaryReport(buildFixtureGraph(tree), "random_pet.n")!;
     expect(report.diagnostics.join(" ")).toMatch(/no known native mapping/i);
   });
 
   test("null for an unknown target", () => {
-    expect(boundaryReport(buildGraph(workedExample), "aws_s3_bucket.nope")).toBeNull();
+    expect(boundaryReport(buildFixtureGraph(workedExample), "aws_s3_bucket.nope")).toBeNull();
   });
 });

package/src/terraform/excise.test.ts

@@ -0,0 +1,92 @@
+import { describe, test, expect } from "vitest";
+import { exciseResourceBlocks, type ExciseTarget } from "./excise";
+
+const bucket: ExciseTarget = { address: "aws_s3_bucket.assets", type: "aws_s3_bucket", name: "assets" };
+const versioning: ExciseTarget = {
+  address: "aws_s3_bucket_versioning.assets",
+  type: "aws_s3_bucket_versioning",
+  name: "assets",
+};
+
+describe("exciseResourceBlocks", () => {
+  test("removes the target block, leaves the rest byte-for-byte", () => {
+    const tf = `# the bucket
+resource "aws_s3_bucket" "assets" {
+  bucket = "myapp-assets-prod"
+  tags   = { Team = "web" }
+}
+
+resource "aws_lambda_function" "api" {
+  function_name = "myapp-api"
+}
+`;
+    const r = exciseResourceBlocks(tf, [bucket]);
+    expect(r.excised).toEqual(["aws_s3_bucket.assets"]);
+    expect(r.content).toBe(`# the bucket
+resource "aws_lambda_function" "api" {
+  function_name = "myapp-api"
+}
+`);
+  });
+
+  test("removes several targets (a folded sub-resource travels with its parent)", () => {
+    const tf = `resource "aws_s3_bucket" "assets" {
+  bucket = "b"
+}
+
+resource "aws_s3_bucket_versioning" "assets" {
+  bucket = aws_s3_bucket.assets.id
+  versioning_configuration {
+    status = "Enabled"
+  }
+}
+
+resource "aws_sns_topic" "alerts" {
+  name = "a"
+}
+`;
+    const r = exciseResourceBlocks(tf, [bucket, versioning]);
+    expect(r.excised).toEqual(["aws_s3_bucket.assets", "aws_s3_bucket_versioning.assets"]);
+    expect(r.content).toBe(`resource "aws_sns_topic" "alerts" {\n  name = "a"\n}\n`);
+  });
+
+  test("a same-name block of a different type stays", () => {
+    const tf = `resource "aws_s3_bucket" "assets" { bucket = "b" }
+resource "aws_s3_bucket_versioning" "assets" { bucket = "b" }
+`;
+    const r = exciseResourceBlocks(tf, [bucket]);
+    expect(r.excised).toEqual(["aws_s3_bucket.assets"]);
+    expect(r.content).toContain('resource "aws_s3_bucket_versioning" "assets"');
+  });
+
+  test("braces inside strings, interpolations, comments, and heredocs do not fool the scanner", () => {
+    const tf = `resource "aws_s3_bucket" "assets" {
+  bucket = "b"
+  # a } in a comment
+  policy = jsonencode({ Statement = [{ Effect = "Allow" }] })
+  note   = "literal } and \${var.m["k}"]} too"
+  user_data = <<EOF
+    if true; then echo "}"; fi
+EOF
+}
+resource "aws_sns_topic" "alerts" { name = "a" }
+`;
+    const r = exciseResourceBlocks(tf, [bucket]);
+    expect(r.excised).toEqual(["aws_s3_bucket.assets"]);
+    expect(r.content).toBe(`resource "aws_sns_topic" "alerts" { name = "a" }\n`);
+  });
+
+  test("no target present → the file comes back unchanged", () => {
+    const tf = `resource "aws_sns_topic" "alerts" { name = "a" }\n`;
+    const r = exciseResourceBlocks(tf, [bucket]);
+    expect(r.excised).toEqual([]);
+    expect(r.content).toBe(tf);
+  });
+
+  test("an unbalanced block is left alone rather than corrupted", () => {
+    const tf = `resource "aws_s3_bucket" "assets" {\n  bucket = "b"\n`;
+    const r = exciseResourceBlocks(tf, [bucket]);
+    expect(r.excised).toEqual([]);
+    expect(r.content).toBe(tf);
+  });
+});

package/src/terraform/excise.ts

@@ -0,0 +1,139 @@
+/**
+ * Excision of a carved resource's own `resource "<type>" "<name>"` block from
+ * the surviving Terraform source (#998 — closes the "auto-excise" limitation).
+ *
+ * After `terraform state rm`, the block left behind would re-CREATE the
+ * resource on the next apply — the one edit the bridge previously left to
+ * hand-work. This removes the carve set's own blocks as part of the survivor
+ * rewrite, so the one bridge `.patch` (#1589) carries the whole handoff edit.
+ *
+ * Pure text transform. The scanner tracks brace depth outside of strings,
+ * comments, template interpolations, and heredocs — enough for real `.tf`
+ * files without pulling in the wasm parser for what is a subtractive edit.
+ */
+
+export interface ExciseTarget {
+  /** Terraform address, e.g. `aws_s3_bucket.assets`. */
+  address: string;
+  type: string;
+  name: string;
+}
+
+export interface ExciseResult {
+  content: string;
+  /** Addresses whose block was found and removed, in file order. */
+  excised: string[];
+}
+
+const HEADER = /^\s*resource\s+"([^"]+)"\s+"([^"]+)"\s*\{/;
+
+/**
+ * Remove the targets' own `resource` blocks from one `.tf` file's text. A
+ * comment line directly above a removed block stays (it may describe more
+ * than the block); the blank line the removal leaves behind is collapsed.
+ */
+export function exciseResourceBlocks(content: string, targets: ExciseTarget[]): ExciseResult {
+  if (targets.length === 0) return { content, excised: [] };
+  const wanted = new Map(targets.map((t) => [`${t.type}.${t.name}`, t.address]));
+  const lines = content.split("\n");
+  const excised: string[] = [];
+  const out: string[] = [];
+
+  let i = 0;
+  while (i < lines.length) {
+    const m = lines[i].match(HEADER);
+    const key = m ? `${m[1]}.${m[2]}` : undefined;
+    if (!m || !wanted.has(key!)) {
+      out.push(lines[i]);
+      i++;
+      continue;
+    }
+
+    const end = blockEnd(lines, i);
+    if (end === -1) {
+      // Unbalanced block — leave the file alone rather than corrupt it.
+      out.push(lines[i]);
+      i++;
+      continue;
+    }
+    excised.push(wanted.get(key!)!);
+    i = end + 1;
+    // Swallow the separator blank line so the removal leaves no doubled gap.
+    if (i < lines.length && lines[i].trim() === "") i++;
+  }
+
+  return { content: out.join("\n"), excised };
+}
+
+/** Index of the line closing the block opened on `start`, or -1 if unbalanced. */
+function blockEnd(lines: string[], start: number): number {
+  // Context stack: block/object braces, strings, `${` interpolations, block
+  // comments. The header's `{` pushes the first "brace"; the block closes when
+  // the stack empties.
+  const stack: Array<"brace" | "string" | "interp" | "comment"> = [];
+  let opened = false;
+  let heredoc: string | null = null;
+
+  for (let ln = start; ln < lines.length; ln++) {
+    const line = lines[ln];
+    if (heredoc !== null) {
+      if (line.trim() === heredoc) heredoc = null;
+      continue;
+    }
+
+    for (let c = 0; c < line.length; c++) {
+      const top = stack[stack.length - 1];
+      const ch = line[c];
+      const next = line[c + 1];
+
+      if (top === "comment") {
+        if (ch === "*" && next === "/") {
+          stack.pop();
+          c++;
+        }
+        continue;
+      }
+
+      if (top === "string") {
+        if (ch === "\\") {
+          c++;
+        } else if (ch === "$" && next === "{" && line[c - 1] !== "$") {
+          stack.push("interp");
+          c++;
+        } else if (ch === '"') {
+          stack.pop();
+        }
+        continue;
+      }
+
+      // Code position (top of file block, a nested brace, or inside `${...}`).
+      if (ch === "#" || (ch === "/" && next === "/")) break; // line comment
+      if (ch === "/" && next === "*") {
+        stack.push("comment");
+        c++;
+        continue;
+      }
+      if (ch === '"') {
+        stack.push("string");
+        continue;
+      }
+      if (ch === "<" && next === "<") {
+        const hd = line.slice(c).match(/^<<-?([A-Za-z_][A-Za-z0-9_-]*)/);
+        if (hd) {
+          heredoc = hd[1];
+          break;
+        }
+      }
+      if (ch === "{") {
+        stack.push("brace");
+        opened = true;
+        continue;
+      }
+      if (ch === "}") {
+        if (top === "brace" || top === "interp") stack.pop();
+        if (opened && stack.length === 0) return ln;
+      }
+    }
+  }
+  return -1;
+}