@portll/cobolwork 0.5.0 → 0.7.0

package/lib/db2/stmt/view.mjs

@@ -0,0 +1,146 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Db2 for z/OS CREATE VIEW, after the Db2 13 SQL Reference: the view's name and columns, its common
+// table expressions and fullselect kept as tokens, the check option, and the names its FROM clauses read.
+
+import { Db2Syntax } from '../cursor.mjs';
+import { readName } from './table.mjs';
+
+const isName = (t) => !!t && (t.t === 'word' || t.t === 'ident');
+const isWord = (t, u) => !!t && t.t === 'word' && (Array.isArray(u) ? u.includes(t.u) : t.u === u);
+const isOpen = (t) => !!t && t.t === 'op' && t.v === '(';
+const isClose = (t) => !!t && t.t === 'op' && t.v === ')';
+
+// What another dialect's view looks like at the token where a Db2 for z/OS one stops.
+function hint(t, after) {
+  if (!t) return '';
+  if (t.t === 'op' && t.v === '/') return " ('/' qualifies names in Db2 for i system naming, not Db2 for z/OS)";
+  if (t.t !== 'word') return '';
+  if (t.u === 'IF' && (isWord(after, 'NOT') || isWord(after, 'EXISTS'))) return ' (IF [NOT] EXISTS is not Db2 for z/OS syntax)';
+  if (t.u === 'MATERIALIZED') return ' (Db2 for z/OS has materialized query tables, made by CREATE TABLE, not materialized views)';
+  if (t.u === 'READ' && isWord(after, 'ONLY')) return ' (WITH READ ONLY is Oracle, not Db2 for z/OS)';
+  if (t.u === 'CONSTRAINT') return ' (a named check option is Oracle, not Db2 for z/OS)';
+  if (t.u === 'WITH' && isOpen(after)) return ' (view options in parentheses are not Db2 for z/OS syntax)';
+  return '';
+}
+
+function refuse(c, what) {
+  const t = c.peek();
+  throw new Db2Syntax(`expected ${what}${t ? ` at '${t.v ?? t.t}'` : ' at end of statement'}${hint(t, c.peek(1))}`, t || c.peek(-1));
+}
+
+function closing(toks, i) {
+  let depth = 0;
+  for (let k = i; k < toks.length; k++) {
+    if (isOpen(toks[k])) depth++;
+    else if (isClose(toks[k]) && --depth === 0) return k;
+  }
+  return toks.length;
+}
+
+const atTop = (toks, words) => {
+  let depth = 0;
+  return toks.some((t) => {
+    if (isOpen(t)) depth++;
+    else if (isClose(t)) depth--;
+    return depth === 0 && isWord(t, words);
+  });
+};
+
+// The words that end a FROM clause; FOR does too unless a period specification follows the table.
+const FROM_END = ['WHERE', 'GROUP', 'HAVING', 'ORDER', 'FETCH', 'OFFSET', 'LIMIT', 'UNION', 'EXCEPT', 'INTERSECT', 'WITH', 'OPTIMIZE', 'QUERYNO', 'SKIP'];
+
+// One FROM clause from i: a name that starts a table reference is recorded; TABLE (…), XMLTABLE (…) and
+// the like are read only for the subqueries inside them. Returns the index where the clause ends.
+function fromClause(toks, i, out) {
+  let start = true;
+  for (; i < toks.length; i++) {
+    const t = toks[i];
+    if (isWord(t, FROM_END) || (isWord(t, 'FOR') && !isWord(toks[i + 1], ['SYSTEM_TIME', 'BUSINESS_TIME']))) return i;
+    if ((t.t === 'op' && t.v === ',') || isWord(t, 'JOIN')) { start = true; continue; }
+    if (isOpen(t)) {
+      const j = closing(toks, i);
+      const inner = toks.slice(i + 1, j);
+      if (start && !atTop(inner, ['SELECT', 'UNION', 'EXCEPT', 'INTERSECT'])) fromClause(inner, 0, out);
+      else fromNames(inner, out);
+      i = j;
+      start = false;
+      continue;
+    }
+    if (!start) continue;
+    start = false;
+    if (!isName(t) || isWord(t, ['TABLE', 'FINAL', 'OLD']) || isOpen(toks[i + 1])) continue;
+    const parts = [t.v];
+    while (toks[i + 1] && toks[i + 1].t === 'op' && toks[i + 1].v === '.' && isName(toks[i + 2])) { parts.push(toks[i + 2].v); i += 2; }
+    out.push(parts.join('.'));
+  }
+  return i;
+}
+
+// The names in the FROM clause of every subselect in toks, subqueries included; a FROM that no SELECT
+// at its own depth precedes (EXTRACT (YEAR FROM D), IS DISTINCT FROM) is not one.
+function fromNames(toks, out) {
+  let select = false;
+  for (let i = 0; i < toks.length; i++) {
+    const t = toks[i];
+    if (isOpen(t)) {
+      const j = closing(toks, i);
+      fromNames(toks.slice(i + 1, j), out);
+      i = j;
+    } else if (isWord(t, 'SELECT')) select = true;
+    else if (isWord(t, 'FROM') && select && !isWord(toks[i - 1], 'DISTINCT')) i = fromClause(toks, i + 1, out) - 1;
+  }
+}
+
+function readColumnNames(c) {
+  return c.items().map((item) => {
+    if (item.length !== 1 || !isName(item[0])) throw new Db2Syntax(`expected an unqualified column name${item[0] ? ` at '${item[0].v}'` : ''}`, item[0] || c.peek(-1));
+    return item[0].v;
+  });
+}
+
+function readCommonTableExpression(c) {
+  const t = c.next();
+  if (!isName(t)) { c.pos -= t ? 1 : 0; refuse(c, 'a common table expression name'); }
+  const cte = { name: t.v, columns: c.isOp('(') ? readColumnNames(c) : null, fullselect: null };
+  c.expectWord('AS');
+  if (!c.isOp('(')) refuse(c, "'(' and the common table expression's fullselect");
+  cte.fullselect = c.group();
+  return cte;
+}
+
+function readView(c) {
+  c.expectWord('CREATE');
+  if (c.isWord('OR') && c.isWord('REPLACE', 1)) refuse(c, 'VIEW (Db2 for z/OS has no CREATE OR REPLACE VIEW)');
+  if (!c.isWord('VIEW')) refuse(c, 'VIEW');
+  c.next();
+  if (c.isWord('IF') && c.isWord(['NOT', 'EXISTS'], 1)) refuse(c, 'a view name');
+  const parts = readName(c);
+  if (parts.length > 3) refuse(c, 'a view name of at most three parts');
+  const node = { kind: 'CREATE VIEW', name: parts.join('.'), columns: null, with: [], fullselect: null, checkOption: null, tables: [] };
+  if (c.isOp('(')) node.columns = readColumnNames(c);
+  if (!c.word('AS')) refuse(c, node.columns ? 'AS' : "'(' or AS");
+  if (c.word('WITH')) {
+    if (c.isWord('RECURSIVE')) refuse(c, 'a common table expression (WITH RECURSIVE is not Db2 for z/OS syntax)');
+    do node.with.push(readCommonTableExpression(c)); while (c.op(','));
+  }
+  if (!c.isWord('SELECT') && !c.isOp('(')) refuse(c, 'a fullselect');
+  node.fullselect = c.until((t) => isWord(t, 'WITH'));
+  if (c.word('WITH')) {
+    const how = c.word(['CASCADED', 'LOCAL']);
+    if (!c.isWord('CHECK')) refuse(c, how ? 'CHECK OPTION' : 'CASCADED, LOCAL or CHECK OPTION');
+    c.next();
+    c.expectWord('OPTION');
+    node.checkOption = how ? how.u : 'CASCADED';
+    if (!c.done()) refuse(c, 'the end of the statement after CHECK OPTION');
+  }
+  const names = [];
+  for (const cte of node.with) fromNames(cte.fullselect, names);
+  fromNames(node.fullselect, names);
+  const local = new Set(node.with.map((cte) => cte.name.toUpperCase()));
+  node.tables = [...new Set(names)].filter((n) => n.includes('.') || !local.has(n.toUpperCase()));
+  return node;
+}
+
+export const parsers = {
+  'CREATE VIEW': (c) => readView(c),
+};

