@intentius/chant 0.89.0 → 0.91.0

package/src/workspace/checks/boxes.ts

@@ -0,0 +1,307 @@
+/**
+ * The box checks, WSP121 and WSP122 (#2726).
+ *
+ * A member whose entry has a `box` block is a box, or holds a box's
+ * declarations. A box holds no credential: each capability it needs outside
+ * itself (inference, Fountain, a third-party API) is reached through a
+ * broker, a runtime such as a lobby or a door, which holds the credential
+ * and enforces the scope the block declares. chant only states and checks
+ * this; it never runs a broker (ws-052).
+ *
+ * | Id | Code | Fails when |
+ * |---|---|---|
+ * | WSP121 | `box-credential-declared` | a file in the box member's directory carries a literal secret (fixed) |
+ * | WSP122 | `box-capability-unbrokered` | a capability in the block names no broker |
+ *
+ * WSP121 reads the member's files from the tree checked, so it works under
+ * `--at`, and runs no member code. A literal secret is either a value with a
+ * well-known credential shape (an AWS key id, a GitHub or Slack token, an
+ * `sk-` key, private key material), wherever it sits, or a literal string
+ * where a credential goes: under a key named like one (`API_KEY`, `token`,
+ * `credential`, `password`, ...), or the `value` of a `{ key, value }` vault
+ * secret. A reference is never one: `${VAR}` and `$VAR`, a secret-manager
+ * reference (`op://`, `bws://`, `infisical://`), a `{{...}}` template
+ * placeholder, and any expression, such as `process.env.X`, that is not a
+ * string literal. WSP121 is fixed: a credential in a box's files is in git.
+ *
+ * WSP123 and WSP124, box isolation (#2727), are in `./box-isolation.ts` and
+ * listed here after these two.
+ */
+
+import * as ts from "typescript";
+import type { WorkspaceCheck, WorkspaceCheckContext, WorkspaceDiagnostic } from "../checks";
+import type { Member } from "../declaration";
+import type { ReasonCode } from "../reason-codes";
+import { joinPath, skippedDir, type WorkspaceTree } from "../tree";
+import { BOX_ISOLATION_CHECKS } from "./box-isolation";
+
+/** The read contract's codes for the box findings, carried as `code` on each. */
+export const BOX_FINDING_CODES = ["box-credential-declared", "box-capability-unbrokered", "box-isolation-collision", "box-isolation-literal"] as const satisfies readonly ReasonCode[];
+
+export const WSP_BOX_CREDENTIAL = "WSP121";
+export const WSP_BOX_UNBROKERED = "WSP122";
+
+/** Values whose shape alone says they are a credential. The list FTN001 uses, plus Anthropic keys. */
+export const CREDENTIAL_SHAPES: readonly { pattern: RegExp; label: string }[] = [
+  { pattern: /\bAKIA[0-9A-Z]{16}\b/, label: "an AWS access key id" },
+  { pattern: /\b(?:ghp|gho|ghs|ghu)_[A-Za-z0-9]{20,}/, label: "a GitHub token" },
+  { pattern: /\bgithub_pat_[A-Za-z0-9_]{20,}/, label: "a GitHub fine-grained token" },
+  { pattern: /\bsk-ant-[A-Za-z0-9_-]{20,}/, label: "an Anthropic API key" },
+  { pattern: /\bsk-[A-Za-z0-9_-]{20,}/, label: "a secret API key (sk-)" },
+  { pattern: /\bftn_[A-Za-z0-9]{16,}/, label: "a Fountain API key" },
+  { pattern: /\bxox[baprs]-[A-Za-z0-9-]{10,}/, label: "a Slack token" },
+  { pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/, label: "private key material" },
+];
+
+/** Secret-manager references a value may be instead of the secret. */
+export const SECRET_REFERENCE_SCHEMES = ["op://", "bws://", "infisical://"] as const;
+
+/**
+ * A key whose value is a credential: `API_KEY`, `GITHUB_TOKEN`, `apiKey`,
+ * `token`, `credential`, `password`, `AWS_SECRET_ACCESS_KEY`. A key that
+ * names where a secret is (`secretKey`, `TOKEN_FILE`, `tokenHash`) is not.
+ */
+const CREDENTIAL_KEY = /(?:^|[_-])(?:API_?KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIALS?|PRIVATE_?KEY|ACCESS_?KEY)$|^(?:apiKey|token|secret|password|credentials?|privateKey|accessKey|authToken)$|[a-z](?:ApiKey|Token|Secret|Password|Credentials?|PrivateKey|AccessKey)$/i;
+
+/** Whether `key` names a credential. Exported for tests. */
+export function isCredentialKey(key: string): boolean {
+  return CREDENTIAL_KEY.test(key);
+}
+
+/** Whether `value` refers to a secret rather than being one. Exported for tests. */
+export function isSecretReference(value: string): boolean {
+  const v = value.trim();
+  if (v === "") return true;
+  if (v.includes("${")) return true;
+  // $VAR, $1, $(command): the shell fills it in.
+  if (v.startsWith("$")) return true;
+  if (/^\{\{[^}]*\}\}$/.test(v)) return true;
+  return SECRET_REFERENCE_SCHEMES.some((s) => v.startsWith(s));
+}
+
+/**
+ * Whether a value under a credential key says where a secret is rather than
+ * being one: a path (`~/box/llm-token`, `/run/secrets/token`), a URL, or an
+ * environment variable's name (`GIT_TOKEN`).
+ */
+function namesWhereSecretIs(value: string): boolean {
+  const v = value.trim();
+  return /^(?:\/|~|\.\.?\/)/.test(v) || /^[a-z][a-z0-9+.-]*:\/\//i.test(v) || /^[A-Z][A-Z0-9_]*$/.test(v);
+}
+
+/** The credential shape `value` has, or undefined. */
+export function credentialShape(value: string): string | undefined {
+  return CREDENTIAL_SHAPES.find((s) => s.pattern.test(value))?.label;
+}
+
+/** One literal secret found in a file. */
+export interface LiteralSecret {
+  /** 1-based. */
+  line: number;
+  column: number;
+  /** What was found, for the message: never the value itself. */
+  what: string;
+}
+
+const CODE_EXTENSIONS: Record<string, ts.ScriptKind> = {
+  ".ts": ts.ScriptKind.TS,
+  ".mts": ts.ScriptKind.TS,
+  ".cts": ts.ScriptKind.TS,
+  ".tsx": ts.ScriptKind.TSX,
+  ".js": ts.ScriptKind.JS,
+  ".mjs": ts.ScriptKind.JS,
+  ".cjs": ts.ScriptKind.JS,
+  ".jsx": ts.ScriptKind.JSX,
+  ".json": ts.ScriptKind.JSON,
+  ".jsonc": ts.ScriptKind.JSON,
+};
+
+const PROSE_EXTENSIONS = new Set([".md", ".mdx", ".txt", ".html", ".rst"]);
+
+/** Files larger than this are not read: a box's declarations are small, and a large file is data or a build. */
+const MAX_FILE_BYTES = 1024 * 1024;
+
+function propertyName(name: ts.PropertyName | undefined): string | undefined {
+  if (!name) return undefined;
+  if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNoSubstitutionTemplateLiteral(name)) return name.text;
+  return undefined;
+}
+
+const isStringLiteral = (n: ts.Node): n is ts.StringLiteral | ts.NoSubstitutionTemplateLiteral => ts.isStringLiteral(n) || ts.isNoSubstitutionTemplateLiteral(n);
+
+/**
+ * The literal secrets in a TypeScript, JavaScript or JSON file, read as
+ * syntax and never run.
+ */
+export function literalSecretsInCode(text: string, file: string, kind: ts.ScriptKind): LiteralSecret[] {
+  const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, kind);
+  const out: LiteralSecret[] = [];
+  const at = (node: ts.Node, what: string) => {
+    const { line, character } = source.getLineAndCharacterOfPosition(node.getStart(source));
+    out.push({ line: line + 1, column: character + 1, what });
+  };
+  const reported = new Set<ts.Node>();
+  const visit = (node: ts.Node) => {
+    if (isStringLiteral(node) && !reported.has(node)) {
+      const shape = credentialShape(node.text);
+      if (shape && !isSecretReference(node.text)) {
+        reported.add(node);
+        at(node, shape);
+      }
+    }
+    if (ts.isPropertyAssignment(node) && isStringLiteral(node.initializer) && !reported.has(node.initializer)) {
+      const key = propertyName(node.name);
+      const value = node.initializer.text;
+      // A value with a credential's shape is reported by that shape, below.
+      if (key !== undefined && !isSecretReference(value) && !namesWhereSecretIs(value) && credentialShape(value) === undefined) {
+        if (isCredentialKey(key)) {
+          reported.add(node.initializer);
+          at(node.initializer, `a literal value for ${key}`);
+        } else if (key === "value" && ts.isObjectLiteralExpression(node.parent) && isVaultSecret(node.parent)) {
+          reported.add(node.initializer);
+          at(node.initializer, `a literal vault secret value for ${vaultSecretKey(node.parent) ?? "a key"}`);
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return out;
+}
+
+/** `{ key, value }` with nothing else but a description: the shape of a vault secret. */
+function isVaultSecret(obj: ts.ObjectLiteralExpression): boolean {
+  const names = obj.properties.map((p) => (ts.isPropertyAssignment(p) || ts.isShorthandPropertyAssignment(p) ? propertyName(p.name) : undefined));
+  return names.includes("key") && names.includes("value") && names.every((n) => n === "key" || n === "value" || n === "description");
+}
+
+function vaultSecretKey(obj: ts.ObjectLiteralExpression): string | undefined {
+  for (const p of obj.properties) {
+    if (ts.isPropertyAssignment(p) && propertyName(p.name) === "key" && isStringLiteral(p.initializer)) return p.initializer.text;
+  }
+  return undefined;
+}
+
+/** `KEY=value`, `export KEY=value` or `KEY: value`, the value optionally quoted. */
+const ASSIGNMENT = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_.-]*)\s*[=:]\s*(["']?)([^"'\s#]+)\2\s*(?:#.*)?$/;
+
+/**
+ * The literal secrets in any other text file, such as a shell script, an
+ * env file or YAML: a credential shape anywhere, or a line assigning a
+ * literal to a credential-named key.
+ */
+export function literalSecretsInText(text: string, assignments = true): LiteralSecret[] {
+  const out: LiteralSecret[] = [];
+  text.split(/\r?\n/).forEach((lineText, i) => {
+    for (const { pattern, label } of CREDENTIAL_SHAPES) {
+      const m = pattern.exec(lineText);
+      if (m && !isSecretReference(m[0])) {
+        out.push({ line: i + 1, column: m.index + 1, what: label });
+        return;
+      }
+    }
+    const a = assignments ? ASSIGNMENT.exec(lineText) : null;
+    if (a && isCredentialKey(a[1]) && !isSecretReference(a[3]) && !namesWhereSecretIs(a[3])) {
+      out.push({ line: i + 1, column: lineText.indexOf(a[3]) + 1, what: `a literal value for ${a[1]}` });
+    }
+  });
+  return out;
+}
+
+function extension(path: string): string {
+  const base = path.slice(path.lastIndexOf("/") + 1);
+  const dot = base.lastIndexOf(".");
+  return dot > 0 ? base.slice(dot).toLowerCase() : "";
+}
+
+/** The literal secrets in one file, or none when the file is binary or too large. */
+export function literalSecretsInFile(text: string, path: string): LiteralSecret[] {
+  if (text.length > MAX_FILE_BYTES || text.includes("\0")) return [];
+  const kind = CODE_EXTENSIONS[extension(path)];
+  if (kind !== undefined) return literalSecretsInCode(text, path, kind);
+  // Prose says "Token: ..." without meaning one, so only a credential's shape counts there.
+  return literalSecretsInText(text, !PROSE_EXTENSIONS.has(extension(path)));
+}
+
+/** Every file under `dir` in `tree`, skipping node_modules and dot-directories, sorted. */
+function filesUnder(tree: WorkspaceTree, dir: string): string[] {
+  const out: string[] = [];
+  const walk = (d: string) => {
+    for (const e of tree.list(d) ?? []) {
+      const p = joinPath(d, e.name);
+      if (e.type === "dir") {
+        if (!skippedDir(e.name)) walk(p);
+      } else out.push(p);
+    }
+  };
+  walk(dir);
+  return out.sort();
+}
+
+const boxMembers = (ctx: WorkspaceCheckContext): Member[] => ctx.declaration.members.filter((m) => m.box !== null);
+
+export const BOX_CHECKS: readonly WorkspaceCheck[] = [
+  {
+    id: WSP_BOX_CREDENTIAL,
+    name: "box-credential-declared",
+    description:
+      "A box holds no credential: no file in a box member's directory carries a literal secret, in its declarations, an env or a vault's defaults. Variable references and secret-manager references (op://, bws://, infisical://) are not secrets.",
+    severity: "error",
+    configurable: false,
+    check(ctx) {
+      const out: WorkspaceDiagnostic[] = [];
+      for (const m of boxMembers(ctx)) {
+        const dir = m.dir === "." ? "" : m.dir;
+        if (ctx.tree.stat(dir) !== "dir") continue;
+        for (const path of filesUnder(ctx.tree, dir)) {
+          let text: string;
+          try {
+            text = ctx.tree.read(path);
+          } catch {
+            continue;
+          }
+          for (const s of literalSecretsInFile(text, path)) {
+            out.push({
+              checkId: this.id,
+              severity: this.severity,
+              code: "box-credential-declared",
+              message: `box-credential-declared: ${path} holds ${s.what}, and member ${m.name} is a box, which holds no credential; replace it with a \${VAR} or secret-manager reference, or declare the capability as brokered in the member's box block`,
+              entity: m.name,
+              pointer: m.box!.pointer,
+              treeFile: path,
+              line: s.line,
+              column: s.column,
+            });
+          }
+        }
+      }
+      return out;
+    },
+  },
+  {
+    id: WSP_BOX_UNBROKERED,
+    name: "box-capability-unbrokered",
+    description: "Every capability a box declares names the broker that holds its credential and enforces its scope.",
+    severity: "error",
+    configurable: true,
+    check(ctx) {
+      const out: WorkspaceDiagnostic[] = [];
+      for (const m of boxMembers(ctx)) {
+        for (const c of m.box!.capabilities) {
+          if (c.broker !== null) continue;
+          out.push({
+            checkId: this.id,
+            severity: this.severity,
+            code: "box-capability-unbrokered",
+            message: `box-capability-unbrokered: member ${m.name}'s box needs ${c.name} and names no broker for it, so the box would hold its credential; set broker to the runtime that holds it, such as the lobby`,
+            entity: m.name,
+            pointer: c.pointer,
+          });
+        }
+      }
+      return out;
+    },
+  },
+  // Box isolation (#2727), WSP123 and WSP124.
+  ...BOX_ISOLATION_CHECKS,
+];

package/src/workspace/checks/records.ts

@@ -14,6 +14,7 @@
  * | WSP113 | a pinned file that a superseding record pins at the old hash: the artifact did not follow the decision |
  * | WSP114 | the records of `--kind` can't be read (fixed) |
  * | WSP115 | a record kind the declaration names is missing or does not load as one (fixed, #2680) |
+ * | WSP116 | an answer kind's decision points file is missing or not valid (fixed, ws-058, #2738) |
  */
 
 import type { WorkspaceCheck, WorkspaceDiagnostic } from "../checks";
@@ -99,4 +100,28 @@ export const RECORD_CHECKS: readonly WorkspaceCheck[] = [
         }));
     },
   },
