@intentius/chant 0.88.0 → 0.90.0

package/src/cli/serve-mcp-workspace.test.ts

@@ -0,0 +1,142 @@
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { pathToFileURL } from "node:url";
+
+/**
+ * #2700 — `chant serve mcp` at a workspace root whose lexicons all live in
+ * members starts, with core's tools and the chant members' lexicons, instead
+ * of refusing with "No lexicon detected". A project with no workspace and no
+ * lexicon still refuses.
+ *
+ * #2701 — `chant --version` and `-V` print the installed version.
+ */
+
+const repoRoot = resolve(import.meta.dirname, "../../../..");
+const mainTs = join(repoRoot, "packages/core/src/cli/main.ts");
+const tsxLoader = pathToFileURL(join(repoRoot, "node_modules/tsx/dist/loader.mjs")).href;
+const TIMEOUT = 90_000;
+
+function chant(cwd: string, args: string[], input?: string) {
+  return spawnSync(process.execPath, ["--import", tsxLoader, mainTs, ...args], {
+    cwd,
+    input,
+    encoding: "utf-8",
+    timeout: 60_000,
+    env: { ...process.env, NO_COLOR: "1" },
+  });
+}
+
+interface InitializeResult {
+  serverInfo: { name: string; version: string };
+  instructions?: string;
+}
+
+/** Send initialize and tools/list over stdio; stdin closing ends the server. */
+function initializeAndList(cwd: string): { status: number | null; stderr: string; init: InitializeResult; tools: string[] } {
+  const input = [
+    { jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2024-11-05", clientInfo: { name: "test" } } },
+    { jsonrpc: "2.0", method: "notifications/initialized" },
+    { jsonrpc: "2.0", id: 2, method: "tools/list", params: {} },
+  ].map((m) => JSON.stringify(m)).join("\n") + "\n";
+  const run = chant(cwd, ["serve", "mcp"], input);
+  const responses = run.stdout.trim().split("\n").filter(Boolean).map((l) => JSON.parse(l));
+  const byId = (id: number) => responses.find((r) => r.id === id);
+  return {
+    status: run.status,
+    stderr: run.stderr,
+    init: byId(1)?.result,
+    tools: (byId(2)?.result?.tools ?? []).map((t: { name: string }) => t.name),
+  };
+}
+
+const CORE_TOOLS = ["composites", "search", "build", "lint", "explain", "op-list", "op-run", "op-status", "op-approve", "op-report"];
+
+describe("chant serve mcp at a workspace root with no lexicon of its own (#2700)", () => {
+  let scratch: string;
+
+  beforeAll(() => {
+    scratch = realpathSync(mkdtempSync(join(tmpdir(), "chant-serve-mcp-ws-")));
+  });
+  afterAll(() => {
+    rmSync(scratch, { recursive: true, force: true });
+  });
+
+  test("the reference workspace root answers initialize and lists core tools with the delivery member's lexicon", () => {
+    const { status, stderr, init, tools } = initializeAndList(join(repoRoot, "reference-workspace"));
+    expect(status, stderr).toBe(0);
+    expect(init.serverInfo.name).toBe("chant");
+    for (const name of CORE_TOOLS) expect(tools).toContain(name);
+    expect(tools).toContain("docker:diff");
+    expect(init.instructions).toContain("Member delivery (delivery/) declares docker.");
+  }, TIMEOUT);
+
+  test("a chud-shaped root, lexicons only in a member, serves core and the lexicons that load", () => {
+    const root = join(scratch, "chud-shaped");
+    mkdirSync(join(root, ".git"), { recursive: true });
+    mkdirSync(join(root, "delivery"), { recursive: true });
+    mkdirSync(join(root, "app"), { recursive: true });
+    writeFileSync(join(root, "chant.workspace.json"), JSON.stringify({
+      name: "t",
+      schema: 1,
+      members: [
+        { name: "app", dir: "app", kind: "other", because: "an app" },
+        { name: "delivery", dir: "delivery", kind: "chant" },
+      ],
+      pins: [],
+    }));
+    // `chud` is not installed here, as it would not be for a chant without
+    // @intentius/chud: it is named as not loaded and the rest is served.
+    writeFileSync(join(root, "delivery", "chant.config.ts"), 'export default { lexicons: ["docker", "chud"] };\n');
+    writeFileSync(join(root, "app", "server.js"), "// not chant\n");
+
+    const { status, stderr, init, tools } = initializeAndList(root);
+    expect(status, stderr).toBe(0);
+    for (const name of CORE_TOOLS) expect(tools).toContain(name);
+    expect(tools).toContain("docker:diff");
+    expect(init.instructions).toContain('workspace "t"');
+    expect(init.instructions).toContain("Lexicon chud did not load");
+    expect(init.instructions).toContain("Lexicon tools and resources served: docker.");
+  }, TIMEOUT);
+
+  test("a workspace root whose members' lexicons all fail to load serves core alone and says so", () => {
+    const root = join(scratch, "core-only");
+    mkdirSync(join(root, ".git"), { recursive: true });
+    mkdirSync(join(root, "delivery"), { recursive: true });
+    writeFileSync(join(root, "chant.workspace.json"), JSON.stringify({
+      name: "core-only",
+      schema: 1,
+      members: [{ name: "delivery", dir: "delivery", kind: "chant" }],
+      pins: [],
+    }));
+    writeFileSync(join(root, "delivery", "chant.config.ts"), 'export default { lexicons: ["no-such-lexicon"] };\n');
+
+    const { status, stderr, init, tools } = initializeAndList(root);
+    expect(status, stderr).toBe(0);
+    for (const name of CORE_TOOLS) expect(tools).toContain(name);
+    expect(tools.filter((t) => t.includes(":"))).toEqual([]);
+    expect(init.instructions).toContain("only chant's core tools and resources are served");
+  }, TIMEOUT);
+
+  test("a project with no workspace and no lexicon still refuses", () => {
+    const root = join(scratch, "plain");
+    mkdirSync(join(root, ".git"), { recursive: true });
+    writeFileSync(join(root, "index.ts"), "export const x = 1;\n");
+    const run = chant(root, ["serve", "mcp"], "");
+    expect(run.status).toBe(1);
+    expect(run.stderr).toContain("No lexicon detected");
+    expect(run.stdout).toBe("");
+  }, TIMEOUT);
+});
+
+describe("chant --version (#2701)", () => {
+  const version = (JSON.parse(readFileSync(join(repoRoot, "packages/core/package.json"), "utf-8")) as { version: string }).version;
+
+  test.each([["--version"], ["-V"]])("%s prints the package version and exits 0", (flag) => {
+    const run = chant(repoRoot, [flag]);
+    expect(run.status, run.stderr).toBe(0);
+    expect(run.stdout.trim()).toBe(version);
+  }, TIMEOUT);
+});

package/src/op/op-verb-class.ts

@@ -47,6 +47,10 @@ const READ_ONLY_ACTIVITY_FNS: ReadonlySet<string> = new Set([
   "spriteListDir",
   "listCheckpoints",
   "convergeTick",
+  "spriteUrl",
+  "spriteServiceGet",
+  "spriteServiceList",
+  "spriteServiceLogs",
 ]);
 
 /** Activity function names that always delete/destroy, regardless of args. */
@@ -57,6 +61,8 @@ const ALWAYS_DESTRUCTIVE_ACTIVITY_FNS: ReadonlySet<string> = new Set([
   "awsDelete",
   "gcpDelete",
   "spriteDestroy",
+  "spriteDelete",
+  "spriteServiceDelete",
   "k3dDown",
   "k3sUninstall",
 ]);

package/src/workspace/conformance/__fixture__/decisions/decision.kind.mjs

@@ -29,4 +29,8 @@ export const recordKind = {
   // Verdicts, and the field naming the decider, for each record's digest and
   // quorum (#2671, #2672).
   reviews: { field: "reviews", decider: "decided_by" },
+  // source is where a decision came from, and says where its proposal came
+  // from too: via, client, harness, model, session, turns and a transcript
+  // pinned by hash (#2708).
+  source: { field: "source" },
 };

package/src/workspace/conformance/__fixture__/decisions/decision.schema.json

@@ -50,8 +50,8 @@
       "type": ["string", "null"]
     },
     "source": {
-      "description": "Where the decision was first recorded: a row of an issue's decisions table, or the workspace itself when no issue holds the decision (#2654).",
-      "oneOf": [{ "$ref": "#/definitions/sourceIssue" }, { "$ref": "#/definitions/sourceWorkspace" }]
+      "description": "Where the decision was first recorded: a row of an issue's decisions table, the workspace itself when no issue holds the decision (#2654), or a harness session when neither does (#2708). Each form may also say where the proposal came from: the fields via, client, harness, model, session, turns and transcript, which the kind opts in to with source: { field: \"source\" }.",
+      "oneOf": [{ "$ref": "#/definitions/sourceIssue" }, { "$ref": "#/definitions/sourceWorkspace" }, { "$ref": "#/definitions/sourceHarness" }]
     },
     "question": {
       "description": "One sentence. Null only in an importer draft.",
@@ -319,7 +319,14 @@
         "revision": {
           "description": "The design revision that last changed this row, such as \"v8\". Null when the row carries no marker.",
           "type": ["string", "null"]
-        }
+        },
+        "session": { "$ref": "#/definitions/sourceSession" },
+        "via": { "$ref": "#/definitions/sourceVia" },
+        "client": { "$ref": "#/definitions/sourceClient" },
+        "harness": { "$ref": "#/definitions/sourceHarnessId" },
+        "model": { "$ref": "#/definitions/sourceModel" },
+        "turns": { "$ref": "#/definitions/sourceTurns" },
+        "transcript": { "$ref": "#/definitions/sourceTranscript" }
       }
     },
     "sourceWorkspace": {
@@ -335,16 +342,103 @@
           "pattern": "^[a-z0-9][a-z0-9-]{0,39}$"
         },
         "session": {
-          "description": "The id of the session the decision was made in, as the member names it. Null or absent when there was none.",
-          "type": ["string", "null"],
-          "minLength": 1
+          "description": "The id of the session the decision was made in, as the member names it, or the harness's session with the chant session record it was held in. Null or absent when there was none.",
+          "$ref": "#/definitions/sourceSession"
         },
         "issue": {
           "description": "An issue the decision relates to, when there is one.",
           "$ref": "#/definitions/issueRef"
+        },
+        "via": { "$ref": "#/definitions/sourceVia" },
+        "client": { "$ref": "#/definitions/sourceClient" },
+        "harness": { "$ref": "#/definitions/sourceHarnessId" },
+        "model": { "$ref": "#/definitions/sourceModel" },
+        "turns": { "$ref": "#/definitions/sourceTurns" },
+        "transcript": { "$ref": "#/definitions/sourceTranscript" }
+      }
+    },
+    "sourceHarness": {
+      "description": "A decision proposed in a harness session, with no issue row or workspace member behind it (#2708). It says how it arrived, in via, and may say the rest of where the proposal came from.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["via"],
+      "properties": {
+        "issue": {
+          "description": "An issue the decision relates to, when there is one.",
+          "$ref": "#/definitions/issueRef"
+        },
+        "session": { "$ref": "#/definitions/sourceSession" },
+        "via": { "$ref": "#/definitions/sourceVia" },
+        "client": { "$ref": "#/definitions/sourceClient" },
+        "harness": { "$ref": "#/definitions/sourceHarnessId" },
+        "model": { "$ref": "#/definitions/sourceModel" },
+        "turns": { "$ref": "#/definitions/sourceTurns" },
+        "transcript": { "$ref": "#/definitions/sourceTranscript" }
+      }
+    },
+    "sourceVia": {
+      "description": "How the record reached the workspace: cli, a person or script at chant workspace records new; mcp, a harness through chant serve mcp, which fills this and client itself; harvest, a transcript read after the fact. A harvested decision is written proposed, and a person decides it. Data about the proposal, not trust.",
+      "enum": ["cli", "mcp", "harvest"]
+    },
+    "sourceClient": {
+      "description": "What wrote the record: the MCP client's clientInfo, or the CLI.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 },
+        "title": { "type": "string", "minLength": 1 }
+      }
+    },
+    "sourceHarnessId": {
+      "description": "The harness the decision was proposed in, such as claude-code, codex, gemini-cli, opencode, fountain or hud.",
+      "type": "string",
+      "minLength": 1
+    },
+    "sourceModel": {
+      "description": "The model id the harness reports.",
+      "type": "string",
+      "minLength": 1
+    },
+    "sourceSession": {
+      "description": "The session the decision was made in: its id as a string, or an object with the harness's session or conversation id and the chant session record it was held in (#2697). Null when there was none.",
+      "oneOf": [
+        { "type": "string", "minLength": 1 },
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "minProperties": 1,
+          "properties": {
+            "id": { "description": "The harness's session or conversation id.", "type": "string", "minLength": 1 },
+            "record": { "description": "The id of the chant session record the decision was held in.", "type": "string", "minLength": 1 }
+          }
         }
+      ]
+    },
+    "sourceTurns": {
+      "description": "The turns of the session the decision was made in, from and to, counted as the harness counts them. to is not before from.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["from", "to"],
+      "properties": {
+        "from": { "type": "integer", "minimum": 0 },
+        "to": { "type": "integer", "minimum": 0 }
       }
     },
