@intentius/chant 0.124.12 → 0.124.14

package/dist/telemetry-attribution.js

@@ -0,0 +1,149 @@
+/**
+ * Telemetry attribution (#2558, #2524 D22, ws-060).
+ *
+ * A workload's spans carry resource attributes that name the declaration and
+ * the release that produced them, so a reader (hud, behold) can join a span
+ * back to a member, a release and a node of `chant workspace graph`. They use
+ * OpenTelemetry semantic conventions where those exist and a `chant.*`
+ * namespace for the rest ({@link TELEMETRY_ATTRIBUTES}).
+ *
+ * A lexicon that declares workloads stamps them as environment variables
+ * (`OTEL_SERVICE_NAME` and `OTEL_RESOURCE_ATTRIBUTES`, which every OTel SDK
+ * reads) when it builds inside a workspace. The build resolves the facts once
+ * ({@link resolveTelemetryAttribution}) and hands them to each serializer on
+ * `SerializeContext.telemetry`, and {@link telemetryEnvironment} turns them
+ * into the variables for one workload.
+ *
+ * Level 0 is untouched: a project with no `chant.workspace.json` above it,
+ * and no `telemetry.attribution: true` in its config, resolves to nothing and
+ * its output is the same bytes as before. The workspace declaration reader is
+ * imported only once a declaration has been found (#2525 rule 5, pinned by
+ * #2526's goldens), and this module's name keeps it off the workspace-module
+ * list.
+ */
+import { relative, resolve, sep } from "node:path";
+import { findWorkspaceRoot } from "./project-root.js";
+export const TELEMETRY_ATTRIBUTES = [
+    { key: "service.name", source: "the declaration's name", joinsTo: "the service", stampedAtBuild: true },
+    { key: "service.version", source: "the release's artifact digest", joinsTo: "the member's release ledger", stampedAtBuild: false },
+    { key: "deployment.environment.name", source: "the environment", joinsTo: "the ledger's environment", stampedAtBuild: true },
+    { key: "vcs.ref.head.revision", source: "the git SHA", joinsTo: "the workspace revision (D15)", stampedAtBuild: false },
+    { key: "chant.workspace", source: "the workspace declaration's `name`", joinsTo: "the workspace", stampedAtBuild: true },
+    { key: "chant.member", source: "the member name", joinsTo: "the member", stampedAtBuild: true },
+    { key: "chant.decl", source: "the declaration id", joinsTo: "the node in `chant workspace graph`", stampedAtBuild: true },
+];
+/** The config's opt-in or opt-out, `telemetry.attribution`. */
+function configured(config) {
+    const telemetry = config?.telemetry;
+    if (typeof telemetry !== "object" || telemetry === null)
+        return undefined;
+    const value = telemetry.attribution;
+    return typeof value === "boolean" ? value : undefined;
+}
+/**
+ * What a build at `projectDir` stamps, or `undefined` for nothing.
+ *
+ * Inside a workspace attribution is on, and `telemetry.attribution: false`
+ * turns it off. Outside one it is off, and `telemetry.attribution: true`
+ * turns it on, with the attributes that need no workspace (`chant.workspace`
+ * and `chant.member` are then absent).
+ *
+ * A declaration that can't be read stamps the workspace-free attributes only:
+ * `chant workspace check` is where a broken declaration is reported, and a
+ * build must not fail on it.
+ */
+export async function resolveTelemetryAttribution(projectDir, config, environment) {
+    const setting = configured(config);
+    if (setting === false)
+        return undefined;
+    const found = findWorkspaceRoot(projectDir);
+    if (!found && setting !== true)
+        return undefined;
+    const out = {};
+    if (found) {
+        // Only now does workspace code load.
+        try {
+            const { readDeclaration, resolveGroups, ownerOf } = await import("./workspace/declaration.js");
+            const { workingTree } = await import("./workspace/tree.js");
+            const tree = workingTree(found.dir);
+            const declaration = readDeclaration(tree);
+            out.workspace = declaration.name;
+            const rel = relative(found.dir, resolve(projectDir));
+            const owner = ownerOf(declaration, resolveGroups(declaration, tree), rel === "" ? "" : rel.split(sep).join("/"));
+            if (owner && "member" in owner)
+                out.member = owner.member.name;
+        }
+        catch {
+            // Left to `chant workspace check`.
+        }
+    }
+    if (environment)
+        out.environment = environment;
+    return out;
+}
+/** The environment variables that carry one workload's attributes. Keys the build can't fill are left out. */
+export function telemetryEnvironment(attribution, workload) {
+    const pairs = [
+        ["chant.workspace", attribution.workspace],
+        ["chant.member", attribution.member],
+        ["chant.decl", workload.decl],
+        ["deployment.environment.name", attribution.environment],
+        ["service.version", workload.version],
+    ];
+    return {
+        OTEL_SERVICE_NAME: workload.service,
+        OTEL_RESOURCE_ATTRIBUTES: pairs
+            .filter((p) => p[1] !== undefined && p[1] !== "")
+            .map(([k, v]) => `${k}=${encodeURIComponent(v)}`)
+            .join(","),
+    };
+}
+/**
+ * Add `extra` to a resource-attributes string a project already set. A key the
+ * project set keeps its value, so a team's own `chant.member` is never
+ * overwritten; a key it didn't set is appended.
+ */
+export function mergeResourceAttributes(existing, extra) {
+    const have = new Set(existing.split(",").map((kv) => kv.split("=")[0].trim()).filter(Boolean));
+    const added = extra.split(",").filter((kv) => kv !== "" && !have.has(kv.split("=")[0]));
+    return [existing, ...added].filter((s) => s !== "").join(",");
+}
+// ── Release attributes (#3061, ws-081) ─────────────────────────────
+/**
+ * The environment variable a deploy sets to the release attributes, as a
+ * suffix for `OTEL_RESOURCE_ATTRIBUTES`. A stamped workload's generated
+ * output appends it where the platform expands variables (Compose
+ * interpolation, a Kubernetes `$(VAR)` reference), so the committed files are
+ * the same bytes whatever is released.
+ */
+export const RELEASE_ATTRIBUTES_VARIABLE = "CHANT_RELEASE_ATTRIBUTES";
+/**
+ * The pod-template annotation a Kubernetes release writes the suffix to. A
+ * stamped container reads it into {@link RELEASE_ATTRIBUTES_VARIABLE} through
+ * the downward API; an absent annotation reads as empty.
+ */
+export const RELEASE_ATTRIBUTES_ANNOTATION = "chant.intentius.io/release-attributes";
+/**
+ * The release attributes as a suffix for `OTEL_RESOURCE_ATTRIBUTES`: each
+ * pair preceded by a comma and percent-encoded the way
+ * {@link telemetryEnvironment} encodes, or `""` when the release knows
+ * neither. The build-time list always has `chant.decl`, so the suffix never
+ * starts the list.
+ */
+export function releaseAttributesSuffix(release) {
+    if (!release)
+        return "";
+    const pairs = [
+        ["service.version", release.version],
+        ["vcs.ref.head.revision", release.revision],
+    ];
+    return pairs
+        .filter((p) => p[1] !== undefined && p[1] !== "")
+        .map(([k, v]) => `,${k}=${encodeURIComponent(v)}`)
+        .join("");
+}
+/** The variables a deploy step exports for a release: {@link RELEASE_ATTRIBUTES_VARIABLE}, or nothing. */
+export function releaseEnvironment(release) {
+    const suffix = releaseAttributesSuffix(release);
+    return suffix === "" ? {} : { [RELEASE_ATTRIBUTES_VARIABLE]: suffix };
+}

