@intentius/chant 0.89.0 → 0.90.0

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": {

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

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

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

@@ -117,7 +117,8 @@
             "asset-stale",
             "record-supersedes-pending",
             "record-no-evidence",
-            "review-undigested"
+            "review-undigested",
+            "source-transcript-drift"
           ]
         },
         "message": {
@@ -161,6 +162,8 @@
                 "record-id-unallocatable",
                 "record-path-unmatched",
                 "record-sign-failed",
+                "source-harvest-not-proposed",
+                "record-state-not-initial",
                 "record-unparseable",
                 "record-schema-invalid",
                 "record-id-duplicate",

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

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

package/src/workspace/records-write.ts

@@ -67,6 +67,8 @@ export const NEW_ERROR_CODES = [
   "record-id-unallocatable",
   "record-path-unmatched",
   "record-sign-failed",
+  "source-harvest-not-proposed",
+  "record-state-not-initial",
   ...RECORD_REASON_CODES,
 ] as const satisfies readonly ReasonCode[];
 
@@ -354,7 +356,7 @@ export async function readAll(o: Opened, source: RecordSource): Promise<RecordEn
     const subjectKind = await loadRecordKind(resolve(dirname(o.loaded.file), o.loaded.kind.session.subjects.kind), o.root);
     subjects = { records: (await readRecords(subjectKind, { root: o.root, source })).records, reviews: subjectKind.kind.reviews?.field ?? "reviews" };
   }
-  return (await readRecords(o.loaded, { root: o.root, source, assets, ...(subjects ? { subjects } : {}) })).records;
+  return (await readRecords(o.loaded, { root: o.root, source, assets, workspaceRoot: o.workspaceRoot, ...(subjects ? { subjects } : {}) })).records;
 }
 
 /** `base` with the file at `path` holding `text`, added to its directory when new. */
@@ -441,6 +443,24 @@ function refuseRevisionFields(kind: LoadedRecordKind["kind"], fields: Record<str
   }
 }
 
+/**
+ * Refuse a harvested record in any state but the kind's first (#2708): a
+ * record whose source block says `via: "harvest"` came out of a transcript
+ * after the fact, so it is a proposal, and a person decides it.
+ */
+function refuseHarvestedDecision(kind: LoadedRecordKind["kind"], fields: Record<string, unknown>): void {
+  if (!kind.source || !kind.states || kind.stateField === undefined) return;
+  const block = fields[kind.source.field];
+  if (block === null || typeof block !== "object" || Array.isArray(block) || (block as Record<string, unknown>).via !== "harvest") return;
+  const opens = kind.states[0];
+  const state = fields[kind.stateField];
+  if (state === opens) return;
+  throw new RecordWriteError(
+    "source-harvest-not-proposed",
+    `${kind.source.field}.via is harvest, and a harvested ${kind.name} opens ${opens}, not ${JSON.stringify(state ?? null)}: write it with ${kind.stateField} "${opens}", and let the person who decides it move it on with chant workspace records amend or review`,
+  );
+}
+
 /**
  * `text`, the record `data` holds, with its author sealed (#2688): an ssh
  * signature by the key `sign` names over the record id, the digest of
@@ -594,14 +614,71 @@ export interface NewRecordOptions {
   sign?: string | true;
 }
 
+/**
+ * A write made through a channel other than the command line (#2707), such
+ * as `chant serve mcp`. The CLI never sets one.
+ */
+export interface WriteChannel {
+  /**
+   * Laid over the kind's source block (#2708) when the kind declares one:
+   * `via` and `client`. A new record gets the block, made when the fields
+   * give none; an amendment only when its fields set the block.
+   */
+  source: Record<string, unknown>;
+  /** A new record opens in the kind's first state: filled in when the fields give no state, and refused with record-state-not-initial when they give another. */
+  opensInitial?: boolean;
+}
+
+/** What a channel's write adds to the command line's: who the author is, and how it came. */
+export interface ChannelOptions {
+  /** The record's author, written to the kind's `reviews.decider` field: the person or agent that decided. */
+  by?: string;
+  through?: WriteChannel;
+}
+
+/** `fields` with the channel's author and source laid over them (#2707). `isNew` for `records new`. */
+function applyChannel(o: Opened, fields: Record<string, unknown>, opts: ChannelOptions, isNew: boolean, flag: string): Record<string, unknown> {
+  const { kind } = o.loaded;
+  const out = { ...fields };
+  if (opts.by !== undefined) {
+    if (!kind.reviews) throw new RecordWriteError("write-usage-invalid", `by names a record's author, the kind's reviews.decider field, and the ${kind.name} kind declares no reviews`);
+    if (opts.by.trim() === "") throw new RecordWriteError("write-usage-invalid", "by needs the name of the person or agent that decided");
+    const f = kind.reviews.decider;
+    if (out[f] !== undefined && out[f] !== null && out[f] !== opts.by) {
+      throw new RecordWriteError("write-input-invalid", `the fields given with ${flag} set ${f} to ${JSON.stringify(out[f])}, and by names ${JSON.stringify(opts.by)}: give one author`);
+    }
+    out[f] = opts.by;
+  }
+  const through = opts.through;
+  if (!through) return out;
+  if (isNew && through.opensInitial && kind.states && kind.stateField !== undefined) {
+    const first = kind.states[0];
+    const state = out[kind.stateField];
+    if (state === undefined) out[kind.stateField] = first;
+    else if (state !== first) {
+      throw new RecordWriteError(
+        "record-state-not-initial",
+        `a new ${kind.name} opens ${first}, and the fields give ${kind.stateField} ${JSON.stringify(state)}: write it ${first}, and let the person who decides it move it on with a review or an amendment`,
+      );
+    }
+  }
+  if (kind.source && (isNew || kind.source.field in out)) {
+    const f = kind.source.field;
+    const block = out[f];
+    if (block === undefined || block === null) out[f] = { ...through.source };
+    else if (typeof block === "object" && !Array.isArray(block)) out[f] = { ...(block as Record<string, unknown>), ...through.source };
+  }
+  return out;
+}
+
 /** `records new`: write one new record from validated fields, sealed by its author with `sign`. */
