@intentius/chant 0.76.0 → 0.77.0

package/dist/cli/handlers/graph.d.ts

@@ -9,5 +9,11 @@ import type { CommandContext } from "../registry.js";
  * `--format` projects the component DAG itself into that format (nodes =
  * components, wave groups, `dependsOn` edges) — the graph behold renders.
  */
+/**
+ * One `chant graph` is one read of the account (chant #2498): the live
+ * observation and the `--traffic` prediction are two plugin methods that
+ * each read a live root, and inside this session a read one of them made
+ * is the read the other gets.
+ */
 export declare function runGraph(ctx: CommandContext): Promise<number>;
 //# sourceMappingURL=graph.d.ts.map

package/dist/cli/handlers/graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/graph.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,aAAa,CAAC;AAkH9D;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAwCnE"}
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/graph.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,aAAa,CAAC;AAkH9D;;;;;;;;;GASG;AACH;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAE7D"}

package/dist/live-read-session.d.ts

@@ -0,0 +1,50 @@
+/**
+ * One command, one read of the account (chant #2498).
+ *
+ * A `chant graph --live --traffic` against a live root reads the account
+ * twice: once for the graph's observation and once for the prediction, and
+ * each of those used to run `live-plan` twice for the document and its human
+ * render. Four `live-plan` runs for one answer, which on a drifted estate
+ * whose provider retries a deleted resource was five minutes against a
+ * consumer's three-minute budget.
+ *
+ * Nothing shared a read because nothing could: a plugin method takes options
+ * alone and cannot be handed the documents another method already holds. So
+ * the sharing is ambient instead. A command that wants its reads shared runs
+ * inside {@link withLiveReadSession}; a read that can be shared calls
+ * {@link memoLiveRead} with a key naming everything that would change its
+ * answer (root, directory, binary, flags, environment), and gets the pending
+ * or settled promise of an identical read made earlier in the same session.
+ *
+ * The scope is the session, never the process. A watch Op ticking on a
+ * schedule runs the same activity every tick and must see the account move,
+ * so outside a session {@link memoLiveRead} simply reads. A rejection is
+ * never memoised either: the next caller tries again, since a read that
+ * failed on credentials or a timeout says nothing about the next one.
+ *
+ * `AsyncLocalStorage` carries the session across every `await` under the
+ * wrapped call, which is how two plugin methods called one after the other
+ * by one handler share it without either knowing about the other.
+ */
+/**
+ * Run `fn` with a fresh read session, so every {@link memoLiveRead} under
+ * it with the same key is one read. A call already inside a session joins
+ * it rather than opening a nested one: the outer command is the unit of
+ * "once".
+ */
+export declare function withLiveReadSession<T>(fn: () => Promise<T>): Promise<T>;
+/** Whether the caller is inside a {@link withLiveReadSession} scope. */
+export declare function inLiveReadSession(): boolean;
+/**
+ * The result of `read()`, shared with every earlier and later call in the
+ * same session that names the same `key`. Outside a session, `read()` and
+ * nothing else. A read that rejects is dropped from the session so the next
+ * call with its key reads again.
+ */
+export declare function memoLiveRead<T>(key: string, read: () => Promise<T>): Promise<T>;
+/**
+ * A key from the facts that decide a read's answer. Sorted keys, so two
+ * callers that spell the same read in a different order share it.
+ */
+export declare function liveReadKey(activity: string, facts: Record<string, unknown>): string;
+//# sourceMappingURL=live-read-session.d.ts.map

package/dist/live-read-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-read-session.d.ts","sourceRoot":"","sources":["../src/live-read-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAQH;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAGvE;AAED,wEAAwE;AACxE,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAW/E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAIpF"}

package/dist/terraform/graph.d.ts

