@intentius/chant 0.57.0 → 0.59.0

package/src/provenance.ts

@@ -71,11 +71,27 @@ export interface EntityProvenance {
  *   is governed by `tier`, which is what an editor needs to know. Under-reports
  *   (a shape the collector does not follow drops a dependency) and never
  *   over-reports a parameter the expression does not mention.
+ * - `composite-parameter` — the fold interpreted the composite's factory body,
+ *   and the expression for this path reads the named factory parameter paths
+ *   (chant #2161). Same syntactic-dependency discipline as `build-param`, and
+ *   for the same reason: a shape the collector does not follow drops a
+ *   parameter, it never invents one.
+ * - `composite-literal` — the fold interpreted the factory body and the
+ *   expression for this path reads no parameter at all. The composite fixes
+ *   this field, and no argument at the call site moves it.
+ *
+ * The coarse `composite` and the two fine kinds are not alternatives. A build
+ * records `composite` when it expanded a composite without interpreting its
+ * body (the run path, an inadmissible factory), and that is why
+ * ./fold-provenance.ts answers `unknown` there rather than falling through to a
+ * direct declaration.
  */
 export type PathOrigin =
   | { kind: "authored" }
   | { kind: "composite"; composite: string; instance: string }
-  | { kind: "build-param"; params: string[] };
+  | { kind: "build-param"; params: string[] }
+  | { kind: "composite-parameter"; composite: string; parameters: string[] }
+  | { kind: "composite-literal"; composite: string };
 
 /** True when `prefix` addresses `path` or an ancestor of it, on a segment boundary. */
 function isPathPrefix(prefix: string, path: string): boolean {
@@ -170,6 +186,10 @@ export function describePathOrigin(origin: PathOrigin): string {
       return `composite ${origin.composite} (${origin.instance})`;
     case "build-param":
       return `param ${origin.params.join(", ")}`;
+    case "composite-parameter":
+      return `composite ${origin.composite} parameter ${origin.parameters.join(", ")}`;
+    case "composite-literal":
+      return `composite ${origin.composite} literal`;
   }
 }
 

package/src/serializer-walker.test.ts

@@ -4,6 +4,7 @@ import { DECLARABLE_MARKER, type Declarable } from "./declarable";
 import { INTRINSIC_MARKER } from "./intrinsic";
 import { AttrRef } from "./attrref";
 import { createResource } from "./runtime";
+import { heldElsewhere } from "./held-elsewhere";
 
 function makeDeclarable(type: string, kind: "resource" | "property" = "resource", props?: Record<string, unknown>): Declarable & { props?: Record<string, unknown> } {
   const d: Declarable & { props?: Record<string, unknown> } = {
@@ -145,3 +146,44 @@ describe("walkValue", () => {
     });
   });
 });
+
+// #2162 — a `heldElsewhere()` marker is never written to the applied
+// payload: the field is omitted entirely so the provider defaults it once at
+// creation and the named holder owns it from there. Every apply this
+// synthesizes omits it, not only the first — re-asserting even the field's
+// own value on a later apply would fight whatever the holder wrote in
+// between.
+describe("walkValue — heldElsewhere() markers (#2162)", () => {
+  test("a top-level held value walks to undefined", () => {
+    const names = new Map<Declarable, string>();
+    const marker = heldElsewhere<number>({ by: "hpa", reason: "x" });
+    expect(walkValue(marker, names, mockVisitor)).toBeUndefined();
+  });
+
+  test("an object key holding a marker is omitted entirely, not set to undefined", () => {
+    const names = new Map<Declarable, string>();
+    const value = {
+      replicas: heldElsewhere<number>({ by: "hpa", reason: "the autoscaler owns replicas after the first apply" }),
+      image: "app:1",
+    };
+    const result = walkValue(value, names, mockVisitor);
+    expect(result).toEqual({ image: "app:1" });
+    expect(Object.keys(result as object)).not.toContain("replicas");
+  });
+
+  test("a held element inside an array is dropped, not left as a hole", () => {
+    const names = new Map<Declarable, string>();
+    const value = { tolerations: ["a", heldElsewhere<string>({ by: "controller", reason: "x" }), "b"] };
+    expect(walkValue(value, names, mockVisitor)).toEqual({ tolerations: ["a", "b"] });
+  });
+
+  test("nested inside a property-kind declarable's own props, still omitted", () => {
+    const names = new Map<Declarable, string>();
+    const scaleTarget = makeDeclarable("K8s::Autoscaling::HorizontalPodAutoscaler.Behavior", "property", {
+      scaleUp: heldElsewhere<Record<string, unknown>>({ by: "hpa", reason: "the controller tunes its own policy" }),
+      stabilizationWindowSeconds: 60,
+    });
+    const result = walkValue(scaleTarget, names, mockVisitor);
+    expect(result).toEqual({ stabilizationWindowSeconds: 60 });
+  });
+});

