@intentius/chant 0.52.2 → 0.53.1

package/src/terraform/adopt-state.test.ts

@@ -159,3 +159,134 @@ describe("adoptFromState", () => {
     expect(adoptFromState({ type: "random_pet", name: "x", attributes: { id: "abc" } })).toBeNull();
   });
 });
+
+/**
+ * `kubernetes_manifest` adoption (#999). The Terraform type names no kind: the
+ * target is whatever the manifest body says it is, so these assertions are
+ * about reading the body, not about a per-type property mapping.
+ */
+describe("adoptFromState — kubernetes_manifest", () => {
+  const configMap: StateResource = {
+    type: "kubernetes_manifest",
+    name: "app_config",
+    attributes: {
+      manifest: {
+        apiVersion: "v1",
+        kind: "ConfigMap",
+        metadata: { name: "app-config", namespace: "web", labels: { "app.kubernetes.io/name": "web" } },
+        data: { LOG_LEVEL: "info" },
+      },
+      field_manager: null,
+      wait: null,
+      computed_fields: ["metadata.labels", "metadata.annotations"],
+    },
+  };
+
+  test("adopts the manifest body verbatim through the lexicon escape hatch", () => {
+    const out = adoptFromState(configMap)!;
+    expect(out.fileName).toBe("app_config.ts");
+    expect(out.mapped).toBe(true);
+    // The kind came out of the body, not out of the Terraform type.
+    expect(out.nativeType).toBe("v1 ConfigMap");
+
+    expect(out.content).toContain('import { k8sManifest } from "@intentius/chant-lexicon-k8s";');
+    expect(out.content).toContain("export const app_config = k8sManifest({");
+    expect(out.content).toContain('apiVersion: "v1"');
+    expect(out.content).toContain('kind: "ConfigMap"');
+    expect(out.content).toContain('namespace: "web"');
+    // A key that is not an identifier is quoted, so the emitted source parses.
+    expect(out.content).toContain('"app.kubernetes.io/name": "web"');
+    expect(out.content).toContain('LOG_LEVEL: "info"');
+    // Provider knobs are reported, never smuggled into the object.
+    expect(out.content).toContain("Provider-behaviour attributes not part of the object: computed_fields");
+    expect(out.content).not.toContain("computed_fields:");
+    expect(out.folded).toEqual([]);
+  });
+
+  test("a CRD body needs no per-type mapping — one rule covers every kind", () => {
+    const out = adoptFromState({
+      type: "kubernetes_manifest",
+      name: "cert",
+      attributes: {
+        manifest: {
+          apiVersion: "cert-manager.io/v1",
+          kind: "Certificate",
+          metadata: { name: "web-tls", namespace: "web" },
+          spec: {
+            secretName: "web-tls",
+            dnsNames: ["web.example.com"],
+            issuerRef: { name: "letsencrypt", kind: "ClusterIssuer" },
+          },
+        },
+      },
+    })!;
+    expect(out.nativeType).toBe("cert-manager.io/v1 Certificate");
+    expect(out.content).toContain('apiVersion: "cert-manager.io/v1"');
+    expect(out.content).toContain('kind: "Certificate"');
+    expect(out.content).toContain('secretName: "web-tls"');
+    expect(out.content).toContain('"web.example.com",');
+  });
+
+  test("falls back to the computed object, without the fields the API server owns", () => {
+    const out = adoptFromState({
+      type: "kubernetes_manifest",
+      name: "ns",
+      attributes: {
+        object: {
+          apiVersion: "v1",
+          kind: "Namespace",
+          metadata: {
+            name: "web",
+            uid: "8f1e",
+            resourceVersion: "4711",
+            creationTimestamp: "2026-01-01T00:00:00Z",
+            labels: {},
+          },
+          status: { phase: "Active" },
+        },
+      },
+    })!;
+    expect(out.content).toContain('name: "web"');
+    expect(out.content).not.toContain("resourceVersion");
+    expect(out.content).not.toContain("creationTimestamp");
+    expect(out.content).not.toContain("uid");
+    expect(out.content).not.toContain("status");
+  });
+
+  test("a deferred input is reported in the source, not substituted", () => {
+    // The survivor value sits inside the body, so the boundary report names the
+    // enclosing `manifest` attribute and state resolves it to an object —
+    // there is no scalar for a `params.<name>` reference to replace.
+    const params: DeferredParam[] = [
+      { name: "manifest", tfAttr: "manifest", survivor: "aws_eks_cluster.main", attrs: ["endpoint"] },
+    ];
+    const out = adoptFromState(configMap, params)!;
+    expect(out.parameterized).toEqual([]);
+    expect(out.content).toContain("Deferred deploy-time input: manifest read aws_eks_cluster.main.endpoint");
+    expect(out.content).toContain('declared as build param "manifest" in chant.config.ts');
+    expect(out.content).not.toContain("params.");
+  });
+
+  test("a name Terraform allows but TypeScript does not becomes an identifier", () => {
+    const out = adoptFromState({
+      type: "kubernetes_manifest",
+      name: "app-config",
+      attributes: { manifest: { apiVersion: "v1", kind: "ConfigMap", metadata: { name: "app-config" } } },
+    })!;
+    expect(out.fileName).toBe("app_config.ts");
+    expect(out.content).toContain("export const app_config = k8sManifest({");
+  });
+
+  test("a body without apiVersion/kind is refused rather than emitted headless", () => {
+    expect(
+      adoptFromState({ type: "kubernetes_manifest", name: "x", attributes: { manifest: { metadata: { name: "x" } } } }),
+    ).toBeNull();
+    expect(adoptFromState({ type: "kubernetes_manifest", name: "x", attributes: {} })).toBeNull();
+  });
+
+  test("a typed kubernetes resource is ranked but not adoptable", () => {
+    expect(canAdoptFromState("kubernetes_manifest")).toBe(true);
+    expect(canAdoptFromState("kubernetes_config_map")).toBe(false);
+    expect(adoptFromState({ type: "kubernetes_config_map", name: "c", attributes: {} })).toBeNull();
+  });
+});

