@intentius/chant 0.52.1 → 0.53.0

package/src/terraform/adopt-state.ts

@@ -4,193 +4,48 @@
  * 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_CARVE_TYPES,
-  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).
+ * 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 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)? */
 export function canAdoptFromState(tfType: string): boolean {
-  return awsCarveType(tfType) !== undefined;
+  return canCarveEmit(tfType);
 }
 
 /** Terraform types that can currently be adopted from state, for user-facing hints. */
 export function supportedStateAdoptionTypes(): string[] {
-  return AWS_CARVE_TYPES.map((t) => t.tfType).sort();
-}
-
-/** Marker for a prop whose value is a `params.<name>` reference, not a literal. */
-class ParamRef {
-  constructor(
-    readonly name: string,
-    readonly type: "string" | "number" | "boolean",
-  ) {}
+  return carveEmitTypes();
 }
 
 /**
- * Render chant source for a state-adopted resource. Emits the native
- * constructor with mapped properties, plus a reference comment listing the
- * Terraform attributes that were not mapped so nothing is silently dropped.
- *
- * A mapped attribute named by a `DeferredParam` renders as a `params.<name>`
- * reference (a real chant build parameter) instead of the state literal —
- * the value came from a survivor, so it stays overridable per build.
+ * 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}.
  *
- * `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,18 +1,42 @@
 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 } 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 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(true);
+    expect(canCarveEmit("random_pet")).toBe(false);
+    expect(canCarveEmit("aws_s3_bucket")).toBe(true);
+    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(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.
+    expect(canBridge("random_pet")).toBe(true);
+    for (const t of AWS_CARVE_TYPES) expect(canBridge(t.tfType)).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 [
@@ -103,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();
     }
   });
 
@@ -203,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]);
+    }
+    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(TIER_MAP.kubernetes_horizontal_pod_autoscaler_v2).toEqual(TIER_MAP.kubernetes_horizontal_pod_autoscaler);
+    expect(tierMap().kubernetes_horizontal_pod_autoscaler_v2).toEqual(tierMap().kubernetes_horizontal_pod_autoscaler);
   });
 
   test("S3 and ECR sub-resources fold into their parent", () => {
@@ -216,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/bridge.test.ts

@@ -51,6 +51,18 @@ describe("generateBridge — inbound (data-source rewrite)", () => {
     );
   });
 
+  test("never renders a dotted identity attribute into the data body (#2015)", () => {
+    const report = boundaryReport(buildFixtureGraph(workedExample), "aws_s3_bucket.assets")!;
+    const dotted = new Map<string, CarvedIdentity>([
+      ["aws_s3_bucket.assets", { attr: "manifest.metadata.name", value: "demo-config" }],
+    ]);
+    const plan = generateBridge(report, [{ path: "api.tf", content: API_TF }], dotted);
+
+    // `manifest.metadata.name = "demo-config"` is not valid HCL.
+    expect(plan.dataSources[0].hcl).not.toContain("manifest.metadata.name =");
+    expect(plan.dataSources[0].hcl).toContain("# TODO: identify the resource");
+  });
+
   test("rewrites survivor references to the data source", () => {
     const report = boundaryReport(buildFixtureGraph(workedExample), "aws_s3_bucket.assets")!;
     const plan = generateBridge(report, [{ path: "api.tf", content: API_TF }], identities);

package/src/terraform/bridge.ts

@@ -81,8 +81,11 @@ function referenceRegex(address: string): RegExp {
 }
 
 function dataSourceHcl(type: string, name: string, identity: CarvedIdentity): string {
+  // A dotted attr is a path into nested blocks; `a.b.c = v` is not valid HCL,
+  // so it falls back to the TODO. `carve bridge` refuses such a type outright.
+  const flat = identity.attr !== undefined && !identity.attr.includes(".");
   const body =
-    identity.attr && identity.value !== undefined
+    flat && 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}`;

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([]);
+  });
+});