@intentius/chant 0.18.36 → 0.19.0

package/src/terraform/aws-resources.test.ts

@@ -0,0 +1,74 @@
+import { describe, test, expect } from "vitest";
+import { AWS_CARVE_TYPES, awsCarveType, applyAwsMapper } from "./aws-resources";
+import { TIER_MAP } from "./tier-map";
+import { canAdoptFromState } from "./adopt-state";
+
+describe("AWS carve-out table", () => {
+  test("advise and emit cover exactly the same AWS types (no cliff)", () => {
+    // Every AWS type the advisor ranks (tier map) must be emittable, and vice
+    // versa. Non-AWS entries (kubernetes_manifest) are excluded.
+    const tierAws = Object.keys(TIER_MAP).filter((t) => t.startsWith("aws_")).sort();
+    const emitAws = AWS_CARVE_TYPES.map((t) => t.tfType).sort();
+    expect(tierAws).toEqual(emitAws);
+    for (const t of emitAws) expect(canAdoptFromState(t)).toBe(true);
+  });
+
+  test("covers the common carve targets across families", () => {
+    const types = new Set(AWS_CARVE_TYPES.map((t) => t.tfType));
+    for (const t of [
+      "aws_s3_bucket", "aws_iam_role", "aws_iam_policy", "aws_dynamodb_table",
+      "aws_lambda_function", "aws_sns_topic", "aws_sqs_queue", "aws_kms_key",
+      "aws_secretsmanager_secret", "aws_ssm_parameter", "aws_ecr_repository",
+      "aws_vpc", "aws_subnet", "aws_security_group", "aws_route53_zone",
+      "aws_cloudwatch_log_group",
+    ]) {
+      expect(types.has(t)).toBe(true);
+    }
+    expect(AWS_CARVE_TYPES.length).toBeGreaterThanOrEqual(20);
+  });
+
+  test("every constructor name is unique and non-empty", () => {
+    const ctors = AWS_CARVE_TYPES.map((t) => t.ctor);
+    expect(ctors.every((c) => c.length > 0)).toBe(true);
+    expect(new Set(ctors).size).toBe(ctors.length);
+  });
+});
+
+describe("applyAwsMapper", () => {
+  test("renames fields to CloudFormation props and reshapes tags", () => {
+    const { props, mappedKeys } = applyAwsMapper(awsCarveType("aws_s3_bucket")!, {
+      id: "b", bucket: "my-bucket", tags: { Env: "prod" }, force_destroy: false,
+    });
+    expect(props).toEqual({ BucketName: "my-bucket", Tags: [{ Key: "Env", Value: "prod" }] });
+    expect(mappedKeys).toContain("bucket");
+    expect(mappedKeys).toContain("tags");
+    expect(mappedKeys).not.toContain("force_destroy"); // stays unmapped
+  });
+
+  test("parses a JSON-string policy into an object", () => {
+    const { props } = applyAwsMapper(awsCarveType("aws_iam_role")!, {
+      name: "r",
+      assume_role_policy: '{"Version":"2012-10-17","Statement":[]}',
+      managed_policy_arns: ["arn:aws:iam::aws:policy/X"],
+    });
+    expect(props.RoleName).toBe("r");
+    expect(props.AssumeRolePolicyDocument).toEqual({ Version: "2012-10-17", Statement: [] });
+    expect(props.ManagedPolicyArns).toEqual(["arn:aws:iam::aws:policy/X"]);
+  });
+
+  test("wraps an instance-profile role into a list", () => {
+    const { props } = applyAwsMapper(awsCarveType("aws_iam_instance_profile")!, { name: "p", role: "my-role" });
+    expect(props).toEqual({ InstanceProfileName: "p", Roles: ["my-role"] });
+  });
+
+  test("a malformed JSON policy is preserved as a string, not dropped", () => {
+    const { props } = applyAwsMapper(awsCarveType("aws_iam_policy")!, { name: "p", policy: "not json {" });
+    expect(props.PolicyDocument).toBe("not json {");
+  });
+
+  test("omits absent attributes", () => {
+    const { props } = applyAwsMapper(awsCarveType("aws_subnet")!, { vpc_id: "vpc-1", cidr_block: "10.0.1.0/24" });
+    expect(props).toEqual({ VpcId: "vpc-1", CidrBlock: "10.0.1.0/24" });
+    expect(props).not.toHaveProperty("AvailabilityZone");
+  });
+});