package/src/terraform/adopt-state.ts

@@ -4,75 +4,23 @@
  * 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.
  *
- * chant AWS constructors take CloudFormation PascalCase properties (e.g.
- * `new Bucket({ BucketName })`), while Terraform state uses the provider's
- * snake_case attributes (`bucket`, `tags`). The mapping is driven by the single
- * 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).
+ * 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 {
-  AWS_LEXICON_IMPORT,
-  awsCarveType,
-  applyAwsMapper,
-  applyAwsFold,
-  unmappedFoldAttrs,
-} from "./aws-resources";
 import { canCarveEmit, carveEmitTypes } from "./tier-map";
+import { resolveEmitProvider, type AdoptedSource, type DeferredParam } from "./carve-provider";
 import type { StateResource } from "./state";
 
-/** The core subpath the emitted source reads build parameters from. */
-export const PARAMS_IMPORT = "@intentius/chant/params";
+export { PARAMS_IMPORT } from "./emit-source";
+export type { AdoptedSource, DeferredParam, FoldedContribution } from "./carve-provider";
 
 /**
- * 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;
-}
-
-/** What one folded sub-resource contributed to the parent's emitted props (#1637). */
-export interface FoldedContribution {
-  /** The sub-resource's Terraform address, e.g. `aws_s3_bucket_versioning.assets`. */
-  address: string;
-  /** CFN properties it added to the parent, e.g. `["VersioningConfiguration"]`. */
-  props: string[];
-}
-
-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[];
-  /** Folded sub-resources and the props each one joined into the parent (#1637). */
-  folded: FoldedContribution[];
-}
-
-/**
- * Is this Terraform type adoptable from state (has a native constructor)? The
- * same table gates the live path, so both are the shared `canCarveEmit`.
+ * 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: string): boolean {
   return canCarveEmit(tfType);
@@ -83,117 +31,21 @@ export function supportedStateAdoptionTypes(): string[] {
   return carveEmitTypes();
 }
 
-/** 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.
+ * 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}.
  *
- * 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.
- *
- * `folded` carries the carve set's sub-resources (`aws_s3_bucket_versioning`
- * and friends), read from the same state file. Their mappable attributes join
- * the parent's props (#1637) — a fold that only announced itself and left the
- * emitted resource without the versioning or public-access block the Terraform
- * declared was a silent loss of configuration. A sub-resource's setting wins
- * over the parent's own legacy in-state block: it is the one the config
- * actually declares.
+ * 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: StateResource,
   params: DeferredParam[] = [],
   folded: StateResource[] = [],
 ): AdoptedSource | null {
-  const entry = awsCarveType(resource.type);
-  if (!entry) return null;
-
-  const { props, mappedKeys } = applyAwsMapper(entry, resource.attributes);
-
-  const contributions: FoldedContribution[] = [];
-  const foldedUnmapped: Record<string, Record<string, unknown>> = {};
-  for (const sub of folded) {
-    const address = `${sub.type}.${sub.name}`;
-    const fold = applyAwsFold(sub.type, sub.attributes);
-    // No fold mapping for this sub-resource type: it still carves with the
-    // parent, so report its attributes rather than dropping them on the floor.
-    const rest = fold ? fold.unmapped : unmappedFoldAttrs(sub.attributes);
-    if (fold) Object.assign(props, fold.props);
-    if (Object.keys(rest).length) foldedUnmapped[address] = rest;
-    contributions.push({ address, props: Object.keys(fold?.props ?? {}) });
-  }
-
-  // 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;
-  }
-  // A folded sub-resource's leftovers are keyed by its address, so the comment
-  // says which block a stray attribute came from.
-  for (const [address, attrs] of Object.entries(foldedUnmapped)) unmapped[address] = attrs;
-
-  const L: string[] = [];
-  L.push(`// Adopted from Terraform state: ${resource.type}.${resource.name} -> ${entry.nativeType}`);
-  L.push(`// Properties mapped from Terraform attributes (CloudFormation PascalCase).`);
-  for (const c of contributions) {
-    const into = c.props.length ? c.props.join(", ") : "nothing mappable — see the reference comment below";
-    L.push(`// Folded in ${c.address} -> ${into}`);
-  }
-  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) {
-    L.push("");
-    L.push("/* Unmapped Terraform attributes (reconcile to native props before building):");
-    L.push(JSON.stringify(unmapped, null, 2));
-    L.push("*/");
-  }
-
-  return {
-    fileName: `${resource.name}.ts`,
-    content: L.join("\n") + "\n",
-    mapped: Object.keys(props).length > 0,
-    nativeType: entry.nativeType,
-    parameterized,
-    folded: contributions,
-  };
-}
-
-/** Render a JS object literal with stable key order and given indent. */
-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}: ${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);
+  const provider = resolveEmitProvider(resource.type);
+  return provider?.adopt?.(resource, params, folded) ?? null;
 }

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