package/lib/diff.mjs

@@ -9,7 +9,7 @@ import { FLOW_MODEL, SCHEMA_VERSION, TOOL_VERSION } from './version.mjs';
 // A diff finding is located by program rather than by line, so it orders on its own key. The text
 // comparison underneath it is the shared one.
 import { byText, evidenceMap } from './kernel/findings.mjs';
-import { directoryTree, gitTree } from './kernel/source-tree.mjs';
+import { directoryTree, gitTree, pdsExportRevision, pdsExportTree } from './kernel/source-tree.mjs';
 import { printable } from './kernel/printable.mjs';
 import { loadSite, SITE_FILE } from './site.mjs';
 import { loadBaseline, BASELINE_FILE, SUPPRESSING } from './baseline.mjs';
@@ -258,6 +258,7 @@ function siteChange(baseAt, headAt) {
   if (b.allowUnvalidatedPacks !== h.allowUnvalidatedPacks) parts.push(`allowUnvalidatedPacks ${h.allowUnvalidatedPacks}`);
   if (JSON.stringify(b.runtimeVersions) !== JSON.stringify(h.runtimeVersions)) parts.push('runtimeVersions');
   if (h.problems.length && h.problems.join() !== b.problems.join()) parts.push(`now reports: ${h.problems[0]}`);
+  if (h.warnings.length && h.warnings.join() !== b.warnings.join()) parts.push(`now warns: ${h.warnings[0]}`);
   return parts.length ? { file: SITE_FILE, change: printable(parts.join('; '), 400) } : null;
 }
 