@@ -1,7 +1,7 @@
 /**
  * Pure Terraform dependency-graph builder for the carve-out advisor (#214 T1).
  *
- * Input is the JSON tree `@cdktf/hcl2json` produces (`Hcl2JsonTree`) plus the
+ * Input is the JSON tree `@cdktn/hcl2json` produces (`Hcl2JsonTree`) plus the
  * traversal accessors its expression AST found per interpolated string
  * (`ExpressionRefs`, resolved in `parse.ts` — #998). Tokenizing `${...}`
  * expression bodies is the AST's job — a quoted address inside an expression

package/dist/terraform/parse.d.ts

@@ -1,9 +1,9 @@
 /**
  * Thin wasm glue for the carve-out advisor (#214 T1): read a Terraform estate's
- * `.tf` files, run them through `@cdktf/hcl2json`, merge into one tree, and hand
+ * `.tf` files, run them through `@cdktn/hcl2json`, merge into one tree, and hand
  * off to the pure `buildGraph`.
  *
- * `@cdktf/hcl2json` is NOT a chant dependency — it carries a ~1.8 MB wasm blob
+ * `@cdktn/hcl2json` is NOT a chant dependency — it carries a ~1.8 MB wasm blob
  * and only carve-out users need it. It is lazy-loaded here and, if absent, the
  * advisor fails with a one-line install hint.
  */
@@ -19,6 +19,24 @@ export interface Hcl2Json {
 export declare class Hcl2JsonNotInstalled extends Error {
     constructor(cause: unknown);
 }
+/**
+ * The environment variable that turns on parser-input recording (chant #2483).
+ *
+ * When set to a file path, every `parse(filename, source)` and every
+ * `getReferencesInExpression(filename, expression)` this process makes is
+ * appended to that file as one JSON line before the real call runs. That is
+ * how `scripts/check-hcl-parser-parity.ts` gets hold of the inline HCL the
+ * test suite parses, which no corpus walk on disk would find: run the suite
+ * with this set, then replay the file through two parsers and compare. Off
+ * unless set, and never changes a result.
+ */
+export declare const HCL2JSON_RECORD_ENV = "CHANT_HCL2JSON_RECORD";
+/** One recorded parser input, as {@link HCL2JSON_RECORD_ENV} writes it. */
+export interface Hcl2JsonRecordLine {
+    kind: "parse" | "refs";
+    filename: string;
+    text: string;
+}
 /**
  * Lazy-load the optional HCL parser. Throws `Hcl2JsonNotInstalled` with an
  * install hint when the package is missing, rather than a raw MODULE_NOT_FOUND.

package/dist/terraform/parse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/terraform/parse.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAErD,wDAAwD;AACxD,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IAChE,yFAAyF;IACzF,yBAAyB,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;CACxG;AAED,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,KAAK,EAAE,OAAO;CAQ3B;AAED;;;GAGG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,QAAQ,CAAC,CAMtD;AAqDD,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,qBAA0B,GAAG,OAAO,CAAC,OAAO,CAAC,CAWvG"}
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/terraform/parse.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAErD,wDAAwD;AACxD,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IAChE,yFAAyF;IACzF,yBAAyB,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;CACxG;AAED,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,KAAK,EAAE,OAAO;CAQ3B;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AAE3D,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAkBD;;;GAGG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,QAAQ,CAAC,CAStD;AAqDD,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,qBAA0B,GAAG,OAAO,CAAC,OAAO,CAAC,CAWvG"}

package/dist/terraform/types.d.ts

@@ -7,7 +7,7 @@
  * source (the emit/boundary/apply phases stay in #197, gated on demand).
  *
  * The graph layer here is intentionally pure: it consumes the JSON shape
- * `@cdktf/hcl2json` produces (see `parse.ts`), so the graph and scoring can
+ * `@cdktn/hcl2json` produces (see `parse.ts`), so the graph and scoring can
  * be tested without loading the wasm parser.
  */
 /** A node in the Terraform dependency graph — one resource or module block. */
@@ -82,7 +82,7 @@ export interface TfGraph {
     edges: TfEdge[];
 }
 /**
- * The subset of `@cdktf/hcl2json`'s `parse()` output the advisor reads. A
+ * The subset of `@cdktn/hcl2json`'s `parse()` output the advisor reads. A
  * merged tree across every `.tf` file in the estate. Values are left as the
  * raw hcl2json encoding (interpolations survive as `"${...}"` strings), which
  * is what edge extraction scans.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.76.0",
+  "version": "0.77.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -100,7 +100,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@cdktf/hcl2json": "^0.21.0",
+    "@cdktn/hcl2json": "^0.24.0",
     "ajv": "^8.20.0"
   },
   "overrides": {

package/src/audit/proof.ts

@@ -168,7 +168,7 @@ function dropRedundantDefaults(content: string): { patched: string; changed: boo
  * (`x = "${var.y}"` becomes `x = var.y`), the deprecated pre-0.12 style
  * tflint's `terraform_deprecated_interpolation` reports. Anchored on the
  * source text rather than the parsed body for the reason TF016's own module
- * gives: `@cdktf/hcl2json` renders a bare reference and a quoted interpolation
+ * gives: `@cdktn/hcl2json` renders a bare reference and a quoted interpolation
  * identically, so the quotes only exist here.
  */
 const INTERPOLATION_ONLY_RE = /^([ \t]*)([A-Za-z_][A-Za-z0-9_-]*)([ \t]*=[ \t]*)"\$\{([^"]+)\}"([ \t]*(?:#.*)?)$/;