+  {
+    id: "WSP116",
+    name: "decision-points-invalid",
+    description:
+      "Every answer kind the declaration names has a decision points file that matches decision-points.schema.json: each input names a read-contract output, each table row tests declared inputs and answers a candidate, each model id is pinned, and the chain ends in its one quorum (ws-058).",
+    severity: "error",
+    configurable: false,
+    check(ctx) {
+      const out: WorkspaceDiagnostic[] = [];
+      for (const k of ctx.facts?.declaredKinds ?? []) {
+        if (!k.points) continue;
+        const where = k.declared.member === null ? "the workspace" : `member ${k.declared.member}`;
+        const finding = (message: string) => ({
+          checkId: this.id,
+          severity: this.severity,
+          message,
+          ...(k.declared.member !== null ? { entity: k.declared.member } : {}),
+          pointer: `${k.declared.pointer}/kind`,
+        });
+        for (const p of k.points.problems) out.push(finding(`${where} declares the answer kind ${k.declared.kind}, whose points file ${k.points.file} ${p.field ? `has ${p.field}, which ${p.message}` : p.message}`));
+      }
+      return out;
+    },
+  },
 ];

package/src/workspace/checks.test.ts

@@ -60,6 +60,13 @@ describe("the WSP catalog", () => {
       "records-unreadable",
       // A declared record kind that doesn't load breaks every reader's default (#2680).
       "record-kind-unloadable",
+      // An answer kind's points file that isn't valid can't be asked (ws-058).
+      "decision-points-invalid",
+      // A credential in a box's files is in git (#2726).
+      "box-credential-declared",
+      // Two boxes sharing a value, or a box that only holds on one machine, is never the fix (#2727).
+      "box-isolation-collision",
+      "box-isolation-literal",
     ]);
   });
 