@@ -1,34 +1,35 @@
 import { describe, test, expect } from "vitest";
 import { AWS_CARVE_TYPES, AWS_FOLD_MAPPERS, awsCarveType, applyAwsMapper, applyAwsFold } from "./aws-resources";
-import { TIER_MAP, FOLDS_INTO, IDENTITY_ATTR, canBridge, canCarveEmit, carveEmitTypes } from "./tier-map";
+import { tierMap, foldParentOf, identityAttrOf, canBridge, canCarveEmit, carveEmitTypes } 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 tierAws = Object.keys(tierMap()).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("the emit gate is narrower than the tier map, which also ranks k8s (#2015)", () => {
-    // `carve advise` bands kubernetes types; emit has no path for them, so the
-    // gate both emit paths share must refuse them.
-    expect(TIER_MAP.kubernetes_config_map).toBeDefined();
+    // `carve advise` bands every typed kubernetes resource; emit has a path for
+    // kubernetes_manifest only (#999), so the gate both emit paths share must
+    // refuse the rest.
+    expect(tierMap().kubernetes_config_map).toBeDefined();
     expect(canCarveEmit("kubernetes_config_map")).toBe(false);
-    expect(canCarveEmit("kubernetes_manifest")).toBe(false);
+    expect(canCarveEmit("kubernetes_manifest")).toBe(true);
     expect(canCarveEmit("random_pet")).toBe(false);
     expect(canCarveEmit("aws_s3_bucket")).toBe(true);
-    expect(carveEmitTypes()).toEqual(AWS_CARVE_TYPES.map((t) => t.tfType).sort());
+    expect(carveEmitTypes()).toEqual([...AWS_CARVE_TYPES.map((t) => t.tfType), "kubernetes_manifest"].sort());
     // State adoption and live emit gate on the same table.
     for (const t of carveEmitTypes()) expect(canAdoptFromState(t)).toBe(true);
   });
 
   test("canBridge rejects a dotted identity attribute (#2015)", () => {
     // A data source body is flat `attr = value`; a dotted path is not HCL.
-    expect(IDENTITY_ATTR.kubernetes_manifest).toContain(".");
+    expect(identityAttrOf("kubernetes_manifest")).toContain(".");
     expect(canBridge("kubernetes_manifest")).toBe(false);
     expect(canBridge("aws_s3_bucket")).toBe(true);
     // No identity entry at all is fine — the bridge writes a TODO comment.
@@ -126,7 +127,7 @@ describe("applyAwsMapper", () => {
 describe("folded sub-resource mappers (#1637)", () => {
   test("every fold mapper is for a type that actually folds", () => {
     for (const tfType of Object.keys(AWS_FOLD_MAPPERS)) {
-      expect(FOLDS_INTO[tfType]).toBeDefined();
+      expect(foldParentOf(tfType)).toBeDefined();
     }
   });
 
@@ -226,12 +227,27 @@ describe("folded sub-resource mappers (#1637)", () => {
 
 describe("tier + identity coverage maps (#998)", () => {
   test("kubernetes provider types rank, with _v1 aliases sharing the entry", () => {
-    expect(TIER_MAP.kubernetes_manifest).toEqual({ tier: 1, mapsTo: "k8s:manifest" });
-    for (const t of ["kubernetes_deployment", "kubernetes_config_map", "kubernetes_service", "kubernetes_namespace"]) {
-      expect(TIER_MAP[t]).toMatchObject({ tier: 2 });
-      expect(TIER_MAP[`${t}_v1`]).toEqual(TIER_MAP[t]);
+    // kubernetes_manifest has no fixed kind — the body names it — so the family
+    // is all `mapsTo` can say. Every other entry is a real three-part entity
+    // type from the generated operation surface: `k8s:Namespace` was in no
+    // table chant addresses by (#999).
+    expect(tierMap().kubernetes_manifest).toEqual({ tier: 1, mapsTo: "K8s::*" });
+    for (const [t, entity] of Object.entries({
+      kubernetes_deployment: "K8s::Apps::Deployment",
+      kubernetes_config_map: "K8s::Core::ConfigMap",
+      kubernetes_service: "K8s::Core::Service",
+      kubernetes_namespace: "K8s::Core::Namespace",
+      kubernetes_priority_class: "K8s::Scheduling::PriorityClass",
+      kubernetes_cron_job: "K8s::Batch::CronJob",
+    })) {
+      expect(tierMap()[t]).toEqual({ tier: 2, mapsTo: entity });
+      expect(tierMap()[`${t}_v1`]).toEqual(tierMap()[t]);
     }
-    expect(TIER_MAP.kubernetes_horizontal_pod_autoscaler_v2).toEqual(TIER_MAP.kubernetes_horizontal_pod_autoscaler);
+    for (const [t, info] of Object.entries(tierMap())) {
+      if (!t.startsWith("kubernetes_") || t === "kubernetes_manifest") continue;
+      expect(info.mapsTo).toMatch(/^K8s::[A-Za-z]+::[A-Za-z]+$/);
+    }
+    expect(tierMap().kubernetes_horizontal_pod_autoscaler_v2).toEqual(tierMap().kubernetes_horizontal_pod_autoscaler);
   });
 
   test("S3 and ECR sub-resources fold into their parent", () => {
@@ -239,17 +255,17 @@ describe("tier + identity coverage maps (#998)", () => {
       "aws_s3_bucket_website_configuration", "aws_s3_bucket_cors_configuration", "aws_s3_bucket_logging",
       "aws_s3_bucket_ownership_controls", "aws_s3_bucket_notification",
     ]) {
-      expect(FOLDS_INTO[t]).toBe("aws_s3_bucket");
+      expect(foldParentOf(t)).toBe("aws_s3_bucket");
     }
-    expect(FOLDS_INTO.aws_ecr_lifecycle_policy).toBe("aws_ecr_repository");
-    expect(FOLDS_INTO.aws_ecr_repository_policy).toBe("aws_ecr_repository");
+    expect(foldParentOf("aws_ecr_lifecycle_policy")).toBe("aws_ecr_repository");
+    expect(foldParentOf("aws_ecr_repository_policy")).toBe("aws_ecr_repository");
   });
 
   test("identity attrs cover the expanded types, including a dotted non-AWS path", () => {
-    expect(IDENTITY_ATTR.aws_elasticache_cluster).toBe("cluster_id");
-    expect(IDENTITY_ATTR.aws_ecs_task_definition).toBe("family");
-    expect(IDENTITY_ATTR.aws_route53_record).toBe("name");
-    expect(IDENTITY_ATTR.aws_eks_node_group).toBe("node_group_name");
-    expect(IDENTITY_ATTR.kubernetes_manifest).toBe("manifest.metadata.name");
+    expect(identityAttrOf("aws_elasticache_cluster")).toBe("cluster_id");
+    expect(identityAttrOf("aws_ecs_task_definition")).toBe("family");
+    expect(identityAttrOf("aws_route53_record")).toBe("name");
+    expect(identityAttrOf("aws_eks_node_group")).toBe("node_group_name");
+    expect(identityAttrOf("kubernetes_manifest")).toBe("manifest.metadata.name");
   });
 });

package/src/terraform/aws-resources.ts

@@ -322,7 +322,7 @@ export function awsCarveType(tfType: string): AwsCarveType | undefined {
 }
 
 /**
- * How a folded sub-resource (see `FOLDS_INTO`) joins its parent's emitted
+ * How a folded sub-resource (see the provider's `foldsInto`) joins its parent's emitted
  * properties (#1637). Terraform splits configuration the CloudFormation shape
  * keeps inside the parent resource, so the fold is not just a carve-set
  * membership claim: the sub-resource's attributes have to land in the parent's

package/src/terraform/carve-provider.test.ts

@@ -0,0 +1,155 @@
+import { describe, test, expect } from "vitest";
+import { readdirSync, readFileSync } from "fs";
+import { join } from "path";
+import {
+  carveEmitLexicons,
+  carveProviders,
+  registerCarveProvider,
+  resolveCarveProvider,
+  resolveEmitProvider,
+  type CarveProvider,
+} from "./carve-provider";
+import { canBridge, canCarveEmit, carveEmitTypes, foldParentOf, identityAttrOf, resolveTier, tierMap } from "./tier-map";
+import { adoptFromState } from "./adopt-state";
+
+const fake: CarveProvider = {
+  name: "test-fake",
+  tfTypePrefixes: ["fake_"],
+  lexicon: "fakelex",
+  tiers: { fake_widget: { tier: 1, mapsTo: "fake:Widget" }, fake_gizmo: { tier: 3, mapsTo: "fake:Gizmo" } },
+  identityAttrs: { fake_widget: "widget_name", fake_nested: "spec.metadata.name" },
+  foldsInto: { fake_widget_setting: "fake_widget" },
+  emitTypes: ["fake_widget"],
+  adopt: (resource) => ({
+    fileName: `${resource.name}.ts`,
+    content: `// fake: ${resource.type}.${resource.name}\n`,
+    mapped: true,
+    nativeType: "fake:Widget",
+    parameterized: [],
+    folded: [],
+  }),
+  liveSelectorType: (tfType) => (tfType === "fake_widget" ? "fake:Widget" : undefined),
+};
+
+describe("carve provider registry (#2016)", () => {
+  test("core ships aws, gcp and kubernetes; aws and kubernetes emit", () => {
+    expect(carveProviders().map((p) => p.name)).toEqual(["aws", "gcp", "kubernetes"]);
+    expect(carveEmitLexicons()).toEqual(["aws", "k8s"]);
+    expect(resolveCarveProvider("aws_s3_bucket")?.name).toBe("aws");
+    expect(resolveCarveProvider("google_storage_bucket")?.name).toBe("gcp");
+    expect(resolveCarveProvider("kubernetes_config_map")?.name).toBe("kubernetes");
+    expect(resolveCarveProvider("random_pet")).toBeUndefined();
+  });
+
+  test("a provider owns every type under its prefix for advise, only its emitTypes for emit", () => {
+    // kubernetes ranks every typed provider resource and emits only
+    // kubernetes_manifest; aws emits everything it ranks.
+    expect(resolveCarveProvider("kubernetes_config_map")?.name).toBe("kubernetes");
+    expect(resolveEmitProvider("kubernetes_config_map")).toBeUndefined();
+    expect(resolveEmitProvider("kubernetes_manifest")?.name).toBe("kubernetes");
+    expect(resolveEmitProvider("aws_s3_bucket")?.name).toBe("aws");
+    // A type under aws_ that the carve table does not list is ranked by nobody
+    // and emitted by nobody, but still resolves to the aws provider.
+    expect(resolveCarveProvider("aws_glue_job")?.name).toBe("aws");
+    expect(resolveEmitProvider("aws_glue_job")).toBeUndefined();
+  });
+
+  test("registering a provider widens advise, emit and bridge without touching them", () => {
+    expect(resolveTier("fake_widget")).toBeNull();
+    const dispose = registerCarveProvider(fake);
+    try {
+      // Tier map, identity, folds — all derived live from the registry.
+      expect(resolveTier("fake_widget")).toEqual({ tier: 1, mapsTo: "fake:Widget" });
+      expect(tierMap().fake_gizmo).toEqual({ tier: 3, mapsTo: "fake:Gizmo" });
+      expect(identityAttrOf("fake_widget")).toBe("widget_name");
+      expect(foldParentOf("fake_widget_setting")).toBe("fake_widget");
+      // The bridge gate reads the same identity attrs: a dotted path is refused.
+      expect(canBridge("fake_widget")).toBe(true);
+      expect(canBridge("fake_nested")).toBe(false);
+      // Emit gate + the user-facing type list.
+      expect(canCarveEmit("fake_widget")).toBe(true);
+      expect(canCarveEmit("fake_gizmo")).toBe(false);
+      expect(carveEmitTypes()).toContain("fake_widget");
+      expect(carveEmitLexicons()).toEqual(["aws", "fakelex", "k8s"]);
+      // adopt-state dispatches to the provider, with no knowledge of it.
+      const adopted = adoptFromState({ type: "fake_widget", name: "w", attributes: { widget_name: "w1" } });
+      expect(adopted).toMatchObject({ fileName: "w.ts", nativeType: "fake:Widget" });
+    } finally {
+      dispose();
+    }
+    // Unregistering leaves the registry exactly as it was found.
+    expect(resolveTier("fake_widget")).toBeNull();
+    expect(carveEmitTypes()).not.toContain("fake_widget");
+    expect(carveEmitLexicons()).toEqual(["aws", "k8s"]);
+    expect(adoptFromState({ type: "fake_widget", name: "w", attributes: {} })).toBeNull();
+  });
+
+  test("the AWS entries are untouched by a second provider being present", () => {
+    const before = carveEmitTypes().filter((t) => t.startsWith("aws_"));
+    const dispose = registerCarveProvider(fake);
+    try {
+      expect(carveEmitTypes().filter((t) => t.startsWith("aws_"))).toEqual(before);
+      expect(resolveTier("aws_s3_bucket")).toEqual({ tier: 1, mapsTo: "AWS::S3::Bucket" });
+      expect(resolveEmitProvider("aws_s3_bucket")?.name).toBe("aws");
+    } finally {
+      dispose();
+    }
+  });
+
+  test("the longest prefix wins, so a narrower provider can claim a subset", () => {
+    const narrow: CarveProvider = {
+      name: "test-narrow",
+      tfTypePrefixes: ["fake_widget"],
+      lexicon: "narrowlex",
+      tiers: { fake_widget: { tier: 2, mapsTo: "narrow:Widget" } },
+    };
+    const disposeWide = registerCarveProvider(fake);
+    const disposeNarrow = registerCarveProvider(narrow);
+    try {
+      expect(resolveCarveProvider("fake_widget")?.name).toBe("test-narrow");
+      expect(resolveCarveProvider("fake_gizmo")?.name).toBe("test-fake");
+    } finally {
+      disposeNarrow();
+      disposeWide();
+    }
+  });
+
+  test("emitTypes without an adopter is refused — it would accept on --env and fail on --state", () => {
+    expect(() =>
+      registerCarveProvider({
+        name: "test-no-adopt",
+        tfTypePrefixes: ["broken_"],
+        lexicon: "brokenlex",
+        tiers: {},
+        emitTypes: ["broken_thing"],
+      }),
+    ).toThrow(/emitTypes but no adopt/);
+    expect(resolveCarveProvider("broken_thing")).toBeUndefined();
+  });
+
+  test("a provider claiming no prefix is refused — nothing would ever resolve to it", () => {
+    expect(() =>
+      registerCarveProvider({ name: "test-no-prefix", tfTypePrefixes: [], lexicon: "x", tiers: {} }),
+    ).toThrow(/claims no Terraform type prefix/);
+  });
+
+  test("the seam pulls in no plugin loader and no lexicon package, so advise stays free", () => {
+    // The reason the registry lives in core rather than behind a LexiconPlugin
+    // capability: `carve advise` runs against a foreign Terraform tree with no
+    // chant project to name lexicons, and `carve emit --state` is offline.
+    // Either would become plugin-dependent if a provider module imported one.
+    const root = join(import.meta.dirname, ".");
+    const files = [
+      ...readdirSync(root).filter((f) => f.endsWith(".ts") && !f.endsWith(".test.ts")).map((f) => join(root, f)),
+      ...readdirSync(join(root, "providers")).map((f) => join(root, "providers", f)),
+    ];
+    expect(files.length).toBeGreaterThan(10); // not a vacuous pass
+    const offenders: string[] = [];
+    for (const file of files) {
+      for (const [, spec] of readFileSync(file, "utf-8").matchAll(/\bfrom\s+"([^"]+)"/g)) {
+        if (spec.includes("chant-lexicon-") || spec.includes("cli/plugins")) offenders.push(`${file}: ${spec}`);
+      }
+    }
+    expect(offenders).toEqual([]);
+  });
+});