package/dist/terraform/__fixtures__/build-graph.js

@@ -0,0 +1,63 @@
+import { buildGraph, collectExpressions } from "../graph.js";
+/**
+ * Shortest-hop count from `address` back through inbound edges — how many
+ * dependents-of-dependents deep the estate goes behind that node (#2323).
+ * Production has no reachability pass yet (that is the spike's sub-issue 3);
+ * this is a test-only BFS over the same `TfGraph` shape, so a fixture's depth
+ * can be asserted without waiting on that feature. Folds/outputs are not
+ * special-cased: an output pseudo-address has no inbound edges by
+ * construction (`buildGraph` never lets anything reference an output), so it
+ * is always a dead end and never inflates the count.
+ */
+function inboundDepthOf(graph, address) {
+    let frontier = new Set([address]);
+    const visited = new Set(frontier);
+    let depth = 0;
+    for (;;) {
+        const next = new Set();
+        for (const e of graph.edges) {
+            if (frontier.has(e.to) && !visited.has(e.from))
+                next.add(e.from);
+        }
+        if (next.size === 0)
+            return depth;
+        depth++;
+        for (const addr of next)
+            visited.add(addr);
+        frontier = next;
+    }
+}
+/**
+ * The longest inbound chain anywhere in the graph — the same "depth" column
+ * the spike measured (docs/design/carve-dependency-blast-radius-spike.md
+ * section 2): 1 hop is a direct dependent, 2 is a dependent of a dependent,
+ * and so on. Every shipped fixture tops out at 1; `depth-estate` is built to
+ * clear that.
+ */
+export function maxTransitiveInboundDepth(graph) {
+    let max = 0;
+    for (const node of graph.nodes) {
+        const depth = inboundDepthOf(graph, node.address);
+        if (depth > max)
+            max = depth;
+    }
+    return max;
+}
+/**
+ * Test-only stand-in for the hcl2json expression AST (`parse.ts`'s
+ * `resolveExpressionRefs`). Fixture expressions are simple `${<accessor>}`
+ * templates, so each one's accessor list is just its interpolation bodies.
+ * Production never takes this path — `parseTerraformDir` resolves every
+ * expression through `getReferencesInExpression`.
+ */
+export function fixtureExprRefs(tree) {
+    const refs = new Map();
+    for (const expr of collectExpressions(tree)) {
+        refs.set(expr, [...expr.matchAll(/\$\{([^}]+)\}/g)].map((m) => m[1].trim()));
+    }
+    return refs;
+}
+/** `buildGraph` over a hand-written fixture tree, accessors derived per {@link fixtureExprRefs}. */
+export function buildFixtureGraph(tree) {
+    return buildGraph(tree, fixtureExprRefs(tree));
+}