package/src/terraform/aws-resources.ts

@@ -0,0 +1,154 @@
+/**
+ * The AWS carve-out resource table — the single source of truth for which AWS
+ * Terraform types chant can carve, and how.
+ *
+ * Both the advisor (tier map / scoring) and `carve emit --state` derive from
+ * this one list, so advise and emit cover exactly the same AWS types: advise
+ * never ranks a resource emit cannot produce, and emit never claims a type
+ * advise did not score. Adding a type here lights it up for both at once.
+ *
+ * Each entry maps the common, high-confidence Terraform attributes to their
+ * CloudFormation property names (chant AWS constructors take CFN PascalCase
+ * props). Attributes without a mapping here are preserved in a reference
+ * comment on emit, never dropped — a curated seed, not a full TF↔CFN transform.
+ */
+
+/** A Terraform attribute → CloudFormation property mapping. */
+type FieldSpec = string | { prop: string; transform: (v: unknown) => unknown };
+
+export interface AwsCarveType {
+  /** Terraform resource type, e.g. `aws_s3_bucket`. */
+  tfType: string;
+  /** Native-spec map tier: 1 clean 1:1, 2 some reshaping, 3 heavy composite. */
+  tier: 1 | 2 | 3;
+  /** CloudFormation type, e.g. `AWS::S3::Bucket`. */
+  nativeType: string;
+  /** chant AWS lexicon constructor, e.g. `Bucket` (verified against generated exports). */
+  ctor: string;
+  /** The HCL attribute carrying the physical name (for the live-import hint / graph identity). */
+  identityAttr?: string;
+  /** Terraform attribute → CFN property mappings. */
+  fields: Record<string, FieldSpec>;
+  /** Map the Terraform `tags` map to CloudFormation `Tags` list. */
+  tags?: boolean;
+}
+
+export const AWS_LEXICON_IMPORT = "@intentius/chant-lexicon-aws";
+
+/** Parse a Terraform JSON-string attribute (IAM policy docs) into an object. */
+const asJson = (v: unknown): unknown => {
+  if (typeof v !== "string") return v;
+  try {
+    return JSON.parse(v);
+  } catch {
+    return v;
+  }
+};
+const json = (prop: string): FieldSpec => ({ prop, transform: asJson });
+
+export const AWS_CARVE_TYPES: AwsCarveType[] = [
+  // ── Storage & data ──
+  { tfType: "aws_s3_bucket", tier: 1, nativeType: "AWS::S3::Bucket", ctor: "Bucket", identityAttr: "bucket",
+    fields: { bucket: "BucketName" }, tags: true },
+  { tfType: "aws_dynamodb_table", tier: 2, nativeType: "AWS::DynamoDB::Table", ctor: "Table", identityAttr: "name",
+    fields: { name: "TableName", billing_mode: "BillingMode" }, tags: true },
+  { tfType: "aws_efs_file_system", tier: 1, nativeType: "AWS::EFS::FileSystem", ctor: "EFSFileSystem",
+    fields: { encrypted: "Encrypted", performance_mode: "PerformanceMode", throughput_mode: "ThroughputMode" }, tags: true },
+
+  // ── Messaging ──
+  { tfType: "aws_sns_topic", tier: 1, nativeType: "AWS::SNS::Topic", ctor: "Topic", identityAttr: "name",
+    fields: { name: "TopicName", display_name: "DisplayName", fifo_topic: "FifoTopic" }, tags: true },
+  { tfType: "aws_sqs_queue", tier: 1, nativeType: "AWS::SQS::Queue", ctor: "Queue", identityAttr: "name",
+    fields: { name: "QueueName", visibility_timeout_seconds: "VisibilityTimeout", fifo_queue: "FifoQueue", delay_seconds: "DelaySeconds" }, tags: true },
+
+  // ── IAM ──
+  { tfType: "aws_iam_role", tier: 2, nativeType: "AWS::IAM::Role", ctor: "Role", identityAttr: "name",
+    fields: { name: "RoleName", assume_role_policy: json("AssumeRolePolicyDocument"), managed_policy_arns: "ManagedPolicyArns", description: "Description", path: "Path" }, tags: true },
+  { tfType: "aws_iam_policy", tier: 1, nativeType: "AWS::IAM::ManagedPolicy", ctor: "ManagedPolicy", identityAttr: "name",
+    fields: { name: "ManagedPolicyName", policy: json("PolicyDocument"), description: "Description", path: "Path" } },
+  { tfType: "aws_iam_instance_profile", tier: 1, nativeType: "AWS::IAM::InstanceProfile", ctor: "InstanceProfile", identityAttr: "name",
+    fields: { name: "InstanceProfileName", path: "Path", role: { prop: "Roles", transform: (v) => (v === undefined ? v : [v]) } } },
+
+  // ── Registry, keys, secrets, config ──
+  { tfType: "aws_ecr_repository", tier: 1, nativeType: "AWS::ECR::Repository", ctor: "ECRRepository", identityAttr: "name",
+    fields: { name: "RepositoryName", image_tag_mutability: "ImageTagMutability" }, tags: true },
+  { tfType: "aws_kms_key", tier: 2, nativeType: "AWS::KMS::Key", ctor: "KmsKey",
+    fields: { description: "Description", enable_key_rotation: "EnableKeyRotation", deletion_window_in_days: "PendingWindowInDays", is_enabled: "Enabled" }, tags: true },
+  { tfType: "aws_secretsmanager_secret", tier: 1, nativeType: "AWS::SecretsManager::Secret", ctor: "Secret", identityAttr: "name",
+    fields: { name: "Name", description: "Description", kms_key_id: "KmsKeyId" }, tags: true },
+  { tfType: "aws_ssm_parameter", tier: 1, nativeType: "AWS::SSM::Parameter", ctor: "SsmParameter", identityAttr: "name",
+    fields: { name: "Name", type: "Type", value: "Value", tier: "Tier", description: "Description" } },
+
+  // ── Compute ──
+  { tfType: "aws_lambda_function", tier: 2, nativeType: "AWS::Lambda::Function", ctor: "Function", identityAttr: "function_name",
+    fields: { function_name: "FunctionName", runtime: "Runtime", handler: "Handler", memory_size: "MemorySize", timeout: "Timeout", description: "Description", architectures: "Architectures" }, tags: true },
+  { tfType: "aws_ecs_service", tier: 3, nativeType: "AWS::ECS::Service", ctor: "EcsService", identityAttr: "name",
+    fields: { name: "ServiceName", cluster: "Cluster", desired_count: "DesiredCount", launch_type: "LaunchType", task_definition: "TaskDefinition" }, tags: true },
+
+  // ── Networking ──
+  { tfType: "aws_vpc", tier: 1, nativeType: "AWS::EC2::VPC", ctor: "Vpc",
+    fields: { cidr_block: "CidrBlock", enable_dns_support: "EnableDnsSupport", enable_dns_hostnames: "EnableDnsHostnames", instance_tenancy: "InstanceTenancy" }, tags: true },
+  { tfType: "aws_subnet", tier: 1, nativeType: "AWS::EC2::Subnet", ctor: "Subnet",
+    fields: { vpc_id: "VpcId", cidr_block: "CidrBlock", availability_zone: "AvailabilityZone", map_public_ip_on_launch: "MapPublicIpOnLaunch" }, tags: true },
+  { tfType: "aws_security_group", tier: 2, nativeType: "AWS::EC2::SecurityGroup", ctor: "SecurityGroup", identityAttr: "name",
+    fields: { description: "GroupDescription", name: "GroupName", vpc_id: "VpcId" }, tags: true },
+  { tfType: "aws_route_table", tier: 2, nativeType: "AWS::EC2::RouteTable", ctor: "RouteTable",
+    fields: { vpc_id: "VpcId" }, tags: true },
+  { tfType: "aws_internet_gateway", tier: 1, nativeType: "AWS::EC2::InternetGateway", ctor: "InternetGateway",
+    fields: {}, tags: true },
+  { tfType: "aws_eip", tier: 1, nativeType: "AWS::EC2::EIP", ctor: "EIP",
+    fields: { domain: "Domain", instance: "InstanceId" }, tags: true },
+  { tfType: "aws_nat_gateway", tier: 2, nativeType: "AWS::EC2::NatGateway", ctor: "NatGateway",
+    fields: { subnet_id: "SubnetId", allocation_id: "AllocationId", connectivity_type: "ConnectivityType" }, tags: true },
+
+  // ── DNS & observability ──
+  { tfType: "aws_route53_zone", tier: 1, nativeType: "AWS::Route53::HostedZone", ctor: "HostedZone", identityAttr: "name",
+    fields: { name: "Name", comment: "HostedZoneConfig" } },
+  { tfType: "aws_cloudwatch_log_group", tier: 1, nativeType: "AWS::Logs::LogGroup", ctor: "LogGroup", identityAttr: "name",
+    fields: { name: "LogGroupName", retention_in_days: "RetentionInDays", kms_key_id: "KmsKeyId" }, tags: true },
+  { tfType: "aws_cloudwatch_metric_alarm", tier: 2, nativeType: "AWS::CloudWatch::Alarm", ctor: "Alarm", identityAttr: "alarm_name",
+    fields: { alarm_name: "AlarmName", comparison_operator: "ComparisonOperator", metric_name: "MetricName", namespace: "Namespace", threshold: "Threshold", evaluation_periods: "EvaluationPeriods", period: "Period", statistic: "Statistic", alarm_description: "AlarmDescription" }, tags: true },
+];
+
+const BY_TYPE = new Map(AWS_CARVE_TYPES.map((t) => [t.tfType, t]));
+
+export function awsCarveType(tfType: string): AwsCarveType | undefined {
+  return BY_TYPE.get(tfType);
+}
+
+/** TF `tags` map → CloudFormation `Tags` list of {Key, Value}. */
+function tagsToCfn(tags: unknown): Array<{ Key: string; Value: unknown }> | undefined {
+  if (!tags || typeof tags !== "object" || Array.isArray(tags)) return undefined;
+  const entries = Object.entries(tags as Record<string, unknown>);
+  return entries.length ? entries.map(([Key, Value]) => ({ Key, Value })) : undefined;
+}
+
+/**
+ * Apply an entry's field mappings to a resource's Terraform attributes, yielding
+ * CloudFormation properties and the set of attribute keys that were consumed
+ * (so the caller can report the rest as unmapped).
+ */
+export function applyAwsMapper(
+  entry: AwsCarveType,
+  attrs: Record<string, unknown>,
+): { props: Record<string, unknown>; mappedKeys: string[] } {
+  const props: Record<string, unknown> = {};
+  const mappedKeys: string[] = ["id", "arn"]; // identity/computed attrs, ignored not dropped
+  for (const [tfAttr, spec] of Object.entries(entry.fields)) {
+    const value = attrs[tfAttr];
+    if (value === undefined) continue;
+    if (typeof spec === "string") {
+      props[spec] = value;
+    } else {
+      const t = spec.transform(value);
+      if (t !== undefined) props[spec.prop] = t;
+    }
+    mappedKeys.push(tfAttr);
+  }
+  if (entry.tags) {
+    const tags = tagsToCfn(attrs.tags);
+    if (tags) props.Tags = tags;
+    mappedKeys.push("tags");
+  }
+  return { props, mappedKeys };
+}

