@rowan-hiro/inkan 0.1.0

package/src/cli.js

@@ -0,0 +1,351 @@
+// Argument parsing, printing, and exit codes. Nothing here holds business
+// logic; that all lives in src/api.js. Exit codes: 0 success, 1 refusal or
+// error.
+
+import { parseArgs } from 'node:util';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import * as api from './api.js';
+import { InkanError } from './api.js';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(path.join(here, '..', 'package.json'), 'utf8'));
+
+// Matches the current YYYY-MM-DD-HHMM-xxxx id form and the legacy YYYY-MM-DD-xxxx form.
+const OUTCOME_ID_RE = /^\d{4}-\d{2}-\d{2}-(?:\d{4}-)?[0-9a-z]{4}$/;
+
+const HELP = `Usage: inkan <command> [options]
+
+Commands:
+  init [--lang <tag>] [--claude]
+      Create .inkan/ and write the agent protocol block into AGENTS.md.
+      --claude also links CLAUDE.md to AGENTS.md.
+  begin "<outcome>" [--accept <text>]... [--decision <id>]... [--lane <tag>]
+      Seal a new outcome; prints its id.
+  amend --reason <text> [<addition>] [--accept <text>]... [--withdraw <n>]...
+        [--decision <id>]... [<id>]
+      Append an amendment to the open outcome; prints the new contract hash.
+  end [<id>] [--met <n>]... [--unmet <n>]... [-s abandoned] --note <text>
+      Record dispositions and close an outcome.
+  status
+      Print every open outcome.
+  log [-n <count>] [--since <date>] [--grep <regex>] [--status <s>]
+      [--decision <id>] [--lane <tag>] [<id>]
+      Print the outcome log, newest first; <id> prints one outcome in full.
+      Filters combine.
+  check [<commit>]
+      Read-only. Reports whether a commit's Inkan-Outcome trailers still
+      match what was recorded. Exit 0 consistent, 1 mismatch, 2 no trailer.
+  doctor
+      Read-only. Reports corrupt outcomes, id mismatches, duplicate
+      decision ids, and dangling decision links. Exit 0 clean, 1 problems.
+  decision add "<title>" --context <text> --decision <text> [--driver <text>]...
+               [--option <text>]... [--consequence <text>]... [-s <status>]
+      Write a numbered MADR record; prints its file path.
+  decision show <id>
+      Print one decision record verbatim. <id> accepts 2, 02, or 0002.
+  decision list [-s <status>]
+      One line per record, ascending by id.
+  decision update <id> --status <status> --reason <text> [--outcome <id>]
+      Append a dated history entry and set the new status.
+  skill install [--claude | --target <dir>]
+      Copy the bundled use-inkan skill to .agents/skills/use-inkan, or to
+      .claude/skills/use-inkan with --claude, or to <dir>/use-inkan; prints
+      the path.
+
+  help, --help, -h     show this help
+  --version, -v        print the version
+
+'ink' is an alias for 'inkan'; both accept identical arguments.`;
+
+function fail(message) {
+  process.stderr.write(`inkan: ${message}\n`);
+  process.exitCode = 1;
+}
+
+function splitAmendPositionals(positionals) {
+  let id;
+  let addition;
+  for (const p of positionals) {
+    if (OUTCOME_ID_RE.test(p) && id === undefined) {
+      id = p;
+    } else if (addition === undefined) {
+      addition = p;
+    } else {
+      throw new InkanError('usage: inkan amend --reason <text> [<addition>] [<id>]');
+    }
+  }
+  return { id, addition };
+}
+
+function printCriterionLine(c, dispositionByIndex) {
+  let line = `  ${c.index}. ${c.text}`;
+  if (c.withdrawn) {
+    line += ' (withdrawn)';
+  } else {
+    const d = dispositionByIndex.get(c.index);
+    if (d) line += d.met ? ' (met)' : ` (unmet${d.note ? `: ${d.note}` : ''})`;
+  }
+  console.log(line);
+}
+
+/** Shared body for `status` and `log <id>`: the open-outcome shape, plus the
+ * closed-only fields when the record has an end event. */
+function printRecord(record) {
+  console.log(`[${record.id}] ${record.closed ? record.status : 'open'}`);
+  console.log(`  sealed: ${record.sealedAt}`);
+  console.log(`  hash: ${record.contractHash}`);
+  if (record.lane) console.log(`  lane: ${record.lane}`);
+  console.log(`  outcome: ${record.outcome}`);
+
+  const dispositionByIndex = new Map((record.dispositions ?? []).map((d) => [d.criterion, d]));
+  for (const c of record.criteria) printCriterionLine(c, dispositionByIndex);
+  for (const a of record.amendments) {
+    console.log(`  amend ${a.ts}: ${a.reason}`);
+    if (a.addition) console.log(`    ${a.addition}`);
+  }
+  if (record.decisionLinks.length > 0) {
+    const links = record.decisionLinks.map((d) => `${d.id} (${d.status ?? 'missing'})`);
+    console.log(`  decisions: ${links.join(', ')}`);
+  }
+
+  if (record.closed) {
+    console.log(`  closed: ${record.closedAt}`);
+    console.log(`  status: ${record.status}`);
+    console.log(`  note: ${record.note}`);
+    console.log(`  tree: ${record.tree ?? 'none'}`);
+    console.log(`  head: ${record.head ?? 'none'}`);
+  }
+}
+
+function printStatus(open) {
+  if (open.length === 0) {
+    console.log('no outcome open');
+    return;
+  }
+  for (const record of open) printRecord(record);
+}
+
+function printCheck(result) {
+  if (result.noTrailer) {
+    console.log(`${result.shortSha}  no Inkan-Outcome trailer`);
+    process.exitCode = 2;
+    return;
+  }
+  for (const r of result.reports) {
+    console.log(`${result.shortSha}  Inkan-Outcome: ${r.id}`);
+    for (const line of r.lines) console.log(`  ${line}`);
+  }
+  if (result.consistent) {
+    console.log('consistent');
+  } else {
+    console.log('mismatch');
+    console.log('a mismatch is a fact about this commit; it is recorded, not repaired');
+    process.exitCode = 1;
+  }
+}
+
+function printDoctor(result) {
+  if (result.problems.length === 0) {
+    console.log(`ok: ${result.outcomeCount} outcomes, ${result.decisionCount} decisions`);
+    return;
+  }
+  for (const p of result.problems) console.log(p);
+  process.exitCode = 1;
+}
+
+function printLogLine(record) {
+  const parts = [record.id, record.closed ? record.status : 'open'];
+  if (record.lane) parts.push(`[${record.lane}]`);
+  parts.push(record.outcome);
+  if (record.closed && record.status !== 'abandoned') {
+    const live = record.criteria.filter((c) => !c.withdrawn).length;
+    const met = (record.dispositions ?? []).filter((d) => d.met).length;
+    parts.push(`(${met}/${live} met)`);
+  }
+  console.log(parts.join('  '));
+}
+
+const DECISION_ADD_USAGE =
+  'usage: inkan decision add "<title>" --context <text> --decision <text> ' +
+  '[--driver <text>]... [--option <text>]... [--consequence <text>]... [-s <status>]';
+
+function runDecision(root, rest) {
+  const [sub, ...subRest] = rest;
+  switch (sub) {
+    case 'add': {
+      const opts = {
+        context: { type: 'string' },
+        decision: { type: 'string' },
+        driver: { type: 'string', multiple: true, default: [] },
+        option: { type: 'string', multiple: true, default: [] },
+        consequence: { type: 'string', multiple: true, default: [] },
+        status: { type: 'string', short: 's' },
+      };
+      const { values, positionals } = parseArgs({ args: subRest, options: opts, allowPositionals: true });
+      if (positionals.length !== 1) throw new InkanError(DECISION_ADD_USAGE);
+      console.log(api.decisionAdd({ root, title: positionals[0], ...values }).file);
+      break;
+    }
+    case 'show': {
+      const { positionals } = parseArgs({ args: subRest, allowPositionals: true });
+      if (positionals.length !== 1) throw new InkanError('usage: inkan decision show <id>');
+      process.stdout.write(api.decisionShow({ root, id: positionals[0] }).content);
+      break;
+    }
+    case 'list': {
+      const { values } = parseArgs({ args: subRest, options: { status: { type: 'string', short: 's' } } });
+      for (const r of api.decisionList({ root, status: values.status }).records) {
+        console.log(`${r.id}  ${r.status}  ${r.title}`);
+      }
+      break;
+    }
+    case 'update': {
+      const opts = { status: { type: 'string' }, reason: { type: 'string' }, outcome: { type: 'string' } };
+      const { values, positionals } = parseArgs({ args: subRest, options: opts, allowPositionals: true });
+      if (positionals.length !== 1) {
+        throw new InkanError('usage: inkan decision update <id> --status <status> --reason <text> [--outcome <id>]');
+      }
+      const result = api.decisionUpdate({ root, id: positionals[0], ...values });
+      console.log(`${result.id} ${result.from} -> ${result.to}`);
+      break;
+    }
+    default:
+      throw new InkanError(`unknown decision subcommand "${sub}"`);
+  }
+}
+
+function run(argv) {
+  const [command, ...rest] = argv;
+
+  if (command === undefined || command === 'help' || command === '--help' || command === '-h') {
+    console.log(HELP);
+    return;
+  }
+  if (command === '--version' || command === '-v') {
+    console.log(pkg.version);
+    return;
+  }
+
+  const root = process.cwd();
+
+  try {
+    switch (command) {
+      case 'init': {
+        const { values } = parseArgs({
+          args: rest,
+          options: { lang: { type: 'string' }, claude: { type: 'boolean', default: false } },
+        });
+        const result = api.init({ root, lang: values.lang, claude: values.claude });
+        const verb = result.changed ? 'Initialized' : 'Already initialized';
+        console.log(`${verb} Inkan in ${result.root}`);
+        if (result.claudeFile) console.log('CLAUDE.md -> AGENTS.md');
+        break;
+      }
+      case 'begin': {
+        const opts = {
+          accept: { type: 'string', multiple: true, default: [] },
+          decision: { type: 'string', multiple: true, default: [] },
+          lane: { type: 'string' },
+        };
+        const { values, positionals } = parseArgs({ args: rest, options: opts, allowPositionals: true });
+        if (positionals.length !== 1) throw new InkanError('usage: inkan begin "<outcome>" [--accept <text>]...');
+        const result = api.begin({ root, outcome: positionals[0], ...values });
+        // Other open outcomes belong to whoever began them; they are named,
+        // never touched (decision 0013).
+        for (const other of result.openAlongside) {
+          process.stderr.write(`inkan: also open: ${other.id}  ${other.outcome}\n`);
+        }
+        console.log(result.id);
+        break;
+      }
+      case 'amend': {
+        const opts = {
+          reason: { type: 'string' },
+          accept: { type: 'string', multiple: true, default: [] },
+          withdraw: { type: 'string', multiple: true, default: [] },
+          decision: { type: 'string', multiple: true, default: [] },
+        };
+        const { values, positionals } = parseArgs({ args: rest, options: opts, allowPositionals: true });
+        const { id, addition } = splitAmendPositionals(positionals);
+        const result = api.amend({ root, id, addition, ...values });
+        console.log(result.contractHash);
+        break;
+      }
+      case 'end': {
+        const opts = {
+          met: { type: 'string', multiple: true, default: [] },
+          unmet: { type: 'string', multiple: true, default: [] },
+          status: { type: 'string', short: 's' },
+          note: { type: 'string' },
+        };
+        const { values, positionals } = parseArgs({ args: rest, options: opts, allowPositionals: true });
+        if (positionals.length > 1) {
+          throw new InkanError('usage: inkan end [<id>] [--met <n>]... [--unmet <n>]... [-s abandoned] --note <text>');
+        }
+        const result = api.end({ root, id: positionals[0], ...values });
+        console.log(`${result.id} ${result.status}`);
+        console.log(`Inkan-Outcome: ${result.id}`);
+        break;
+      }
+      case 'status': {
+        parseArgs({ args: rest });
+        printStatus(api.status({ root }).open);
+        break;
+      }
+      case 'log': {
+        const opts = {
+          n: { type: 'string', short: 'n' },
+          lane: { type: 'string' },
+          since: { type: 'string' },
+          grep: { type: 'string' },
+          status: { type: 'string' },
+          decision: { type: 'string' },
+        };
+        const { values, positionals } = parseArgs({ args: rest, options: opts, allowPositionals: true });
+        if (positionals.length > 1) {
+          throw new InkanError(
+            'usage: inkan log [-n <count>] [--since <date>] [--grep <regex>] [--status <s>] [--decision <id>] [--lane <tag>] [<id>]'
+          );
+        }
+        const n = values.n !== undefined ? Number(values.n) : undefined;
+        const result = api.log({ root, ...values, n, id: positionals[0] });
+        if (result.record) printRecord(result.record);
+        else for (const record of result.records) printLogLine(record);
+        break;
+      }
+      case 'check': {
+        const { positionals } = parseArgs({ args: rest, allowPositionals: true });
+        if (positionals.length > 1) throw new InkanError('usage: inkan check [<commit>]');
+        printCheck(api.check({ root, commit: positionals[0] }));
+        break;
+      }
+      case 'doctor': {
+        parseArgs({ args: rest });
+        printDoctor(api.doctor({ root }));
+        break;
+      }
+      case 'decision': {
+        runDecision(root, rest);
+        break;
+      }
+      case 'skill': {
+        const [sub, ...subRest] = rest;
+        if (sub !== 'install') throw new InkanError(`unknown skill subcommand "${sub}"`);
+        const { values } = parseArgs({
+          args: subRest,
+          options: { target: { type: 'string' }, claude: { type: 'boolean', default: false } },
+        });
+        console.log(api.skillInstall({ root, target: values.target, claude: values.claude }).dest);
+        break;
+      }
+      default:
+        fail(`unknown command "${command}"`);
+    }
+  } catch (err) {
+    fail(err instanceof InkanError ? err.message : (err.message ?? String(err)));
+  }
+}
+
+run(process.argv.slice(2));