@@ -307,14 +308,25 @@ export function withRefs(repo, baseRef, headRef, opts, fn) {
   }
 }
 
+// The members of a PDS export's working tree whose files git tracks or would track: an archive's
+// members by the archive's file.
+function exportScope(repo, tree) {
+  const scope = gitScope(repo);
+  return new Set(tree.list().filter((p) => scope.has(resolve(repo, tree.origin(p).replace(/\([^)]*\)$/, '')))));
+}
+
 // Reads each revision out of git without writing it anywhere; the head is the working tree when
-// headRef is null.
+// headRef is null. With pdsExport each side is read as a PDS export, members named for their data
+// sets on both.
 export function diffRefs(repo, baseRef, headRef = null, opts = {}) {
   const trees = { systemDirs: opts.systemDirs || [] };
-  const base = gitTree(repo, baseRef, trees);
-  const head = headRef ? gitTree(repo, headRef, trees) : repo;
-  const res = diffTrees(base, head, headRef ? opts : { ...opts, allow: gitScope(repo) });
+  const revision = (ref) => (opts.pdsExport ? pdsExportRevision(repo, ref, trees) : gitTree(repo, ref, trees));
+  const base = revision(baseRef);
+  const head = headRef ? revision(headRef) : opts.pdsExport ? pdsExportTree(repo, trees) : repo;
+  const allow = headRef ? null : opts.pdsExport ? exportScope(repo, head) : gitScope(repo);
+  const res = diffTrees(base, head, allow ? { ...opts, allow } : opts);
   res.summary.base = baseRef;
   res.summary.head = headRef || WORKING_TREE;
+  if (opts.pdsExport) res.summary.pdsExport = { base: base.export, head: head.export };
   return res;
 }

package/lib/equivalence.mjs

@@ -50,6 +50,34 @@ function closure(root, file, idx, systemDirs) {
   return out;
 }
 
