@intentius/chant 0.72.2 → 0.72.3

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