package/src/serializer-walker.ts

@@ -7,6 +7,7 @@
 
 import type { Declarable } from "./declarable";
 import { isPropertyDeclarable } from "./declarable";
+import { isHeldElsewhere } from "./held-elsewhere";
 import { INTRINSIC_MARKER } from "./intrinsic";
 import { AttrRef } from "./attrref";
 import { isAttrRefLike } from "./utils";
@@ -33,6 +34,16 @@ export function walkValue(
     return value;
   }
 
+  // A `heldElsewhere()` marker (#2162) is never written to the applied
+  // payload — the provider defaults the field once at actual creation, and
+  // whoever the declaration names as holder owns it from there. Every apply
+  // this synthesizes therefore omits the field entirely, not only the
+  // first: re-asserting even the field's own value on a later apply would
+  // fight whatever the holder wrote in between. Checked first, ahead of
+  // every other dispatch branch below — a held marker is never an AttrRef,
+  // an Intrinsic, or authored Declarable data.
+  if (isHeldElsewhere(value)) return undefined;
+
   // Handle AttrRef
   if (isAttrRefLike(value)) {
     const name = value.getLogicalName();
@@ -77,9 +88,13 @@ export function walkValue(
     return visitor.propertyDeclarable(decl, (v) => walkValue(v, entityNames, visitor));
   }
 
-  // Handle arrays
+  // Handle arrays. A held marker element is filtered out before recursing —
+  // `walkValue` would return `undefined` for it too, but leaving it in the
+  // array would emit a hole (`[a, null, b]`) rather than omitting it.
   if (Array.isArray(value)) {
-    return value.map((item) => walkValue(item, entityNames, visitor));
+    return value
+      .filter((item) => !isHeldElsewhere(item))
+      .map((item) => walkValue(item, entityNames, visitor));
   }
 
   // Handle serialized AttrRef envelopes (produced by AttrRef.toJSON() inside intrinsics)
@@ -92,6 +107,10 @@ export function walkValue(
   if (typeof value === "object") {
     const result: Record<string, unknown> = {};
     for (const [key, val] of Object.entries(value)) {
+      // A held marker key is omitted entirely (#2162), not set to
+      // `undefined` — the two read differently to a YAML emitter, and only
+      // omission is "the provider never hears about this field".
+      if (isHeldElsewhere(val)) continue;
       const outKey = key;
       result[outKey] = walkValue(val, entityNames, visitor);
     }

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

@@ -1,6 +1,6 @@
 import { describe, test, expect } from "vitest";
 import { AWS_CARVE_TYPES, AWS_FOLD_MAPPERS, awsCarveType, applyAwsMapper, applyAwsFold } from "./aws-resources";
-import { tierMap, foldParentOf, identityAttrOf, canBridge, canCarveEmit, carveEmitTypes } from "./tier-map";
+import { tierMap, foldParentOf, identityAttrOf, canBridge, dataSourceShapeOf, canCarveEmit, carveEmitTypes } from "./tier-map";
 import { canAdoptFromState } from "./adopt-state";
 
 describe("AWS carve-out table", () => {
@@ -27,13 +27,22 @@ describe("AWS carve-out 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.
+  test("canBridge follows the data-source shape, not the identity attribute (#2015, #2034)", () => {
+    // A data source body is flat `attr = value`; a dotted path is not HCL. So a
+    // dotted identity attribute bridges only through a declared shape, which is
+    // what `kubernetes_manifest` has: `data "kubernetes_resource"`.
     expect(identityAttrOf("kubernetes_manifest")).toContain(".");
-    expect(canBridge("kubernetes_manifest")).toBe(false);
+    expect(canBridge("kubernetes_manifest")).toBe(true);
+    expect(dataSourceShapeOf("kubernetes_manifest")!.type).toBe("kubernetes_resource");
+    // A plain identity attribute implies its own same-type shape.
     expect(canBridge("aws_s3_bucket")).toBe(true);
+    expect(dataSourceShapeOf("aws_s3_bucket")).toEqual({
+      type: "aws_s3_bucket",
+      args: [{ name: "bucket", from: "bucket", required: true }],
+    });
     // No identity entry at all is fine — the bridge writes a TODO comment.
     expect(canBridge("random_pet")).toBe(true);
+    expect(dataSourceShapeOf("random_pet")).toEqual({ type: "random_pet" });
     for (const t of AWS_CARVE_TYPES) expect(canBridge(t.tfType)).toBe(true);
   });
 

package/src/terraform/bridge.test.ts

@@ -1,7 +1,8 @@
 import { describe, test, expect } from "vitest";
 import { buildFixtureGraph } from "./__fixtures__/build-graph";
 import { boundaryReport } from "./carve";
-import { generateBridge, type CarvedIdentity } from "./bridge";
+import { generateBridge, type CarvedDataSource } from "./bridge";
+import { dataSourceShapeOf } from "./tier-map";
 import type { Hcl2JsonTree } from "./types";
 
 const workedExample: Hcl2JsonTree = {
@@ -35,8 +36,10 @@ const API_TF = `resource "aws_lambda_function" "api" {
 }
 `;
 
-const identities = new Map<string, CarvedIdentity>([
-  ["aws_s3_bucket.assets", { attr: "bucket", value: "myapp-assets-prod" }],
+// The read-back for the bucket: the shape its identity attribute implies, plus
+// the literal the graph resolved out of the block.
+const identities = new Map<string, CarvedDataSource>([
+  ["aws_s3_bucket.assets", { shape: dataSourceShapeOf("aws_s3_bucket"), values: { bucket: "myapp-assets-prod" } }],
 ]);
 
 describe("generateBridge — inbound (data-source rewrite)", () => {
@@ -51,18 +54,28 @@ describe("generateBridge — inbound (data-source rewrite)", () => {
     );
   });
 
-  test("never renders a dotted identity attribute into the data body (#2015)", () => {
+  test("a type with no shape gets a TODO body, never a dotted attr assignment (#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);
+    // A dotted identity attribute implies no shape at all — `canBridge` refuses
+    // such a type before the bridge runs — but an empty read-back still has to
+    // produce a block Terraform can parse, not `manifest.metadata.name = "x"`.
+    const noShape = new Map<string, CarvedDataSource>([["aws_s3_bucket.assets", {}]]);
+    const plan = generateBridge(report, [{ path: "api.tf", content: API_TF }], noShape);
 
-    // `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("a shape whose required argument has no literal falls back to the TODO (#2034)", () => {
+    const report = boundaryReport(buildFixtureGraph(workedExample), "aws_s3_bucket.assets")!;
+    const unresolved = new Map<string, CarvedDataSource>([
+      ["aws_s3_bucket.assets", { shape: dataSourceShapeOf("aws_s3_bucket"), values: {} }],
+    ]);
+    const plan = generateBridge(report, [{ path: "api.tf", content: API_TF }], unresolved);
+    // A `data "aws_s3_bucket" "assets" {}` with no `bucket` would not plan.
+    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

@@ -7,6 +7,9 @@
  *  - inbound edge  → the survivor loses its reference to the carved resource.
  *    Bridge: add a `data` source for the (now chant-managed) resource and
  *    rewrite the survivor's `type.name.attr` references to `data.type.name.attr`.
+ *    The provider's data-source shape (`data-source-shape.ts`, #2034) decides
+ *    both halves — the data type and body, and the attribute path survivors
+ *    read through, which need not be the resource's own.
  *    Required immediately, or `terraform plan` errors on the dangling ref.
  *    An `output` block reading the carved resource is such a survivor (#1638):
  *    same data source, same textual rewrite, applied to the output's value.
@@ -22,18 +25,32 @@
  */
 
 import { deferredParamName, type CarveReport } from "./carve";
+import { rewriteReadPath, type DataSourceShape, type ShapeField } from "./data-source-shape";
 import { exciseResourceBlocks, type ExciseTarget } from "./excise";
 
-export interface CarvedIdentity {
-  /** The HCL identity attribute, e.g. `bucket` or `name`. */
-  attr?: string;
-  /** Its literal value, e.g. `myapp-assets-prod`. */
-  value?: string;
+/** How one carved resource is read back, and the literals to render it with. */
+export interface CarvedDataSource {
+  /**
+   * The type's data-source shape (`dataSourceShapeOf`): the `data` type, its
+   * arguments and where each comes from, and the survivor path translation.
+   */
+  shape?: DataSourceShape;
+  /**
+   * Literals resolved from the carved block, keyed by the shape field's source
+   * path — `{ bucket: "myapp-assets-prod" }`, or for a manifest
+   * `{ "manifest.apiVersion": "v1", "manifest.metadata.name": "app-config" }`.
+   */
+  values?: Record<string, string>;
 }
 
 export interface DataSourceBlock {
   /** Carved resource address the data source stands in for. */
   address: string;
+  /**
+   * The `data` type. Usually the carved resource's own type; the shape can
+   * name another, as `kubernetes_manifest` reads back through
+   * `data "kubernetes_resource"` (#2034).
+   */
   type: string;
   name: string;
   hcl: string;
@@ -73,22 +90,64 @@ export interface BridgePlan {
   runbook: string;
 }
 
-/** `aws_s3_bucket.assets` → a regex matching that reference head, not already `data.`-prefixed. */
+/**
+ * `aws_s3_bucket.assets` → a regex matching that reference head plus the
+ * attribute path that follows it, not already `data.`-prefixed. The path is
+ * captured because the data source may expose it under a different attribute:
+ * a survivor reading `kubernetes_manifest.app_config.manifest.data.x` has to
+ * come out as `data.kubernetes_resource.app_config.object.data.x`.
+ */
 function referenceRegex(address: string): RegExp {
   const escaped = address.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   // (?<!data\.) — do not double-prefix an existing data source reference.
-  return new RegExp(`(?<!data\\.)\\b${escaped}\\b`, "g");
+  return new RegExp(`(?<!data\\.)\\b${escaped}\\b((?:\\.[A-Za-z_][A-Za-z0-9_-]*)*)`, "g");
 }
 
-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 =
-    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}`;
+const IDENTIFY_TODO = "  # TODO: identify the resource (its name/id was interpolated in the source)";
+
+/** `terraform fmt` aligns the `=` of consecutive assignments; so do we. */
+function alignedAssignments(pairs: Array<[string, string]>, indent: string): string[] {
+  const width = Math.max(...pairs.map(([key]) => key.length));
+  return pairs.map(([key, value]) => `${indent}${key.padEnd(width)} = ${JSON.stringify(value)}`);
+}
+
+/** Resolved `[name, value]` pairs, or null when a required field has no literal. */
+function resolveFields(fields: readonly ShapeField[], values: Record<string, string>): Array<[string, string]> | null {
+  const pairs: Array<[string, string]> = [];
+  for (const field of fields) {
+    const value = values[field.from];
+    if (value === undefined) {
+      if (field.required) return null;
+      continue;
+    }
+    pairs.push([field.name, value]);
+  }
+  return pairs;
+}
+
+/**
+ * The `data` block standing in for the carved resource. A shape whose required
+ * arguments the carved block did not supply as literals renders the TODO body
+ * instead of a block `terraform validate` would reject.
+ */
+function dataSourceHcl(shape: DataSourceShape, name: string, values: Record<string, string>): string {
+  const body: string[] = [];
+  const args = resolveFields(shape.args ?? [], values);
+  if (args === null) return todoBlock(shape.type, name);
+  if (args.length) body.push(...alignedAssignments(args, "  "));
+  for (const block of shape.blocks ?? []) {
+    const fields = resolveFields(block.fields, values);
+    if (fields === null) return todoBlock(shape.type, name);
+    if (!fields.length) continue;
+    if (body.length) body.push("");
+    body.push(`  ${block.name} {`, ...alignedAssignments(fields, "    "), "  }");
+  }
+  if (!body.length) body.push(IDENTIFY_TODO);
+  return `data ${JSON.stringify(shape.type)} ${JSON.stringify(name)} {\n${body.join("\n")}\n}`;
+}
+
+function todoBlock(type: string, name: string): string {
+  return `data ${JSON.stringify(type)} ${JSON.stringify(name)} {\n${IDENTIFY_TODO}\n}`;
 }
 
 /**
@@ -96,26 +155,26 @@ function dataSourceHcl(type: string, name: string, identity: CarvedIdentity): st
  *
  * @param report    the boundary report (from `boundaryReport`)
  * @param files     every `.tf` file in the estate, as { path, content }
- * @param identities physical identity per carved address, for the data sources
+ * @param readBacks how each carved address is read back as a data source, and
+ *                  the literals to render it with (`dataSourceShapeOf` +
+ *                  the graph node's `dataSourceValues`)
  */
 export function generateBridge(
   report: CarveReport,
   files: Array<{ path: string; content: string }>,
-  identities: Map<string, CarvedIdentity>,
+  readBacks: Map<string, CarvedDataSource>,
 ): BridgePlan {
   // Carved resources that something still depends on need a data source.
-  const carvedWithInbound = new Map<string, { type: string; name: string }>();
+  const carvedWithInbound = new Map<string, { type: string; name: string; readBack: CarvedDataSource }>();
   for (const e of report.inbound) {
     const [type, ...rest] = e.carved.split(".");
-    carvedWithInbound.set(e.carved, { type, name: rest.join(".") });
+    carvedWithInbound.set(e.carved, { type, name: rest.join("."), readBack: readBacks.get(e.carved) ?? {} });
   }
 
-  const dataSources: DataSourceBlock[] = [...carvedWithInbound.entries()].map(([address, { type, name }]) => ({
-    address,
-    type,
-    name,
-    hcl: dataSourceHcl(type, name, identities.get(address) ?? {}),
-  }));
+  const dataSources: DataSourceBlock[] = [...carvedWithInbound.entries()].map(([address, { type, name, readBack }]) => {
+    const shape = readBack.shape ?? { type };
+    return { address, type: shape.type, name, hcl: dataSourceHcl(shape, name, readBack.values ?? {}) };
+  });
 
   // Excise the carve set's own blocks (#998): after `terraform state rm`, a
   // block left behind would re-create the resource on the next apply. Then
@@ -129,8 +188,10 @@ export function generateBridge(
   const rewrites: FileRewrite[] = files.map(({ path, content }) => {
     const excision = exciseResourceBlocks(content, exciseTargets);
     let rewritten = excision.content;
-    for (const address of carvedWithInbound.keys()) {
-      rewritten = rewritten.replace(referenceRegex(address), `data.${address}`);
+    for (const [address, { type, name, readBack }] of carvedWithInbound) {
+      const shape = readBack.shape;
+      const head = `data.${shape?.type ?? type}.${name}`;
+      rewritten = rewritten.replace(referenceRegex(address), (_match, path: string) => head + rewriteReadPath(shape, path));
     }
     return { path, original: content, rewritten, changed: rewritten !== content, excised: excision.excised };
   });

package/src/terraform/carve-provider.ts

@@ -28,6 +28,7 @@
  * not require plugin loading for the paths that run without one.
  */
 
+import { identityAttrShape, type DataSourceShape } from "./data-source-shape";
 import { BUILTIN_CARVE_PROVIDERS } from "./providers";
 import type { StateResource } from "./state";
 
@@ -95,10 +96,20 @@ export interface CarveProvider {
   readonly tiers: Readonly<Record<string, TierInfo>>;
   /**
    * Terraform type → the HCL attribute carrying the physical name. A dotted
-   * entry is a path into nested blocks (`manifest.metadata.name`); the bridge
-   * refuses those, since a data-source body is flat `attr = value`.
+   * entry is a path into nested values (`manifest.metadata.name`), which a
+   * flat `attr = value` body cannot express, so it implies no data-source
+   * shape on its own — see {@link dataSourceShapes}.
    */
   readonly identityAttrs?: Readonly<Record<string, string>>;
+  /**
+   * Terraform type → how `carve bridge` reads it back as a `data` source
+   * (#2034): the data-source type, where each argument comes from in the
+   * carved body, and how a survivor's attribute path translates. Needed when
+   * the data source is not the resource's own type, or when its body is more
+   * than one flat argument. A type with a plain identity attribute and no
+   * entry here gets that attribute's shape ({@link identityAttrShape}).
+   */
+  readonly dataSourceShapes?: Readonly<Record<string, DataSourceShape>>;
   /**
    * Sub-resource Terraform type → parent type, for types Terraform splits out
    * of the resource the native spec keeps them in.
@@ -169,6 +180,7 @@ interface RegistryIndex {
   prefixes: Array<{ prefix: string; provider: CarveProvider }>;
   tiers: Record<string, TierInfo>;
   identityAttrs: Record<string, string>;
+  dataSourceShapes: Record<string, DataSourceShape>;
   foldsInto: Record<string, string>;
   /** Terraform type → the provider that emits it. */
   emitters: Map<string, CarveProvider>;
@@ -182,6 +194,7 @@ function index(): RegistryIndex {
     prefixes: [],
     tiers: {},
     identityAttrs: {},
+    dataSourceShapes: {},
     foldsInto: {},
     emitters: new Map(),
   };
@@ -189,6 +202,7 @@ function index(): RegistryIndex {
     for (const prefix of provider.tfTypePrefixes) built.prefixes.push({ prefix, provider });
     Object.assign(built.tiers, provider.tiers);
     if (provider.identityAttrs) Object.assign(built.identityAttrs, provider.identityAttrs);
+    if (provider.dataSourceShapes) Object.assign(built.dataSourceShapes, provider.dataSourceShapes);
     if (provider.foldsInto) Object.assign(built.foldsInto, provider.foldsInto);
     for (const tfType of provider.emitTypes ?? []) built.emitters.set(tfType, provider);
   }
@@ -235,3 +249,25 @@ export function carveIdentityAttr(tfType: string): string | undefined {
 export function carveFoldParent(tfType: string): string | undefined {
   return index().foldsInto[tfType];
 }
+
+/**
+ * How `carve bridge` reads this type back as a `data` source (#2034), or
+ * undefined when it cannot be read back at all — which is what makes
+ * `canBridge` refuse it.
+ *
+ * Resolution order:
+ *  1. a shape the owning provider declared for the type;
+ *  2. otherwise the shape a plain identity attribute implies (same type, one
+ *     required argument) — the path every AWS and google type takes;
+ *  3. otherwise undefined, when the identity attribute is a dotted path into
+ *     nested values and no provider declared a shape for it;
+ *  4. and for a type with no identity attribute at all, the bare data-source
+ *     type: the bridge still emits a block, with a TODO for the body.
+ */
+export function carveDataSourceShape(tfType: string): DataSourceShape | undefined {
+  const declared = index().dataSourceShapes[tfType];
+  if (declared) return declared;
+  const attr = index().identityAttrs[tfType];
+  if (attr === undefined) return { type: tfType };
+  return identityAttrShape(tfType, attr);
+}

package/src/terraform/data-source-shape.ts

@@ -0,0 +1,95 @@
+/**
+ * How a carved Terraform type is read back as a `data` source (#2034).
+ *
+ * `carve bridge` replaces a carved resource with a data source the survivors
+ * read instead. Until now a carve provider said only which attribute carries
+ * the physical name (`identityAttrs`), and the bridge assumed the data source
+ * was the same type as the resource, with that one attribute in its body:
+ *
+ *     data "aws_s3_bucket" "assets" { bucket = "myapp-assets-prod" }
+ *
+ * That assumption holds for AWS and google, and breaks for Kubernetes twice
+ * over. `kubernetes_manifest` names itself by `manifest.metadata.name`, a path
+ * into a nested value that a flat `attr = value` body cannot express; and the
+ * kubernetes provider ships no `kubernetes_manifest` data source at all
+ * (verified against hashicorp/kubernetes v3.2.1: 27 data sources, none a
+ * manifest). Its generic read is `data "kubernetes_resource"`, with a
+ * different type, different arguments, a nested `metadata` block, and its own
+ * attribute path for survivors to read through.
+ *
+ * So a provider contributes a *shape*: the data-source type, where each
+ * argument comes from in the carved body, and how a survivor's attribute path
+ * translates. An identity attribute is one instance of that shape
+ * ({@link identityAttrShape}), so nothing that bridges today changes.
+ */
+
+/** One argument of the data-source body, and where its value comes from. */
+export interface ShapeField {
+  /** Argument name in the emitted data source, e.g. `api_version`. */
+  name: string;
+  /**
+   * Dotted path into the carved resource's HCL body the literal is read from,
+   * e.g. `manifest.apiVersion`. Nested blocks are walked by segment.
+   */
+  from: string;
+  /**
+   * A shape that cannot resolve a required field renders the TODO body rather
+   * than a data source missing an argument Terraform needs.
+   */
+  required?: boolean;
+}
+
+/** A nested block in the data-source body, e.g. `metadata { name = "x" }`. */
+export interface ShapeBlock {
+  name: string;
+  fields: readonly ShapeField[];
+}
+
+export interface DataSourceShape {
+  /** The `data` type standing in for the carved resource, e.g. `kubernetes_resource`. */
+  type: string;
+  /** Flat `name = value` arguments of the body. */
+  args?: readonly ShapeField[];
+  /** Nested `name { ... }` blocks of the body. */
+  blocks?: readonly ShapeBlock[];
+  /**
+   * The carved resource's top-level attribute → the data source's, for the
+   * survivor rewrite. `kubernetes_manifest` exposes both `manifest` (what the
+   * config declared) and `object` (the API server's read-back), and
+   * `kubernetes_resource` exposes only `object`, so both map to `object`. An
+   * attribute with no entry passes through unchanged, which is what every
+   * same-type identity-attribute shape wants.
+   */
+  readAttrs?: Readonly<Record<string, string>>;
+}
+
+/**
+ * The shape a plain identity attribute implies: the same type as the resource,
+ * one required argument, no path translation. Returns undefined for a dotted
+ * attribute, which is a path into nested values and needs a declared shape.
+ */
+export function identityAttrShape(tfType: string, attr: string): DataSourceShape | undefined {
+  if (attr.includes(".")) return undefined;
+  return { type: tfType, args: [{ name: attr, from: attr, required: true }] };
+}
+
+/** Every source path the shape reads, for the graph to resolve out of the carved block. */
+export function shapeSourcePaths(shape: DataSourceShape): string[] {
+  const paths = (shape.args ?? []).map((f) => f.from);
+  for (const block of shape.blocks ?? []) for (const f of block.fields) paths.push(f.from);
+  return [...new Set(paths)];
+}
+
+/**
+ * Translate a survivor's attribute path onto the data source. `path` is the
+ * text after the address, leading dot included (`.manifest.data.log_level`) or
+ * empty. Only the first segment is mapped: everything under it is the object's
+ * own structure, which the data source reproduces.
+ */
+export function rewriteReadPath(shape: DataSourceShape | undefined, path: string): string {
+  if (!path || !shape?.readAttrs) return path;
+  const [head, ...rest] = path.slice(1).split(".");
+  const mapped = shape.readAttrs[head];
+  if (mapped === undefined) return path;
+  return `.${[mapped, ...rest].join(".")}`;
+}