@intentius/chant 0.58.0 → 0.59.0

package/src/op/operator.test.ts

@@ -9,7 +9,11 @@ import {
   runOperatorRound,
   runOperatorForever,
   formatRoundLine,
+  formatSignalLine,
   DEFAULT_OPERATOR_INTERVAL_MS,
+  type ChangeSubscriber,
+  type OperatorSignalEvent,
+  type OperatorTickEvent,
 } from "./operator";
 import { readLease } from "../lifecycle/lease";
 import { appendConvergeRecord, readConvergeLedger } from "../lifecycle/converge-ledger";
@@ -513,3 +517,367 @@ describe("formatRoundLine", () => {
       .toContain("not-due:*/10 * * * *");
   });
 });
+
+describe("runOperatorForever: a substrate change signal wakes a tick (#1981)", () => {
+  async function waitFor(predicate: () => boolean, maxWaitMs = 5_000): Promise<void> {
+    const deadline = Date.now() + maxWaitMs;
+    while (!predicate() && Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, 5));
+    }
+  }
+
+  /**
+   * A stub `subscribeChanges` seam. Hands the loop's `onChange`/`onError` back
+   * to the test so it can fabricate signals and kill the subscription, with no
+   * substrate anywhere near it, which is the whole point of the seam being a
+   * plain callback pair.
+   */
+  function stubSubscriber(lexicon = "stub") {
+    const handle = {
+      lexicon,
+      subscribes: 0,
+      closes: 0,
+      onChange: undefined as undefined | (() => void),
+      onError: undefined as undefined | ((message: string) => void),
+      signal: undefined as undefined | AbortSignal,
+      failNextSubscribe: undefined as undefined | string,
+    };
+    const subscriber: ChangeSubscriber = {
+      lexicon,
+      async subscribe(ctx) {
+        handle.subscribes++;
+        if (handle.failNextSubscribe) {
+          const message = handle.failNextSubscribe;
+          handle.failNextSubscribe = undefined;
+          throw new Error(message);
+        }
+        handle.onChange = ctx.onChange;
+        handle.onError = ctx.onError;
+        handle.signal = ctx.signal;
+        return {
+          async close() {
+            handle.closes++;
+          },
+        };
+      },
+    };
+    return { handle, subscriber };
+  }
+
+  test("a signal wakes the next round early, well inside the interval", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      writeFixtureConvergeOp(dir, "staging-converge", "staging");
+      const activities = fakeTickActivities(dir, "staging", "staging-converge");
+      const { handle, subscriber } = stubSubscriber("k8s");
+
+      const controller = new AbortController();
+      const rounds: number[] = [];
+      const signalEvents: OperatorSignalEvent[] = [];
+      const loop = runOperatorForever({
+        cwd: dir,
+        holder: "op-a",
+        intervalMs: 60_000, // a full minute: nothing but a signal can produce a second round
+        signalFloorMs: 0,
+        activities,
+        profiles: PROFILES,
+        signal: controller.signal,
+        subscribers: [subscriber],
+        onRound: () => rounds.push(Date.now()),
+        onSignalEvent: (e) => signalEvents.push(e),
+      });
+
+      await waitFor(() => handle.onChange !== undefined);
+      expect(rounds.length).toBe(1);
+      handle.onChange!();
+      await waitFor(() => rounds.length >= 2);
+      expect(rounds.length).toBeGreaterThanOrEqual(2);
+
+      controller.abort();
+      await loop;
+      expect(signalEvents.some((e) => e.kind === "subscribed" && e.lexicon === "k8s")).toBe(true);
+      expect(signalEvents.some((e) => e.kind === "woken")).toBe(true);
+    });
+  }, 15_000);
+
+  test("a fabricated signal cannot change what the tick reports, only when it runs", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      writeFixtureConvergeOp(dir, "staging-converge", "staging");
+
+      /** One round's events, run to completion on a timer alone. */
+      async function roundsWithoutSignal(): Promise<string> {
+        const controller = new AbortController();
+        const seen: OperatorTickEvent[][] = [];
+        const loop = runOperatorForever({
+          cwd: dir,
+          holder: "op-a",
+          intervalMs: 60_000,
+          activities: fakeTickActivities(dir, "staging", "staging-converge"),
+          profiles: PROFILES,
+          signal: controller.signal,
+          onRound: (events) => {
+            seen.push(events);
+            controller.abort();
+          },
+        });
+        await loop;
+        return JSON.stringify(seen[0].map((e) => ({ kind: e.kind, op: e.op, env: e.env })));
+      }
+
+      /** The same, woken by a signal carrying a fabricated payload. */
+      async function roundsWithFabricatedSignal(): Promise<string> {
+        const { handle, subscriber } = stubSubscriber("liar");
+        const controller = new AbortController();
+        const seen: OperatorTickEvent[][] = [];
+        const loop = runOperatorForever({
+          cwd: dir,
+          holder: "op-a",
+          intervalMs: 60_000,
+          signalFloorMs: 0,
+          activities: fakeTickActivities(dir, "staging", "staging-converge"),
+          profiles: PROFILES,
+          signal: controller.signal,
+          subscribers: [subscriber],
+          onRound: (events) => {
+            seen.push(events);
+            if (seen.length >= 2) controller.abort();
+          },
+        });
+        await waitFor(() => handle.onChange !== undefined);
+        // `onChange` takes no arguments; a caller that fabricates a resource
+        // has nowhere to put it, and the extra arguments go nowhere.
+        (handle.onChange as unknown as (...args: unknown[]) => void)(
+          { kind: "Deployment", name: "ghost", status: "Drifted" },
+          "fabricated",
+        );
+        await waitFor(() => seen.length >= 2);
+        controller.abort();
+        await loop;
+        return JSON.stringify(seen[1].map((e) => ({ kind: e.kind, op: e.op, env: e.env })));
+      }
+
+      const timerOnly = await roundsWithoutSignal();
+      const signalled = await roundsWithFabricatedSignal();
+      // Byte for byte the same verdict: the signal moved the clock, nothing else.
+      expect(signalled).toBe(timerOnly);
+      // And the seam itself carries no payload channel to begin with.
+      const { handle } = stubSubscriber();
+      expect(handle.onChange?.length ?? 0).toBe(0);
+    });
+  }, 20_000);
+
+  test("a storm of signals wakes at most one round per floor", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      writeFixtureConvergeOp(dir, "staging-converge", "staging");
+      const { handle, subscriber } = stubSubscriber();
+
+      const controller = new AbortController();
+      const rounds: number[] = [];
+      const loop = runOperatorForever({
+        cwd: dir,
+        holder: "op-a",
+        intervalMs: 60_000,
+        signalFloorMs: 400,
+        activities: fakeTickActivities(dir, "staging", "staging-converge"),
+        profiles: PROFILES,
+        signal: controller.signal,
+        subscribers: [subscriber],
+        onRound: () => rounds.push(Date.now()),
+      });
+
+      await waitFor(() => handle.onChange !== undefined);
+      const before = rounds.length;
+      for (let i = 0; i < 300; i++) handle.onChange!();
+      // Well past a floor, but nowhere near the 60s interval: at most one
+      // extra round may have happened, and a per-signal wake would have
+      // produced hundreds.
+      await waitFor(() => rounds.length > before, 2_000);
+      expect(rounds.length - before).toBeLessThanOrEqual(1);
+
+      controller.abort();
+      await loop;
+    });
+  }, 15_000);
+
+  test("a killed subscription is reported once, the loop keeps ticking, and the next round re-subscribes", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      writeFixtureConvergeOp(dir, "staging-converge", "staging");
+      const { handle, subscriber } = stubSubscriber("k8s");
+
+      const controller = new AbortController();
+      const rounds: number[] = [];
+      const signalEvents: OperatorSignalEvent[] = [];
+      const loop = runOperatorForever({
+        cwd: dir,
+        holder: "op-a",
+        intervalMs: 60,
+        signalFloorMs: 0,
+        activities: fakeTickActivities(dir, "staging", "staging-converge"),
+        profiles: PROFILES,
+        signal: controller.signal,
+        subscribers: [subscriber],
+        onRound: () => rounds.push(Date.now()),
+        onSignalEvent: (e) => signalEvents.push(e),
+      });
+
+      await waitFor(() => handle.onError !== undefined);
+      const subscribesBefore = handle.subscribes;
+      // The watch dies. Twice, because a dead subscription reports once.
+      handle.onError!("connection reset by peer");
+      handle.onError!("connection reset by peer");
+
+      await waitFor(() => handle.subscribes > subscribesBefore);
+      const roundsAtDeath = rounds.length;
+      await waitFor(() => rounds.length > roundsAtDeath + 1);
+
+      controller.abort();
+      await loop;
+
+      const lost = signalEvents.filter((e) => e.kind === "subscription-lost");
+      expect(lost).toHaveLength(1);
+      expect(formatSignalLine(lost[0])).toContain("polling on the timer");
+      // The loop kept ticking on the timer, and re-subscribed.
+      expect(rounds.length).toBeGreaterThan(roundsAtDeath + 1);
+      expect(handle.subscribes).toBeGreaterThan(subscribesBefore);
+    });
+  }, 15_000);
+
+  test("a subscription that cannot be established degrades to polling with one line, never a crash", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      writeFixtureConvergeOp(dir, "staging-converge", "staging");
+      const failing: ChangeSubscriber = {
+        lexicon: "k8s",
+        async subscribe() {
+          throw new Error("no cluster binding for env staging");
+        },
+      };
+
+      const controller = new AbortController();
+      const rounds: number[] = [];
+      const signalEvents: OperatorSignalEvent[] = [];
+      const loop = runOperatorForever({
+        cwd: dir,
+        holder: "op-a",
+        intervalMs: 40,
+        activities: fakeTickActivities(dir, "staging", "staging-converge"),
+        profiles: PROFILES,
+        signal: controller.signal,
+        subscribers: [failing],
+        onRound: () => rounds.push(Date.now()),
+        onSignalEvent: (e) => signalEvents.push(e),
+      });
+
+      await waitFor(() => rounds.length >= 3);
+      controller.abort();
+      await loop; // resolves: a failing subscription never rejects the loop
+
+      const failed = signalEvents.filter((e) => e.kind === "subscribe-failed");
+      expect(failed.length).toBeGreaterThanOrEqual(1);
+      expect(formatSignalLine(failed[0])).toContain("no cluster binding for env staging");
+      expect(rounds.length).toBeGreaterThanOrEqual(3);
+    });
+  }, 15_000);
+
+  test("stopping the operator closes every subscription and aborts its signal", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      writeFixtureConvergeOp(dir, "staging-converge", "staging");
+      const a = stubSubscriber("k8s");
+      const b = stubSubscriber("docker");
+
+      const controller = new AbortController();
+      const loop = runOperatorForever({
+        cwd: dir,
+        holder: "op-a",
+        intervalMs: 60_000,
+        activities: fakeTickActivities(dir, "staging", "staging-converge"),
+        profiles: PROFILES,
+        signal: controller.signal,
+        subscribers: [a.subscriber, b.subscriber],
+      });
+
+      await waitFor(() => a.handle.onChange !== undefined && b.handle.onChange !== undefined);
+      expect(a.handle.signal!.aborted).toBe(false);
+
+      controller.abort();
+      await loop;
+
+      expect(a.handle.closes).toBe(1);
+      expect(b.handle.closes).toBe(1);
+      expect(a.handle.signal!.aborted).toBe(true);
+      expect(b.handle.signal!.aborted).toBe(true);
+    });
+  }, 15_000);
+
+  test("a close() that throws still unwinds the loop cleanly", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      writeFixtureConvergeOp(dir, "staging-converge", "staging");
+      let subscribed = false;
+      const hostile: ChangeSubscriber = {
+        lexicon: "k8s",
+        async subscribe() {
+          subscribed = true;
+          return { close: async () => { throw new Error("close blew up"); } };
+        },
+      };
+
+      const controller = new AbortController();
+      const loop = runOperatorForever({
+        cwd: dir,
+        holder: "op-a",
+        intervalMs: 60_000,
+        activities: fakeTickActivities(dir, "staging", "staging-converge"),
+        profiles: PROFILES,
+        signal: controller.signal,
+        subscribers: [hostile],
+      });
+
+      await waitFor(() => subscribed);
+      controller.abort();
+      await expect(loop).resolves.toBeUndefined();
+    });
+  }, 15_000);
+
+  test("no subscribers: the loop is exactly the timer it always was", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      writeFixtureConvergeOp(dir, "staging-converge", "staging");
+      const controller = new AbortController();
+      const rounds: number[] = [];
+      const signalEvents: OperatorSignalEvent[] = [];
+      const loop = runOperatorForever({
+        cwd: dir,
+        holder: "op-a",
+        intervalMs: 40,
+        activities: fakeTickActivities(dir, "staging", "staging-converge"),
+        profiles: PROFILES,
+        signal: controller.signal,
+        subscribers: [], // a project whose lexicons implement no signal seam
+        onRound: () => rounds.push(Date.now()),
+        onSignalEvent: (e) => signalEvents.push(e),
+      });
+
+      await waitFor(() => rounds.length >= 3);
+      controller.abort();
+      await loop;
+      expect(rounds.length).toBeGreaterThanOrEqual(3);
+      expect(signalEvents).toEqual([]);
+    });
+  }, 15_000);
+});
+
+describe("formatSignalLine", () => {
+  test("renders each signal event kind as one line, none of them an observation", () => {
+    expect(formatSignalLine({ kind: "subscribed", lexicon: "k8s" })).toContain("the timer still runs");
+    expect(formatSignalLine({ kind: "subscribe-failed", lexicon: "k8s", error: "no binding" }))
+      .toContain("polling on the timer");
+    expect(formatSignalLine({ kind: "subscription-lost", lexicon: "k8s", error: "410 Gone" }))
+      .toContain("re-subscribes");
+    expect(formatSignalLine({ kind: "woken", afterMs: 120 })).toContain("running an ordinary round");
+  });
+});