package/src/terraform/bridge.test.ts

@@ -0,0 +1,118 @@
+import { describe, test, expect } from "vitest";
+import { buildGraph } from "./graph";
+import { boundaryReport } from "./carve";
+import { generateBridge, type CarvedIdentity } from "./bridge";
+import type { Hcl2JsonTree } from "./types";
+
+const workedExample: Hcl2JsonTree = {
+  resource: {
+    aws_s3_bucket: { assets: [{ bucket: "myapp-assets-prod" }] },
+    aws_lambda_function: {
+      api: [
+        {
+          function_name: "myapp-api",
+          environment: {
+            variables: {
+              ASSETS_BUCKET: "${aws_s3_bucket.assets.bucket}",
+              ASSETS_ARN: "${aws_s3_bucket.assets.arn}",
+            },
+          },
+        },
+      ],
+    },
+  },
+};
+
+// The original surviving Terraform text (bare HCL references, as authored).
+const API_TF = `resource "aws_lambda_function" "api" {
+  function_name = "myapp-api"
+  environment {
+    variables = {
+      ASSETS_BUCKET = aws_s3_bucket.assets.bucket
+      ASSETS_ARN    = aws_s3_bucket.assets.arn
+    }
+  }
+}
+`;
+
+const identities = new Map<string, CarvedIdentity>([
+  ["aws_s3_bucket.assets", { attr: "bucket", value: "myapp-assets-prod" }],
+]);
+
+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 plan = generateBridge(report, [{ path: "api.tf", content: API_TF }], identities);
+
+    expect(plan.dataSources).toHaveLength(1);
+    expect(plan.dataSources[0]).toMatchObject({ address: "aws_s3_bucket.assets", type: "aws_s3_bucket", name: "assets" });
+    expect(plan.dataSources[0].hcl).toBe(
+      'data "aws_s3_bucket" "assets" {\n  bucket = "myapp-assets-prod"\n}',
+    );
+  });
+
+  test("rewrites survivor references to the data source", () => {
+    const report = boundaryReport(buildGraph(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")!;
+    expect(rewrite.changed).toBe(true);
+    expect(rewrite.rewritten).toContain("data.aws_s3_bucket.assets.bucket");
+    expect(rewrite.rewritten).toContain("data.aws_s3_bucket.assets.arn");
+    // The bare references are gone.
+    expect(rewrite.rewritten).not.toMatch(/(?<!data\.)\baws_s3_bucket\.assets\.bucket/);
+  });
+
+  test("does not double-prefix an already-rewritten reference (idempotent)", () => {
+    const report = boundaryReport(buildGraph(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")!;
+    expect(rewrite.changed).toBe(false);
+    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`;
+    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);
+  });
+
+  test("unknown identity emits a TODO data source instead of a wrong value", () => {
+    const report = boundaryReport(buildGraph(workedExample), "aws_s3_bucket.assets")!;
+    const plan = generateBridge(report, [{ path: "api.tf", content: API_TF }], new Map());
+    expect(plan.dataSources[0].hcl).toContain("# TODO");
+  });
+});
+
+describe("generateBridge — outbound (deferred inputs)", () => {
+  test("records outbound edges as deferred deploy-time inputs", () => {
+    const tree: Hcl2JsonTree = {
+      resource: {
+        aws_sns_topic: { alerts: [{ name: "a" }] },
+        aws_sqs_queue: { dlq: [{ name: "d", redrive: "${aws_sns_topic.alerts.arn}" }] },
+      },
+    };
+    const report = boundaryReport(buildGraph(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" });
+  });
+});
+
+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 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");
+    expect(plan.runbook).toContain("terraform import aws_s3_bucket.assets");
+    expect(plan.runbook).toMatch(/reversible/i);
+  });
+});

package/src/terraform/bridge.ts

@@ -0,0 +1,164 @@
+/**
+ * Boundary bridging for the strangler-fig carve (#197) — the centerpiece.
+ *
+ * Carving a resource cuts edges. This generates the edits to the Terraform you
+ * LEAVE BEHIND so its plan stays valid once the resource is chant-owned:
+ *
+ *  - inbound edge  → the survivor loses its reference to the carved resource.
+ *    Bridge: add a `data` source for the (now chant-managed) resource and
+ *    rewrite the survivor's `type.name.attr` references to `data.type.name.attr`.
+ *    Required immediately, or `terraform plan` errors on the dangling ref.
+ *
+ *  - outbound edge → the carved resource read a value from a survivor. That
+ *    value must enter chant from outside synthesis, as a deploy-time input.
+ *    Deferred until apply; here we only record the provenance.
+ *
+ * Pure text transform over the original `.tf` content — no wasm, no shell, no
+ * mutation. The command layer writes the results and (optionally) diffs them
+ * into a git-applyable patch. A carve never destroys or recreates; the runbook
+ * is reversible via `terraform import`.
+ */
+
+import type { CarveReport } from "./carve";
+
+export interface CarvedIdentity {
+  /** The HCL identity attribute, e.g. `bucket` or `name`. */
+  attr?: string;
+  /** Its literal value, e.g. `myapp-assets-prod`. */
+  value?: string;
+}
+
+export interface DataSourceBlock {
+  /** Carved resource address the data source stands in for. */
+  address: string;
+  type: string;
+  name: string;
+  hcl: string;
+}
+
+export interface FileRewrite {
+  path: string;
+  original: string;
+  rewritten: string;
+  changed: boolean;
+}
+
+export interface DeferredInput {
+  survivor: string;
+  carved: string;
+  attrs: string[];
+  note: string;
+}
+
+export interface BridgePlan {
+  target: string;
+  dataSources: DataSourceBlock[];
+  rewrites: FileRewrite[];
+  deferredInputs: DeferredInput[];
+  runbook: string;
+}
+
+/** `aws_s3_bucket.assets` → a regex matching that reference head, not already `data.`-prefixed. */
+function referenceRegex(address: string): RegExp {
+  const escaped = address.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  // (?<!data\.) — do not double-prefix an existing data source reference.
+  return new RegExp(`(?<!data\\.)\\b${escaped}\\b`, "g");
+}
+
+function dataSourceHcl(type: string, name: string, identity: CarvedIdentity): string {
+  const body =
+    identity.attr && identity.value !== undefined
+      ? `  ${identity.attr} = ${JSON.stringify(identity.value)}`
+      : `  # TODO: identify the resource (its name/id was interpolated in the source)`;
+  return `data ${JSON.stringify(type)} ${JSON.stringify(name)} {\n${body}\n}`;
+}
+
+/**
+ * Build the bridge plan for a carve.
+ *
+ * @param report    the boundary report (from `boundaryReport`)
+ * @param files     every `.tf` file in the estate, as { path, content }
+ * @param identities physical identity per carved address, for the data sources
+ */
+export function generateBridge(
+  report: CarveReport,
+  files: Array<{ path: string; content: string }>,
+  identities: Map<string, CarvedIdentity>,
+): BridgePlan {
+  // Carved resources that something still depends on need a data source.
+  const carvedWithInbound = new Map<string, { type: string; name: string }>();
+  for (const e of report.inbound) {
+    const [type, ...rest] = e.carved.split(".");
+    carvedWithInbound.set(e.carved, { type, name: rest.join(".") });
+  }
+
+  const dataSources: DataSourceBlock[] = [...carvedWithInbound.entries()].map(([address, { type, name }]) => ({
+    address,
+    type,
+    name,
+    hcl: dataSourceHcl(type, name, identities.get(address) ?? {}),
+  }));
+
+  // Rewrite every survivor reference to the carved resources into a data ref.
+  const rewrites: FileRewrite[] = files.map(({ path, content }) => {
+    let rewritten = content;
+    for (const address of carvedWithInbound.keys()) {
+      rewritten = rewritten.replace(referenceRegex(address), `data.${address}`);
+    }
+    return { path, original: content, rewritten, changed: rewritten !== content };
+  });
+
+  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.`,
+  }));
+
+  return {
+    target: report.target,
+    dataSources,
+    rewrites,
+    deferredInputs,
+    runbook: buildRunbook(report, dataSources, deferredInputs),
+  };
+}
+
+/** The reversible, observe-first handoff runbook (#197). */
+function buildRunbook(report: CarveReport, dataSources: DataSourceBlock[], deferred: DeferredInput[]): string {
+  const carvedAddrs = report.carveSet.map((m) => m.address);
+  const L: string[] = [];
+  L.push(`# Carve-out: ${report.target} → chant   [observe-first, reversible]`);
+  L.push("");
+  L.push(`Peelability ${report.peelability}. Carves ${carvedAddrs.length} Terraform resource(s) into chant, leaving the live resource untouched.`);
+  L.push("");
+  L.push("## 1. Review the emitted chant source");
+  L.push("    (produced by `chant carve emit` — confirm it builds to a spec-true template)");
+  L.push("");
+  L.push("## 2. Stop Terraform managing the resource (does NOT destroy it)");
+  L.push(`    terraform state rm ${carvedAddrs.join(" ")}`);
+  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 (dataSources.length) {
+    L.push("    # apply the generated bridge patch — it adds these data sources and rewires references:");
+    for (const ds of dataSources) L.push(`    #   data.${ds.type}.${ds.name}  (for ${ds.address})`);
+  } else {
+    L.push("    # no inbound edges — no survivor patch needed.");
+  }
+  L.push("    terraform plan   # expect: in-place updates to the survivors only");
+  L.push("    terraform apply");
+  L.push("");
+  L.push("## 4. Adopt the live resource into chant (now an orphan)");
+  L.push("    chant carve emit --from <tf-dir> --select " + report.target + " --env <env>   # already done if you ran emit");
+  L.push("    # then apply the ownership marker so chant owns it (carve apply, next step)");
+  if (deferred.length) {
+    L.push("");
+    L.push("## Deferred deploy-time inputs (wire these when you turn the dial to apply)");
+    for (const d of deferred) L.push(`    - ${d.note}`);
+  }
+  L.push("");
+  L.push("## Rollback (any time before apply-graduation)");
+  L.push(`    terraform import ${report.target} <physical-id>   # back under Terraform`);
+  return L.join("\n");
+}

package/src/terraform/carve.test.ts

@@ -0,0 +1,97 @@
+import { describe, test, expect } from "vitest";
+import { buildGraph } from "./graph";
+import { resolveCarveSet, boundaryReport } from "./carve";
+import type { Hcl2JsonTree } from "./types";
+
+// #197 worked example: a bucket a Lambda reads, with a versioning sub-resource.
+const workedExample: Hcl2JsonTree = {
+  resource: {
+    aws_s3_bucket: { assets: [{ bucket: "myapp-assets-prod" }] },
+    aws_s3_bucket_versioning: {
+      assets: [{ bucket: "${aws_s3_bucket.assets.id}", versioning_configuration: { status: "Enabled" } }],
+    },
+    aws_lambda_function: {
+      api: [
+        {
+          environment: {
+            variables: {
+              ASSETS_BUCKET: "${aws_s3_bucket.assets.bucket}",
+              ASSETS_ARN: "${aws_s3_bucket.assets.arn}",
+            },
+          },
+        },
+      ],
+    },
+  },
+};
+
+describe("resolveCarveSet", () => {
+  test("selected node plus its folded sub-resources", () => {
+    const set = resolveCarveSet(buildGraph(workedExample), "aws_s3_bucket.assets");
+    expect(set.map((m) => m.address).sort()).toEqual([
+      "aws_s3_bucket.assets",
+      "aws_s3_bucket_versioning.assets",
+    ]);
+    const folded = set.find((m) => m.address === "aws_s3_bucket_versioning.assets");
+    expect(folded?.foldedInto).toBe("aws_s3_bucket.assets");
+  });
+
+  test("empty for an unknown address", () => {
+    expect(resolveCarveSet(buildGraph(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")!;
+    expect(report.target).toBe("aws_s3_bucket.assets");
+    expect(report.peelability).toBe(88);
+    expect(report.reversible).toBe(true);
+
+    // The only boundary edge is the Lambda → bucket inbound; the versioning →
+    // bucket edge is internal to the carve set and dropped.
+    expect(report.inbound).toEqual([
+      {
+        direction: "inbound",
+        survivor: "aws_lambda_function.api",
+        carved: "aws_s3_bucket.assets",
+        attrs: ["arn", "bucket"],
+        bridge: "tf-data-source",
+        required: "immediately",
+      },
+    ]);
+    expect(report.outbound).toEqual([]);
+  });
+
+  test("outbound edges become deferred inputs", () => {
+    const tree: Hcl2JsonTree = {
+      resource: {
+        aws_sns_topic: { alerts: [{ name: "a" }] },
+        aws_sqs_queue: { dlq: [{ name: "d", redrive: "${aws_sns_topic.alerts.arn}" }] },
+      },
+    };
+    // Carve the queue: it depends on the topic (a survivor) → outbound/deferred.
+    const report = boundaryReport(buildGraph(tree), "aws_sqs_queue.dlq")!;
+    expect(report.inbound).toEqual([]);
+    expect(report.outbound).toEqual([
+      {
+        direction: "outbound",
+        survivor: "aws_sns_topic.alerts",
+        carved: "aws_sqs_queue.dlq",
+        attrs: ["arn"],
+        bridge: "deferred-input",
+        required: "at-apply",
+      },
+    ]);
+  });
+
+  test("unsupported type is flagged in diagnostics", () => {
+    const tree: Hcl2JsonTree = { resource: { random_pet: { n: [{ length: 2 }] } } };
+    const report = boundaryReport(buildGraph(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();
+  });
+});

package/src/terraform/graduate.test.ts

@@ -0,0 +1,49 @@
+import { describe, test, expect } from "vitest";
+import { buildGraph } from "./graph";
+import { boundaryReport } from "./carve";
+import { graduationPlan, DEFAULT_TAG_OWNERSHIP_KEYS } from "./graduate";
+import type { Hcl2JsonTree } from "./types";
+
+const bucketTree: Hcl2JsonTree = {
+  resource: {
+    aws_s3_bucket: { assets: [{ bucket: "myapp-assets-prod" }] },
+    aws_lambda_function: { api: [{ x: "${aws_s3_bucket.assets.arn}" }] },
+  },
+};
+
+describe("graduationPlan", () => {
+  test("resolves the ownership marker + tags (chant-owned)", () => {
+    const report = boundaryReport(buildGraph(bucketTree), "aws_s3_bucket.assets")!;
+    const plan = graduationPlan(report, { stack: "assets", env: "prod" });
+
+    expect(plan.marker).toEqual({ stack: "assets", env: "prod" });
+    expect(plan.ownershipTags).toEqual({
+      [DEFAULT_TAG_OWNERSHIP_KEYS.managedBy]: "chant",
+      [DEFAULT_TAG_OWNERSHIP_KEYS.stack]: "assets",
+      [DEFAULT_TAG_OWNERSHIP_KEYS.env]: "prod",
+    });
+  });
+
+  test("stack defaults to the resource's local name", () => {
+    const report = boundaryReport(buildGraph(bucketTree), "aws_s3_bucket.assets")!;
+    const plan = graduationPlan(report);
+    expect(plan.marker.stack).toBe("assets");
+    expect(plan.ownershipTags).not.toHaveProperty(DEFAULT_TAG_OWNERSHIP_KEYS.env); // no env → omitted
+  });
+
+  test("runbook is reversible and BYOL (import rollback, no chant-runs-apply)", () => {
+    const report = boundaryReport(buildGraph(bucketTree), "aws_s3_bucket.assets")!;
+    const plan = graduationPlan(report, { env: "prod" });
+    const runbook = plan.steps.join("\n");
+    expect(runbook).toMatch(/terraform import aws_s3_bucket\.assets/);
+    expect(runbook).toMatch(/cloudformation deploy|ApplyOp/);
+    expect(runbook).toMatch(/lifecycle diff --live/);
+  });
+
+  test("warns when outbound edges leave deferred inputs to wire", () => {
+    // Carve the Lambda: it depends on the bucket (survivor) → outbound/deferred.
+    const report = boundaryReport(buildGraph(bucketTree), "aws_lambda_function.api")!;
+    const plan = graduationPlan(report, { env: "prod" });
+    expect(plan.warnings.join(" ")).toMatch(/deferred deploy-time input/i);
+  });
+});