+// The first program's paragraphs, by name, each as its own statements read with every position
+// left out, so a paragraph that only moved is the same paragraph (as ironwork compare reads them).
+function paragraphPrints(file) {
+  let program;
+  try { program = parseSource(readSource(file).text, file, { format: 'auto', mainDir: dirname(file) }).programs[0]; } catch { return null; }
+  if (!program) return null;
+  const positionFree = (x) => (Array.isArray(x) ? x.map(positionFree)
+    : x && typeof x === 'object' ? Object.fromEntries(Object.entries(x).filter(([k]) => !['line', 'file', 'at', 'end', 'col', 'fmt'].includes(k)).map(([k, v]) => [k, positionFree(v)]))
+      : x);
+  const labels = [...program.labels].sort((a, b) => a.at - b.at);
+  const prints = new Map();
+  labels.forEach((label, i) => {
+    if (label.kind !== 'P') return;
+    const end = i + 1 < labels.length ? labels[i + 1].at : Infinity;
+    const body = program.statements.filter((s) => s.at > label.at && s.at < end).map(positionFree);
+    prints.set(label.name, [...(prints.get(label.name) || []), JSON.stringify(body)]);
+  });
+  return prints;
+}
+
+// The head's paragraphs whose own statements the change edits or adds.
+function editedParagraphs(baseFile, headFile) {
+  const before = paragraphPrints(baseFile);
+  const after = paragraphPrints(headFile);
+  if (!before || !after) return [];
+  return [...after].filter(([name, prints]) => String(before.get(name)) !== String(prints)).map(([name]) => name).sort();
+}
+
 // Programs the change edits, adds or deletes, or whose copybooks it edits: [{ path, base, head, via }]
 // with each side's source digest (head null for a deleted program) and the copybooks that changed
 // under an unchanged program.