package/src/decisions.js

@@ -0,0 +1,169 @@
+// MADR decision records under .inkan/decisions/NNNN-slug.md. `render` and
+// `parse` are exact inverses for a well-formed file: every section is raw
+// text, so reassembling them reproduces the original bytes. `appendHistory`
+// is the only writer once a file exists, touching only Status and History.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { decisionsDir } from './store.js';
+
+export const STATUSES = ['proposed', 'accepted', 'rejected', 'deferred', 'deprecated', 'superseded'];
+
+const HEADINGS = [
+  ['status', 'Status'],
+  ['context', 'Context and Problem Statement'],
+  ['drivers', 'Decision Drivers'],
+  ['options', 'Considered Options'],
+  ['outcome', 'Decision Outcome'],
+  ['consequences', 'Consequences'],
+  ['history', 'Decision History'],
+];
+
+function capitalizeStatus(status) {
+  return status.charAt(0).toUpperCase() + status.slice(1).toLowerCase();
+}
+
+/** Locate every `## Heading` line, in file order, with the offset where its body starts. */
+function findHeadings(content) {
+  const headingRe = /^## (.+?)\r?\n/gm;
+  const found = [];
+  let m;
+  while ((m = headingRe.exec(content)) !== null) {
+    found.push({ name: m[1], start: m.index, bodyStart: m.index + m[0].length });
+  }
+  return found;
+}
+
+/** Strip the blank-line padding a heading's body is wrapped in. */
+function unwrap(raw) {
+  let s = raw;
+  if (s.startsWith('\n')) s = s.slice(1);
+  if (s.endsWith('\n\n')) s = s.slice(0, -2);
+  else if (s.endsWith('\n')) s = s.slice(0, -1);
+  return s;
+}
+
+/** Parse one MADR record into `{ id, title, date, status, file, sections }`
+ * (`sections` holds each heading's raw text). Throws naming `file` when a
+ * heading is missing or the status token is unknown. */
+export function parse(content, file) {
+  const h1 = content.match(/^# (\d+)\.\s+(.+?)\r?\n/);
+  if (!h1) throw new Error(`${file}: missing "# N. Title" heading`);
+  const title = h1[2];
+  const id = h1[1].padStart(4, '0');
+  const dateMatch = content.match(/^Date:\s*(\S+)\s*$/m);
+  if (!dateMatch) throw new Error(`${file}: missing "Date: YYYY-MM-DD" line`);
+  const date = dateMatch[1];
+  const found = findHeadings(content);
+  const sections = {};
+  let status;
+  for (let i = 0; i < HEADINGS.length; i++) {
+    const [key, name] = HEADINGS[i];
+    const entry = found[i];
+    if (!entry || entry.name !== name) {
+      throw new Error(`${file}: missing required heading "## ${name}"`);
+    }
+    const bodyEnd = i + 1 < found.length ? found[i + 1].start : content.length;
+    const body = unwrap(content.slice(entry.bodyStart, bodyEnd));
+    if (key === 'status') {
+      status = body.trim().toLowerCase();
+      if (!STATUSES.includes(status)) throw new Error(`${file}: unknown status "${body.trim()}"`);
+    } else {
+      sections[key] = body;
+    }
+  }
+
+  return { id, title, date, status, file, sections };
+}
+
+function wrap(raw, last) {
+  if (raw === '') return '';
+  return last ? `\n${raw}\n` : `\n${raw}\n\n`;
+}
+
+/** `* item1\n* item2...`, or `raw` itself if it is already a string (as `parse` returns it). */
+function bullets(raw) {
+  return Array.isArray(raw) ? raw.map((item) => `* ${item}`).join('\n') : raw ?? '';
+}
+
+/** Render `{ id, title, date, status, sections }` back into MADR text. Each
+ * `sections` value is the raw per-heading text, or an array of bullet items. */
+export function render({ id, title, date, status, sections = {} }) {
+  let out = `# ${Number(id)}. ${title}\n\nDate: ${date}\n\n## Status\n${wrap(capitalizeStatus(status))}`;
+  for (const [key, name] of HEADINGS.slice(1)) {
+    out += `## ${name}\n${wrap(bullets(sections[key]), key === 'history')}`;
+  }
+  return out;
+}
+
+/** Every decision record under `.inkan/decisions/`, parsed and sorted by id. */
+export function list(root) {
+  const dir = decisionsDir(root);
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((name) => name.endsWith('.md'))
+    .map((name) => {
+      const file = path.join(dir, name);
+      return parse(fs.readFileSync(file, 'utf8'), file);
+    })
+    .sort((a, b) => (a.id < b.id ? -1 : 1));
+}
+
+/** One more than the highest decision id present, as a zero-padded string. */
+export function nextId(root) {
+  const max = list(root).reduce((acc, r) => Math.max(acc, Number(r.id)), 0);
+  return String(max + 1).padStart(4, '0');
+}
+
+/** Lowercase, non-alphanumeric runs collapsed to one hyphen, trimmed, capped at 80 chars. */
+export function slugify(title) {
+  const slug = title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slug.slice(0, 80).replace(/-+$/, '');
+}
+
+function atomicWrite(file, content) {
+  const dir = path.dirname(file);
+  const temp = path.join(dir, `.${path.basename(file)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+  const fd = fs.openSync(temp, 'w', 0o644);
+  try {
+    fs.writeFileSync(fd, content, 'utf8');
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(temp, file);
+}
+
+/** Append a dated history entry and set the new status; every other byte in
+ * the file is preserved. `outcomeId` names the heading when given, else the
+ * heading is a bare `### <ts>`. Returns the previous status. */
+export function appendHistory(file, { ts, outcomeId, to, reason }) {
+  const content = fs.readFileSync(file, 'utf8');
+  const before = parse(content, file); // validates shape and the new status token below
+  if (!STATUSES.includes(to)) throw new Error(`${file}: unknown status "${to}"`);
+  const found = findHeadings(content);
+  const statusEntry = found[0];
+  const historyEntry = found[found.length - 1];
+  const statusBodyEnd = found[1] ? found[1].start : content.length;
+  const statusRaw = content.slice(statusEntry.bodyStart, statusBodyEnd);
+  const token = statusRaw.match(/\S+/);
+  const newStatusRaw =
+    statusRaw.slice(0, token.index) + capitalizeStatus(to) + statusRaw.slice(token.index + token[0].length);
+  const historyRaw = content.slice(historyEntry.bodyStart);
+  const heading = outcomeId ? `### ${ts}, outcome ${outcomeId}` : `### ${ts}`;
+  const newHistoryRaw = `${historyRaw}\n${heading}\n\nStatus: ${before.status} -> ${to}\n\n${reason}\n`;
+
+  const newContent =
+    content.slice(0, statusEntry.bodyStart) +
+    newStatusRaw +
+    content.slice(statusBodyEnd, historyEntry.bodyStart) +
+    newHistoryRaw;
+
+  atomicWrite(file, newContent);
+  return before.status;
+}

package/src/fold.js

@@ -0,0 +1,173 @@
+// Event validation and the fold of one outcome's events into a record.
+// A file that violates the rules throws, naming the file, the line, and the
+// rule. Never repaired, here or anywhere else.
+
+import crypto from 'node:crypto';
+
+const EVENT_TYPES = new Set(['begin', 'amend', 'end']);
+const STATUSES = new Set(['completed', 'partial', 'abandoned']);
+
+function corrupt(where, message) {
+  return new Error(`${where}: ${message}`);
+}
+
+/** Deterministic JSON with sorted object keys, for hashing. */
+export function canonicalJSON(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJSON).join(',')}]`;
+  if (value !== null && typeof value === 'object') {
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJSON(value[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+/**
+ * sha256 over canonical JSON of { outcome, criteria with withdrawn flags,
+ * decisions, amendments as [reason, addition] }. The lane tag is excluded on
+ * purpose: it is a filing label, not part of what was promised.
+ */
+export function computeContractHash({ outcome, criteria, decisions, amendments }) {
+  const payload = {
+    outcome,
+    criteria: criteria.map((c) => ({ text: c.text, withdrawn: c.withdrawn })),
+    decisions,
+    amendments: amendments.map((a) => [a.reason, a.addition ?? null]),
+  };
+  return crypto.createHash('sha256').update(canonicalJSON(payload)).digest('hex');
+}
+
+function positiveInteger(value) {
+  const n = Number(value);
+  return Number.isInteger(n) && n >= 1 ? n : null;
+}
+
+/**
+ * Fold one outcome's events into a plain record. `file` is used only to
+ * label errors. Throws on any violation of the rules in decision 0005: `begin`
+ * first and unique; `amend`/`end` only while open; exactly one `end`;
+ * `completed` requires every live criterion met; `partial` requires every
+ * live criterion to have a disposition and at least one unmet; `abandoned`
+ * requires a note and needs no dispositions.
+ */
+export function fold(events, file) {
+  if (!Array.isArray(events) || events.length === 0) throw corrupt(file, 'no events');
+
+  const record = {
+    id: null,
+    outcome: null,
+    lane: null,
+    decisions: [],
+    criteria: [],
+    amendments: [],
+    sealedAt: null,
+    beginHead: null,
+    closed: false,
+  };
+  let began = false;
+  let closed = false;
+
+  events.forEach((event, i) => {
+    const where = `${file}:${i + 1}`;
+    if (event === null || typeof event !== 'object') throw corrupt(where, 'event is not an object');
+    if (event.v !== 1) throw corrupt(where, `unsupported event version ${event.v}`);
+    if (!EVENT_TYPES.has(event.type)) throw corrupt(where, `unknown event type "${event.type}"`);
+
+    if (event.type === 'begin') {
+      if (i !== 0 || began) throw corrupt(where, 'begin must be first and unique');
+      began = true;
+      if (!event.outcome || typeof event.outcome !== 'string') {
+        throw corrupt(where, 'begin missing an outcome');
+      }
+      record.id = event.id;
+      record.outcome = event.outcome;
+      record.lane = event.lane ?? null;
+      record.sealedAt = event.ts;
+      record.beginHead = event.head ?? null;
+      for (const text of event.criteria ?? []) {
+        record.criteria.push({ index: record.criteria.length + 1, text, withdrawn: false });
+      }
+      for (const d of event.decisions ?? []) {
+        if (!record.decisions.includes(d)) record.decisions.push(d);
+      }
+      return;
+    }
+
+    if (!began) throw corrupt(where, 'begin must be first and unique');
+    if (closed) throw corrupt(where, `${event.type} after outcome closed`);
+
+    if (event.type === 'amend') {
+      if (!event.reason || typeof event.reason !== 'string') throw corrupt(where, 'amend missing reason');
+      for (const raw of event.withdraw ?? []) {
+        const n = positiveInteger(raw);
+        const criterion = n === null ? null : record.criteria[n - 1];
+        if (!criterion || criterion.withdrawn) {
+          throw corrupt(where, `withdraw of unknown or already-withdrawn criterion ${raw}`);
+        }
+        criterion.withdrawn = true;
+      }
+      for (const text of event.criteria ?? []) {
+        record.criteria.push({ index: record.criteria.length + 1, text, withdrawn: false });
+      }
+      for (const d of event.decisions ?? []) {
+        if (!record.decisions.includes(d)) record.decisions.push(d);
+      }
+      record.amendments.push({
+        ts: event.ts,
+        reason: event.reason,
+        addition: event.addition ?? null,
+        head: event.head ?? null,
+      });
+      return;
+    }
+
+    // event.type === 'end'
+    if (!STATUSES.has(event.status)) throw corrupt(where, `unknown status "${event.status}"`);
+    if (!event.note || typeof event.note !== 'string') throw corrupt(where, 'end missing note');
+
+    const seen = new Set();
+    const dispositions = [];
+    for (const d of event.dispositions ?? []) {
+      const n = positiveInteger(d?.criterion);
+      const criterion = n === null ? null : record.criteria[n - 1];
+      if (!criterion) throw corrupt(where, `disposition for unknown criterion ${d?.criterion}`);
+      if (criterion.withdrawn) throw corrupt(where, `disposition for withdrawn criterion ${n}`);
+      if (seen.has(n)) throw corrupt(where, `duplicate disposition for criterion ${n}`);
+      seen.add(n);
+      dispositions.push({ criterion: n, met: Boolean(d.met), note: d.note ?? null });
+    }
+
+    if (event.status !== 'abandoned') {
+      for (const c of record.criteria) {
+        if (!c.withdrawn && !seen.has(c.index)) {
+          throw corrupt(where, `missing disposition for criterion ${c.index}`);
+        }
+      }
+      const anyUnmet = dispositions.some((d) => !d.met);
+      if (event.status === 'completed' && anyUnmet) {
+        throw corrupt(where, 'status "completed" but a live criterion is unmet');
+      }
+      if (event.status === 'partial' && !anyUnmet) {
+        throw corrupt(where, 'status "partial" but no live criterion is unmet');
+      }
+    }
+
+    const expectedHash = computeContractHash(record);
+    if (event.contractHash !== expectedHash) {
+      throw corrupt(where, 'contract hash does not match the folded record (tampering or corruption)');
+    }
+
+    record.closed = true;
+    record.closedAt = event.ts;
+    record.status = event.status;
+    record.dispositions = dispositions;
+    record.note = event.note;
+    record.contractHash = event.contractHash;
+    record.tree = event.tree ?? null;
+    record.head = event.head ?? null;
+    closed = true;
+  });
+
+  if (!began) throw corrupt(file, 'begin must be first and unique');
+  if (!record.closed) record.contractHash = computeContractHash(record);
+  return record;
+}