-export async function newRecord(opts: NewRecordOptions): Promise<NewDocument> {
+export async function newRecord(opts: NewRecordOptions & ChannelOptions): Promise<NewDocument> {
   try {
     if (opts.prefix !== undefined && !/^[A-Za-z][A-Za-z0-9]*$/.test(opts.prefix)) {
       throw new RecordWriteError("write-usage-invalid", `--prefix takes letters and digits, starting with a letter, not ${JSON.stringify(opts.prefix)}`);
     }
-    const fields = parseFields(opts.fields, "--from");
     const o = await open(opts.kind, opts.cwd);
+    const fields = applyChannel(o, parseFields(opts.fields, "--from"), opts, true, "--from");
     const { kind, schema } = o.loaded;
     refuseSealField(o, fields, "--from");
     refuseRevisionFields(kind, fields, {}, "--from");
@@ -617,6 +694,7 @@ export async function newRecord(opts: NewRecordOptions): Promise<NewDocument> {
       if (taken) throw new RecordWriteError("record-id-taken", `id ${given} is already used by ${taken.path}; ids are never reused, so leave ${idField} out to have the next one allocated`);
       id = given;
     }
+    refuseHarvestedDecision(kind, fields);
     // A session records the commit it opened at (#2693): HEAD now, or null before the first commit.
     const opened = kind.session?.openedRev ? { [kind.session.openedRev]: headCommit(o.root) } : {};
     const full = { ...fields, ...opened, [idField]: id };
@@ -676,10 +754,10 @@ export interface AmendRecordOptions {
  * changes only the reviews leaves the digest, and the seal, as they were.
  * `--sign` with nothing to change seals the record as it is.
  */
-export async function amendRecord(opts: AmendRecordOptions): Promise<AmendDocument> {
+export async function amendRecord(opts: AmendRecordOptions & ChannelOptions): Promise<AmendDocument> {
   try {
-    const given = parseFields(opts.fields, "--set");
     const o = await open(opts.kind, opts.cwd);
+    const given = applyChannel(o, parseFields(opts.fields, "--set"), opts, false, "--set");
     const { kind } = o.loaded;
     refuseSealField(o, given, "--set");
     const before = await readAll(o, o.source);
@@ -922,7 +1000,7 @@ function usage(schema: string, message: string): WriteFailure<"write-usage-inval
  * message the verb has always given; several are refused, since a write
  * never guesses which kind it means.
  */
-function declaredWriteKind(schema: string, cwd: string, missing: string): string | WriteFailure<"write-usage-invalid"> {
+export function declaredWriteKind(schema: string, cwd: string, missing: string): string | WriteFailure<"write-usage-invalid"> {
   let kinds: ReturnType<typeof declaredKindFiles>;
   try {
     kinds = declaredKindFiles(cwd);
@@ -978,7 +1056,7 @@ function readInput(schema: string, flag: string, value: string | undefined, cwd:
  * The session kind `records close` goes through when none is named (#2693):
  * the one session kind the declaration names.
  */
-async function declaredSessionKind(schema: string, cwd: string): Promise<string | WriteFailure<"write-usage-invalid">> {
+export async function declaredSessionKind(schema: string, cwd: string): Promise<string | WriteFailure<"write-usage-invalid">> {
   const kinds = (await findSessionKinds(cwd)).map((k) => k.file);
   if (kinds.length === 1) return kinds[0];
   if (kinds.length === 0) return usage(schema, "--kind <session kind file> is required: the declaration names no session kind");

package/src/workspace/records.schema.json

@@ -209,6 +209,7 @@
             "record-supersedes-pending",
             "record-no-evidence",
             "review-undigested",
+            "source-transcript-drift",
             "work-needs-unknown",
             "work-implements-unknown",
             "work-needs-cycle",

package/src/workspace/records.ts

@@ -29,6 +29,7 @@ import type { ReasonCode } from "./reason-codes";
 import { checkPins, pinEntries, type AssetPin } from "./record-assets";
 import { joinSessions, type SessionCitation } from "./record-sessions";
 import type { RecordSource } from "./record-source";
+import { sourceBlock, sourceBlockProblems, transcriptDrift } from "./source-block";
 import type { WorkspaceTree } from "./tree";
 import type { DecisionWork, WorkLink, WorkWarningCode } from "./work";
 
@@ -84,6 +85,12 @@ export const RECORD_WARNING_CODES = [
    * amendment does not stop it counting (#2672).
    */
   "review-undigested",
+  /**
+   * The kind'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 (#2708).
+   */
+  "source-transcript-drift",
 ] as const satisfies readonly ReasonCode[];
 export type RecordWarningCode = (typeof RECORD_WARNING_CODES)[number];
 
@@ -299,6 +306,15 @@ export const recordKindSchema = z
      * `withdrawn_on`. Optional.
      */
     reviews: z.object({ field: z.string().min(1), decider: z.string().min(1) }).strict().optional(),
+    /**
+     * The front-matter object that says where a record came from, opted in
+     * to the stored source block (#2708): `via`, `client`, `harness`,
+     * `model`, `session`, `turns` and `transcript`, beside the kind's own
+     * fields in the same object. With it, those fields are checked for their
+     * shapes, a write with `via: "harvest"` must open in the kind's first
+     * state, and `records` warns `source-transcript-drift`. Optional.
+     */
+    source: z.object({ field: z.string().min(1) }).strict().optional(),
     /**
      * A review-session kind (#2673, #2650 C10): the front-matter list of the
      * verdicts a session produced, the field that seals a closed session, and
@@ -1076,6 +1092,8 @@ export async function readRecords(loaded: LoadedRecordKind, options: ReadRecords
   const match = new RegExp(kind.location.match);
   const validate = await compileSchema(loaded.schema, loaded.refs);
   const workspaceRoot = options.workspaceRoot ?? ".";
+  // Where a relative transcript path resolves (#2708): the workspace root in the working tree.
+  const workspaceDir = workspaceRoot === "." ? options.root : resolve(options.root, ...workspaceRoot.split("/"));
 
   const entries: RecordEntry[] = [];
   const texts = new Map<string, string>();
@@ -1127,6 +1145,16 @@ export async function readRecords(loaded: LoadedRecordKind, options: ReadRecords
     if (!result.ok) {
       entry.reasons.push({ code: "record-schema-invalid", message: result.errors.join("; ") });
     }
+    if (kind.source) {
+      // The stored source block (#2708): its proposal fields' shapes, and the transcript it pins.
+      const block = sourceBlock(fm.value, kind.source.field);
+      if (block) {
+        const problems = sourceBlockProblems(block, kind.source.field);
+        if (problems.length > 0) entry.reasons.push({ code: "record-schema-invalid", message: problems.join("; ") });
+        const drift = transcriptDrift(block, kind.source.field, workspaceDir);
+        if (drift) entry.warnings.push({ code: "source-transcript-drift", message: drift });
+      }
+    }
     if (kind.pins) {
       const cited = fm.value[kind.pins.field];
       if (Array.isArray(cited) && cited.length === 0) {