@intentius/chant 0.72.1 → 0.72.3

package/src/discovery/fold-no-invoke-declared.test.ts

@@ -0,0 +1,118 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { foldProject, foldExecutionCounts, resetFoldExecutionCounts } from "../index";
+
+/**
+ * chant#2453 — a declared function is judged by its body, never invoked.
+ *
+ * `resolveCallExpression` used to catch a fold failure on an imported callee
+ * and fall back to importing and invoking it. chant#2441 stopped that rescuing
+ * a depth refusal. The external corpus then showed what the rest of it did, in
+ * a project nobody here maintains (jhgaylor/infisical-chant, via
+ * INTENTIUS/typescript-as-data#129):
+ *
+ *     export const namingParams = namingParamsFromEnv();
+ *
+ * whose body reads `process.env`. `F-Eval-Ident` step 4 rejects `process`, so
+ * the body does not fold — and chant imported the module and ran it, folding
+ * the file to whatever the FOLDING PROCESS's environment held.
+ *
+ * The reason this is a correctness bug and not only a conformance divergence:
+ * the file reported `fold`, which reads as "determined statically". Two people
+ * folding the same source got different output, and nothing said so. `--fold`
+ * is the value you would get by running, without running. This ran.
+ */
+describe("a declared function is folded or refused, never invoked (chant#2453)", () => {
+  let root: string;
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "chant-no-invoke-"));
+    resetFoldExecutionCounts();
+  });
+
+  afterEach(() => rmSync(root, { recursive: true, force: true }));
+
+  const write = (name: string, source: string): string => {
+    const p = join(root, name);
+    writeFileSync(p, source);
+    return p;
+  };
+
+  test("an ambient read inside an imported function refuses, rather than folding the shell's environment in", async () => {
+    const params = write(
+      "params.ts",
+      'export function namingParamsFromEnv() {\n  return { prefix: process.env.CHANT_TEST_PREFIX ?? "fallback" };\n}\n',
+    );
+    const app = write(
+      "app.ts",
+      'import { namingParamsFromEnv } from "./params";\nexport const namingParams = namingParamsFromEnv();\n',
+    );
+
+    process.env.CHANT_TEST_PREFIX = "leaked-from-the-test-runner";
+    try {
+      const verdict = (await foldProject([app, params], [], {})).get(app)!;
+
+      // Before the fix this was `fold` with prefix "leaked-from-the-test-runner".
+      expect(verdict.verdict).toBe("run");
+      expect(verdict.reason).toContain("namingParamsFromEnv");
+
+      // The counter is the direct evidence: nothing of the project was run.
+      expect(foldExecutionCounts().projectFactoryInvocations).toBe(0);
+    } finally {
+      delete process.env.CHANT_TEST_PREFIX;
+    }
+  });
+
+  test("the folded output never depends on the environment, which is the property at stake", async () => {
+    const params = write(
+      "params.ts",
+      'export function fromEnv() {\n  return { v: process.env.CHANT_TEST_SWING ?? "d" };\n}\n',
+    );
+    const app = write("app.ts", 'import { fromEnv } from "./params";\nexport const c = fromEnv();\n');
+
+    // Fold the same source twice under different environments. Before the fix
+    // these disagreed, which is the part no reader of a `fold` verdict could
+    // have known.
+    process.env.CHANT_TEST_SWING = "one";
+    const first = (await foldProject([app, params], [], {})).get(app)!;
+    process.env.CHANT_TEST_SWING = "two";
+    const second = (await foldProject([app, params], [], {})).get(app)!;
+    delete process.env.CHANT_TEST_SWING;
+
+    expect(first.verdict).toBe(second.verdict);
+    expect(first.verdict).toBe("run");
+  });
+
+  test("a function whose body does fold still folds, so this narrows nothing it should not", async () => {
+    const helper = write(
+      "helper.ts",
+      'export function joined() {\n  const parts = ["a", "b"];\n  return { joined: parts.join("-") };\n}\n',
+    );
+    const app = write("app.ts", 'import { joined } from "./helper";\nexport const v = joined();\n');
+
+    const verdict = (await foldProject([app, helper], [], {})).get(app)!;
+
+    expect(verdict.verdict).toBe("fold");
+    expect(JSON.parse(JSON.stringify(Object.fromEntries(verdict.exports!)))).toEqual({
+      v: { joined: "a-b" },
+    });
+    // Folded by interpretation, not by running it.
+    expect(foldExecutionCounts().projectFactoryInvocations).toBe(0);
+  });
+
+  test("a same-file callee behaves the same as an imported one", async () => {
+    // Before the fix these two differed for no reason a reader could defend: a
+    // same-file callee had nothing to import, so its rejection was the verdict,
+    // while the identical function one file over got invoked instead.
+    const app = write(
+      "app.ts",
+      'function fromEnv() {\n  return { v: process.env.CHANT_TEST_SAME ?? "d" };\n}\nexport const c = fromEnv();\n',
+    );
+
+    const verdict = (await foldProject([app], [], {})).get(app)!;
+
+    expect(verdict.verdict).toBe("run");
+  });
+});