+    "sourceTranscript": {
+      "description": "The session's transcript, pinned by a path or URI and the lowercase hex SHA-256 of its bytes, never copied into the record. A reader checks the transcript it holds is the one meant; chant workspace records warns source-transcript-drift when the file can be read here and hashes to something else. A path is absolute, starts ~/ from the home directory, or starts at the workspace root; of URIs, only file: ones are read.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sha256"],
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "uri": { "type": "string", "minLength": 1 },
+        "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+      },
+      "oneOf": [{ "required": ["path"] }, { "required": ["uri"] }]
+    },
     "issueRef": {
       "type": "string",
       "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+#[0-9]+$"

package/src/workspace/conformance/index.mjs

@@ -23,6 +23,9 @@ export const {
   readerCallProblems,
   checkReaderRead,
   selectCommands,
+  MCP_READ_TOOLS,
+  mcpToolCall,
+  startMcpSession,
   createConformanceWorkspace,
   conformanceTarget,
   recordingTransport,

package/src/workspace/conformance/index.ts

@@ -131,6 +131,14 @@ export interface WorkspaceReaderConformanceOptions {
   chantCommand?: string[];
   /** How long one chant run may take, in milliseconds. Default 120000. */
   timeoutMs?: number;
+  /**
+   * How the reader's chant calls reach chant (#2707). `cli`, the default,
+   * runs the command. `mcp` answers each call with the matching tool of one
+   * `chant serve mcp` session started in the workspace, and also runs the
+   * command, so the suite holds the tool's document to the command's: they
+   * must be equal. `check` has no tool and is not applicable over MCP.
+   */
+  over?: "cli" | "mcp";
 }
 
 export interface WorkspaceReaderConformanceConfig extends WorkspaceReaderConformanceOptions {
@@ -289,14 +297,151 @@ export function checkReaderRead(command: ReadContractCommand, args: string[], ca
 }
 
 /** The commands to exercise and the ones skipped, from `commands`. Throws on a name that is not a contract command. */
-export function selectCommands(commands?: readonly ReadContractCommand[]): { checked: ReadContractCommand[]; skipped: ReadContractCommand[] } {
-  if (commands === undefined) return { checked: [...READ_CONTRACT_COMMANDS], skipped: [] };
+export function selectCommands(commands?: readonly ReadContractCommand[], over: "cli" | "mcp" = "cli"): { checked: ReadContractCommand[]; skipped: ReadContractCommand[] } {
+  const served = over === "mcp" ? READ_CONTRACT_COMMANDS.filter((c) => MCP_READ_TOOLS[c] !== undefined) : [...READ_CONTRACT_COMMANDS];
+  if (commands === undefined) return { checked: served, skipped: READ_CONTRACT_COMMANDS.filter((c) => !served.includes(c)) };
   const unknown = commands.filter((c) => !(READ_CONTRACT_COMMANDS as readonly string[]).includes(c));
   if (unknown.length > 0) throw new Error(`not read-contract commands: ${unknown.join(", ")}; the commands are ${READ_CONTRACT_COMMANDS.join(", ")}`);
   if (commands.length === 0) throw new Error("commands is empty; list at least one read-contract command");
+  const toolless = commands.filter((c) => !served.includes(c));
+  if (toolless.length > 0) throw new Error(`chant serve mcp has no tool for ${toolless.join(", ")}; over MCP the commands are ${served.join(", ")}`);
   return { checked: READ_CONTRACT_COMMANDS.filter((c) => commands.includes(c)), skipped: READ_CONTRACT_COMMANDS.filter((c) => !commands.includes(c)) };
 }
 
+// ── Over MCP (#2707) ─────────────────────────────────────────────────────────
+
+/** The `chant serve mcp` tool that answers each read-contract command. `check` has none. */
+export const MCP_READ_TOOLS: Partial<Record<ReadContractCommand, string>> = {
+  ls: "workspace-ls",
+  graph: "workspace-graph",
+  status: "workspace-status",
+  records: "workspace-records",
+  "graph --intent": "workspace-graph",
+  "graph --composites": "workspace-graph",
+};
+
+/**
+ * The tool call that answers `chant <argv>`, a read-contract command with its
+ * arguments and JSON flag, or undefined when no tool does. Flags map to the
+ * tool's arguments of the same meaning; the JSON flag is dropped, since a tool
+ * always returns the document.
+ */
+export function mcpToolCall(argv: readonly string[]): { name: string; arguments: Record<string, unknown> } | undefined {
+  if (argv[0] !== "workspace") return undefined;
+  const verb = argv[1];
+  const rest = argv.slice(2);
+  const args: Record<string, unknown> = {};
+  const positional: string[] = [];
+  const kinds: string[] = [];
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    const value = (): string | undefined => rest[++i];
+    if (a === "--json") continue;
+    if (a === "--format" && rest[i + 1] === "json") {
+      i++;
+      continue;
+    }
+    if (a === "--kind") kinds.push(value() ?? "");
+    else if (a === "--at") args.at = value();
+    else if (a === "--since") args.since = value();
+    else if (a === "--compare-to") args.compareTo = value();
+    else if (a === "--intent") args.intent = value();
+    else if (a === "--current") args.current = true;
+    else if (a === "--composites") args.composites = true;
+    else if (a.startsWith("-")) return undefined;
+    else positional.push(a);
+  }
+  switch (verb) {
+    case "ls":
+      return positional.length === 0 && kinds.length === 0 ? { name: "workspace-ls", arguments: args } : undefined;
+    case "status":
+      return positional.length === 1 && kinds.length === 0 ? { name: "workspace-status", arguments: { ...args, env: positional[0] } } : undefined;
+    case "records":
+      return positional.length === 0 && kinds.length <= 1 ? { name: "workspace-records", arguments: { ...args, ...(kinds.length ? { kind: kinds[0] } : {}) } } : undefined;
+    case "graph":
+      return positional.length === 0 ? { name: "workspace-graph", arguments: { ...args, ...(kinds.length ? { kind: kinds } : {}) } } : undefined;
+    default:
+      return undefined;
+  }
+}
+
+/** One `chant serve mcp` session over stdio: JSON-RPC lines in, one response line per request out. */
+export interface McpSession {
+  /** Call a tool and return its structured result, or reject with the error the server gave. */
+  call(name: string, args: Record<string, unknown>): Promise<unknown>;
+  close(): void;
+}
+
+/**
+ * Start `chant serve mcp` in `cwd` and initialize it as `clientInfo`. The
+ * server speaks over stdio only (ws-052): nothing here opens a port.
+ */
+export async function startMcpSession(
+  command: string[],
+  cwd: string,
+  options: { clientInfo?: { name: string; version?: string }; timeoutMs?: number } = {},
+): Promise<McpSession> {
+  const child = spawn(command[0], [...command.slice(1), "serve", "mcp"], { cwd, env: { ...process.env, NO_COLOR: "1" }, stdio: ["pipe", "pipe", "pipe"] });
+  const pending = new Map<number, { settle: (v: unknown) => void; fail: (e: Error) => void; timer: ReturnType<typeof setTimeout> }>();
+  let stderr = "";
+  let buffered = "";
+  let next = 1;
+  const failAll = (e: Error) => {
+    for (const p of pending.values()) {
+      clearTimeout(p.timer);
+      p.fail(e);
+    }
+    pending.clear();
+  };
+  child.stderr.setEncoding("utf-8").on("data", (s: string) => (stderr += s));
+  child.stdout.setEncoding("utf-8").on("data", (s: string) => {
+    buffered += s;
+    let nl: number;
+    while ((nl = buffered.indexOf("\n")) >= 0) {
+      const line = buffered.slice(0, nl).trim();
+      buffered = buffered.slice(nl + 1);
+      if (!line) continue;
+      let msg: { id?: number; result?: unknown; error?: { message: string } };
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      const p = msg.id !== undefined ? pending.get(msg.id) : undefined;
+      if (!p) continue;
+      pending.delete(msg.id!);
+      clearTimeout(p.timer);
+      if (msg.error) p.fail(new Error(msg.error.message));
+      else p.settle(msg.result);
+    }
+  });
+  child.on("error", (e) => failAll(new Error(`could not start chant serve mcp: ${e.message}`)));
+  child.on("close", (code) => failAll(new Error(`chant serve mcp exited (${code})${stderr.trim() ? `: ${stderr.trim()}` : ""}`)));
+  const request = (method: string, params: Record<string, unknown>): Promise<unknown> =>
+    new Promise((settle, fail) => {
+      const id = next++;
+      const timer = setTimeout(() => {
+        pending.delete(id);
+        fail(new Error(`chant serve mcp did not answer ${method} in time`));
+      }, options.timeoutMs ?? 120_000);
+      pending.set(id, { settle, fail, timer });
+      child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`);
+    });
+  await request("initialize", { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: options.clientInfo ?? { name: "chant-reader-conformance" } });
+  child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" })}\n`);
+  return {
+    async call(name, args) {
+      const result = (await request("tools/call", { name, arguments: args })) as { isError?: boolean; structuredContent?: unknown; content?: { text?: string }[] };
+      if (result.isError) throw new Error(result.content?.[0]?.text ?? `${name} failed`);
+      return result.structuredContent ?? JSON.parse(result.content?.[0]?.text ?? "null");
+    },
+    close() {
+      child.stdin.end();
+      child.kill();
+    },
+  };
+}
+
 const GIT_ENV = { GIT_CONFIG_GLOBAL: process.platform === "win32" ? "NUL" : "/dev/null", GIT_CONFIG_NOSYSTEM: "1" };
 
 function git(cwd: string, ...args: string[]): void {
@@ -381,14 +526,39 @@ function runChant(command: string[], argv: string[], cwd: string, timeoutMs: num
  * A transport that runs chant in the workspace `target()` names and records
  * every call and what it printed. `reset()` clears the record before a read.
  */
-export function recordingTransport(target: () => { workspaceDir: string; chantCommand: string[] }, timeoutMs = 120_000) {
+export function recordingTransport(target: () => { workspaceDir: string; chantCommand: string[] }, timeoutMs = 120_000, over: "cli" | "mcp" = "cli") {
   const calls: string[][] = [];
   const printed: ChantRun[] = [];
+  /** Over MCP: where a tool's document and the command's differ. */
+  const problems: string[] = [];
+  let session: Promise<McpSession> | undefined;
+  const viaMcp = async (argv: string[]): Promise<ChantRun> => {
+    const t = target();
+    const call = mcpToolCall(argv);
+    if (!call) return { argv: [...argv], status: null, stdout: "", stderr: `no chant serve mcp tool answers chant ${argv.join(" ")}` };
+    session ??= startMcpSession(t.chantCommand, t.workspaceDir, { timeoutMs });
+    let doc: unknown;
+    try {
+      doc = await (await session).call(call.name, call.arguments);
+    } catch (e) {
+      return { argv: [...argv], status: 1, stdout: "", stderr: `${call.name}: ${(e as Error).message}` };
+    }
+    // The command the tool stands for, run directly: the two documents must be equal.
+    const cli = await runChant(t.chantCommand, argv, t.workspaceDir, timeoutMs);
+    let printedDoc: unknown;
+    try {
+      printedDoc = JSON.parse(cli.stdout);
+    } catch {
+      printedDoc = undefined;
+    }
+    if (!isDeepStrictEqual(doc, printedDoc)) problems.push(`${argv.slice(1).join(" ")}: the MCP tool ${call.name} returned a document other than chant ${argv.join(" ")} printed`);
+    return { argv: [...argv], status: 0, stdout: JSON.stringify(doc), stderr: "" };
+  };
   const transport: ChantTransport = {
     async run(argv) {
       calls.push([...argv]);
       const t = target();
-      const run = await runChant(t.chantCommand, argv, t.workspaceDir, timeoutMs);
+      const run = over === "mcp" ? await viaMcp(argv) : await runChant(t.chantCommand, argv, t.workspaceDir, timeoutMs);
       printed.push(run);
       return run;
     },
@@ -397,9 +567,16 @@ export function recordingTransport(target: () => { workspaceDir: string; chantCo
     transport,
     calls,
     printed,
+    problems,
     reset() {
       calls.length = 0;
       printed.length = 0;
+      problems.length = 0;
+    },
+    /** Stop the MCP session, when one was started. */
+    async close() {
+      if (session) (await session.catch(() => undefined))?.close();
+      session = undefined;
     },
   };
 }
@@ -415,7 +592,7 @@ export async function readAndCheck(reader: WorkspaceReader, recorder: ReturnType
     const stderr = recorder.printed[0]?.stderr.trim();
     return { command, args, problems: [`${command}: the reader threw: ${(e as Error).message}${stderr ? `; chant's stderr: ${stderr}` : ""}`] };
   }
-  return { command, args, problems: checkReaderRead(command, args, recorder.calls, recorder.printed, doc) };
+  return { command, args, problems: [...checkReaderRead(command, args, recorder.calls, recorder.printed, doc), ...recorder.problems] };
 }
 
 /**
@@ -435,10 +612,10 @@ export async function readAndCheck(reader: WorkspaceReader, recorder: ReturnType
  * ```
  */
 export async function runWorkspaceReaderConformance(reader: WorkspaceReaderFactory, options: WorkspaceReaderConformanceOptions = {}): Promise<WorkspaceReaderConformanceReport> {
-  const { checked, skipped } = selectCommands(options.commands);
+  const { checked, skipped } = selectCommands(options.commands, options.over);
   const target = conformanceTarget(options);
+  const recorder = recordingTransport(() => target, options.timeoutMs, options.over);
   try {
-    const recorder = recordingTransport(() => target, options.timeoutMs);
     const built = reader(recorder.transport);
     const before = treeDigest(target.workspaceDir);
     const results: ReaderReadResult[] = [];
@@ -448,6 +625,7 @@ export async function runWorkspaceReaderConformance(reader: WorkspaceReaderFacto
     if (changed.length > 0) problems.push(`workspace: the reads changed files: ${changed.join(", ")}`);
     return { problems, checked, skipped, results, workspaceDir: target.workspaceDir };
   } finally {
+    await recorder.close();
     target.dispose();
   }
 }

package/src/workspace/conformance/vitest.ts

@@ -9,6 +9,7 @@
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import {
   conformanceTarget,
+  MCP_READ_TOOLS,
   READ_CONTRACT_COMMANDS,
   READ_CONTRACT_SCHEMAS,
   readAndCheck,
@@ -20,25 +21,33 @@ import {
 } from "./index";
 
 export function describeWorkspaceReaderConformance(config: WorkspaceReaderConformanceConfig): void {
-  const { checked } = selectCommands(config.commands);
+  const { checked } = selectCommands(config.commands, config.over);
   let target: ReturnType<typeof conformanceTarget> | undefined;
-  const recorder = recordingTransport(() => {
-    if (!target) throw new Error("the conformance workspace is not ready");
-    return target;
-  }, config.timeoutMs);
+  const recorder = recordingTransport(
+    () => {
+      if (!target) throw new Error("the conformance workspace is not ready");
+      return target;
+    },
+    config.timeoutMs,
+    config.over,
+  );
+  const over = config.over === "mcp" ? " over MCP (#2707)" : "";
 
-  describe(`workspace reader conformance (#2657): ${config.name}`, () => {
+  describe(`workspace reader conformance (#2657)${over}: ${config.name}`, () => {
     let before: Record<string, string> | undefined;
     const reader = config.reader(recorder.transport);
 
     beforeAll(() => {
       target = conformanceTarget(config);
     }, 300_000);
-    afterAll(() => target?.dispose());
+    afterAll(async () => {
+      await recorder.close();
+      target?.dispose();
+    });
 
     for (const command of READ_CONTRACT_COMMANDS) {
       if (!checked.includes(command)) {
-        it.skip(`${command}: not applicable, the reader does not list it in commands`, () => {});
+        it.skip(`${command}: not applicable, ${config.over === "mcp" && !MCP_READ_TOOLS[command] ? "chant serve mcp has no tool for it" : "the reader does not list it in commands"}`, () => {});
         continue;
       }
       it(

package/src/workspace/reason-codes.ts

@@ -73,6 +73,7 @@ export const REASONS = {
   "record-supersedes-pending": "A supersedes link from a record whose state is weaker than the record it names, so the link has no effect yet.",
   "record-no-evidence": "The record's evidence list is empty: it cites nothing and pins no file. Information for a reviewer, never an error.",
   "review-undigested": "A verdict names no digest of the text it judged. It still counts, and an amendment does not stop it counting.",
+  "source-transcript-drift": "The record's source block pins a transcript by hash, the file it names can be read here, and its bytes hash to something else: it is not the transcript the record means.",
   // A work record that is valid but warned about (records and graph --intent, #2683).
   "work-needs-unknown": "A work record's needs list names a work id no record has, so the item stays blocked.",
   "work-implements-unknown": "A work record's implements list names a decision id no decision has.",
@@ -114,6 +115,8 @@ export const REASONS = {
   "review-unsupported": "The kind's schema has no reviews field, so its records take no review.",
   "review-note-required": "A dissent was given with no note: a dissent needs a reason.",
   "review-sign-failed": "--sign was given and no seal could be made: the key can't be read or used, git names no ssh signing key, or ssh-keygen is not installed.",
+  "record-state-not-initial": "A record written through chant serve mcp gives a state other than the kind's first: a new record opens proposed, and a person moves it on.",
+  "source-harvest-not-proposed": "A harvested record (source.via harvest) was written in a state other than the kind's first: a harvest proposes, and a person decides.",
   "record-sign-failed": "--sign was given and no author seal could be made: the record names no author, the key can't be read or used, git names no ssh signing key, or ssh-keygen is not installed.",
   // A review given in a session (records review --session, #2693).
   "session-unknown": "--session names no session of a session kind whose subjects are the record's kind.",

package/src/workspace/records-amend.schema.json

@@ -129,7 +129,8 @@
             "asset-stale",
             "record-supersedes-pending",
             "record-no-evidence",
-            "review-undigested"
+            "review-undigested",
+            "source-transcript-drift"
           ]
         },
         "message": {