package/src/workspace/checks.ts

@@ -28,6 +28,9 @@
  * | WSP101 to WSP106 | generated files |
  * | WSP111 to WSP114 | records read with `--kind` (#2549) |
  * | WSP115 | the record kinds the declaration names (#2680) |
+ * | WSP116 | the decision points file of each declared answer kind (ws-058) |
+ * | WSP121, WSP122 | boxes: no literal credential, every capability brokered (#2726) |
+ * | WSP123, WSP124 | box isolation: no shared port, state path or cookie, no literal machine path (#2727) |
  */
 
 import { realpathSync } from "node:fs";
@@ -45,6 +48,7 @@ import { gatherGeneratedFacts, GENERATED_CHECKS, type GeneratedFileFacts } from
 import { gatherLedgerFacts, LEDGER_CHECKS, type MemberLedgerFacts } from "./checks/ledgers";
 import { gatherPipelineFacts, PIPELINE_CHECKS, type MemberPipelineFacts } from "./checks/pipelines";
 import { RECORD_CHECKS, type RecordFacts } from "./checks/records";
+import { BOX_CHECKS } from "./checks/boxes";
 import { loadDeclaredKinds, type DeclaredKind } from "./declared-kinds";
 
 /**
@@ -87,6 +91,12 @@ export interface WorkspaceDiagnostic extends PostSynthDiagnostic {
   pointer: string;
   /** An absolute path, for a finding about a file other than the declaration, such as a record (#2549). It is reported at its first line. */
   file?: string;
+  /** A path in the tree checked, relative to the workspace root, for a finding about a file there (#2726). It is reported at `line` and `column`. */
+  treeFile?: string;
+  line?: number;
+  column?: number;
+  /** The read contract's code for the finding, when it has one (#2726). */
+  code?: ReasonCode;
 }
 
 export interface WorkspaceCheck {
@@ -104,7 +114,7 @@ export interface WorkspaceCheck {
 /** A diagnostic ready for lint's reporters, with the entry it is about. */
 export interface WorkspaceFinding extends LintDiagnostic {
   entity?: string;
-  /** The read contract's reason code, for a WSP001 finding: why the declaration can't be read (#2536). */
+  /** The read contract's reason code: for a WSP001 finding, why the declaration can't be read (#2536); for a box check, its finding code (#2726). */
   code?: ReasonCode;
 }
 
@@ -307,6 +317,8 @@ export const WORKSPACE_CHECKS: readonly WorkspaceCheck[] = [
   ...GENERATED_CHECKS,
   // Records read with --kind (#2549).
   ...RECORD_CHECKS,
+  // Boxes and their brokered capabilities (#2726).
+  ...BOX_CHECKS,
 ];
 
 const BY_ID = new Map(WORKSPACE_CHECKS.map((c) => [c.id, c]));
@@ -459,11 +471,16 @@ export async function runDeclarationChecks(
   const locate = (pointer: string): TextLocation => (parsed.ok ? parsed.locate(pointer) : { line: 1, column: 1 });
   const file = display(declaration.file);
   const toFinding = (d: WorkspaceDiagnostic): WorkspaceFinding => ({
-    ...(d.file !== undefined ? { file: display(relative(root, d.file).split(sep).join("/")), line: 1, column: 1 } : { file, ...locate(d.pointer) }),
+    ...(d.treeFile !== undefined
+      ? { file: display(d.treeFile), line: d.line ?? 1, column: d.column ?? 1 }
+      : d.file !== undefined
+        ? { file: display(relative(root, d.file).split(sep).join("/")), line: 1, column: 1 }
+        : { file, ...locate(d.pointer) }),
     ruleId: d.checkId,
     severity: d.severity,
     message: d.message,
     ...(d.entity !== undefined ? { entity: d.entity } : {}),
+    ...(d.code !== undefined ? { code: d.code } : {}),
   });
   const order = (a: LintDiagnostic, b: LintDiagnostic) => a.line - b.line || a.column - b.column || (a.ruleId < b.ruleId ? -1 : a.ruleId > b.ruleId ? 1 : 0);
   const diagnostics = active.map(toFinding).sort(order);

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,