@@ -112,14 +140,21 @@ export function checkEquivalence({ baseDir, headDir, allow, files = [], allowed
       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 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;
   // Every statement that names a program is judged, and the program passes only if each does.
+  // Where equivalence may be required, a statement no allowed signer signed could have been written
+  // by anyone who can commit.
   const programs = changed.map((c) => {
     if (c.deleted) return { path: c.path, deleted: true, statement: null, ok: false, because: 'the change deletes this program, and no equivalence statement can show what its callers do now' };
     const matching = statements.filter((x) => x.statement && subjectDigest(x.statement, 'head') === c.head && subjectDigest(x.statement, 'base') === c.base);
     const via = c.via ? { via: c.via } : {};
     if (!matching.length) 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 judged = matching.map((s) => judge(c, s));
-    return judged.find((j) => !j.ok) || judged[0];
+    const failed = judged.find((j) => !j.ok);
+    if (failed) return failed;
+    if (!allowed && required !== false) return { ...judged[0], ok: false, because: 'no --allowed-signers were given, so nothing shows who wrote the statement' };
+    return judged[0];
   });
   function judge(c, s) {
     const via = c.via ? { via: c.via } : {};
@@ -128,15 +163,19 @@ export function checkEquivalence({ baseDir, headDir, allow, files = [], allowed
     const covered = !!p.coverage && typeof p.coverage === 'object' && Array.isArray(p.coverage.unreached) && p.coverage.unreached.every((u) => typeof u === 'string');
     const ranOn = new Set(((p.closure && p.closure.head) || []).map((x) => x.sha256));
     const missing = (c.viaDigests || []).filter((d) => !ranOn.has(d));
+    // ironwork decides which paragraphs changed; a paragraph whose statements this diff shows
+    // edited and the statement does not list as changed was never held to coverage.
+    const claimed = covered && Array.isArray(p.coverage.changed) ? new Set(p.coverage.changed.map((n) => String(n).toUpperCase())) : null;
+    const edited = covered && c.base ? editedParagraphs(join(baseDir, c.path), join(headDir, c.path)) : [];
+    const unclaimed = edited.filter((n) => !claimed || !claimed.has(n));
     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;
+        : unclaimed.length ? `the statement's coverage does not list ${unclaimed.join(', ')} as changed, and the change edits ${unclaimed.length > 1 ? 'them' : 'it'}`
+          : allowed && !s.signed ? `the statement is ${s.reason}`
+            : null;
     const unreached = covered ? 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

@@ -1,15 +1,26 @@
 // 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 { existsSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join, 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 { EvidenceRefusal, createExclusive, evidenceDirFrom, syncClose, writeAll } from './store.mjs';
 import { verifyEvidence } from './verify.mjs';
+import { EVIDENCE_RESULT_SCHEMA_VERSION } from '../version.mjs';
+import { evidenceClausesFor } from '../compliance.mjs';
 
 const VERBS = ['verify', 'seal', 'anchor', 'sign'];
 
+// The clauses a verified directory's evidence answers: a run journal's records, and the chain once
+// it verifies.
+function complianceOf(dir, verdict) {
+  const runs = join(dir, 'runs');
+  const journals = existsSync(runs) && readdirSync(runs).some((n) => n.endsWith('.jsonl'));
+  const present = journals ? ['journal-records', ...(verdict.verified ? ['journal-chain'] : [])] : [];
+  return present.flatMap((evidenceId) => evidenceClausesFor(evidenceId).map((c) => ({ evidenceId, ...c })));
+}
+
 function anchorNewest(dir, opts) {
   const seals = sealFiles(dir);
   if (!seals.length) throw new EvidenceRefusal('there is no seal to anchor; run evidence seal first');
@@ -22,7 +33,12 @@ function anchorNewest(dir, opts) {
   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 };
+    // The request is kept beside its seal, so verify can check the response's nonce against it.
+    const kept = join(dir, 'seals', `${newest.seq}.tsq`);
+    if (existsSync(kept)) unlinkSync(kept);
+    const fd = createExclusive(kept);
+    try { writeAll(fd, req.der); } finally { syncClose(fd); }
+    out.tsq = { path: resolve(opts.tsq), sha256: req.digest, nonce: req.nonce, kept: `seals/${newest.seq}.tsq` };
   }
   return out;
 }
@@ -41,14 +57,17 @@ export function evidenceCommand(verb, opts, { toolVersion, write, env = process.
   }
   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`);
+  const emit = (doc) => write(`${JSON.stringify({ tool: 'cobolwork-evidence', schemaVersion: EVIDENCE_RESULT_SCHEMA_VERSION, 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);
+    if (opts.anchorPin && !opts.anchorGit) throw new EvidenceRefusal('--anchor-pin names a commit of the --anchor-git witness');
+    const file = (x) => (x ? resolve(x) : null);
+    const cosign = opts.cosignBundle ? { bundle: file(opts.cosignBundle), key: file(opts.cosignKey), identity: opts.certificateIdentity || null, issuer: opts.certificateOidcIssuer || null, trustedRoot: file(opts.trustedRoot), ignoreTlog: opts.insecureIgnoreTlog === true } : null;
+    const verdict = verifyEvidence(dir, { allowed, anchorGit: file(opts.anchorGit), anchorRef: opts.ref || null, anchorPin: opts.anchorPin || null, tsr: file(opts.tsr), tsaCa: file(opts.tsaCa), cosign, maxUnsealed: max, env });
+    emit({ ...verdict, compliance: complianceOf(dir, verdict) });
     return verdict.exit;
   }
   if (verb === 'seal') {

package/lib/evidence/record.mjs

@@ -21,7 +21,8 @@ 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.
+// kind -> { field: check }; a field listed as required must be present, and `check`, where a kind
+// has one, names what its fields fail together.
 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'] },
@@ -31,19 +32,26 @@ export const KINDS = {
   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'] },
+  // ironwork's run journal closes with the program's true RETURN-CODE, which may be negative.
+  close: { fields: { exit: (x) => x === null || Number.isSafeInteger(x), counts: any, durationMs: int, ledger: str, executor: (x) => ['vm', 'interpreter'].includes(x) }, 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'] },
   step: { fields: { step: str, pgm: str, outcome: str }, required: ['step', 'pgm', 'outcome'] },
-  sink: { fields: { sink: str, file: str, line: int, marker: str, reached: (x) => typeof x === 'boolean' }, required: ['sink', 'file', 'line', 'marker', 'reached'] },
-  genesis: { fields: { createdAt: str, rotatedFrom: any }, required: ['createdAt'] },
+  sink: {
+    fields: { sink: str, file: str, line: int, marker: str, reached: (x) => typeof x === 'boolean', input: (x) => x === null || typeof x === 'boolean' },
+    required: ['sink', 'file', 'line'],
+    check: (f) => ((f.marker === undefined) !== (f.reached === undefined) ? 'marker and reached come together'
+      : f.marker === undefined && f.input === undefined ? 'needs marker and reached, or input' : null),
+  },
+  statement: { fields: { file: str, line: int, capped: (x) => x === true }, required: ['file', 'line'] },
+  genesis: { fields: { createdAt: str }, 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'] },
+  'lock-broken': { fields: { holderPid: (x) => x === null || int(x), ageMs: int }, required: ['holderPid', 'ageMs'] },
 };
 
-export const JOURNAL_KINDS = new Set(['open', 'input', 'finding', 'suppressed', 'baseline-write', 'witness', 'verdict', 'output', 'close', 'dd', 'call', 'abend', 'step', 'sink']);
+export const JOURNAL_KINDS = new Set(['open', 'input', 'finding', 'suppressed', 'baseline-write', 'witness', 'verdict', 'output', 'close', 'dd', 'call', 'abend', 'step', 'sink', 'statement']);
 export const LEDGER_KINDS = new Set(['genesis', 'run', 'lock-broken']);
 
 export const newChain = () => randomBytes(16).toString('hex');
@@ -80,6 +88,8 @@ export function checkFields(kind, fields) {
     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`);
+  const fault = spec.check?.(fields);
+  if (fault) throw new TypeError(`${kind}: ${fault}`);
 }
 
 // The next record after `prev` ({ chain, seq, hash } or null for the first), as its line.

package/lib/evidence/seal.mjs

@@ -159,6 +159,23 @@ export function resolveRef(repo, ref, env = process.env) {
   return r.status === 0 ? String(r.stdout).trim() : null;
 }
 
+// Whether commit `older` is in the history of `newer`.
+export function isAncestor(repo, older, newer, env = process.env) {
+  return git(repo, ['merge-base', '--is-ancestor', older, newer], env).status === 0;
+}
+
+// The blob of every seal the witness holds at `ref`, by its path: Map(`<chain>/<seq>.dsse.json` -> blob id).
+export function witnessedBlobs(repo, ref, env = process.env) {
+  const r = git(repo, ['ls-tree', '-r', ref], env);
+  const out = new Map();
+  if (r.status !== 0) return out;
+  for (const line of String(r.stdout).split('\n')) {
+    const m = /^\d+ blob ([0-9a-f]+)\t([0-9a-f]{32}\/\d+\.dsse\.json)$/.exec(line.trim());
+    if (m) out.set(m[2], m[1]);
+  }
+  return out;
+}
+
 // A DER TimeStampReq (RFC 3161) over SHA-256 of `bytes`, with a random nonce and certReq true.
 export function timeStampRequest(bytes) {
   const der = (tag, body) => {

package/lib/evidence/store.mjs

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 // The evidence directory on disk: where it may be, how its files are opened (never through a
 // symbolic link, owner-only), the ledger lock, and reading a chain file back line by line.
-import { closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, realpathSync, statSync, unlinkSync, writeSync } from 'node:fs';
+import { closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readSync, realpathSync, renameSync, statSync, unlinkSync, writeSync } from 'node:fs';
 import { basename, dirname, join, resolve, sep } from 'node:path';
 
 const { O_WRONLY, O_CREAT, O_EXCL, O_APPEND, O_NOFOLLOW } = constants;
@@ -138,32 +138,61 @@ export function lastLine(path) {
 const pidAlive = (pid) => { try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; } };
 const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 
+// A lock file as read: its inode and text, the pid it names and its age, or null when there is none.
+// A lock whose pid and time cannot be read was left by a writer that died between creating it and
+// writing them; it is aged from its modification time.
+function readLock(path, now) {
+  let fd;
+  try { fd = openRead(path); } catch { return null; }
+  try {
+    const st = fstatSync(fd);
+    const text = readAll(fd).toString('utf8');
+    const [p, t] = text.trim().split(/\s+/).map(Number);
+    const pid = Number.isSafeInteger(p) && p > 0 ? p : null;
+    const since = Number.isSafeInteger(t) && t > 0 ? t : null;
+    return { ino: st.ino, text, pid, age: pid !== null && since !== null ? now() - since : now() - st.mtimeMs };
+  } finally { closeSync(fd); }
+}
+
+const isStale = (lock, staleMs) => lock !== null && lock.age > staleMs && (lock.pid === null || !pidAlive(lock.pid));
+
+// Replaces the stale lock `seen` with this writer's own. Breakers hold ledger.lock.break while they
+// break, so one breaks at a time, and rename it over the lock only while the lock is still the file
+// judged stale: a lock a peer took since is never moved. Returns whether this writer holds the lock.
+export function breakStale(path, seen, { staleMs = 60000, now = Date.now } = {}) {
+  const claim = `${path}.break`;
+  let fd;
+  try { fd = createExclusive(claim); } catch (e) {
+    if (e.code !== 'EEXIST') throw e;
+    if (isStale(readLock(claim, now), staleMs)) { try { unlinkSync(claim); } catch { /* already gone */ } }
+    return false;
+  }
+  writeAll(fd, `${process.pid} ${now()}\n`);
+  closeSync(fd);
+  const still = readLock(path, now);
+  if (still && still.ino === seen.ino && still.text === seen.text) {
+    try { renameSync(claim, path); return true; } catch { /* the claim is removed below */ }
+  }
+  try { unlinkSync(claim); } catch { /* already gone */ }
+  return false;
+}
+
 // Takes ledger.lock, breaking one that is older than staleMs and whose holder is gone. Returns
 // { release, broken } or null when the lock could not be had within waitMs.
 export function takeLock(path, { waitMs = 5000, staleMs = 60000, now = Date.now } = {}) {
   const deadline = now() + waitMs;
-  let broken = null;
+  const held = (broken) => ({ release: () => { try { unlinkSync(path); } catch { /* already gone */ } }, broken });
   for (;;) {
     try {
       const fd = createExclusive(path);
       writeAll(fd, `${process.pid} ${now()}\n`);
       closeSync(fd);
-      return { release: () => { try { unlinkSync(path); } catch { /* already gone */ } }, broken };
+      return held(null);
     } catch (e) {
       if (e.code !== 'EEXIST') throw e;
     }
-    let pid = null;
-    let since = null;
-    try {
-      const [p, t] = readFileSync(path, 'utf8').trim().split(/\s+/).map(Number);
-      pid = Number.isSafeInteger(p) ? p : null;
-      since = Number.isSafeInteger(t) ? t : null;
-    } catch { /* removed between the open and the read */ }
-    const age = since === null ? null : now() - since;
-    if (pid !== null && age !== null && age > staleMs && !pidAlive(pid)) {
-      try { unlinkSync(path); broken = { holderPid: pid, ageMs: Math.max(0, Math.trunc(age)) }; } catch { /* a peer broke it first */ }
-      continue;
-    }
+    const seen = readLock(path, now);
+    if (isStale(seen, staleMs) && breakStale(path, seen, { staleMs, now })) return held({ holderPid: seen.pid, ageMs: Math.max(0, Math.trunc(seen.age)) });
     if (now() >= deadline) return null;
     sleep(25);
   }

package/lib/evidence/timestamp.mjs

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// RFC 3161 as the git witness's sibling (docs/spec/evidence.md §8): the request `anchor --tsq`
+// keeps beside a seal, and the facts of a time-stamp response cobolwork checks itself, its status,
+// message imprint, nonce and time. The TSA's signature is OpenSSL's to check.
+
+const SHA256_OID = Buffer.from([0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x01]);
+
+// One DER element at `at`: its tag and where its contents start and end.
+function element(buf, at, end = buf.length) {
+  if (at + 2 > end) throw new Error('a DER element runs past the end');
+  const tag = buf[at];
+  let length = buf[at + 1];
+  let start = at + 2;
+  if (length & 0x80) {
+    const n = length & 0x7f;
+    if (n < 1 || n > 4 || start + n > end) throw new Error('a DER length is not one this reads');
+    length = 0;
+    for (let i = 0; i < n; i++) length = length * 256 + buf[start + i];
+    start += n;
+  }
+  if (start + length > end) throw new Error('a DER element runs past the end');
+  return { tag, start, end: start + length };
+}
+
+function children(buf, parent) {
+  const out = [];
+  for (let at = parent.start; at < parent.end;) {
+    const c = element(buf, at, parent.end);
+    out.push(c);
+    at = c.end;
+  }
+  return out;
+}
+
+const contents = (buf, el) => buf.subarray(el.start, el.end);
+const expect = (el, tag, what) => {
+  if (!el || el.tag !== tag) throw new Error(`${what} is not where RFC 3161 puts it`);
+  return el;
+};
+// An INTEGER's magnitude as hex, leading zero bytes dropped, so 00 80 and 80 compare equal.
+const integerHex = (bytes) => {
+  let i = 0;
+  while (i < bytes.length - 1 && bytes[i] === 0) i++;
+  return Buffer.from(bytes.subarray(i)).toString('hex');
+};
+
+function imprintOf(buf, el, what) {
+  const [algorithm, hashed] = children(buf, expect(el, 0x30, `${what}'s message imprint`));
+  const oid = expect(children(buf, expect(algorithm, 0x30, `${what}'s hash algorithm`))[0], 0x06, `${what}'s hash algorithm`);
+  if (!contents(buf, oid).equals(SHA256_OID)) throw new Error(`${what} is not over SHA-256`);
+  return Buffer.from(contents(buf, expect(hashed, 0x04, `${what}'s hashed message`))).toString('hex');
+}
+
+// The message imprint and nonce of a TimeStampReq that `anchor --tsq` wrote.
+export function readRequest(der) {
+  const [version, imprint, ...rest] = children(der, expect(element(der, 0), 0x30, 'the request'));
+  expect(version, 0x02, "the request's version");
+  const nonce = rest.find((e) => e.tag === 0x02);
+  return { digest: imprintOf(der, imprint, 'the request'), nonce: nonce ? integerHex(contents(der, nonce)) : null };
+}
+
+// status, digest (hex), nonce (hex or null) and genTime of a TimeStampResp; throws on a response
+// whose shape is not RFC 3161's.
+export function readResponse(der) {
+  const [statusInfo, token] = children(der, expect(element(der, 0), 0x30, 'the response'));
+  const status = parseInt(integerHex(contents(der, expect(children(der, expect(statusInfo, 0x30, 'the status'))[0], 0x02, 'the status'))), 16);
+  if (status > 1 || !token) return { status, digest: null, nonce: null, genTime: null };
+  const [, signedWrapper] = children(der, expect(token, 0x30, 'the time-stamp token'));
+  const signedData = children(der, expect(signedWrapper, 0xa0, 'the signed data'))[0];
+  const encapsulated = children(der, expect(signedData, 0x30, 'the signed data'))[2];
+  const [, contentWrapper] = children(der, expect(encapsulated, 0x30, 'the encapsulated content'));
+  const octets = children(der, expect(contentWrapper, 0xa0, 'the TSTInfo'))[0];
+  const tst = element(der, expect(octets, 0x04, 'the TSTInfo').start, octets.end);
+  const fields = children(der, expect(tst, 0x30, 'the TSTInfo'));
+  const genTime = expect(fields[4], 0x18, 'genTime');
+  const nonce = fields.slice(5).find((e) => e.tag === 0x02);
+  return {
+    status,
+    digest: imprintOf(der, fields[2], 'the response'),
+    nonce: nonce ? integerHex(contents(der, nonce)) : null,
+    genTime: contents(der, genTime).toString('latin1'),
+  };
+}