@intentius/chant 0.88.0 → 0.90.0

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) {

package/src/workspace/source-block.test.ts

@@ -0,0 +1,167 @@
+/**
+ * A record's stored source block (#2708): the decision schema documents it,
+ * records new writes it and records returns it unchanged, a harvested record
+ * opens proposed, and records warns source-transcript-drift when the pinned
+ * transcript is here and hashes to something else.
+ */
+
+import { createHash } from "node:crypto";
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { parseFrontMatter, type RecordEntry } from "./records";
+import { queryRecords } from "./records-cli";
+import { newRecord, renderRecord, stableJson } from "./records-write";
+import { sourceBlockProblems, transcriptDrift, transcriptFile } from "./source-block";
+
+const REPO = join(import.meta.dirname, "..", "..", "..", "..");
+const DECISIONS = join(REPO, "docs", "design", "decisions");
+const KIND = "decisions/decision.kind.mjs";
+
+type Data = Record<string, unknown>;
+
+const SAMPLE = (() => {
+  const fm = parseFrontMatter(readFileSync(join(DECISIONS, "ws-003-seal-scope.md"), "utf-8"));
+  if (!fm.ok) throw new Error(fm.message);
+  return fm.value;
+})();
+
+/** A proposed decision like ws-003, with `over` laid on top. */
+function proposal(over: Data = {}): Data {
+  const d: Data = { ...structuredClone(SAMPLE), state: "proposed", choice: null, decided_by: null, decided_on: null, reviews: [], ...over };
+  delete d.id;
+  return d;
+}
+
+const sha = (text: string) => createHash("sha256").update(text).digest("hex");
+const TRANSCRIPT = '{"turn":1,"role":"user","text":"which way do we deploy?"}\n';
+
+const HARNESS = {
+  via: "mcp",
+  client: { name: "claude-code", version: "2.1.0" },
+  harness: "claude-code",
+  model: "claude-opus-5-5",
+  session: { id: "0f4c2a", record: "S-0002" },
+  turns: { from: 12, to: 18 },
+  transcript: { path: "transcripts/0f4c2a.jsonl", sha256: sha(TRANSCRIPT) },
+};
+
+let dir: string;
+beforeEach(() => {
+  dir = realpathSync(mkdtempSync(join(tmpdir(), "chant-source-block-")));
+  mkdirSync(join(dir, "decisions"));
+  mkdirSync(join(dir, "transcripts"));
+  cpSync(join(DECISIONS, "decision.kind.mjs"), join(dir, "decisions", "decision.kind.mjs"));
+  cpSync(join(DECISIONS, "decision.schema.json"), join(dir, "decisions", "decision.schema.json"));
+  writeFileSync(join(dir, "decisions", "ws-001-one.md"), renderRecord({ ...proposal({ title: "One" }), id: "ws-001" }, "\n# One\n"));
+  writeFileSync(join(dir, "transcripts", "0f4c2a.jsonl"), TRANSCRIPT);
+});
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+const code = (doc: object) => ("error" in doc ? (doc as { error: { code: string } }).error.code : "ok");
+
+async function read(): Promise<RecordEntry[]> {
+  const doc = await queryRecords({ kind: KIND, cwd: dir });
+  if (!("records" in doc)) throw new Error(JSON.stringify(doc));
+  return doc.records;
+}
+
+async function write(source: unknown, over: Data = {}) {
+  return newRecord({ kind: KIND, fields: JSON.stringify(proposal({ title: "Two", source, ...over })), cwd: dir });
+}
+
+describe("the decision schema documents the block", () => {
+  test("each form takes the proposal fields, and a harness form needs via", async () => {
+    for (const source of [
+      HARNESS,
+      { ...HARNESS, issue: "INTENTIUS/chant#2708" },
+      { issue: "INTENTIUS/chant#2708", row: "Source", revision: null, ...HARNESS },
+      { kind: "workspace", member: "app", ...HARNESS, session: "S-0001" },
+      { via: "cli" },
+    ]) {
+      const doc = await write(source, { title: `T ${Math.random()}` });
+      expect(code(doc), JSON.stringify(source)).toBe("ok");
+    }
+    const { via: _via, ...noVia } = HARNESS;
+    for (const source of [
+      noVia,
+      { ...HARNESS, via: "email" },
+      { ...HARNESS, transcript: { path: "a", uri: "file:///a", sha256: sha("a") } },
+      { ...HARNESS, transcript: { path: "a", sha256: "ABC" } },
+      { ...HARNESS, turns: { from: 3 } },
+      { ...HARNESS, session: {} },
+      { ...HARNESS, client: { version: "1" } },
+      { ...HARNESS, row: "a row without an issue" },
+    ]) {
+      const doc = await write(source);
+      expect(code(doc), JSON.stringify(source)).toBe("record-schema-invalid");
+    }
+  });
+
+  test("chant checks the shapes the schema can't: turns that end before they start", async () => {
+    const doc = await write({ ...HARNESS, turns: { from: 18, to: 12 } });
+    expect(doc).toMatchObject({ error: { code: "record-schema-invalid", message: expect.stringContaining("/source/turns ends before it starts") } });
+    expect(sourceBlockProblems({ ...HARNESS, turns: { from: 18, to: 12 } }, "source")).toEqual(["/source/turns ends before it starts"]);
+    expect(sourceBlockProblems({ issue: "o/r#1", row: "anything the kind says" }, "source")).toEqual([]);
+  });
+});
+
+describe("records new and records", () => {
+  test("records new --from with a source block writes it, and records --json returns it unchanged", async () => {
+    const doc = await write(HARNESS);
+    expect(code(doc)).toBe("ok");
+    const written = (await read()).find((r) => r.id === "ws-002");
+    expect(stableJson(written?.data?.source)).toBe(stableJson(HARNESS));
+    expect(written?.valid).toBe(true);
+    expect(written?.warnings.map((w) => w.code)).not.toContain("source-transcript-drift");
+  });
+
+  test("a harvested record opens proposed; any other state is refused with a remedy", async () => {
+    const decided = await write(
+      { ...HARNESS, via: "harvest" },
+      { state: "decided", choice: SAMPLE.choice, decided_by: "alice", decided_on: "2026-09-25" },
+    );
+    expect(decided).toMatchObject({ error: { code: "source-harvest-not-proposed", message: expect.stringContaining('write it with state "proposed"') } });
+    const withdrawn = await write({ ...HARNESS, via: "harvest" }, { state: "withdrawn" });
+    expect(code(withdrawn)).toBe("source-harvest-not-proposed");
+    expect(code(await write({ ...HARNESS, via: "harvest" }))).toBe("ok");
+    // Only a harvest opens proposed: a decision written at the CLI may still be decided in one go.
+    const cli = await write({ via: "cli" }, { title: "Three", state: "decided", choice: SAMPLE.choice, decided_by: "alice", decided_on: "2026-09-25" });
+    expect(code(cli)).toBe("ok");
+  });
+});
+
+describe("source-transcript-drift", () => {
+  test("warns when the transcript is here and its bytes changed, and not when they match or it is missing", async () => {
+    expect(code(await write(HARNESS))).toBe("ok");
+    const drift = async () => (await read()).find((r) => r.id === "ws-002")!.warnings.filter((w) => w.code === "source-transcript-drift");
+    expect(await drift()).toEqual([]);
+    writeFileSync(join(dir, "transcripts", "0f4c2a.jsonl"), TRANSCRIPT + '{"turn":2}\n');
+    const warned = await drift();
+    expect(warned).toHaveLength(1);
+    expect(warned[0].message).toContain("transcripts/0f4c2a.jsonl is pinned at sha256");
+    rmSync(join(dir, "transcripts", "0f4c2a.jsonl"));
+    expect(await drift()).toEqual([]);
+  });
+
+  test("reads an absolute path, ~/ and file: URIs, and never fetches another URI", () => {
+    const file = join(dir, "transcripts", "0f4c2a.jsonl");
+    const bad = "0".repeat(64);
+    expect(transcriptDrift({ transcript: { path: file, sha256: sha(TRANSCRIPT) } }, "source", "/nowhere")).toBeUndefined();
+    expect(transcriptDrift({ transcript: { path: file, sha256: bad } }, "source", "/nowhere")).toContain("is pinned at sha256 000000000000");
+    expect(transcriptDrift({ transcript: { uri: pathToFileURL(file).href, sha256: bad } }, "source", "/nowhere")).toContain("file:");
+    expect(transcriptDrift({ transcript: { uri: "https://example.com/t.jsonl", sha256: bad } }, "source", dir)).toBeUndefined();
+    expect(transcriptFile({ path: "~/t.jsonl" }, dir)).toMatch(/\/t\.jsonl$/);
+    expect(transcriptFile({ path: "t.jsonl" }, dir)).toBe(join(dir, "t.jsonl"));
+  });
+
+  test("a kind that does not opt in is not checked", async () => {
+    const kindFile = join(dir, "decisions", "decision.kind.mjs");
+    writeFileSync(kindFile, readFileSync(kindFile, "utf-8").replace(/\n\s*source: \{ field: "source" \},/, ""));
+    expect(code(await write({ ...HARNESS, turns: { from: 18, to: 12 } }))).toBe("ok");
+    writeFileSync(join(dir, "transcripts", "0f4c2a.jsonl"), "changed");
+    expect((await read()).flatMap((r) => r.warnings.map((w) => w.code))).not.toContain("source-transcript-drift");
+  });
+});

package/src/workspace/source-block.ts

@@ -0,0 +1,129 @@
+/**
+ * A record's stored source block (#2708): where a proposal came from.
+ *
+ * chant's provenance (`trust/provenance.ts`) is computed from git: who
+ * committed a record, and with which key. It says nothing about the harness,
+ * model and session a decision was proposed in, or the conversation behind it.
+ * A record kind that declares `source: { field }` opts in to a stored block
+ * holding that, next to whatever else its source field says (a decision's
+ * issue row or workspace member, a work item's finding):
+ *
+ * - `via`: how the record reached the workspace, `cli`, `mcp` or `harvest`;
+ * - `client`: the MCP client's `clientInfo` (`name`, `version`), or the CLI;
+ * - `harness`: the harness's id, such as `claude-code` or `codex`;
+ * - `model`: the model id the harness reports;
+ * - `session`: the harness's session or conversation id, as a string, or as
+ *   `{ id, record }` with the chant session record it was held in (#2697);
+ * - `turns`: the turn range the decision was made in, `{ from, to }`;
+ * - `transcript`: `{ path | uri, sha256 }`, pinning a transcript by hash and
+ *   never copying it, the way evidence pins a file.
+ *
+ * Every field is optional, and the block is data about the proposal, not
+ * trust: nothing here raises or lowers a record's standing. The rules are
+ * three. The fields that are present must have these shapes
+ * (`record-schema-invalid` otherwise, beside the kind's own schema). A record
+ * written with `via: "harvest"` must open in the kind's first state, since a
+ * harvest proposes and a person decides (`source-harvest-not-proposed`, a
+ * write refusal). And `records` warns `source-transcript-drift` when the
+ * pinned transcript can be read here and its bytes hash to something else.
+ */
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { sha256Hex } from "../content-digest";
+
+/** How a record reached the workspace. Closed. */
+export const SOURCE_VIAS = ["cli", "mcp", "harvest"] as const;
+export type SourceVia = (typeof SOURCE_VIAS)[number];
+
+const text = z.string().min(1);
+const sha256 = z.string().regex(/^[0-9a-f]{64}$/, "must be the lowercase hex SHA-256 of the transcript's bytes");
+
+/** The proposal fields of a source block. Other fields of the block are the kind's, and left to its schema. */
+export const sourceBlockSchema = z.object({
+  via: z.enum(SOURCE_VIAS).optional(),
+  client: z.object({ name: text, version: text.optional(), title: text.optional() }).strict().optional(),
+  harness: text.optional(),
+  model: text.optional(),
+  session: z
+    .union([
+      text,
+      z.null(),
+      z
+        .object({ id: text.optional(), record: text.optional() })
+        .strict()
+        .refine((s) => s.id !== undefined || s.record !== undefined, { message: "names neither the harness's session id nor a chant session record" }),
+    ])
+    .optional(),
+  turns: z
+    .object({ from: z.number().int().min(0), to: z.number().int().min(0) })
+    .strict()
+    .refine((t) => t.to >= t.from, { message: "ends before it starts" })
+    .optional(),
+  transcript: z
+    .union([z.object({ path: text, sha256 }).strict(), z.object({ uri: text, sha256 }).strict()])
+    .optional(),
+});
+
+export type SourceBlock = z.infer<typeof sourceBlockSchema>;
+
+/** The source block of `data`, when `field` holds an object. */
+export function sourceBlock(data: Record<string, unknown> | null, field: string): Record<string, unknown> | undefined {
+  const v = data?.[field];
+  return v !== null && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, unknown>) : undefined;
+}
+
+/** What is wrong with the proposal fields of `block`, as `<path> <message>` lines. Empty when nothing is. */
+export function sourceBlockProblems(block: Record<string, unknown>, field: string): string[] {
+  const parsed = sourceBlockSchema.safeParse(block);
+  if (parsed.success) return [];
+  return parsed.error.issues.map((i) => `/${[field, ...i.path].join("/")} ${i.message}`);
+}
+
+/**
+ * The file a transcript pin names, when it can be read here: a `path`
+ * (absolute, `~/` from the home directory, or else from the workspace root)
+ * or a `file:` URI. Any other URI is not fetched, so it is never reachable.
+ */
+export function transcriptFile(transcript: { path?: string; uri?: string }, workspaceDir: string): string | undefined {
+  if (transcript.path !== undefined) {
+    const p = transcript.path;
+    if (p === "~" || p.startsWith("~/")) return join(homedir(), p.slice(1));
+    return isAbsolute(p) ? p : resolve(workspaceDir, p);
+  }
+  if (transcript.uri !== undefined && transcript.uri.startsWith("file:")) {
+    try {
+      return fileURLToPath(transcript.uri);
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The `source-transcript-drift` message for `block`, or undefined: when its
+ * transcript pin is well formed, the file it names can be read here, and its
+ * bytes hash to something other than the pin. A transcript that can't be
+ * read says nothing either way.
+ */
+export function transcriptDrift(block: Record<string, unknown>, field: string, workspaceDir: string): string | undefined {
+  const parsed = sourceBlockSchema.shape.transcript.safeParse(block.transcript);
+  if (!parsed.success || parsed.data === undefined) return undefined;
+  const t = parsed.data as { path?: string; uri?: string; sha256: string };
+  const file = transcriptFile(t, workspaceDir);
+  if (file === undefined) return undefined;
+  let bytes: Uint8Array;
+  try {
+    bytes = readFileSync(file);
+  } catch {
+    return undefined;
+  }
+  const actual = sha256Hex(bytes);
+  if (actual === t.sha256) return undefined;
+  const named = t.path ?? t.uri!;
+  return `${field}.transcript ${named} is pinned at sha256 ${t.sha256.slice(0, 12)}, and the file here hashes to ${actual.slice(0, 12)}: it is not the transcript the record means`;
+}