package/dist/terraform/adopt-state.js

@@ -0,0 +1,40 @@
+/**
+ * Adopt a Terraform-managed resource into chant source from its `.tfstate`
+ * (#1009). This is the correct adoption source for carving OUT of Terraform:
+ * a TF resource is created through the provider API, not CloudFormation, so it
+ * is not in any CFN stack — but its resolved attributes ARE in the state file.
+ *
+ * The mapping itself belongs to the carve provider that owns the Terraform type
+ * (`carve-provider.ts`, #2016) — aws maps snake_case provider attributes to
+ * CloudFormation PascalCase props over the AWS carve-out table. This module is
+ * the dispatch: it resolves the provider and hands off. A new provider adds a
+ * file under `providers/`, never an edit here.
+ */
+import { canCarveEmit, carveEmitTypes } from "./tier-map.js";
+import { resolveEmitProvider } from "./carve-provider.js";
+export { PARAMS_IMPORT } from "./emit-source.js";
+/**
+ * Is this Terraform type adoptable from state (a provider emits it)? The same
+ * gate serves the live path, so both are the shared `canCarveEmit`.
+ */
+export function canAdoptFromState(tfType) {
+    return canCarveEmit(tfType);
+}
+/** Terraform types that can currently be adopted from state, for user-facing hints. */
+export function supportedStateAdoptionTypes() {
+    return carveEmitTypes();
+}
+/**
+ * Render chant source for a state-adopted resource, through the provider that
+ * owns its Terraform type. `params` carries the deferred outbound inputs the
+ * boundary report found (#998) and `folded` the carve set's sub-resources read
+ * from the same state file (#1637); what a provider does with them is its own
+ * business, and both are reported back on the {@link AdoptedSource}.
+ *
+ * Null means no registered provider emits this type — the caller has already
+ * refused it at the emit gate, so this is the belt-and-braces path.
+ */
+export function adoptFromState(resource, params = [], folded = []) {
+    const provider = resolveEmitProvider(resource.type);
+    return provider?.adopt?.(resource, params, folded) ?? null;
+}

package/dist/terraform/aws-resources.js

