@portll/cobolwork 0.2.76 → 0.2.140

package/lib/embedded-sql.mjs

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// EXEC SQL as Db2 reads it, whichever language embeds it: a statement's words, host variables and
+// literals, and which host variables it reads and which it writes.
+// The words, host variables and literals of a statement. A host variable is :NAME, qualified as
+// :GROUP.NAME, and may carry an indicator variable, :NAME:IND or :NAME INDICATOR :IND.
+export function sqlTokens(sql) {
+  const toks = [];
+  const re = /'(?:[^']|'')*'|"(?:[^"]|"")*"|:\s*[A-Z0-9_$#@-]+(?:\.[A-Z0-9_$#@-]+)*|[A-Z0-9_$#@-]+|[(),=<>+*/;.]/gi;
+  for (const m of sql.matchAll(re)) {
+    const t = m[0];
+    if (t.startsWith(':')) toks.push({ host: t.slice(1).trim().toUpperCase() });
+    else if (/^['"]/.test(t)) toks.push({ lit: t });
+    else toks.push({ word: t.toUpperCase() });
+  }
+  return toks;
+}
+
+// Clauses that end an INTO list.
+const AFTER_INTO = new Set(['FROM', 'WHERE', 'GROUP', 'HAVING', 'ORDER', 'FETCH', 'FOR', 'WITH', 'OPTIMIZE', 'QUERYNO', 'SKIP', 'UNION', 'USING', 'VALUES']);
+
+// Which host variables a statement reads and which it writes, as Db2's SQL reference gives them. A
+// variable both read and written is in both lists. INTO a host variable writes it (INSERT INTO and
+// MERGE INTO name a table); so do SET's targets, GET DIAGNOSTICS' and ASSOCIATE LOCATORS' list. A
+// procedure's argument that is a lone variable may be IN, OUT or INOUT, which only the server knows.
+export function sqlRoles(toks) {
+  const sending = [];
+  const receiving = [];
+  const read = (h) => { if (!sending.includes(h)) sending.push(h); };
+  const write = (h) => { if (!receiving.includes(h)) receiving.push(h); };
+  const verb = toks.find((t) => t.word)?.word;
+  if (verb === 'CALL') return callRoles(toks, read, write), { sending, receiving };
+  // DESCRIBE and PREPARE read the SQLDA's SQLN and write the rest of it.
+  const intoBoth = verb === 'DESCRIBE' || verb === 'PREPARE';
+  let into = false;
+  let assigning = verb === 'SET';
+  let depth = 0;
+  for (let i = 0; i < toks.length; i++) {
+    const t = toks[i];
+    const next = toks[i + 1];
+    if (t.word === '(') depth++;
+    else if (t.word === ')') depth--;
+    else if (verb === 'SET' && t.word === '=' && depth === 0) assigning = false;
+    else if (verb === 'SET' && t.word === ',' && depth === 0) assigning = true;
+    if (t.word === 'INTO' && next && (next.host || next.word === 'DESCRIPTOR')) { into = true; continue; }
+    if (into && t.word && AFTER_INTO.has(t.word)) into = false;
+    if (t.word === 'DESCRIPTOR' && next?.host) {
+      // FETCH ... INTO DESCRIPTOR and USING DESCRIPTOR are synonyms: the program fills the SQLDA and Db2 writes where it points.
+      if (verb === 'FETCH' || intoBoth) { read(next.host); write(next.host); } else read(next.host);
+      i++;
+      continue;
+    }
+    if (!t.host) continue;
+    const written = into || assigning
+      || (verb === 'GET' && next?.word === '=')
+      || (verb === 'ASSOCIATE' && !toks.slice(0, i).some((x) => x.word === 'WITH'));
+    if (!written || (into && intoBoth)) read(t.host);
+    if (written) write(t.host);
+  }
+  return { sending, receiving };
+}
+
+// CALL :name reads the name. Each argument that is a lone variable, with or without its indicator,
+// is read and may be written; any other argument is an expression, IN only.
+function callRoles(toks, read, write) {
+  let depth = 0;
+  let arg = [];
+  const close = () => {
+    const hosts = arg.filter((t) => t.host);
+    const lone = hosts.length && arg.every((t) => t.host || t.word === 'INDICATOR');
+    for (const h of hosts) { read(h.host); if (lone) write(h.host); }
+    arg = [];
+  };
+  for (let i = 1; i < toks.length; i++) {
+    const t = toks[i];
+    if (t.word === 'DESCRIPTOR' && toks[i + 1]?.host) { read(toks[i + 1].host); write(toks[i + 1].host); i++; continue; }
+    if (t.word === '(') { if (depth++ > 0) arg.push(t); continue; }
+    if (t.word === ')') { if (--depth > 0) arg.push(t); else close(); continue; }
+    if (depth === 0) { if (t.host) read(t.host); continue; }
+    if (depth === 1 && t.word === ',') { close(); continue; }
+    arg.push(t);
+  }
+}
+
+export function hostVariableRoles(sql) {
+  return sqlRoles(sqlTokens(sql));
+}
+
+// The host variables in a parsed EXEC SQL block: a colon, then a name qualified by joined periods as
+// :GROUP.FIELD. Each carries its path, the token naming the item, where it stands, and whether the
+// statement writes it by sqlRoles.
+export function hostVariablesIn(toks) {
+  const found = [];
+  const sql = [];
+  for (let k = 0; k < toks.length; k++) {
+    const t = toks[k];
+    if (t.t === 'op' && t.v === ':' && toks[k + 1] && toks[k + 1].t === 'word') {
+      const path = [toks[k + 1]];
+      let j = k + 2;
+      for (; j + 1 < toks.length && toks[j].t === 'period' && toks[j].joined && toks[j + 1].t === 'word'; j += 2) path.push(toks[j + 1]);
+      const host = path.map((p) => p.u).join('.');
+      found.push({ path, tok: path[path.length - 1], at: k + 1, host });
+      sql.push({ host });
+      k = j - 1;
+      continue;
+    }
+    sql.push(t.t === 'lit' ? { lit: t.v } : { word: String(t.u ?? t.v).toUpperCase() });
+  }
+  const { receiving } = sqlRoles(sql);
+  return found.map((h) => ({ ...h, written: receiving.includes(h.host) }));
+}

package/lib/enterprise-options.mjs

@@ -0,0 +1,255 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Enterprise COBOL's compiler options: every spelling each one answers to, and where it may be given.
+//
+// GENERATED - do not edit by hand. Run `node diag/generate-options.mjs` to rebuild it from
+// provenance/enterprise-options.json, which names the IBM table and page behind each row.
+
+// Each spelling's option, and whether the spelling turns the option off.
+export const OPTION_SPELLINGS = {
+  "APOST": ["APOST/QUOTE", false],
+  "QUOTE": ["APOST/QUOTE", false],
+  "Q": ["APOST/QUOTE", false],
+  "ARITH": ["ARITH", false],
+  "AR": ["ARITH", false],
+  "CICS": ["CICS", false],
+  "NOCICS": ["CICS", true],
+  "CODEPAGE": ["CODEPAGE", false],
+  "CP": ["CODEPAGE", false],
+  "CURRENCY": ["CURRENCY", false],
+  "NOCURRENCY": ["CURRENCY", true],
+  "CURR": ["CURRENCY", false],
+  "NOCURR": ["CURRENCY", true],
+  "DBCS": ["DBCS", false],
+  "NODBCS": ["DBCS", true],
+  "NSYMBOL": ["NSYMBOL", false],
+  "NS": ["NSYMBOL", false],
+  "NUMBER": ["NUMBER", false],
+  "NONUMBER": ["NUMBER", true],
+  "NUM": ["NUMBER", false],
+  "NONUM": ["NUMBER", true],
+  "QUALIFY": ["QUALIFY", false],
+  "QUA": ["QUALIFY", false],
+  "SEQUENCE": ["SEQUENCE", false],
+  "NOSEQUENCE": ["SEQUENCE", true],
+  "SEQ": ["SEQUENCE", false],
+  "NOSEQ": ["SEQUENCE", true],
+  "SQL": ["SQL", false],
+  "NOSQL": ["SQL", true],
+  "SQLCCSID": ["SQLCCSID", false],
+  "NOSQLCCSID": ["SQLCCSID", true],
+  "SQLC": ["SQLCCSID", false],
+  "NOSQLC": ["SQLCCSID", true],
+  "SQLIMS": ["SQLIMS", false],
+  "NOSQLIMS": ["SQLIMS", true],
+  "SUPPRESS": ["SUPPRESS", false],
+  "NOSUPPRESS": ["SUPPRESS", true],
+  "SUPP": ["SUPPRESS", false],
+  "NOSUPP": ["SUPPRESS", true],
+  "WORD": ["WORD", false],
+  "NOWORD": ["WORD", true],
+  "WD": ["WORD", false],
+  "NOWD": ["WORD", true],
+  "XMLPARSE": ["XMLPARSE", false],
+  "XP": ["XMLPARSE", false],
+  "INTDATE": ["INTDATE", false],
+  "CONDCOMP": ["CONDCOMP", false],
+  "CC": ["CONDCOMP", false],
+  "LANGUAGE": ["LANGUAGE", false],
+  "LANG": ["LANGUAGE", false],
+  "LINECOUNT": ["LINECOUNT", false],
+  "LC": ["LINECOUNT", false],
+  "LIST": ["LIST", false],
+  "NOLIST": ["LIST", true],
+  "MAP": ["MAP", false],
+  "NOMAP": ["MAP", true],
+  "OFFSET": ["OFFSET", false],
+  "NOOFFSET": ["OFFSET", true],
+  "OFF": ["OFFSET", false],
+  "NOOFF": ["OFFSET", true],
+  "SOURCE": ["SOURCE", false],
+  "NOSOURCE": ["SOURCE", true],
+  "S": ["SOURCE", false],
+  "NOS": ["SOURCE", true],
+  "SPACE": ["SPACE", false],
+  "TERMINAL": ["TERMINAL", false],
+  "NOTERMINAL": ["TERMINAL", true],
+  "TERM": ["TERMINAL", false],
+  "NOTERM": ["TERMINAL", true],
+  "VBREF": ["VBREF", false],
+  "NOVBREF": ["VBREF", true],
+  "XREF": ["XREF", false],
+  "NOXREF": ["XREF", true],
+  "X": ["XREF", false],
+  "NOX": ["XREF", true],
+  "COMPILE": ["COMPILE", false],
+  "NOCOMPILE": ["COMPILE", true],
+  "C": ["COMPILE", false],
+  "NOC": ["COMPILE", true],
+  "COPYRIGHT": ["COPYRIGHT", false],
+  "NOCOPYRIGHT": ["COPYRIGHT", true],
+  "CPYR": ["COPYRIGHT", false],
+  "NOCPYR": ["COPYRIGHT", true],
+  "DECK": ["DECK", false],
+  "NODECK": ["DECK", true],
+  "D": ["DECK", false],
+  "NOD": ["DECK", true],
+  "NAME": ["NAME", false],
+  "NONAME": ["NAME", true],
+  "OBJECT": ["OBJECT", false],
+  "NOOBJECT": ["OBJECT", true],
+  "OBJ": ["OBJECT", false],
+  "NOOBJ": ["OBJECT", true],
+  "PGMNAME": ["PGMNAME", false],
+  "PGMN": ["PGMNAME", false],
+  "SERVICE": ["SERVICE", false],
+  "NOSERVICE": ["SERVICE", true],
+  "SERV": ["SERVICE", false],
+  "NOSERV": ["SERVICE", true],
+  "ADV": ["ADV", false],
+  "NOADV": ["ADV", true],
+  "AFP": ["AFP", false],
+  "ARCH": ["ARCH", false],
+  "AWO": ["AWO", false],
+  "NOAWO": ["AWO", true],
+  "BLOCK0": ["BLOCK0", false],
+  "NOBLOCK0": ["BLOCK0", true],
+  "DEFINE": ["DEFINE", false],
+  "NODEFINE": ["DEFINE", true],
+  "DEF": ["DEFINE", false],
+  "NODEF": ["DEFINE", true],
+  "DISPSIGN": ["DISPSIGN", false],
+  "DS": ["DISPSIGN", false],
+  "DLL": ["DLL", false],
+  "NODLL": ["DLL", true],
+  "EXPORTALL": ["EXPORTALL", false],
+  "NOEXPORTALL": ["EXPORTALL", true],
+  "EXP": ["EXPORTALL", false],
+  "NOEXP": ["EXPORTALL", true],
+  "FASTSRT": ["FASTSRT", false],
+  "NOFASTSRT": ["FASTSRT", true],
+  "FSRT": ["FASTSRT", false],
+  "NOFSRT": ["FASTSRT", true],
+  "HGPR": ["HGPR", false],
+  "INITIAL": ["INITIAL", false],
+  "NOINITIAL": ["INITIAL", true],
+  "INLINE": ["INLINE", false],
+  "NOINLINE": ["INLINE", true],
+  "INL": ["INLINE", false],
+  "NOINL": ["INLINE", true],
+  "INVDATA": ["INVDATA", false],
+  "NOINVDATA": ["INVDATA", true],
+  "NOINV": ["INVDATA", true],
+  "INVD": ["INVDATA", false],
+  "NOINVD": ["INVDATA", true],
+  "JAVAIOP": ["JAVAIOP", false],
+  "NOJAVAIOP": ["JAVAIOP", true],
+  "JIOP": ["JAVAIOP", false],
+  "NOJIOP": ["JAVAIOP", true],
+  "LP": ["LP", false],
+  "MAXPCF": ["MAXPCF", false],
+  "NUMCHECK": ["NUMCHECK", false],
+  "NONUMCHECK": ["NUMCHECK", true],
+  "NC": ["NUMCHECK", false],
+  "NONC": ["NUMCHECK", true],
+  "NUMPROC": ["NUMPROC", false],
+  "OPTIMIZE": ["OPTIMIZE", false],
+  "NOOPTIMIZE": ["OPTIMIZE", true],
+  "OPT": ["OPTIMIZE", false],
+  "OUTDD": ["OUTDD", false],
+  "OUT": ["OUTDD", false],
+  "PARMCHECK": ["PARMCHECK", false],
+  "NOPARMCHECK": ["PARMCHECK", true],
+  "PC": ["PARMCHECK", false],
+  "NOPC": ["PARMCHECK", true],
+  "TRUNC": ["TRUNC", false],
+  "TUNE": ["TUNE", false],
+  "VLR": ["VLR", false],
+  "ZONECHECK": ["ZONECHECK", false],
+  "NOZONECHECK": ["ZONECHECK", true],
+  "NOZC": ["ZONECHECK", true],
+  "ZC": ["ZONECHECK", false],
+  "ZONEDATA": ["ZONEDATA", false],
+  "ZD": ["ZONEDATA", false],
+  "ZWB": ["ZWB", false],
+  "NOZWB": ["ZWB", true],
+  "BUFSIZE": ["BUFSIZE", false],
+  "BUF": ["BUFSIZE", false],
+  "DATA": ["DATA", false],
+  "DYNAM": ["DYNAM", false],
+  "NODYNAM": ["DYNAM", true],
+  "DYN": ["DYNAM", false],
+  "NODYN": ["DYNAM", true],
+  "RENT": ["RENT", false],
+  "NORENT": ["RENT", true],
+  "RMODE": ["RMODE", false],
+  "STGOPT": ["STGOPT", false],
+  "NOSTGOPT": ["STGOPT", true],
+  "SO": ["STGOPT", false],
+  "NOSO": ["STGOPT", true],
+  "DIAGTRUNC": ["DIAGTRUNC", false],
+  "NODIAGTRUNC": ["DIAGTRUNC", true],
+  "DTR": ["DIAGTRUNC", false],
+  "NODTR": ["DIAGTRUNC", true],
+  "DUMP": ["DUMP", false],
+  "NODUMP": ["DUMP", true],
+  "DU": ["DUMP", false],
+  "NODU": ["DUMP", true],
+  "FLAG": ["FLAG", false],
+  "NOFLAG": ["FLAG", true],
+  "F": ["FLAG", false],
+  "NOF": ["FLAG", true],
+  "FLAGSTD": ["FLAGSTD", false],
+  "NOFLAGSTD": ["FLAGSTD", true],
+  "INITCHECK": ["INITCHECK", false],
+  "NOINITCHECK": ["INITCHECK", true],
+  "IC": ["INITCHECK", false],
+  "NOIC": ["INITCHECK", true],
+  "RULES": ["RULES", false],
+  "NORULES": ["RULES", true],
+  "SSRANGE": ["SSRANGE", false],
+  "NOSSRANGE": ["SSRANGE", true],
+  "SSR": ["SSRANGE", false],
+  "NOSSR": ["SSRANGE", true],
+  "TEST": ["TEST", false],
+  "NOTEST": ["TEST", true],
+  "ADATA": ["ADATA", false],
+  "NOADATA": ["ADATA", true],
+  "COPYLOC": ["COPYLOC", false],
+  "NOCOPYLOC": ["COPYLOC", true],
+  "CPLC": ["COPYLOC", false],
+  "NOCPLC": ["COPYLOC", true],
+  "EXIT": ["EXIT", false],
+  "NOEXIT": ["EXIT", true],
+  "NOEX": ["EXIT", true],
+  "EX": ["EXIT", false],
+  "MDECK": ["MDECK", false],
+  "NOMDECK": ["MDECK", true],
+  "NOMD": ["MDECK", true],
+  "MD": ["MDECK", false],
+  "OPTFILE": ["OPTFILE", false],
+  "SMARTBIN": ["SMARTBIN", false],
+  "NOSMARTBIN": ["SMARTBIN", true],
+  "THREAD": ["THREAD", false],
+  "NOTHREAD": ["THREAD", true],
+  "VSAMOPENFS": ["VSAMOPENFS", false],
+  "VS": ["VSAMOPENFS", false],
+};
+
+// The options with a rule on where they may be given: not in a CBL or PROCESS statement (process),
+// in one only before a batch compilation's first program (firstProgramOnly), or not as an
+// installation default (installationDefault). Every other option may be given anywhere.
+export const OPTION_PLACEMENT = {
+  "CICS": { firstProgramOnly: true },
+  "SQL": { firstProgramOnly: true },
+  "SQLIMS": { firstProgramOnly: true },
+  "DEFINE": { firstProgramOnly: true },
+  "JAVAIOP": { firstProgramOnly: true },
+  "LP": { firstProgramOnly: true },
+  "OUTDD": { firstProgramOnly: true },
+  "BUFSIZE": { firstProgramOnly: true },
+  "ADATA": { process: false },
+  "COPYLOC": { firstProgramOnly: true },
+  "EXIT": { process: false },
+  "MDECK": { process: false },
+  "OPTFILE": { installationDefault: false },
+};

package/lib/equivalence.mjs

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// The build's change-assurance check (docs/spec/evidence.md §12): an ironwork equivalence
+// statement for each program the change edits, matched to the base and head bytes by digest,
+// verdict equivalent, coverage measured, and signed by an allowed signer where signers are named.
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { directoryTree } from './kernel/source-tree.mjs';
+import { parseSource } from './parser.mjs';
+import { isProgram, readSource, relPath } from './sources.mjs';
+import { NAMESPACE, PAYLOAD_TYPE, cleanGitEnv, pae } from './evidence/seal.mjs';
+import { verifySshsig } from './evidence/sshsig.mjs';
+
+export const EQUIVALENCE_PREDICATE = 'https://github.com/Portll/ironwork/blob/main/docs/evidence.md#equivalence-v1';
+const PASSING = new Set(['equivalent', 'equivalent-as-declared']);
+const sha256 = (b) => createHash('sha256').update(b).digest('hex');
+
+// { statement, signed, signer, reason } for one file holding a statement or a DSSE envelope of one.
+export function readStatement(path, allowed = null) {
+  let doc;
+  try { doc = JSON.parse(readFileSync(path, 'utf8')); } catch (e) { return { statement: null, reason: `${basename(path)} is not JSON (${e.message})` }; }
+  if (doc && doc.payloadType === PAYLOAD_TYPE && typeof doc.payload === 'string') {
+    const payload = Buffer.from(doc.payload, 'base64');
+    let statement;
+    try { statement = JSON.parse(payload.toString('utf8')); } catch { return { statement: null, reason: `${basename(path)} carries no statement` }; }
+    const checks = (doc.signatures || []).map((s) => (allowed ? verifySshsig({ blob: Buffer.from(String(s.sig), 'base64'), message: pae(PAYLOAD_TYPE, payload), namespace: NAMESPACE, allowed }) : { valid: null }));
+    const good = checks.find((c) => c.valid === true);
+    return { statement, signed: Boolean(good), signer: good ? good.principals : null, reason: good ? null : allowed ? 'no signature from an allowed signer' : 'no allowed signers were given' };
+  }
+  return { statement: doc, signed: false, signer: null, reason: 'the statement is not signed' };
+}
+
+const subjectDigest = (st, side) => {
+  const s = (st.subject || []).find((x) => String(x.name || '').startsWith(`${side}:`));
+  return s && s.digest ? s.digest.sha256 : null;
+};
+
+// The copybooks a program resolves, by path relative to its tree and digest.
+function closure(root, file, idx, systemDirs) {
+  let res;
+  try {
+    res = parseSource(readSource(file).text, file, { format: 'auto', includeDirs: idx.copyDirs, fileIndex: idx.index, mainDir: dirname(file), copyFormat: 'auto', systemDirs });
+  } catch { return null; }
+  const out = new Map();
+  for (const c of res.copies) {
+    if (c.status !== 'resolved' || !c.path) continue;
+    try { out.set(relPath(root, c.path), sha256(readFileSync(c.path))); } catch { out.set(relPath(root, c.path), null); }
+  }
+  return out;
+}
+
+// Programs the change edits or adds, or whose copybooks it edits: [{ path, base, head, via }] with
+// each side's source digest and the copybooks that changed under an unchanged program.
+export function changedPrograms(baseDir, headDir, allow = null, systemDirs = []) {
+  const out = [];
+  const headTree = directoryTree(headDir);
+  const baseIdx = directoryTree(baseDir).index;
+  for (const head of headTree.list().filter((p) => isProgram(p) && (!allow || allow.has(p))).sort()) {
+    const path = relPath(headDir, head);
+    const h = sha256(readFileSync(head));
+    const baseFile = join(baseDir, path);
+    const b = existsSync(baseFile) ? sha256(readFileSync(baseFile)) : null;
+    if (b !== h) { out.push({ path, base: b, head: h }); continue; }
+    const after = closure(headDir, head, headTree.index, systemDirs);
+    const before = closure(baseDir, baseFile, baseIdx, systemDirs);
+    if (!after || !before) continue;
+    const via = [...new Set([...after.keys(), ...before.keys()])].filter((k) => after.get(k) !== before.get(k)).sort();
+    if (via.length) out.push({ path, base: b, head: h, via, viaDigests: via.map((k) => after.get(k)).filter(Boolean) });
+  }
+  return out;
+}
+
+// Whether a commit in base..head reads as authored by a tool, from its identities and trailers.
+const TOOL = /\[bot\]|(^|[^a-z])bot@|copilot|claude|anthropic|openai|codex|devin|cursor|gemini|aider|sweep-ai|dependabot|renovate/i;
+export function machineAuthored(repo, base, head, env = process.env) {
+  const r = spawnSync('git', ['-C', repo, 'rev-list', '--format=%x1e%an%x00%ae%x00%cn%x00%ce%x00%B', `${base}..${head}`], { encoding: 'utf8', timeout: 30000, maxBuffer: 16 << 20, env: cleanGitEnv(env) });
+  if (r.status !== 0) return { known: false, commits: [] };
+  const commits = [];
+  for (const chunk of r.stdout.split('\x1e').slice(1)) {
+    const [an, ae, cn, ce, body = ''] = chunk.split('\x00');
+    const trailers = body.split('\n').filter((l) => /^(co-authored-by|generated-by|assisted-by):/i.test(l.trim()));
+    const signals = [an, ae, cn, ce, ...trailers, ...(/generated with/i.test(body) ? ['generated with'] : [])].filter((x) => x && TOOL.test(x));
+    if (signals.length) commits.push({ signals: [...new Set(signals.map((s) => s.trim().slice(0, 80)))] });
+  }
+  return { known: true, commits };
+}
+
+// The equivalence check for one build: which changed programs a statement covers, and whether the
+// policy's requirement is met. `required` is true, false, or null when machine authorship is unknown.
+export function checkEquivalence({ baseDir, headDir, allow, files = [], allowed = null, mode = 'never', repo = null, base = null, head = null, systemDirs = [], env = process.env }) {
+  const changed = changedPrograms(baseDir, headDir, allow, systemDirs);
+  const statements = files.map((f) => ({ file: basename(f), ...readStatement(f, allowed) }));
+  const problems = [];
+  for (const s of statements) {
+    if (!s.statement) { problems.push(s.reason); continue; }
+    if (s.statement.predicateType !== EQUIVALENCE_PREDICATE) { problems.push(`${s.file} is not an ironwork equivalence statement`); continue; }
+    const h = subjectDigest(s.statement, 'head');
+    const b = subjectDigest(s.statement, 'base');
+    if (!changed.some((c) => c.head === h && (c.base === b || (c.base === null && b === null)))) {
+      problems.push(`${s.file} names head ${h ? h.slice(0, 12) : 'nothing'} and base ${b ? b.slice(0, 12) : 'nothing'}, which match no program this change edits`);
+    }
+  }
+  const programs = changed.map((c) => {
+    const s = statements.find((x) => x.statement && subjectDigest(x.statement, 'head') === c.head && subjectDigest(x.statement, 'base') === c.base);
+    const via = c.via ? { via: c.via } : {};
+    if (!s) return { path: c.path, ...via, statement: null, ok: false, because: c.via ? `no equivalence statement names this program, whose copybook${c.via.length > 1 ? 's' : ''} ${c.via.join(', ')} the change edits` : 'no equivalence statement names this change' };
+    const p = s.statement.predicate || {};
+    const verdict = p.verdict || null;
+    const covered = p.coverage !== null && p.coverage !== undefined;
+    const ranOn = new Set(((p.closure && p.closure.head) || []).map((x) => x.sha256));
+    const missing = (c.viaDigests || []).filter((d) => !ranOn.has(d));
+    const because = !PASSING.has(verdict) ? `the statement's verdict is ${verdict}${Array.isArray(p.inconclusive) && p.inconclusive.length ? ` (${p.inconclusive.join('; ')})` : ''}`
+      : missing.length ? `the statement does not show the head run read the edited copybook${c.via.length > 1 ? 's' : ''} ${c.via.join(', ')}`
+      : !covered ? 'the statement measured no coverage of the changed paragraphs, so it is inconclusive'
+        : allowed && !s.signed ? `the statement is ${s.reason}`
+          : null;
+    const unreached = covered && Array.isArray(p.coverage.unreached) ? p.coverage.unreached : [];
+    return { path: c.path, ...via, statement: s.file, verdict, signed: s.signed, signer: s.signer, coverage: covered, ...(unreached.length ? { unreached } : {}), ok: because === null && !unreached.length, ...(because || unreached.length ? { because: because || `the inputs never reached ${unreached.join(', ')}` } : {}) };
+  });
+  const authorship = mode === 'machineAuthored' && repo && base ? machineAuthored(repo, base, head || 'HEAD', env) : null;
+  const required = mode === 'always' ? true : mode === 'machineAuthored' ? (authorship && authorship.known ? authorship.commits.length > 0 : null) : false;
+  return { mode, required, ...(authorship ? { machineAuthored: authorship } : {}), programs, problems };
+}

package/lib/evidence/cli.mjs

@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// `cobolwork evidence verify|seal|anchor`: the command half of docs/spec/evidence.md §7-9. Returns
+// the exit status; writes one JSON document through `write`.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { anchorGit, envelopeFor, seal, sealFiles, timeStampRequest } from './seal.mjs';
+import { parseAllowedSigners } from './sshsig.mjs';
+import { EvidenceRefusal, evidenceDirFrom } from './store.mjs';
+import { verifyEvidence } from './verify.mjs';
+
+const VERBS = ['verify', 'seal', 'anchor', 'sign'];
+
+function anchorNewest(dir, opts) {
+  const seals = sealFiles(dir);
+  if (!seals.length) throw new EvidenceRefusal('there is no seal to anchor; run evidence seal first');
+  const newest = seals[seals.length - 1];
+  const text = readFileSync(newest.path, 'utf8');
+  const payload = JSON.parse(Buffer.from(JSON.parse(text).payload, 'base64').toString('utf8'));
+  const chain = /^ledger:([0-9a-f]{32})$/.exec(payload.subject[0].name)[1];
+  const out = { seal: newest.name };
+  if (opts.anchorGit) out.git = anchorGit(newest.path, { repo: resolve(opts.anchorGit), chain, seq: newest.seq, push: opts.push === true });
+  if (opts.tsq) {
+    const req = timeStampRequest(Buffer.from(text, 'utf8'));
+    writeFileSync(resolve(opts.tsq), req.der);
+    out.tsq = { path: resolve(opts.tsq), sha256: req.digest, nonce: req.nonce };
+  }
+  return out;
+}
+
+export function evidenceCommand(verb, opts, { toolVersion, write, env = process.env }) {
+  if (!VERBS.includes(verb)) throw new EvidenceRefusal(`evidence takes ${VERBS.join(', ')}; got ${verb || 'nothing'}`);
+  if (verb === 'sign') {
+    const file = opts._[2];
+    if (!file) throw new EvidenceRefusal('evidence sign needs the statement file to sign');
+    const payload = readFileSync(resolve(file));
+    JSON.parse(payload.toString('utf8'));
+    const env2 = envelopeFor(payload, { sshKey: opts.sshKey ? resolve(opts.sshKey) : null, signer: opts.signer ? resolve(opts.signer) : null, expectKeyid: opts.expectKey || null, env });
+    const text = `${JSON.stringify(env2)}\n`;
+    if (opts.out) writeFileSync(resolve(opts.out), text); else write(text);
+    return 0;
+  }
+  const dir = evidenceDirFrom(opts, env);
+  if (!dir) throw new EvidenceRefusal('evidence needs --evidence <dir> or COBOLWORK_EVIDENCE');
+  const emit = (doc) => write(`${JSON.stringify({ tool: 'cobolwork-evidence', verb, ...doc }, null, opts.quiet ? 0 : 1)}\n`);
+
+  if (verb === 'verify') {
+    const allowed = opts.allowedSigners ? parseAllowedSigners(readFileSync(resolve(opts.allowedSigners), 'utf8')) : null;
+    const max = opts.maxUnsealed === undefined ? 0 : Number(opts.maxUnsealed);
+    if (!Number.isSafeInteger(max) || max < 0) throw new EvidenceRefusal(`--max-unsealed takes a whole number; got ${opts.maxUnsealed}`);
+    const verdict = verifyEvidence(dir, { allowed, anchorGit: opts.anchorGit ? resolve(opts.anchorGit) : null, anchorRef: opts.ref || null, maxUnsealed: max, env });
+    emit(verdict);
+    return verdict.exit;
+  }
+  if (verb === 'seal') {
+    if (opts.sshKey && opts.signer) throw new EvidenceRefusal('one signer per seal: --ssh-key or --signer');
+    const s = seal(dir, { sshKey: opts.sshKey ? resolve(opts.sshKey) : null, signer: opts.signer ? resolve(opts.signer) : null, expectKeyid: opts.expectKey || null, toolVersion, env });
+    const out = { seq: s.seq, path: s.path, sha256: s.digest, signed: s.signed, ledgerLength: s.statement.predicate.ledgerLength, tip: s.statement.subject[0].digest.sha256 };
+    if (opts.anchorGit || opts.tsq) out.anchor = anchorNewest(dir, opts);
+    emit(out);
+    return 0;
+  }
+  if (!opts.anchorGit && !opts.tsq) throw new EvidenceRefusal('anchor needs --anchor-git <repo> or --tsq <file>');
+  emit(anchorNewest(dir, opts));
+  return 0;
+}

package/lib/evidence/journal.mjs

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// A run journal (runs/<runId>.jsonl) and the ledger (ledger.jsonl) that chains the runs' tips.
+// docs/spec/evidence.md §5-6.
+import { randomBytes } from 'node:crypto';
+import { closeSync } from 'node:fs';
+import { join } from 'node:path';
+import { makeRecord, newChain, recordHash } from './record.mjs';
+import { EvidenceRefusal, createExclusive, lastLine, openAppend, prepareDir, syncClose, takeLock, writeAll } from './store.mjs';
+
+export const LEDGER = 'ledger.jsonl';
+export const LOCK = 'ledger.lock';
+
+const isoNow = () => new Date().toISOString();
+const runStamp = (iso) => iso.replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z');
+
+// The record the next ledger line extends: one whose chain, seq and hash hold.
+function ledgerTip(line, path) {
+  let r = null;
+  try { r = JSON.parse(line); } catch { /* refused below */ }
+  const ok = r && typeof r === 'object' && /^[0-9a-f]{32}$/.test(r.chain) && Number.isInteger(r.seq) && r.seq >= 0 && typeof r.hash === 'string' && recordHash(r) === r.hash;
+  if (!ok) throw new EvidenceRefusal(`${path} ends in a line that is no ledger record; verify it before anything is appended`);
+  return r;
+}
+
+// Appends to the ledger; the caller holds the lock. A torn ledger is refused rather than extended.
+function appendLedger(dir, entries, now) {
+  const path = join(dir, LEDGER);
+  const { line, torn } = lastLine(path);
+  if (torn) throw new EvidenceRefusal(`${path} ends in a partial line; verify it before anything is appended`);
+  let prev = line ? ledgerTip(line, path) : null;
+  const fd = openAppend(path);
+  try {
+    const out = [];
+    if (!prev) entries = [{ kind: 'genesis', fields: { createdAt: now() } }, ...entries];
+    const chain = prev ? prev.chain : newChain();
+    for (const { kind, fields } of entries) {
+      const { record, line: text } = makeRecord({ chain, prev, kind, fields, at: now() });
+      writeAll(fd, text);
+      out.push(record);
+      prev = record;
+    }
+    return out;
+  } finally { syncClose(fd); }
+}
+
+// `roots` is what the journal records; `readRoots` are the trees the run reads, which the evidence
+// directory must not be inside.
+export function openJournal(dir, { command, argv = [], roots = [], readRoots = [], toolVersion, toolRevision = null, now = isoNow, lock = {} }) {
+  const real = prepareDir(dir, readRoots);
+  const started = Date.now();
+  const openedAt = now();
+  const id = `${runStamp(openedAt)}-${randomBytes(8).toString('hex')}`;
+  const path = join(real, 'runs', `${id}.jsonl`);
+  const fd = createExclusive(path);
+  const chain = newChain();
+  const counts = {};
+  let prev = null;
+  let closed = false;
+
+  const append = (kind, fields) => {
+    if (closed) throw new EvidenceRefusal(`run ${id} is closed`);
+    const { record, line } = makeRecord({ chain, prev, kind, fields, at: prev ? now() : openedAt });
+    writeAll(fd, line);
+    prev = record;
+    counts[kind] = (counts[kind] || 0) + 1;
+    return record;
+  };
+
+  append('open', { tool: 'cobolwork', toolVersion, toolRevision, command, argv, roots, node: process.version, platform: process.platform });
+
+  // Writes close, then the ledger record carrying this journal's tip. Returns the ledger outcome.
+  const close = ({ exit }) => {
+    const held = takeLock(join(real, LOCK), lock);
+    const ledger = held ? 'recorded' : 'unrecorded';
+    try {
+      append('close', { exit, counts: { ...counts }, durationMs: Math.max(0, Date.now() - started), ledger });
+      closed = true;
+      syncClose(fd);
+      if (!held) return { ledger, reason: 'the ledger lock could not be had' };
+      const entries = [];
+      if (held.broken) entries.push({ kind: 'lock-broken', fields: held.broken });
+      entries.push({ kind: 'run', fields: { run: id, runChain: chain, runLength: prev.seq + 1, runTip: prev.hash } });
+      appendLedger(real, entries, now);
+      return { ledger };
+    } catch (e) {
+      if (!closed) { closed = true; try { closeSync(fd); } catch { /* already closed */ } }
+      return { ledger: 'unrecorded', reason: e.message };
+    } finally {
+      if (held) held.release();
+    }
+  };
+
+  return { id, path, dir: real, chain, append, close, get tip() { return prev; } };
+}