@portll/cobolwork 0.2.75 → 0.2.117

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,85 @@
+// 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 } 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');
+
+// 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 ? JSON.parse(line) : 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; } };
+}

package/lib/evidence/record.mjs

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// One evidence record: its canonical JSON, its SHA-256 under a domain tag, and the fields each kind
+// may carry (docs/spec/evidence.md §4-6). The writer refuses anything outside these tables, so a
+// new field is a change to the spec rather than a silent addition.
+import { createHash, randomBytes } from 'node:crypto';
+
+export const DOMAIN = 'cobolwork-evidence/v1\n';
+export const ZERO = '0'.repeat(64);
+export const VERSION = 1;
+
+const HEX64 = /^[0-9a-f]{64}$/;
+const HEX32 = /^[0-9a-f]{32}$/;
+const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?Z$/;
+const COMMON = ['v', 'chain', 'seq', 'at', 'kind', 'prev', 'hash'];
+
+const str = (x) => typeof x === 'string';
+const int = (x) => Number.isSafeInteger(x) && x >= 0;
+const hex64 = (x) => str(x) && HEX64.test(x);
+const hex32 = (x) => str(x) && HEX32.test(x);
+const strOrNull = (x) => x === null || str(x);
+const any = () => true;
+const strings = (x) => Array.isArray(x) && x.every(str);
+
+// kind -> { field: check }; a field listed as required must be present.
+export const KINDS = {
+  open: { fields: { tool: str, toolVersion: str, toolRevision: any, command: str, argv: strings, roots: strings, node: str, platform: str }, required: ['tool', 'toolVersion', 'command', 'argv', 'roots'] },
+  input: { fields: { root: int, path: str, sha256: hex64, bytes: int }, required: ['root', 'path', 'sha256'] },
+  finding: { fields: { fingerprint: str, rule: str, tier: str, path: str, line: int }, required: ['fingerprint', 'rule'] },
+  suppressed: { fields: { fingerprint: str, by: str, who: strOrNull, expires: strOrNull, reasonSha256: (x) => x === null || hex64(x) }, required: ['fingerprint', 'by'] },
+  'baseline-write': { fields: { added: strings, removed: strings, who: strOrNull, expires: strOrNull, reasonSha256: (x) => x === null || hex64(x), path: str, sha256: hex64 }, required: ['added', 'removed', 'sha256'] },
+  witness: { fields: { fingerprint: str, outcome: str, who: strOrNull, when: strOrNull, system: strOrNull, sourceSha256: hex64 }, required: ['fingerprint', 'outcome'] },
+  verdict: { fields: { verdict: str, checks: any, relaxed: strings, exit: int }, required: ['verdict'] },
+  output: { fields: { name: str, sha256: hex64, bytes: int, path: str, stdout: (x) => x === true }, required: ['name', 'sha256'] },
+  close: { fields: { exit: (x) => x === null || int(x), counts: any, durationMs: int, ledger: str }, required: ['exit'] },
+  // Written by ironwork's run journal, in this format, so one verifier reads both tools.
+  dd: { fields: { dd: str, event: (x) => ['open', 'close', 'end'].includes(x), mode: str, sha256: hex64, bytes: int }, required: ['dd', 'event'] },
+  call: { fields: { program: str, from: str, sha256: hex64 }, required: ['program'] },
+  abend: { fields: { code: str, file: str, line: int }, required: ['code'] },
+  genesis: { fields: { createdAt: str, rotatedFrom: any }, required: ['createdAt'] },
+  run: { fields: { run: str, runChain: hex32, runLength: int, runTip: hex64 }, required: ['run', 'runChain', 'runLength', 'runTip'] },
+  'lock-broken': { fields: { holderPid: int, ageMs: int }, required: ['holderPid', 'ageMs'] },
+};
+
+export const JOURNAL_KINDS = new Set(['open', 'input', 'finding', 'suppressed', 'baseline-write', 'witness', 'verdict', 'output', 'close', 'dd', 'call', 'abend']);
+export const LEDGER_KINDS = new Set(['genesis', 'run', 'lock-broken']);
+
+export const newChain = () => randomBytes(16).toString('hex');
+
+// Keys sorted by UTF-16 code unit at every depth, integers only, no undefined.
+export function canonical(value) {
+  if (value === null || typeof value === 'boolean' || typeof value === 'string') return JSON.stringify(value);
+  if (typeof value === 'number') {
+    if (!Number.isSafeInteger(value)) throw new TypeError(`an evidence record holds integers only, not ${value}`);
+    return String(value);
+  }
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
+    return `{${Object.keys(value).sort().map((k) => {
+      if (value[k] === undefined) throw new TypeError(`an evidence record holds no undefined value (${k})`);
+      return `${JSON.stringify(k)}:${canonical(value[k])}`;
+    }).join(',')}}`;
+  }
+  throw new TypeError(`an evidence record holds JSON values only, not ${typeof value}`);
+}
+
+export function recordHash(record) {
+  const { hash, ...body } = record;
+  return createHash('sha256').update(DOMAIN).update(canonical(body)).digest('hex');
+}
+
+export function checkFields(kind, fields) {
+  const spec = KINDS[kind];
+  if (!spec) throw new TypeError(`no evidence record kind ${kind}`);
+  for (const [k, v] of Object.entries(fields)) {
+    if (COMMON.includes(k)) throw new TypeError(`${kind}: ${k} is set by the writer`);
+    const check = spec.fields[k];
+    if (!check) throw new TypeError(`${kind}: no field ${k} (docs/spec/evidence.md §5)`);
+    if (v !== undefined && !check(v)) throw new TypeError(`${kind}: ${k} does not hold what the spec says it holds`);
+  }
+  for (const k of spec.required) if (fields[k] === undefined) throw new TypeError(`${kind}: ${k} is required`);
+}
+
+// The next record after `prev` ({ chain, seq, hash } or null for the first), as its line.
+export function makeRecord({ chain, prev, kind, fields, at }) {
+  checkFields(kind, fields);
+  const clean = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined));
+  const record = { ...clean, v: VERSION, chain, seq: prev ? prev.seq + 1 : 0, at, kind, prev: prev ? prev.hash : ZERO };
+  record.hash = recordHash(record);
+  return { record, line: `${canonical(record)}\n` };
+}
+
+// A line as read back: which check it fails, if any, against the record before it.
+export function checkLine(line, prev, { chain, kinds }) {
+  let record;
+  try { record = JSON.parse(line); } catch { return { record: null, fail: 'json' }; }
+  if (!record || typeof record !== 'object' || Array.isArray(record)) return { record: null, fail: 'json' };
+  let text;
+  try { text = canonical(record); } catch { return { record, fail: 'canonical' }; }
+  if (text !== line) return { record, fail: 'canonical' };
+  if (record.v !== VERSION) return { record, fail: 'version' };
+  if (!ISO.test(record.at)) return { record, fail: 'at' };
+  if (!hex64(record.hash) || recordHash(record) !== record.hash) return { record, fail: 'hash' };
+  if (record.chain !== chain) return { record, fail: 'chain' };
+  if (record.seq !== (prev ? prev.seq + 1 : 0)) return { record, fail: 'seq' };
+  if (record.prev !== (prev ? prev.hash : ZERO)) return { record, fail: 'prev' };
+  if (!kinds.has(record.kind)) return { record, fail: 'kind' };
+  const { v, chain: c, seq, at, kind, prev: p, hash, ...fields } = record;
+  try { checkFields(kind, fields); } catch { return { record, fail: 'fields' }; }
+  return { record, fail: null };
+}