package/src/behaviour-kinds.ts

@@ -307,7 +307,7 @@ export function unmappedDetail(
     ? `the lexicon that owns ${owner.prefixes.join(", ")}`
     : "the lexicon that owns this entity type";
   return (
-    `${label} has no row in any contributed coverage table — it is a type from a substrate that is ` +
+    `${label} has no row in any contributed coverage table. It is a type from a substrate that is ` +
     "modelled, and is neither mapped to an engine kind nor declared unmapped, so nothing has an " +
     `opinion about it rather than a stated one. Add a row in ${where}.`
   );

package/src/cli/handlers/graph.ts

@@ -10,6 +10,7 @@ import { buildDeclaredPerStack } from "../../graph-declared";
 import { mergeProjectOps } from "../../graph-ops";
 import { reconstructEdges, mergeCatalogs, containmentGroups, type ReferenceCatalog, type ContainmentPair } from "../../graph-refs";
 import { observeResources } from "../../lifecycle/observe";
+import { withLiveReadSession } from "../../live-read-session";
 import { replaySnapshots, hasSnapshot } from "../../lifecycle/replay";
 import { loadChantConfig, environmentNames, matchesDeclaredEnvironment, loadChantConfigUpward, type ChantConfig } from "../../config";
 import { applyLiveEndpoint } from "../../live-endpoint";
@@ -146,7 +147,17 @@ async function mergeGraphOps(
  * `--format` projects the component DAG itself into that format (nodes =
  * components, wave groups, `dependsOn` edges) — the graph behold renders.
  */
-export async function runGraph(ctx: CommandContext): Promise<number> {
+/**
+ * One `chant graph` is one read of the account (chant #2498): the live
+ * observation and the `--traffic` prediction are two plugin methods that
+ * each read a live root, and inside this session a read one of them made
+ * is the read the other gets.
+ */
+export function runGraph(ctx: CommandContext): Promise<number> {
+  return withLiveReadSession(() => runGraphCommand(ctx));
+}
+
+async function runGraphCommand(ctx: CommandContext): Promise<number> {
   const viewFormats = ["ir", "mermaid", "dot", "layout"] as const;
   const isViewFormat = (viewFormats as readonly string[]).includes(ctx.args.format);
   // `--projection <lexicon>` (#989) only means anything for the component

package/src/cli/main.ts

@@ -511,8 +511,8 @@ Commands:
   carve advise          Read-only peelability advisor: rank which resources
                         --from <dir>      are cheap to carve into native chant
                         (--json, --report <path>). Emits nothing, changes nothing.
-                        --from a Terraform dir needs @cdktf/hcl2json
-                        (npm install -D @cdktf/hcl2json); --from a CDK cloud
+                        --from a Terraform dir needs @cdktn/hcl2json
+                        (npm install -D @cdktn/hcl2json); --from a CDK cloud
                         assembly (cdk.out) needs nothing and ranks constructs.
   carve emit            Adopt a selected TF resource into chant source + report
                         --from <tf-dir>   its boundary. --state <tfstate> adopts offline

package/src/discovery/sandbox/bundle.ts

@@ -28,10 +28,10 @@ const require = createRequire(import.meta.url);
  * file that imports a lexicon package pulls `typescript` in transitively,
  * every time, not just for the rare file that uses the compiler itself.
  *
- * `@cdktf/hcl2json` is here for the same reason and by a longer road. It is
+ * `@cdktn/hcl2json` is here for the same reason and by a longer road. It is
  * an OPTIONAL dependency — `../../terraform/parse.ts` reaches it through
  * `await import(...)` and turns a missing module into an actionable "npm
- * install -D @cdktf/hcl2json" — but esbuild follows a dynamic import as
+ * install -D @cdktn/hcl2json" — but esbuild follows a dynamic import as
  * eagerly as a static one, and the package ships a Go `wasm_exec` shim whose
  * `performance` reference does not resolve under `platform: "node"`. So a
  * bundle that merely *reaches* the carve commands fails outright. Reaching
@@ -42,7 +42,7 @@ const require = createRequire(import.meta.url);
  * cannot fold — pulled the whole CLI, and carve with it, into its sandbox
  * bundle (chant #2129).
  */
-const EXTERNAL_PACKAGES = ["typescript", "@cdktf/hcl2json"];
+const EXTERNAL_PACKAGES = ["typescript", "@cdktn/hcl2json"];
 
 /**
  * Resolve each of {@link EXTERNAL_PACKAGES} to its real, absolute path on

package/src/live-read-session.test.ts

@@ -0,0 +1,79 @@
+/**
+ * The read session shares an identical read inside one scope and nowhere
+ * else (chant #2498).
+ */
+
+import { describe, expect, it } from "vitest";
+import { inLiveReadSession, liveReadKey, memoLiveRead, withLiveReadSession } from "./live-read-session";
+
+function counter(): { read: () => Promise<number>; calls: number } {
+  const state = { calls: 0, read: async () => ++state.calls };
+  return state;
+}
+
+describe("memoLiveRead", () => {
+  it("reads every time outside a session", async () => {
+    const c = counter();
+    expect(inLiveReadSession()).toBe(false);
+    expect(await memoLiveRead("k", c.read)).toBe(1);
+    expect(await memoLiveRead("k", c.read)).toBe(2);
+    expect(c.calls).toBe(2);
+  });
+
+  it("reads once per key inside a session, including for callers that overlap in flight", async () => {
+    const c = counter();
+    await withLiveReadSession(async () => {
+      expect(inLiveReadSession()).toBe(true);
+      const [a, b] = await Promise.all([memoLiveRead("k", c.read), memoLiveRead("k", c.read)]);
+      expect(a).toBe(1);
+      expect(b).toBe(1);
+      expect(await memoLiveRead("k", c.read)).toBe(1);
+      expect(await memoLiveRead("other", c.read)).toBe(2);
+    });
+    expect(c.calls).toBe(2);
+  });
+
+  it("does not carry a read from one session into the next", async () => {
+    const c = counter();
+    await withLiveReadSession(() => memoLiveRead("k", c.read));
+    await withLiveReadSession(() => memoLiveRead("k", c.read));
+    expect(c.calls).toBe(2);
+    expect(inLiveReadSession()).toBe(false);
+  });
+
+  it("joins an enclosing session rather than opening a nested one", async () => {
+    const c = counter();
+    await withLiveReadSession(async () => {
+      await memoLiveRead("k", c.read);
+      await withLiveReadSession(() => memoLiveRead("k", c.read));
+    });
+    expect(c.calls).toBe(1);
+  });
+
+  it("does not memoise a rejection", async () => {
+    let attempts = 0;
+    const read = async (): Promise<string> => {
+      attempts++;
+      if (attempts === 1) throw new Error("credentials");
+      return "ok";
+    };
+    await withLiveReadSession(async () => {
+      await expect(memoLiveRead("k", read)).rejects.toThrow("credentials");
+      expect(await memoLiveRead("k", read)).toBe("ok");
+      expect(await memoLiveRead("k", read)).toBe("ok");
+    });
+    expect(attempts).toBe(2);
+  });
+});
+
+describe("liveReadKey", () => {
+  it("is the same key whichever order the facts are given in, and differs on any fact", () => {
+    expect(liveReadKey("live-plan", { root: "app", dir: "/x", adoptionOnly: false })).toBe(
+      liveReadKey("live-plan", { adoptionOnly: false, dir: "/x", root: "app" }),
+    );
+    expect(liveReadKey("live-plan", { root: "app", dir: "/x" })).not.toBe(liveReadKey("live-ls", { root: "app", dir: "/x" }));
+    expect(liveReadKey("live-plan", { root: "app", adoptionOnly: false })).not.toBe(
+      liveReadKey("live-plan", { root: "app", adoptionOnly: true }),
+    );
+  });
+});

package/src/live-read-session.ts

@@ -0,0 +1,79 @@
+/**
+ * One command, one read of the account (chant #2498).
+ *
+ * A `chant graph --live --traffic` against a live root reads the account
+ * twice: once for the graph's observation and once for the prediction, and
+ * each of those used to run `live-plan` twice for the document and its human
+ * render. Four `live-plan` runs for one answer, which on a drifted estate
+ * whose provider retries a deleted resource was five minutes against a
+ * consumer's three-minute budget.
+ *
+ * Nothing shared a read because nothing could: a plugin method takes options
+ * alone and cannot be handed the documents another method already holds. So
+ * the sharing is ambient instead. A command that wants its reads shared runs
+ * inside {@link withLiveReadSession}; a read that can be shared calls
+ * {@link memoLiveRead} with a key naming everything that would change its
+ * answer (root, directory, binary, flags, environment), and gets the pending
+ * or settled promise of an identical read made earlier in the same session.
+ *
+ * The scope is the session, never the process. A watch Op ticking on a
+ * schedule runs the same activity every tick and must see the account move,
+ * so outside a session {@link memoLiveRead} simply reads. A rejection is
+ * never memoised either: the next caller tries again, since a read that
+ * failed on credentials or a timeout says nothing about the next one.
+ *
+ * `AsyncLocalStorage` carries the session across every `await` under the
+ * wrapped call, which is how two plugin methods called one after the other
+ * by one handler share it without either knowing about the other.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+type Memo = Map<string, Promise<unknown>>;
+
+const sessions = new AsyncLocalStorage<Memo>();
+
+/**
+ * Run `fn` with a fresh read session, so every {@link memoLiveRead} under
+ * it with the same key is one read. A call already inside a session joins
+ * it rather than opening a nested one: the outer command is the unit of
+ * "once".
+ */
+export function withLiveReadSession<T>(fn: () => Promise<T>): Promise<T> {
+  if (sessions.getStore()) return fn();
+  return sessions.run(new Map(), fn);
+}
+
+/** Whether the caller is inside a {@link withLiveReadSession} scope. */
+export function inLiveReadSession(): boolean {
+  return sessions.getStore() !== undefined;
+}
+
+/**
+ * The result of `read()`, shared with every earlier and later call in the
+ * same session that names the same `key`. Outside a session, `read()` and
+ * nothing else. A read that rejects is dropped from the session so the next
+ * call with its key reads again.
+ */
+export function memoLiveRead<T>(key: string, read: () => Promise<T>): Promise<T> {
+  const memo = sessions.getStore();
+  if (!memo) return read();
+  const shared = memo.get(key);
+  if (shared) return shared as Promise<T>;
+  const pending = read();
+  memo.set(key, pending);
+  pending.catch(() => {
+    if (memo.get(key) === pending) memo.delete(key);
+  });
+  return pending;
+}
+
+/**
+ * A key from the facts that decide a read's answer. Sorted keys, so two
+ * callers that spell the same read in a different order share it.
+ */
+export function liveReadKey(activity: string, facts: Record<string, unknown>): string {
+  const ordered: Record<string, unknown> = {};
+  for (const name of Object.keys(facts).sort()) ordered[name] = facts[name];
+  return `${activity}:${JSON.stringify(ordered)}`;
+}

package/src/meta/declared-imports.test.ts

@@ -41,7 +41,7 @@ const CORE = fileURLToPath(new URL("../../", import.meta.url));
  */
 const DELIBERATELY_UNDECLARED = new Map<string, string>([
   [
-    "@cdktf/hcl2json",
+    "@cdktn/hcl2json",
     "carries a ~1.8 MB wasm blob and is only needed by `chant carve`; " +
       "`terraform/parse.ts` catches the failed import and prints the install line",
   ],

package/src/terraform/graph.test.ts

@@ -4,7 +4,7 @@ import { buildFixtureGraph } from "./__fixtures__/build-graph";
 import type { Hcl2JsonTree } from "./types";
 
 /**
- * The #197 worked example, in the JSON shape `@cdktf/hcl2json` emits: a bucket,
+ * The #197 worked example, in the JSON shape `@cdktn/hcl2json` emits: a bucket,
  * its versioning sub-resource, and a Lambda that reads the bucket's name + arn.
  */
 const workedExample: Hcl2JsonTree = {

package/src/terraform/graph.ts

@@ -1,7 +1,7 @@
 /**
  * Pure Terraform dependency-graph builder for the carve-out advisor (#214 T1).
  *
- * Input is the JSON tree `@cdktf/hcl2json` produces (`Hcl2JsonTree`) plus the
+ * Input is the JSON tree `@cdktn/hcl2json` produces (`Hcl2JsonTree`) plus the
  * traversal accessors its expression AST found per interpolated string
  * (`ExpressionRefs`, resolved in `parse.ts` — #998). Tokenizing `${...}`
  * expression bodies is the AST's job — a quoted address inside an expression

package/src/terraform/parse.test.ts

@@ -2,10 +2,11 @@ import { describe, test, expect, beforeAll } from "vitest";
 import { mkdtempSync, writeFileSync, rmSync } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
-import { parseTerraformDir, loadHcl2json, Hcl2JsonNotInstalled } from "./parse";
+import { parseTerraformDir, loadHcl2json, Hcl2JsonNotInstalled, HCL2JSON_RECORD_ENV } from "./parse";
+import { readFileSync } from "fs";
 
 /**
- * `@cdktf/hcl2json` is an optional (dev-only in this repo) dependency. These
+ * `@cdktn/hcl2json` is an optional (dev-only in this repo) dependency. These
  * tests exercise the real wasm parser when it resolves and skip cleanly when it
  * does not, so a consumer install without the parser never fails the suite.
  */
@@ -21,13 +22,44 @@ beforeAll(async () => {
 
 describe("loadHcl2json", () => {
   test("missing parser throws an install-hint error, not a raw MODULE_NOT_FOUND", () => {
-    const err = new Hcl2JsonNotInstalled(new Error("Cannot find module '@cdktf/hcl2json'"));
-    expect(err.message).toContain("npm install -D @cdktf/hcl2json");
+    const err = new Hcl2JsonNotInstalled(new Error("Cannot find module '@cdktn/hcl2json'"));
+    expect(err.message).toContain("npm install -D @cdktn/hcl2json");
     expect(err.message).toContain("HCL parser");
     expect(err.name).toBe("Hcl2JsonNotInstalled");
   });
 });
 
+describe("parser-input recording (#2483)", () => {
+  test("with the record variable set, every parse and expression call is appended as one JSON line", async () => {
+    if (!parserAvailable) return;
+    const dir = mkdtempSync(join(tmpdir(), "chant-tf-record-"));
+    const record = join(dir, "record.jsonl");
+    process.env[HCL2JSON_RECORD_ENV] = record;
+    try {
+      const parser = await loadHcl2json();
+      const tree = await parser.parse("main.tf", `locals {\n  a = var.x\n}\n`);
+      const refs = await parser.getReferencesInExpression("expression.tf", "${var.x}");
+      expect(tree).toEqual({ locals: [{ a: "${var.x}" }] });
+      expect(refs.map((r) => r.value)).toEqual(["var.x"]);
+      const lines = readFileSync(record, "utf-8").trim().split("\n").map((l) => JSON.parse(l));
+      expect(lines).toEqual([
+        { kind: "parse", filename: "main.tf", text: `locals {\n  a = var.x\n}\n` },
+        { kind: "refs", filename: "expression.tf", text: "${var.x}" },
+      ]);
+    } finally {
+      delete process.env[HCL2JSON_RECORD_ENV];
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("without the variable, the parser is handed back as is", async () => {
+    if (!parserAvailable) return;
+    delete process.env[HCL2JSON_RECORD_ENV];
+    const parser = await loadHcl2json();
+    expect(typeof (parser as unknown as { convertFiles?: unknown }).convertFiles).toBe("function");
+  });
+});
+
 describe.runIf(true)("parseTerraformDir (real wasm)", () => {
   test("parses a multi-file estate into the expected graph", async () => {
     if (!parserAvailable) return; // optional dep absent — skip

package/src/terraform/parse.ts

@@ -1,14 +1,14 @@
 /**
  * Thin wasm glue for the carve-out advisor (#214 T1): read a Terraform estate's
- * `.tf` files, run them through `@cdktf/hcl2json`, merge into one tree, and hand
+ * `.tf` files, run them through `@cdktn/hcl2json`, merge into one tree, and hand
  * off to the pure `buildGraph`.
  *
- * `@cdktf/hcl2json` is NOT a chant dependency — it carries a ~1.8 MB wasm blob
+ * `@cdktn/hcl2json` is NOT a chant dependency — it carries a ~1.8 MB wasm blob
  * and only carve-out users need it. It is lazy-loaded here and, if absent, the
  * advisor fails with a one-line install hint.
  */
 
-import { readdirSync, readFileSync } from "fs";
+import { appendFileSync, readdirSync, readFileSync } from "fs";
 import { join } from "path";
 import { buildGraph, collectExpressions, type ExpressionRefs } from "./graph";
 import { readStateInstanceCounts, applyStateCounts } from "./state";
@@ -25,23 +25,62 @@ export class Hcl2JsonNotInstalled extends Error {
   constructor(cause: unknown) {
     super(
       "Terraform carve-out needs the HCL parser, which is not installed.\n" +
-        "  Install it once:  npm install -D @cdktf/hcl2json\n" +
+        "  Install it once:  npm install -D @cdktn/hcl2json\n" +
         `(underlying error: ${cause instanceof Error ? cause.message : String(cause)})`,
     );
     this.name = "Hcl2JsonNotInstalled";
   }
 }
 
+/**
+ * The environment variable that turns on parser-input recording (chant #2483).
+ *
+ * When set to a file path, every `parse(filename, source)` and every
+ * `getReferencesInExpression(filename, expression)` this process makes is
+ * appended to that file as one JSON line before the real call runs. That is
+ * how `scripts/check-hcl-parser-parity.ts` gets hold of the inline HCL the
+ * test suite parses, which no corpus walk on disk would find: run the suite
+ * with this set, then replay the file through two parsers and compare. Off
+ * unless set, and never changes a result.
+ */
+export const HCL2JSON_RECORD_ENV = "CHANT_HCL2JSON_RECORD";
+
+/** One recorded parser input, as {@link HCL2JSON_RECORD_ENV} writes it. */
+export interface Hcl2JsonRecordLine {
+  kind: "parse" | "refs";
+  filename: string;
+  text: string;
+}
+
+function recording(parser: Hcl2Json, path: string): Hcl2Json {
+  const note = (line: Hcl2JsonRecordLine): void => {
+    appendFileSync(path, `${JSON.stringify(line)}\n`);
+  };
+  return {
+    parse: (filename, hcl) => {
+      note({ kind: "parse", filename, text: hcl });
+      return parser.parse(filename, hcl);
+    },
+    getReferencesInExpression: (filename, expression) => {
+      note({ kind: "refs", filename, text: expression });
+      return parser.getReferencesInExpression(filename, expression);
+    },
+  };
+}
+
 /**
  * Lazy-load the optional HCL parser. Throws `Hcl2JsonNotInstalled` with an
  * install hint when the package is missing, rather than a raw MODULE_NOT_FOUND.
  */
 export async function loadHcl2json(): Promise<Hcl2Json> {
+  let parser: Hcl2Json;
   try {
-    return (await import("@cdktf/hcl2json")) as Hcl2Json;
+    parser = (await import("@cdktn/hcl2json")) as Hcl2Json;
   } catch (err) {
     throw new Hcl2JsonNotInstalled(err);
   }
+  const record = process.env[HCL2JSON_RECORD_ENV];
+  return record ? recording(parser, record) : parser;
 }
 
 /**

package/src/terraform/types.ts

@@ -7,7 +7,7 @@
  * source (the emit/boundary/apply phases stay in #197, gated on demand).
  *
  * The graph layer here is intentionally pure: it consumes the JSON shape
- * `@cdktf/hcl2json` produces (see `parse.ts`), so the graph and scoring can
+ * `@cdktn/hcl2json` produces (see `parse.ts`), so the graph and scoring can
  * be tested without loading the wasm parser.
  */
 
@@ -86,7 +86,7 @@ export interface TfGraph {
 }
 
 /**
- * The subset of `@cdktf/hcl2json`'s `parse()` output the advisor reads. A
+ * The subset of `@cdktn/hcl2json`'s `parse()` output the advisor reads. A
  * merged tree across every `.tf` file in the estate. Values are left as the
  * raw hcl2json encoding (interpolations survive as `"${...}"` strings), which
  * is what edge extraction scans.