package/src/op/operator.ts

@@ -41,6 +41,8 @@ import { runOpLocally, OpRunFailure, type OpRunResult } from "./local-executor";
 import { acquireLease, stillHoldsLease, currentHolderId, DEFAULT_LEASE_TTL_MS, type LeaseRecord, type AcquireLeaseResult } from "../lifecycle/lease";
 import { StaleLockError } from "../lifecycle/git";
 import { cronMatches, cronDueBetween } from "./cron";
+import { createChangeSignalGate, DEFAULT_SIGNAL_FLOOR_MS, type WakeReason } from "./change-signal";
+import type { ChangeSubscription } from "../lexicon";
 
 /**
  * Poll interval between rounds — the operator's own cadence, and the fallback
@@ -211,11 +213,67 @@ function sleepAbortable(ms: number, signal?: AbortSignal): Promise<void> {
   });
 }
 
+/**
+ * One lexicon's change-signal seam, already bound to an environment (#1981).
+ *
+ * The loop never sees a `LexiconPlugin`: core's operator does not import
+ * plugins, and binding happens where plugins are already loaded
+ * (`collectChangeSubscribers` in `../cli/plugins.ts`), the same extract-then-
+ * thread shape `collectBuildRootContributors` uses for build roots.
+ */
+export interface ChangeSubscriber {
+  /** Which lexicon supplies the signal. Log lines only; never a fact. */
+  lexicon: string;
+  subscribe(ctx: {
+    onChange: () => void;
+    onError: (message: string) => void;
+    signal: AbortSignal;
+  }): Promise<ChangeSubscription>;
+}
+
+/**
+ * What the loop's change-signal machinery reports, alongside the per-op tick
+ * events. Separate from {@link OperatorTickEvent} on purpose: none of this is
+ * about an Op, and none of it is an observation.
+ */
+export type OperatorSignalEvent =
+  /** A lexicon's subscription is live and the loop may now wake early. */
+  | { kind: "subscribed"; lexicon: string }
+  /** Establishing it failed. The loop keeps its timer and retries next round. */
+  | { kind: "subscribe-failed"; lexicon: string; error: string }
+  /** A live subscription died. Reported once; the next round re-subscribes. */
+  | { kind: "subscription-lost"; lexicon: string; error: string }
+  /** A signal shortened the sleep. The round that follows is an ordinary round. */
+  | { kind: "woken"; afterMs: number };
+
+/** Render one signal event as `chant operator`'s log line shape. */
+export function formatSignalLine(event: OperatorSignalEvent): string {
+  switch (event.kind) {
+    case "subscribed":
+      return `operator: ${event.lexicon} change signal subscribed (the timer still runs)`;
+    case "subscribe-failed":
+      return `operator: ${event.lexicon} change signal unavailable, polling on the timer (${event.error})`;
+    case "subscription-lost":
+      return `operator: ${event.lexicon} change signal lost, polling on the timer until the next round re-subscribes (${event.error})`;
+    case "woken":
+      return `operator: woken by a change signal after ${event.afterMs}ms, running an ordinary round`;
+  }
+}
+
 export interface OperatorLoopOptions extends OperatorRoundOptions {
   /** @default DEFAULT_OPERATOR_INTERVAL_MS */
   intervalMs?: number;
   /** Called after every round completes — the CLI's one-line-per-tick log lives here, not inside the loop itself, so a test can drive rounds without capturing stdout. */
   onRound?: (events: OperatorTickEvent[]) => void;
+  /**
+   * Change-signal seams to keep subscribed for the life of the loop (#1981).
+   * Omitted, or empty, and the loop is exactly what it was: a timer.
+   */
+  subscribers?: readonly ChangeSubscriber[];
+  /** @default DEFAULT_SIGNAL_FLOOR_MS. The shortest gap a signal may force between two rounds. */
+  signalFloorMs?: number;
+  /** Called for every subscription and wake event. The CLI logs one line each. */
+  onSignalEvent?: (event: OperatorSignalEvent) => void;
 }
 
 /**
@@ -224,6 +282,12 @@ export interface OperatorLoopOptions extends OperatorRoundOptions {
  * (issue: "if it dies, nothing breaks and nothing is lost") — this function
  * is exactly `while (!aborted) { round(); sleep(); }`, nothing durable lives
  * in its own memory that a restart would need to recover.
+ *
+ * With `subscribers` (#1981) the sleep gains a second wake source, and only a
+ * wake source. A signal aborts the current sleep; the round that follows is
+ * the same round the timer would have run, deriving everything from a fresh
+ * observation. Nothing a subscription reports reaches a tick, because the
+ * seam has nowhere to put it: `onChange` takes no arguments.
  */
 export async function runOperatorForever(opts: OperatorLoopOptions): Promise<void> {
   const holder = opts.holder ?? currentHolderId();
@@ -232,11 +296,83 @@ export async function runOperatorForever(opts: OperatorLoopOptions): Promise<voi
   // lands on a firing minute — a fresh operator owes no catch-up for the ticks
   // it was not running for.
   const scheduleState = opts.scheduleState ?? new Map<string, Date>();
-  while (!opts.signal?.aborted) {
-    const events = await runOperatorRound({ ...opts, holder, scheduleState });
-    opts.onRound?.(events);
-    if (opts.signal?.aborted) break;
-    await sleepAbortable(opts.intervalMs ?? DEFAULT_OPERATOR_INTERVAL_MS, opts.signal);
+  const intervalMs = opts.intervalMs ?? DEFAULT_OPERATOR_INTERVAL_MS;
+  const subscribers = opts.subscribers ?? [];
+
+  // Nothing to subscribe to: the loop below is byte for byte the loop that
+  // shipped before #1981, and takes none of the machinery's cost.
+  if (subscribers.length === 0) {
+    while (!opts.signal?.aborted) {
+      const events = await runOperatorRound({ ...opts, holder, scheduleState });
+      opts.onRound?.(events);
+      if (opts.signal?.aborted) break;
+      await sleepAbortable(intervalMs, opts.signal);
+    }
+    return;
+  }
+
+  const gate = createChangeSignalGate({ floorMs: opts.signalFloorMs ?? DEFAULT_SIGNAL_FLOOR_MS });
+  // The subscriptions the loop currently holds, by lexicon. A lexicon absent
+  // from this map is one to (re-)subscribe on the next round, which is how a
+  // killed watch comes back without a special retry path.
+  const live = new Map<string, ChangeSubscription>();
+  // Stops every subscription at once when the loop ends, whatever ends it.
+  const subscriptionsAbort = new AbortController();
+
+  const closeAll = async (): Promise<void> => {
+    subscriptionsAbort.abort();
+    const open = [...live.values()];
+    live.clear();
+    // A close that throws must not mask why the loop is unwinding.
+    await Promise.allSettled(open.map((s) => s.close()));
+  };
+
+  const ensureSubscribed = async (): Promise<void> => {
+    for (const subscriber of subscribers) {
+      if (live.has(subscriber.lexicon) || subscriptionsAbort.signal.aborted) continue;
+      try {
+        const subscription = await subscriber.subscribe({
+          onChange: () => gate.signal(),
+          onError: (error) => {
+            // Reported once, then forgotten: dropping it from `live` is what
+            // makes the next round re-subscribe. The loop itself is untouched.
+            if (!live.delete(subscriber.lexicon)) return;
+            opts.onSignalEvent?.({ kind: "subscription-lost", lexicon: subscriber.lexicon, error });
+          },
+          signal: subscriptionsAbort.signal,
+        });
+        live.set(subscriber.lexicon, subscription);
+        opts.onSignalEvent?.({ kind: "subscribed", lexicon: subscriber.lexicon });
+      } catch (err) {
+        // A subscription that cannot be established is a slower loop, never a
+        // stopped one: report it and fall through to the timer.
+        opts.onSignalEvent?.({
+          kind: "subscribe-failed",
+          lexicon: subscriber.lexicon,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  };
+
+  try {
+    while (!opts.signal?.aborted) {
+      gate.roundStarted();
+      const startedAt = Date.now();
+      const events = await runOperatorRound({ ...opts, holder, scheduleState });
+      opts.onRound?.(events);
+      if (opts.signal?.aborted) break;
+
+      await ensureSubscribed();
+      if (opts.signal?.aborted) break;
+
+      const reason: WakeReason = await gate.wait(intervalMs, opts.signal);
+      if (reason === "signal") {
+        opts.onSignalEvent?.({ kind: "woken", afterMs: Date.now() - startedAt });
+      }
+    }
+  } finally {
+    await closeAll();
   }
 }
 

package/src/op/runtimes/local.test.ts

@@ -123,7 +123,7 @@ describe("the local op runtime", () => {
 
     const handle = await runtime.start(
       op("gated", [
-        { kind: "gate", signalName: "approve-prod" },
+        { kind: "gate", gate: "approve-prod" },
         { kind: "activity", fn: "after", args: {} },
       ]),
       {},

package/src/op/types.ts

@@ -170,13 +170,33 @@ export interface EffectStep {
   description?: string;
 }
 
-export interface GateStep {
+/** Everything on a gate step except the key that names it. */
+export interface GateStepBase {
   kind: "gate";
-  /** The gate's name — what `chant approve <op> <gate>` resolves. */
-  signalName: string;
   /** How long a recorded pending gate stays valid, as a duration string. Default: "48h". */
   timeout?: string;
   /** Human-readable description of the action required to unblock this gate. */
   description?: string;
 }
 
+/**
+ * A human approval decided against the gate ledger. The name lives on `gate`;
+ * `signalName` is the key it carried through 0.58.0 and is still accepted
+ * (#2202) — read both through `gateName()` in `./gate-name.ts` rather than
+ * reaching for either key directly.
+ */
+export type GateStep = GateStepBase &
+  (
+    | {
+        /** The gate's name — what `chant approve <op> <gate>` resolves. */
+        gate: string;
+        /** @deprecated Renamed to `gate` in #2202. Accepted through 0.59.0, removed in 0.60.0. */
+        signalName?: string;
+      }
+    | {
+        gate?: undefined;
+        /** @deprecated Renamed to `gate` in #2202. Accepted through 0.59.0, removed in 0.60.0. */
+        signalName: string;
+      }
+  );
+

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);
   });