package/src/fold/fold.ts

@@ -383,8 +383,22 @@ export class FoldError extends Error {
   readonly line: number;
   readonly column: number;
   readonly ruleId: SubsetRuleId;
+  /**
+   * This refusal is `F-Div-Depth` (chant#2441), not an ordinary fold failure.
+   *
+   * The distinction is load-bearing rather than informational. An ordinary
+   * failure to fold an imported call is allowed to fall back to importing and
+   * invoking the callee, which is `resolveCallExpression`'s pre-#1373 arm and
+   * is right for a helper that wraps a composite call. A depth refusal must
+   * NOT take that arm: the specification says the folder declines here, and
+   * invoking instead produces the envelope the fixture's own note warns about
+   * — a value the file's own declarators never produced. Unlike every other
+   * `F-Div` row this one is not a fallback, so papering over it is wrong
+   * output rather than a safe degradation.
+   */
+  readonly refusedAtDepth: boolean;
 
-  constructor(message: string, line: number, column: number, ruleId: SubsetRuleId = "EVL001") {
+  constructor(message: string, line: number, column: number, ruleId: SubsetRuleId = "EVL001", refusedAtDepth = false) {
     const prevStackTraceLimit = Error.stackTraceLimit;
     Error.stackTraceLimit = 0;
     super(`${line}:${column} - ${message}`);
@@ -393,6 +407,7 @@ export class FoldError extends Error {
     this.line = line;
     this.column = column;
     this.ruleId = ruleId;
+    this.refusedAtDepth = refusedAtDepth;
   }
 }
 
@@ -690,7 +705,7 @@ const MAX_FUNCTION_CALL_DEPTH = 32;
 
 function insideFunctionBody(node: ts.Node, what: string): FoldError | undefined {
   if (functionBodyDepth === 0) return undefined;
-  return foldError(node, `${what} inside a folded function body is not foldable`);
+  return foldError(node, `${what} inside a folded function body is not foldable`, "EVL001", true);
 }
 
 function fileLabel(file: string): string {
@@ -769,6 +784,10 @@ function callFoldableFunction(
       node,
       `${label} is not foldable: ${fileLabel(callee.file)}:${err.line}:${err.column} - ${reason}`,
       err.ruleId,
+      // chant#2441 — the refusal happened inside the callee's body and this
+      // frame is the CALL site, so without carrying the flag the caller sees
+      // an ordinary failure and falls back to invoking.
+      err.refusedAtDepth,
     );
   } finally {
     functionBodyDepth -= 1;
@@ -823,9 +842,9 @@ export function locate(node: ts.Node): { line: number; column: number } {
   return { line: line + 1, column: character + 1 };
 }
 
-function foldError(node: ts.Node, message: string, ruleId: SubsetRuleId = "EVL001"): FoldError {
+function foldError(node: ts.Node, message: string, ruleId: SubsetRuleId = "EVL001", refusedAtDepth = false): FoldError {
   const { line, column } = locate(node);
-  return new FoldError(message, line, column, ruleId);
+  return new FoldError(message, line, column, ruleId, refusedAtDepth);
 }
 
 /**

package/src/fold/subset.ts

@@ -178,8 +178,45 @@ import { intrinsicCallFolds, intrinsicCallFoldsEagerly, type IntrinsicDef } from
  *
  * `spec/VERSION` in the specification repository carries the same string, and
  * the conformance adapter reads this one to fill its `specVersion` field.
+ *
+ * ## Why 1.6, and what each version since 1.0 asked for (chant#2445)
+ *
+ * Raising this is the last step of adopting a rule set, so each version was
+ * checked against what chant does rather than against whether the suite is
+ * green:
+ *
+ * - **1.1** added the two profiles. Its own changelog says nothing in `full`
+ *   changed, so an implementation of 1.0 implements 1.1's `full` unchanged.
+ * - **1.2** added `S-LocalFunction`, which chant already folded in both forms,
+ *   and `S-CallLocal`, which chant's classifier rejected until `chant-v0.72.0`
+ *   (#2435). `S-ExportDefault` is `data-host`; the profile table records it in
+ *   `full` as permitted, not required.
+ * - **1.3** dropped the number from `F-Eval-CallLocal` step 2, which chant
+ *   satisfies by reporting the engine's stack overflow as a fallback under
+ *   `F-Depth`, and clarified `F-Eval-Ident` step 3 with the reading both
+ *   implementations already had.
+ * - **1.4** added the `F-Rule-*` family, extracted from chant's own
+ *   post-synthesis engine. The conformance bridge answers all five fixtures
+ *   with no disagreements.
+ * - **1.5** added `F-Val-Source`, and this is the one that looks like a gap and
+ *   is not. The rule says that for every value of the domain there is source in
+ *   the subset whose fold is that value: a property of the subset, not a demand
+ *   that an implementation ship a generator. The round trip's fidelity half is
+ *   named in the specification's README as an obligation on generators and
+ *   explicitly not a rule. Inventory rows `L12.1` to `L12.4` record chant's
+ *   generators against it. The conformance adapter's unanswered `generate`
+ *   hook is a harness capability, not a rule chant fails.
+ * - **1.6** was written from chant's behaviour and no further: `F-Call` step 7
+ *   binding whatever an invoked factory returns is what chant never checked
+ *   (`L8.19`), and a declarator reaching a call through a const alias is what
+ *   chant resolves while refusing a call nested elsewhere (`L2.18`).
+ *
+ * `scripts/check-docs-citations.ts` refuses to run when this constant and the
+ * pinned specification disagree, so `.github/workflows/docs-check.yml` pins the
+ * `spec-1.6` commit and the two move together. That coupling is deliberate: it
+ * is what stops the docs being gated against a rule set nobody writes against.
  */
-export const SPEC_VERSION = "1.0";
+export const SPEC_VERSION = "1.6";
 
 /** The two EVL rule ids a shape violation can be attributed to. */
 export type SubsetRuleId = "EVL001" | "EVL003";

package/src/graph-ir.ts

@@ -725,7 +725,7 @@ export function buildLiveGraphIr(observations: LiveObservation[]): GraphIR {
   for (const observation of observations) {
     for (const edge of observation.edges ?? []) {
       if (!observedIds.has(edge.from) || !observedIds.has(edge.to)) continue;
-      const key = `${edge.from}${edge.to}${edge.viaAttr ?? ""}${edge.toAttr ?? ""}`;
+      const key = `${edge.from}\u0000${edge.to}\u0000${edge.viaAttr ?? ""}\u0000${edge.toAttr ?? ""}`;
       if (seen.has(key)) continue;
       seen.add(key);
       edges.push(edge);

package/src/index.ts

@@ -61,6 +61,16 @@ export {
   type FoldProjectVerdict,
   type TaintPlan,
   type TaintEdgeKind,
+  // F-Obs-Counters' three integers: what a build invoked, what it invoked from
+  // project code, and what it interpreted instead. Already exported from the
+  // module; on the public entry so a conformance harness can report them per
+  // build (chant#2446, INTENTIUS/typescript-as-data#121). The counters are
+  // process-wide and monotonic, so a per-build figure means calling
+  // `resetFoldExecutionCounts()` first — which is why both travel together and
+  // neither is useful alone.
+  foldExecutionCounts,
+  resetFoldExecutionCounts,
+  type FoldExecutionCounts,
 } from "./discovery/fold-import";
 export * from "./lint/parser";
 export * from "./lint/rule";

package/src/lifecycle/gate-ledger.ts

@@ -42,6 +42,7 @@
  * `"resolution"` is the default reading).
  */
 import { sortedJsonReplacer } from "../utils";
+import { currentGateOrigin, type GateOrigin } from "./gate-origin";
 import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASConflictError } from "./git";
 
 const DIR = "_gates";
@@ -138,6 +139,27 @@ export interface GateResolutionRecord {
    * such a record proves is that somebody approved *something*.
    */
   planDigest?: string;
+  /**
+   * The channel this resolution was authored on (chant#2384) — set by the
+   * writer, never by the caller. `chant approve` records `"cli"`, the
+   * `op-approve` MCP tool records `"mcp"`, an ACP-driven approve records
+   * `"acp"`.
+   *
+   * Absent on every resolution written before chant#2384, and absent is not
+   * `"cli"`: an old record simply does not say. `sameOriginRefusal`
+   * (./gate-origin.ts) refuses only on a positive match, so an unlabelled
+   * record is never refused on this ground.
+   */
+  origin?: GateOrigin;
+  /**
+   * This resolution was recorded from the same channel that reached the gate,
+   * deliberately (chant#2384's `--allow-same-origin`).
+   *
+   * On the record rather than only in the console, because the point of the
+   * refusal is that someone chose to bypass it. A reader auditing the ledger
+   * later should see which approvals had a second party and which did not.
+   */
+  sameOriginOverride?: boolean;
 }
 
 export type GateResolutionInput = Omit<GateResolutionRecord, "version" | "kind">;
@@ -183,6 +205,13 @@ export interface PendingGateRecord {
    * step with no `plan`), which is the shape every gate had before #2300.
    */
   planDigest?: string;
+  /**
+   * The channel the run that reached this gate was driven from (chant#2384).
+   *
+   * This is the half a resolution is compared against: a gate reached over MCP
+   * and resolved over MCP has one author, not two.
+   */
+  origin?: GateOrigin;
 }
 
 export type PendingGateInput = Omit<PendingGateRecord, "version" | "kind">;
@@ -233,7 +262,16 @@ export async function appendPendingGate(
   input: PendingGateInput,
   opts?: { cwd?: string },
 ): Promise<{ commit: string; record: PendingGateRecord }> {
-  const record: PendingGateRecord = { version: 1, kind: "pending", ...input };
+  // chant#2384 — stamped here rather than at each caller, because every pending
+  // fact goes through this function and a channel is a property of the process
+  // rather than of the call. An explicit `origin` on the input still wins, so a
+  // caller that knows better can say so.
+  const record: PendingGateRecord = {
+    version: 1,
+    kind: "pending",
+    origin: currentGateOrigin(),
+    ...input,
+  };
   const commit = await appendGateLine(record, "Pending gate record", opts);
   return { commit, record };
 }

package/src/lifecycle/gate-origin.test.ts

@@ -0,0 +1,93 @@
+import { describe, test, expect, afterEach } from "vitest";
+import {
+  currentGateOrigin,
+  setGateOrigin,
+  resetGateOrigin,
+  isModelAuthored,
+  sameOriginRefusal,
+  UNATTESTED_APPROVER,
+} from "./gate-origin";
+
+/**
+ * chant#2384 — the gate's two halves must have different authors.
+ *
+ * The gate as a durable, plan-bound fact is the strongest thing chant says
+ * about agent-driven change: a run reaching an unapproved gate records a
+ * pending fact and exits 3, and since #2300 a resolution counts only for the
+ * plan it names. All of that rests on the run and the approval being authored
+ * by different parties.
+ *
+ * At a shell they are, and the ledger's existing stance is right there: anyone
+ * who can run `chant approve` can also run `chant run`, the same trust boundary
+ * a local commit has. On MCP and ACP it stops being right, because the person's
+ * only act was launching the server — `op-run` returns the gate it stopped on
+ * and `op-approve` resolves it, both authored by the same model in the same
+ * session, and #2300's plan binding does not close it because the digest comes
+ * off the pending fact that same caller produced one tool call earlier.
+ */
+describe("gate origin (chant#2384)", () => {
+  afterEach(() => resetGateOrigin());
+
+  test("the process serves one channel, and it is the CLI unless an entry point says otherwise", () => {
+    expect(currentGateOrigin()).toBe("cli");
+    setGateOrigin("mcp");
+    expect(currentGateOrigin()).toBe("mcp");
+    resetGateOrigin();
+    expect(currentGateOrigin()).toBe("cli");
+  });
+
+  test("only MCP and ACP are model-authored", () => {
+    expect(isModelAuthored("mcp")).toBe(true);
+    expect(isModelAuthored("acp")).toBe(true);
+    // The distinction the whole rule rests on: at a shell a person typed each
+    // command, so the two halves already have different authors.
+    expect(isModelAuthored("cli")).toBe(false);
+    expect(isModelAuthored(undefined)).toBe(false);
+  });
+
+  describe("the same-origin rule", () => {
+    test("refuses a gate reached and resolved on the same model-authored channel", () => {
+      expect(sameOriginRefusal("mcp", "mcp")).toContain("the same caller wrote both halves");
+      expect(sameOriginRefusal("acp", "acp")).toContain("the same caller wrote both halves");
+    });
+
+    test("allows run-then-approve at a shell, which is the intended workflow", () => {
+      // Both halves are `cli` and that is fine. This is the case the issue is
+      // explicit about keeping: `chant approve` typed at a shell followed by
+      // `chant run` still walks through.
+      expect(sameOriginRefusal("cli", "cli")).toBeUndefined();
+    });
+
+    test("allows a model's run approved by a person, which is the separation the gate is for", () => {
+      expect(sameOriginRefusal("mcp", "cli")).toBeUndefined();
+      expect(sameOriginRefusal("acp", "cli")).toBeUndefined();
+    });
+
+    test("allows a person's run approved over MCP, since a person still authored one half", () => {
+      expect(sameOriginRefusal("cli", "mcp")).toBeUndefined();
+    });
+
+    test("refuses across the two model channels only when they are the same one", () => {
+      // Distinct model channels are two sessions, not one caller writing both
+      // halves — so this is permitted, and deliberately so.
+      expect(sameOriginRefusal("mcp", "acp")).toBeUndefined();
+      expect(sameOriginRefusal("acp", "mcp")).toBeUndefined();
+    });
+
+    test("an unlabelled pending fact is never refused, so old ledgers keep working", () => {
+      // Every record written before this change has no origin. Absent is not
+      // "cli" and not a wildcard: the rule fires on a positive match only, so a
+      // pre-#2384 pending fact cannot start refusing approvals retroactively.
+      expect(sameOriginRefusal(undefined, "mcp")).toBeUndefined();
+      expect(sameOriginRefusal(undefined, "acp")).toBeUndefined();
+      expect(sameOriginRefusal(undefined, "cli")).toBeUndefined();
+    });
+  });
+
+  test("the unattested approver is a fixed marker, not a name anyone chose", () => {
+    // `op-approve` took a free-text `approver` on a channel that cannot verify
+    // one, so the model named itself whatever it liked and the ledger recorded
+    // it indistinguishably from a name a person gave.
+    expect(UNATTESTED_APPROVER).toBe("unattested");
+  });
+});

package/src/lifecycle/gate-origin.ts

@@ -0,0 +1,113 @@
+/**
+ * Which channel a gate fact was authored on — chant#2384.
+ *
+ * The gate is the strongest thing chant says about agent-driven change: a run
+ * that reaches an unapproved gate records a pending fact and exits 3, and since
+ * #2300 a resolution counts only for the plan it names. That property rests on
+ * the two halves being authored by different parties.
+ *
+ * `gate-ledger.ts` already states the trust boundary, and is right about it:
+ *
+ * > this record is *not* itself an authorization check — anyone who can run
+ * > `chant approve` locally can write one, the same trust boundary a local
+ * > commit already has.
+ *
+ * That holds at a shell. A person who can run `chant approve` can also run
+ * `chant run`, and the ledger records what they did. It stops holding on MCP
+ * and ACP, because the person's only act was launching the server once; every
+ * call after that is authored by the model. `op-run` returns the gate it
+ * stopped on and `op-approve` resolves it, so the same caller writes both
+ * halves and the separation is gone.
+ *
+ * The ledger could not tell those situations apart, because both produce a
+ * `resolvedBy` string with no record of where it came from. This records the
+ * where.
+ *
+ * ## Why an ambient value rather than a parameter
+ *
+ * A channel is a property of the process, not of a call. A `chant mcp` server
+ * is launched once by a person and then serves a model for its lifetime; there
+ * is no call on it that is not model-authored. So the origin is established at
+ * the entry point and read by whoever writes a ledger line, rather than
+ * threaded through every runtime, executor and step that sits between them.
+ *
+ * This is provenance, not authentication. It records the door a fact came
+ * through. It does not prove who was behind it, and nothing here should be read
+ * as if it did — see {@link UNATTESTED_APPROVER}.
+ */
+
+/** A channel a gate fact can be authored on. */
+export type GateOrigin = "cli" | "mcp" | "acp";
+
+/**
+ * Channels where the caller is a model rather than a person.
+ *
+ * The distinction this type exists to draw. On `cli` a human typed each
+ * command and the existing trust boundary is the right one. On `mcp` and `acp`
+ * a human launched a server and a model authored everything after, so a gate
+ * resolved from the same channel that produced it has no second party in it.
+ */
+const MODEL_AUTHORED: ReadonlySet<GateOrigin> = new Set<GateOrigin>(["mcp", "acp"]);
+
+/** Whether a channel's calls are authored by a model rather than by a person. */
+export function isModelAuthored(origin: GateOrigin | undefined): boolean {
+  return origin !== undefined && MODEL_AUTHORED.has(origin);
+}
+
+/**
+ * What `resolvedBy` says for a resolution recorded on a channel that cannot
+ * attest to a name.
+ *
+ * `op-approve` used to take a free-text `approver` and write it down. Recording
+ * a name the model chose is worse than recording nothing, because it reads in
+ * the ledger exactly like a name a person gave. This is the honest value.
+ */
+export const UNATTESTED_APPROVER = "unattested";
+
+let ambient: GateOrigin = "cli";
+
+/**
+ * Declare the channel this process serves. Called once at an entry point, not
+ * per call: `chant mcp` sets `"mcp"` before it serves anything, `chant acp`
+ * sets `"acp"`, and the CLI leaves the default.
+ */
+export function setGateOrigin(origin: GateOrigin): void {
+  ambient = origin;
+}
+
+/** The channel this process serves. `"cli"` unless an entry point said otherwise. */
+export function currentGateOrigin(): GateOrigin {
+  return ambient;
+}
+
+/** Restore the default. For tests, which must not leak a channel into each other. */
+export function resetGateOrigin(): void {
+  ambient = "cli";
+}
+
+/**
+ * Why a resolution from this origin cannot answer a pending fact from the same
+ * one, or `undefined` when it can.
+ *
+ * The rule, and the two cases it deliberately leaves alone:
+ *
+ *   - Same channel, model-authored. Refused. `op-run` produced the pending
+ *     fact and `op-approve` would resolve it, both authored by the same model
+ *     in the same session. Nothing about that is an approval.
+ *   - Same channel, `cli`. Allowed. A person ran `chant run`, read the plan and
+ *     ran `chant approve`. That is the intended workflow and the trust boundary
+ *     the ledger already documents.
+ *   - Different channels. Allowed, and the point: a model's run approved by a
+ *     person at a shell is exactly the separation the gate is for.
+ */
+export function sameOriginRefusal(
+  pendingOrigin: GateOrigin | undefined,
+  resolutionOrigin: GateOrigin,
+): string | undefined {
+  if (!isModelAuthored(resolutionOrigin)) return undefined;
+  if (pendingOrigin !== resolutionOrigin) return undefined;
+  return (
+    `the gate was reached over ${resolutionOrigin} and this resolution arrived over ${resolutionOrigin} too, ` +
+    "so the same caller wrote both halves"
+  );
+}

package/src/meta/source-is-text.test.ts

@@ -0,0 +1,72 @@
+import { describe, test, expect } from "vitest";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Every shipped source file is text a text tool can read.
+ *
+ * chant#2280 — `graph-ir.ts` carried three literal NUL bytes inside a template
+ * literal, used as separators in a composite key. The value was right and the
+ * code worked; what broke was everything that reads the file as text. ripgrep
+ * classifies a file containing NUL as binary, so it answers `binary file
+ * matches (found a NUL byte around offset 32631)` instead of the matching
+ * lines, and a repo-wide search does not list the file at all. 911 lines were
+ * invisible to every grep-driven search of this repository for as long as the
+ * bytes were there.
+ *
+ * That is worse than a silent bug, because it is a silent bug in the tool you
+ * would use to find bugs. Any audit, any "I searched the codebase", any
+ * refactor that greps for a symbol defined in that file quietly skipped it and
+ * reported success.
+ *
+ * The fix is not to stop using NUL as a separator — it is a good one, being the
+ * character that cannot appear in an identifier or an attribute name. It is to
+ * write it as an escape, four ASCII characters in the file and the same single
+ * code unit at runtime.
+ */
+const SRC = fileURLToPath(new URL("../", import.meta.url));
+
+/** Every TypeScript file under core's src, tests and fixtures included. */
+function sourceFiles(dir: string): string[] {
+  return readdirSync(dir).flatMap((entry) => {
+    const path = join(dir, entry);
+    if (statSync(path).isDirectory()) return entry === "node_modules" ? [] : sourceFiles(path);
+    return /\.(ts|mts|cts)$/.test(entry) ? [path] : [];
+  });
+}
+
+describe("source files are text, not binary (chant#2280)", () => {
+  test("no shipped source file contains a NUL byte", () => {
+    const offenders: string[] = [];
+    for (const file of sourceFiles(SRC)) {
+      const buf = readFileSync(file);
+      const at = buf.indexOf(0);
+      if (at !== -1) offenders.push(`${relative(SRC, file)} (first at byte ${at})`);
+    }
+
+    expect(
+      offenders,
+      "a NUL byte makes ripgrep treat the file as binary, so it reports a " +
+        "binary-file-matches line instead of the matches and a repo-wide search omits " +
+        "the file entirely. Write the character as a unicode escape instead — same " +
+        "value at runtime, plain ASCII in the file.",
+    ).toEqual([]);
+  });
+
+  test("the composite edge key still separates on NUL, which is the point of using it", () => {
+    // Guards the fix rather than the file: the escape must denote the same
+    // character the literal byte did, or the separator silently becomes
+    // something that CAN occur in an identifier and distinct edges collide.
+    const source = readFileSync(join(SRC, "graph-ir.ts"), "utf8");
+    const key = source.split("\n").find((l) => l.includes("const key = `${edge.from}"));
+    expect(key, "the composite edge key moved; check its separator is still NUL").toBeDefined();
+    expect(key).toContain("\\u0000");
+
+    // And the escape really is the NUL character, not a look-alike. Built with
+    // fromCharCode so this file stays plain ASCII and does not fail its own gate.
+    const nul = String.fromCharCode(0);
+    expect(`a${nul}b`.charCodeAt(1)).toBe(0);
+    expect(`a${nul}b`.split(nul)).toEqual(["a", "b"]);
+  });
+});