@@ -0,0 +1,384 @@
+/**
+ * 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.
+ */
+export const AWS_LEXICON_IMPORT = "@intentius/chant-lexicon-aws";
+/** Parse a Terraform JSON-string attribute (IAM policy docs) into an object. */
+const asJson = (v) => {
+    if (typeof v !== "string")
+        return v;
+    try {
+        return JSON.parse(v);
+    }
+    catch {
+        return v;
+    }
+};
+const json = (prop) => ({ prop, transform: asJson });
+/**
+ * Terraform state renders a nested block as a one-element list. Take that
+ * entry (or the object itself, if the provider wrote it unwrapped).
+ */
+function firstBlock(value) {
+    const candidate = Array.isArray(value) ? value[0] : value;
+    return candidate && typeof candidate === "object" ? candidate : undefined;
+}
+/**
+ * A list of TF server-side-encryption `rule` blocks → the CFN `BucketEncryption`
+ * property. Shared by the bucket's own (deprecated, still state-resident)
+ * `server_side_encryption_configuration` block and by the modern
+ * `aws_s3_bucket_server_side_encryption_configuration` sub-resource, whose
+ * `rule` list has the same shape.
+ */
+function sseRulesToCfn(rules) {
+    if (!Array.isArray(rules))
+        return undefined;
+    const cfnRules = [];
+    for (const raw of rules) {
+        if (!raw || typeof raw !== "object")
+            continue;
+        const rule = raw;
+        const out = {};
+        const byDefault = firstBlock(rule.apply_server_side_encryption_by_default);
+        const algorithm = byDefault?.sse_algorithm;
+        if (typeof algorithm === "string" && algorithm) {
+            const sse = { SSEAlgorithm: algorithm };
+            const kmsKey = byDefault?.kms_master_key_id;
+            if (typeof kmsKey === "string" && kmsKey)
+                sse.KMSMasterKeyID = kmsKey;
+            out.ServerSideEncryptionByDefault = sse;
+        }
+        if (typeof rule.bucket_key_enabled === "boolean")
+            out.BucketKeyEnabled = rule.bucket_key_enabled;
+        if (Object.keys(out).length)
+            cfnRules.push(out);
+    }
+    return cfnRules.length ? { ServerSideEncryptionConfiguration: cfnRules } : undefined;
+}
+/**
+ * The bucket's own deprecated `versioning` block, as state still carries it.
+ * Only an enabled bucket says anything CloudFormation needs: a bucket that
+ * never had versioning has no `VersioningConfiguration` at all, so `enabled =
+ * false` maps to nothing and the block stays in the unmapped comment.
+ */
+function legacyVersioningToCfn(value) {
+    const block = firstBlock(value);
+    return block?.enabled === true ? { Status: "Enabled" } : undefined;
+}
+export const AWS_CARVE_TYPES = [
+    // ── Storage & data ──
+    { tfType: "aws_s3_bucket", tier: 1, nativeType: "AWS::S3::Bucket", ctor: "Bucket", identityAttr: "bucket",
+        fields: {
+            bucket: "BucketName",
+            // The provider still resolves these two into the bucket's own state, even
+            // when the config declares them through sub-resources (#1637).
+            server_side_encryption_configuration: { prop: "BucketEncryption", transform: (v) => sseRulesToCfn(firstBlock(v)?.rule) },
+            versioning: { prop: "VersioningConfiguration", transform: legacyVersioningToCfn },
+        }, 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 },
+    { tfType: "aws_cloudwatch_event_rule", tier: 2, nativeType: "AWS::Events::Rule", ctor: "EventRule", identityAttr: "name",
+        fields: { name: "Name", schedule_expression: "ScheduleExpression", event_pattern: json("EventPattern"), description: "Description", state: "State" } },
+    // ── Compute (EC2 / ECS / ASG) ──
+    { tfType: "aws_instance", tier: 2, nativeType: "AWS::EC2::Instance", ctor: "Instance",
+        fields: { ami: "ImageId", instance_type: "InstanceType", subnet_id: "SubnetId", key_name: "KeyName", availability_zone: "AvailabilityZone", iam_instance_profile: "IamInstanceProfile" }, tags: true },
+    { tfType: "aws_launch_template", tier: 2, nativeType: "AWS::EC2::LaunchTemplate", ctor: "LaunchTemplate", identityAttr: "name",
+        fields: { name: "LaunchTemplateName" }, tags: true },
+    { tfType: "aws_autoscaling_group", tier: 2, nativeType: "AWS::AutoScaling::AutoScalingGroup", ctor: "AutoScalingGroup", identityAttr: "name",
+        fields: { name: "AutoScalingGroupName", min_size: "MinSize", max_size: "MaxSize", desired_capacity: "DesiredCapacity", vpc_zone_identifier: "VPCZoneIdentifier", health_check_type: "HealthCheckType" } },
+    { tfType: "aws_ecs_cluster", tier: 1, nativeType: "AWS::ECS::Cluster", ctor: "EcsCluster", identityAttr: "name",
+        fields: { name: "ClusterName" }, tags: true },
+    { tfType: "aws_ecs_task_definition", tier: 3, nativeType: "AWS::ECS::TaskDefinition", ctor: "TaskDefinition", identityAttr: "family",
+        fields: { family: "Family", cpu: "Cpu", memory: "Memory", network_mode: "NetworkMode", execution_role_arn: "ExecutionRoleArn", task_role_arn: "TaskRoleArn" }, tags: true },
+    { tfType: "aws_ebs_volume", tier: 1, nativeType: "AWS::EC2::Volume", ctor: "EC2Volume",
+        fields: { availability_zone: "AvailabilityZone", size: "Size", type: "VolumeType", encrypted: "Encrypted", iops: "Iops" }, tags: true },
+    // ── Load balancing (ELBv2; aws_alb is a legacy alias) ──
+    { tfType: "aws_lb", tier: 2, nativeType: "AWS::ElasticLoadBalancingV2::LoadBalancer", ctor: "LoadBalancer", identityAttr: "name",
+        fields: { name: "Name", load_balancer_type: "Type", internal: { prop: "Scheme", transform: (v) => (v === true ? "internal" : v === false ? "internet-facing" : v) } }, tags: true },
+    { tfType: "aws_alb", tier: 2, nativeType: "AWS::ElasticLoadBalancingV2::LoadBalancer", ctor: "LoadBalancer", identityAttr: "name",
+        fields: { name: "Name", load_balancer_type: "Type", internal: { prop: "Scheme", transform: (v) => (v === true ? "internal" : v === false ? "internet-facing" : v) } }, tags: true },
+    { tfType: "aws_lb_target_group", tier: 2, nativeType: "AWS::ElasticLoadBalancingV2::TargetGroup", ctor: "TargetGroup", identityAttr: "name",
+        fields: { name: "Name", port: "Port", protocol: "Protocol", vpc_id: "VpcId", target_type: "TargetType" }, tags: true },
+    { tfType: "aws_lb_listener", tier: 2, nativeType: "AWS::ElasticLoadBalancingV2::Listener", ctor: "Listener",
+        fields: { port: "Port", protocol: "Protocol", load_balancer_arn: "LoadBalancerArn" } },
+    // ── Databases & cache ──
+    { tfType: "aws_db_instance", tier: 2, nativeType: "AWS::RDS::DBInstance", ctor: "DbInstance", identityAttr: "identifier",
+        fields: { identifier: "DBInstanceIdentifier", engine: "Engine", engine_version: "EngineVersion", instance_class: "DBInstanceClass", allocated_storage: "AllocatedStorage", db_name: "DBName", multi_az: "MultiAZ", storage_encrypted: "StorageEncrypted" }, tags: true },
+    { tfType: "aws_db_subnet_group", tier: 1, nativeType: "AWS::RDS::DBSubnetGroup", ctor: "RDSDBSubnetGroup", identityAttr: "name",
+        fields: { name: "DBSubnetGroupName", description: "DBSubnetGroupDescription", subnet_ids: "SubnetIds" }, tags: true },
+    { tfType: "aws_elasticache_cluster", tier: 2, nativeType: "AWS::ElastiCache::CacheCluster", ctor: "CacheCluster", identityAttr: "cluster_id",
+        fields: { cluster_id: "ClusterName", engine: "Engine", node_type: "CacheNodeType", num_cache_nodes: "NumCacheNodes", engine_version: "EngineVersion" }, tags: true },
+    { tfType: "aws_elasticache_replication_group", tier: 2, nativeType: "AWS::ElastiCache::ReplicationGroup", ctor: "ReplicationGroup", identityAttr: "replication_group_id",
+        fields: { replication_group_id: "ReplicationGroupId", description: "ReplicationGroupDescription", node_type: "CacheNodeType", engine: "Engine" }, tags: true },
+    // ── DNS, CDN & API ──
+    { tfType: "aws_route53_record", tier: 2, nativeType: "AWS::Route53::RecordSet", ctor: "RecordSet", identityAttr: "name",
+        fields: { name: "Name", type: "Type", ttl: "TTL", zone_id: "HostedZoneId", records: "ResourceRecords" } },
+    { tfType: "aws_api_gateway_rest_api", tier: 2, nativeType: "AWS::ApiGateway::RestApi", ctor: "RestApi", identityAttr: "name",
+        fields: { name: "Name", description: "Description" }, tags: true },
+    { tfType: "aws_apigatewayv2_api", tier: 2, nativeType: "AWS::ApiGatewayV2::Api", ctor: "HttpApi", identityAttr: "name",
+        fields: { name: "Name", protocol_type: "ProtocolType", description: "Description" }, tags: true },
+    // ── IAM (users/groups), certs & keys ──
+    { tfType: "aws_iam_user", tier: 1, nativeType: "AWS::IAM::User", ctor: "IAMUser", identityAttr: "name",
+        fields: { name: "UserName", path: "Path" }, tags: true },
+    { tfType: "aws_iam_group", tier: 1, nativeType: "AWS::IAM::Group", ctor: "IAMGroup", identityAttr: "name",
+        fields: { name: "GroupName", path: "Path" } },
+    { tfType: "aws_acm_certificate", tier: 2, nativeType: "AWS::CertificateManager::Certificate", ctor: "AcmCertificate", identityAttr: "domain_name",
+        fields: { domain_name: "DomainName", validation_method: "ValidationMethod", subject_alternative_names: "SubjectAlternativeNames" }, tags: true },
+    { tfType: "aws_kms_alias", tier: 1, nativeType: "AWS::KMS::Alias", ctor: "KMSAlias", identityAttr: "name",
+        fields: { name: "AliasName", target_key_id: "TargetKeyId" } },
+    // ── Messaging & step functions ──
+    { tfType: "aws_sns_topic_subscription", tier: 2, nativeType: "AWS::SNS::Subscription", ctor: "Subscription",
+        fields: { protocol: "Protocol", endpoint: "Endpoint", topic_arn: "TopicArn" } },
+    { tfType: "aws_sfn_state_machine", tier: 3, nativeType: "AWS::StepFunctions::StateMachine", ctor: "StateMachine", identityAttr: "name",
+        fields: { name: "StateMachineName", role_arn: "RoleArn", type: "StateMachineType" }, tags: true },
+    { tfType: "aws_sqs_queue_policy", tier: 2, nativeType: "AWS::SQS::QueuePolicy", ctor: "QueuePolicy",
+        fields: { policy: json("PolicyDocument"), queue_url: { prop: "Queues", transform: (v) => (v === undefined ? v : [v]) } } },
+    { tfType: "aws_sns_topic_policy", tier: 2, nativeType: "AWS::SNS::TopicPolicy", ctor: "TopicPolicy",
+        fields: { policy: json("PolicyDocument"), arn: { prop: "Topics", transform: (v) => (v === undefined ? v : [v]) } } },
+    // ── Streaming ──
+    { tfType: "aws_kinesis_stream", tier: 1, nativeType: "AWS::Kinesis::Stream", ctor: "KinesisStream", identityAttr: "name",
+        fields: { name: "Name", shard_count: "ShardCount", retention_period: "RetentionPeriodHours" }, tags: true },
+    { tfType: "aws_kinesis_firehose_delivery_stream", tier: 3, nativeType: "AWS::KinesisFirehose::DeliveryStream", ctor: "DeliveryStream", identityAttr: "name",
+        fields: { name: "DeliveryStreamName" }, tags: true },
+    // ── EKS ──
+    { tfType: "aws_eks_cluster", tier: 2, nativeType: "AWS::EKS::Cluster", ctor: "EKSCluster", identityAttr: "name",
+        fields: { name: "Name", role_arn: "RoleArn", version: "Version" }, tags: true },
+    { tfType: "aws_eks_node_group", tier: 2, nativeType: "AWS::EKS::Nodegroup", ctor: "Nodegroup", identityAttr: "node_group_name",
+        fields: { cluster_name: "ClusterName", node_group_name: "NodegroupName", node_role_arn: "NodeRole", subnet_ids: "Subnets",
+            instance_types: "InstanceTypes", ami_type: "AmiType", capacity_type: "CapacityType", disk_size: "DiskSize" } },
+    // ── Lambda periphery ──
+    { tfType: "aws_lambda_permission", tier: 1, nativeType: "AWS::Lambda::Permission", ctor: "Permission",
+        fields: { action: "Action", function_name: "FunctionName", principal: "Principal", source_arn: "SourceArn", source_account: "SourceAccount" } },
+    { tfType: "aws_lambda_event_source_mapping", tier: 2, nativeType: "AWS::Lambda::EventSourceMapping", ctor: "EventSourceMapping",
+        fields: { event_source_arn: "EventSourceArn", function_name: "FunctionName", batch_size: "BatchSize", enabled: "Enabled",
+            starting_position: "StartingPosition", maximum_batching_window_in_seconds: "MaximumBatchingWindowInSeconds" } },
+    { tfType: "aws_lambda_alias", tier: 1, nativeType: "AWS::Lambda::Alias", ctor: "LambdaAlias", identityAttr: "name",
+        fields: { name: "Name", function_name: "FunctionName", function_version: "FunctionVersion", description: "Description" } },
+    { tfType: "aws_lambda_layer_version", tier: 2, nativeType: "AWS::Lambda::LayerVersion", ctor: "LayerVersion", identityAttr: "layer_name",
+        fields: { layer_name: "LayerName", description: "Description", compatible_runtimes: "CompatibleRuntimes",
+            compatible_architectures: "CompatibleArchitectures", license_info: "LicenseInfo" } },
+    // ── Networking (endpoints, routes, peering, flow logs) ──
+    { tfType: "aws_vpc_endpoint", tier: 2, nativeType: "AWS::EC2::VPCEndpoint", ctor: "VPCEndpoint",
+        fields: { vpc_id: "VpcId", service_name: "ServiceName", vpc_endpoint_type: "VpcEndpointType", route_table_ids: "RouteTableIds",
+            subnet_ids: "SubnetIds", security_group_ids: "SecurityGroupIds", private_dns_enabled: "PrivateDnsEnabled", policy: json("PolicyDocument") }, tags: true },
+    { tfType: "aws_route_table_association", tier: 2, nativeType: "AWS::EC2::SubnetRouteTableAssociation", ctor: "SubnetRouteTableAssociation",
+        fields: { subnet_id: "SubnetId", route_table_id: "RouteTableId" } },
+    { tfType: "aws_route", tier: 2, nativeType: "AWS::EC2::Route", ctor: "EC2Route",
+        fields: { route_table_id: "RouteTableId", destination_cidr_block: "DestinationCidrBlock", destination_ipv6_cidr_block: "DestinationIpv6CidrBlock",
+            gateway_id: "GatewayId", nat_gateway_id: "NatGatewayId", transit_gateway_id: "TransitGatewayId",
+            vpc_peering_connection_id: "VpcPeeringConnectionId", network_interface_id: "NetworkInterfaceId" } },
+    { tfType: "aws_egress_only_internet_gateway", tier: 1, nativeType: "AWS::EC2::EgressOnlyInternetGateway", ctor: "EgressOnlyInternetGateway",
+        fields: { vpc_id: "VpcId" } },
+    { tfType: "aws_vpc_peering_connection", tier: 2, nativeType: "AWS::EC2::VPCPeeringConnection", ctor: "VPCPeeringConnection",
+        fields: { vpc_id: "VpcId", peer_vpc_id: "PeerVpcId", peer_owner_id: "PeerOwnerId", peer_region: "PeerRegion" }, tags: true },
+    { tfType: "aws_flow_log", tier: 2, nativeType: "AWS::EC2::FlowLog", ctor: "FlowLog",
+        fields: { traffic_type: "TrafficType", log_destination: "LogDestination", log_destination_type: "LogDestinationType",
+            iam_role_arn: "DeliverLogsPermissionArn", log_group_name: "LogGroupName", max_aggregation_interval: "MaxAggregationInterval" }, tags: true },
+    { tfType: "aws_key_pair", tier: 1, nativeType: "AWS::EC2::KeyPair", ctor: "KeyPair", identityAttr: "key_name",
+        fields: { key_name: "KeyName", public_key: "PublicKeyMaterial" }, tags: true },
+    // ── Audit & observability ──
+    { tfType: "aws_cloudtrail", tier: 2, nativeType: "AWS::CloudTrail::Trail", ctor: "Trail", identityAttr: "name",
+        fields: { name: "TrailName", s3_bucket_name: "S3BucketName", s3_key_prefix: "S3KeyPrefix",
+            include_global_service_events: "IncludeGlobalServiceEvents", is_multi_region_trail: "IsMultiRegionTrail",
+            enable_logging: "IsLogging", enable_log_file_validation: "EnableLogFileValidation", kms_key_id: "KMSKeyId",
+            sns_topic_name: "SnsTopicName", cloud_watch_logs_group_arn: "CloudWatchLogsLogGroupArn", cloud_watch_logs_role_arn: "CloudWatchLogsRoleArn" }, tags: true },
+    { tfType: "aws_cloudwatch_dashboard", tier: 1, nativeType: "AWS::CloudWatch::Dashboard", ctor: "CwDashboard", identityAttr: "dashboard_name",
+        fields: { dashboard_name: "DashboardName", dashboard_body: "DashboardBody" } },
+    // ── Databases & cache (groups, clusters) ──
+    { tfType: "aws_elasticache_subnet_group", tier: 1, nativeType: "AWS::ElastiCache::SubnetGroup", ctor: "EcSubnetGroup", identityAttr: "name",
+        fields: { name: "CacheSubnetGroupName", description: "Description", subnet_ids: "SubnetIds" }, tags: true },
+    { tfType: "aws_db_parameter_group", tier: 2, nativeType: "AWS::RDS::DBParameterGroup", ctor: "RDSDBParameterGroup", identityAttr: "name",
+        fields: { name: "DBParameterGroupName", family: "Family", description: "Description" }, tags: true },
+    { tfType: "aws_rds_cluster", tier: 2, nativeType: "AWS::RDS::DBCluster", ctor: "DbCluster", identityAttr: "cluster_identifier",
+        fields: { cluster_identifier: "DBClusterIdentifier", engine: "Engine", engine_version: "EngineVersion", database_name: "DatabaseName",
+            master_username: "MasterUsername", backup_retention_period: "BackupRetentionPeriod", preferred_backup_window: "PreferredBackupWindow",
+            storage_encrypted: "StorageEncrypted", kms_key_id: "KmsKeyId", port: "Port" }, tags: true },
+    // ── Load balancing & API stages ──
+    { tfType: "aws_lb_listener_rule", tier: 3, nativeType: "AWS::ElasticLoadBalancingV2::ListenerRule", ctor: "ListenerRule",
+        fields: { listener_arn: "ListenerArn", priority: "Priority" } },
+    { tfType: "aws_api_gateway_stage", tier: 2, nativeType: "AWS::ApiGateway::Stage", ctor: "ApigwStage", identityAttr: "stage_name",
+        fields: { rest_api_id: "RestApiId", stage_name: "StageName", deployment_id: "DeploymentId", description: "Description" }, tags: true },
+    { tfType: "aws_api_gateway_deployment", tier: 2, nativeType: "AWS::ApiGateway::Deployment", ctor: "ApigwDeployment",
+        fields: { rest_api_id: "RestApiId", description: "Description" } },
+    { tfType: "aws_apigatewayv2_stage", tier: 2, nativeType: "AWS::ApiGatewayV2::Stage", ctor: "Apigwv2Stage", identityAttr: "name",
+        fields: { api_id: "ApiId", name: "StageName", auto_deploy: "AutoDeploy", description: "Description" } },
+    // ── Identity & scaling ──
+    { tfType: "aws_cognito_user_pool", tier: 3, nativeType: "AWS::Cognito::UserPool", ctor: "UserPool", identityAttr: "name",
+        fields: { name: "UserPoolName", mfa_configuration: "MfaConfiguration", deletion_protection: "DeletionProtection" } },
+    { tfType: "aws_appautoscaling_target", tier: 2, nativeType: "AWS::ApplicationAutoScaling::ScalableTarget", ctor: "ScalableTarget",
+        fields: { max_capacity: "MaxCapacity", min_capacity: "MinCapacity", resource_id: "ResourceId",
+            scalable_dimension: "ScalableDimension", service_namespace: "ServiceNamespace", role_arn: "RoleARN" } },
+    // ── EFS periphery ──
+    { tfType: "aws_efs_mount_target", tier: 1, nativeType: "AWS::EFS::MountTarget", ctor: "EFSMountTarget",
+        fields: { file_system_id: "FileSystemId", subnet_id: "SubnetId", ip_address: "IpAddress", security_groups: "SecurityGroups" } },
+    { tfType: "aws_efs_access_point", tier: 2, nativeType: "AWS::EFS::AccessPoint", ctor: "EFSAccessPoint",
+        fields: { file_system_id: "FileSystemId" } },
+];
+const BY_TYPE = new Map(AWS_CARVE_TYPES.map((t) => [t.tfType, t]));
+export function awsCarveType(tfType) {
+    return BY_TYPE.get(tfType);
+}
+/** Identity and parent-link attributes: never content, never reported unmapped. */
+const FOLD_LINK_ATTRS = new Set(["id", "arn", "bucket"]);
+export const AWS_FOLD_MAPPERS = {
+    aws_s3_bucket_versioning: {
+        consumes: ["versioning_configuration"],
+        map: (attrs) => {
+            const status = firstBlock(attrs.versioning_configuration)?.status;
+            // CFN takes Enabled/Suspended only; TF's third state ("Disabled", write-once
+            // buckets) has no CloudFormation spelling and stays in the comment.
+            return status === "Enabled" || status === "Suspended" ? { VersioningConfiguration: { Status: status } } : {};
+        },
+    },
+    aws_s3_bucket_public_access_block: {
+        consumes: ["block_public_acls", "block_public_policy", "ignore_public_acls", "restrict_public_buckets"],
+        map: (attrs) => {
+            const config = {};
+            const flags = [
+                ["block_public_acls", "BlockPublicAcls"],
+                ["block_public_policy", "BlockPublicPolicy"],
+                ["ignore_public_acls", "IgnorePublicAcls"],
+                ["restrict_public_buckets", "RestrictPublicBuckets"],
+            ];
+            for (const [tfAttr, prop] of flags) {
+                if (typeof attrs[tfAttr] === "boolean")
+                    config[prop] = attrs[tfAttr];
+            }
+            return Object.keys(config).length ? { PublicAccessBlockConfiguration: config } : {};
+        },
+    },
+    aws_s3_bucket_server_side_encryption_configuration: {
+        consumes: ["rule"],
+        map: (attrs) => {
+            const encryption = sseRulesToCfn(attrs.rule);
+            return encryption ? { BucketEncryption: encryption } : {};
+        },
+    },
+};
+/**
+ * Apply a folded sub-resource's state attributes to its parent's properties.
+ *
+ * Returns the props it contributes plus the attributes that stay genuinely
+ * unmappable (which the emitted source preserves in its reference comment). A
+ * mapper that produced nothing consumes nothing — the caller reports the whole
+ * sub-resource rather than claiming a fold that did not happen. `null` means
+ * this sub-resource type has no fold mapping at all.
+ */
+export function applyAwsFold(tfType, attrs) {
+    const mapper = AWS_FOLD_MAPPERS[tfType];
+    if (!mapper)
+        return null;
+    const props = mapper.map(attrs);
+    const consumed = new Set(Object.keys(props).length ? mapper.consumes : []);
+    return { props, unmapped: unmappedFoldAttrs(attrs, consumed) };
+}
+/** A folded sub-resource's attributes minus what was consumed and its parent link. */
+export function unmappedFoldAttrs(attrs, consumed = new Set()) {
+    const rest = {};
+    for (const [key, value] of Object.entries(attrs)) {
+        if (consumed.has(key) || FOLD_LINK_ATTRS.has(key))
+            continue;
+        rest[key] = value;
+    }
+    return rest;
+}
+/** TF `tags` map → CloudFormation `Tags` list of {Key, Value}. */
+function tagsToCfn(tags) {
+    if (!tags || typeof tags !== "object" || Array.isArray(tags))
+        return undefined;
+    const entries = Object.entries(tags);
+    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, attrs) {
+    const props = {};
+    const mappedKeys = ["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 {
+            // A transform that declines (undefined) has mapped nothing — the attribute
+            // stays in the unmapped report rather than being claimed and dropped.
+            const t = spec.transform(value);
+            if (t === undefined)
+                continue;
+            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 };
+}