@portll/cobolwork 0.5.0 → 0.7.0

package/lib/evidence/verify.mjs

@@ -1,14 +1,16 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 // Verifies an evidence directory and reports verified, broken, unrecorded, open, anchored, sealed,
 // unsealedTail and signatures as separate facts. docs/spec/evidence.md §9.
+import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { JOURNAL_KINDS, LEDGER_KINDS, checkLine } from './record.mjs';
 import { readLines } from './store.mjs';
 import { LEDGER } from './journal.mjs';
-import { NAMESPACE, PAYLOAD_TYPE, SEAL_PREDICATE, STATEMENT_TYPE, listWitnessed, pae, readWitnessed, resolveRef, sealFiles } from './seal.mjs';
+import { NAMESPACE, PAYLOAD_TYPE, SEAL_PREDICATE, STATEMENT_TYPE, isAncestor, listWitnessed, pae, readWitnessed, resolveRef, sealFiles, witnessedBlobs } from './seal.mjs';
 import { verifySshsig } from './sshsig.mjs';
+import { readRequest, readResponse } from './timestamp.mjs';
 
 const sha256 = (b) => createHash('sha256').update(b).digest('hex');
 
@@ -68,7 +70,108 @@ function signaturesOf(seal, allowed) {
   });
 }
 
-export function verifyEvidence(dir, { allowed = null, anchorGit = null, anchorRef = null, maxUnsealed = 0, env = process.env } = {}) {
+// With a pinned commit, the witness's history since then: the pin must still be an ancestor of the
+// ref, and every seal it held must be at the ref unchanged. A rewritten branch or a later commit
+// that deletes seals is a contradiction, which a fresh reading of the ref alone cannot see.
+function pinProblem(repo, pin, ref, env) {
+  const pinned = resolveRef(repo, pin, env);
+  if (!pinned) return `the pinned commit ${pin} is not in the witness`;
+  const at = resolveRef(repo, ref, env);
+  if (!isAncestor(repo, pinned, at, env)) return `the witness was rewritten: the pinned commit ${pinned.slice(0, 12)} is not in the history of ${ref}`;
+  const now = witnessedBlobs(repo, at, env);
+  for (const [path, blob] of witnessedBlobs(repo, pinned, env)) {
+    if (now.get(path) !== blob) return `the witness held ${path} at the pinned commit, and ${now.has(path) ? 'holds another' : 'no longer holds it'} at ${ref}`;
+  }
+  return null;
+}
+
+// A seal a witness vouches for counts when the ledger holds the state it names and an allowed
+// signer signed it.
+function accepting(recs, allowed) {
+  return (ws, name) => {
+    const a = agrees(ws, recs);
+    if (!a.ok) return { sealed: false, reason: `${name}: ${a.why}` };
+    const sigs = signaturesOf(ws, allowed);
+    if (sigs.some((x) => x.valid === true)) return { sealed: true, seal: ws };
+    if (sigs.every((x) => x.valid === false)) return { sealed: false, unsigned: true, reason: `${name} carries no signature from an allowed signer` };
+    return { sealed: null, reason: allowed ? `${name} carries no valid signature` : 'no allowed signers were given' };
+  };
+}
+
+const firstLine = (text) => String(text || '').trim().split('\n')[0].slice(0, 300);
+const BOUNDED = { timeout: 30000, maxBuffer: 1 << 20, windowsHide: true };
+
+// The git witness is the authority for its ledger: every seal it holds is checked, whether or not
+// the directory still has its copy, so deleting local seals cannot hide a cut tail.
+function gitWitness({ repo, ref, pin, recs, local, accept, allowed, verdict, env }) {
+  const witnessCommit = resolveRef(repo, ref, env);
+  if (!witnessCommit) return { sealed: null, reason: `${ref} does not resolve in ${repo}` };
+  verdict.witnessCommit = witnessCommit;
+  const rewritten = pin ? pinProblem(repo, pin, ref, env) : null;
+  if (rewritten) return { sealed: false, reason: rewritten };
+  const held = listWitnessed(repo, ref, env);
+  const chain = recs.length ? recs[0].chain : null;
+  const seqs = chain ? held.get(chain) || [] : [];
+  const localSeqs = new Set(local.filter((s) => s.chain === chain).map((s) => s.seq));
+  let result = null;
+  let newest = null;
+  if (!seqs.length && held.size) result = { sealed: false, reason: `the witness holds seals for ledger ${[...held.keys()].join(', ')}, and this directory holds ledger ${chain || 'none'}` };
+  else if (!seqs.length) result = { sealed: null, reason: `not on ${ref}: the witness holds no seal for ledger ${chain || 'none'}` };
+  for (const seq of result ? [] : seqs) {
+    const name = `${seq}.dsse.json`;
+    let ws;
+    try { ws = decodeSeal(readWitnessed(repo, ref, `${chain}/${name}`, env).text); } catch (e) { result = { sealed: false, reason: `the witnessed ${name} is not a seal: ${e.message}` }; break; }
+    const r = accept(ws, `witnessed ${name}`);
+    if (r.sealed === false && !r.unsigned) { result = r; break; }
+    verdict.seals.push({ seal: name, witnessed: true, local: localSeqs.has(seq), length: ws.length, signed: r.sealed === true });
+    if (r.sealed === false) { result = r; break; }
+    if (r.sealed === true) newest = ws;
+  }
+  for (const s of local) if (s.chain === chain && !seqs.includes(s.seq)) verdict.seals.push({ seal: s.name, witnessed: false, reason: `not on ${ref}` });
+  if (result) return result;
+  if (newest) return { sealed: true, seal: newest };
+  return { sealed: null, reason: allowed ? 'no witnessed seal carries a valid signature' : 'no allowed signers were given' };
+}
+
+// An RFC 3161 response: its imprint names a seal, its nonce is the kept request's, and OpenSSL
+// verifies the authority's signature against --tsa-ca.
+function tsrWitness({ dir, tsr, ca, local, accept, verdict, env }) {
+  let resp;
+  try { resp = readResponse(readFileSync(tsr)); } catch (e) { return { sealed: null, reason: `--tsr ${tsr} is not a time-stamp response (${e.message})` }; }
+  if (resp.status > 1) return { sealed: null, reason: `the time-stamp authority refused the request (status ${resp.status})` };
+  const s = local.find((x) => sha256(x.text) === resp.digest);
+  if (!s) return { sealed: false, reason: `the time-stamp response's message imprint ${resp.digest.slice(0, 12)} matches no seal in seals/` };
+  verdict.timeStamp = { seal: s.name, genTime: resp.genTime };
+  const kept = join(dir, 'seals', `${s.seq}.tsq`);
+  if (!existsSync(kept)) return { sealed: null, reason: `seals/${s.seq}.tsq, the request for ${s.name}, is not kept, so the response's nonce cannot be checked` };
+  let req;
+  try { req = readRequest(readFileSync(kept)); } catch (e) { return { sealed: null, reason: `seals/${s.seq}.tsq is not a time-stamp request (${e.message})` }; }
+  if (req.digest !== resp.digest || !resp.nonce || req.nonce !== resp.nonce) return { sealed: false, reason: `the time-stamp response's nonce is not that of the request kept for ${s.name}` };
+  if (!ca) return { sealed: null, reason: '--tsr needs --tsa-ca, the certificate the time-stamp authority chains to' };
+  const r = spawnSync('openssl', ['ts', '-verify', '-in', tsr, '-data', s.path, '-CAfile', ca], { ...BOUNDED, env });
+  if (r.error) return { sealed: null, reason: `OpenSSL could not be run (${r.error.code || r.error.message}), so the authority's signature is unchecked` };
+  if (r.status !== 0) return { sealed: false, reason: `OpenSSL does not verify the time-stamp response: ${firstLine(r.stderr) || firstLine(r.stdout)}` };
+  return accept(s, `the time-stamped ${s.name}`);
+}
+
+// A transparency-log bundle, checked by cosign against each local seal, newest first.
+function cosignWitness({ bundle, key, identity, issuer, trustedRoot, ignoreTlog, local, accept, verdict, env }) {
+  if (!key && !(identity && issuer)) return { sealed: null, reason: '--cosign-bundle needs --cosign-key, or --certificate-identity with --certificate-oidc-issuer' };
+  let last = '';
+  for (const s of [...local].reverse()) {
+    const who = key ? ['--key', key] : ['--certificate-identity', identity, '--certificate-oidc-issuer', issuer];
+    const r = spawnSync('cosign', ['verify-blob', '--bundle', bundle, ...who, ...(trustedRoot ? ['--trusted-root', trustedRoot] : []), ...(ignoreTlog ? ['--insecure-ignore-tlog=true'] : []), s.path], { ...BOUNDED, env });
+    if (r.error) return { sealed: null, reason: `cosign could not be run (${r.error.code || r.error.message})` };
+    if (r.status === 0) {
+      verdict.transparencyLog = { seal: s.name, tlogChecked: !ignoreTlog };
+      return accept(s, `the cosign-witnessed ${s.name}`);
+    }
+    last = firstLine(r.stderr);
+  }
+  return { sealed: false, reason: `the cosign bundle verifies against no seal in seals/${last ? ` (cosign: ${last})` : ''}` };
+}
+
+export function verifyEvidence(dir, { allowed = null, anchorGit = null, anchorRef = null, anchorPin = null, tsr = null, tsaCa = null, cosign = null, maxUnsealed = 0, env = process.env } = {}) {
   const verdict = { verified: true, broken: [], unrecorded: [], open: [], anchored: null, sealed: null, sealedReason: null, unsealedTail: null, signatures: [], seals: [] };
   const ledger = verifyChain(join(dir, LEDGER), LEDGER);
   verdict.broken.push(...ledger.broken);
@@ -107,7 +210,7 @@ export function verifyEvidence(dir, { allowed = null, anchorGit = null, anchorRe
     try { s = decodeSeal(text); } catch (e) { verdict.broken.push({ file: `seals/${f.name}`, line: 1, check: 'seal', reason: e.message }); prevDigest = sha256(text); continue; }
     if (s.previous !== prevDigest) verdict.broken.push({ file: `seals/${f.name}`, line: 1, check: 'seal-chain' });
     prevDigest = sha256(text);
-    local.push({ ...s, seq: f.seq, name: f.name, text });
+    local.push({ ...s, seq: f.seq, name: f.name, path: f.path, text });
   }
   if (local.length) {
     const newest = local[local.length - 1];
@@ -120,45 +223,20 @@ export function verifyEvidence(dir, { allowed = null, anchorGit = null, anchorRe
     verdict.signatures.push({ seal: s.name, results: sigs });
   }
 
-  if (anchorGit) {
-    const ref = anchorRef || '@{upstream}';
-    if (!resolveRef(anchorGit, ref, env)) {
-      verdict.sealedReason = `${ref} does not resolve in ${anchorGit}`;
-    } else {
-      // The witness is the authority: every seal it holds for this ledger is checked, whether or
-      // not the directory still has its copy, so deleting local seals cannot hide a cut tail.
-      const held = listWitnessed(anchorGit, ref, env);
-      const chain = recs.length ? recs[0].chain : null;
-      const seqs = chain ? held.get(chain) || [] : [];
-      const localSeqs = new Set(local.filter((s) => s.chain === chain).map((s) => s.seq));
-      let newestOk = null;
-      if (!seqs.length && held.size) {
-        verdict.sealed = false;
-        verdict.sealedReason = `the witness holds seals for ledger ${[...held.keys()].join(', ')}, and this directory holds ledger ${chain || 'none'}`;
-      } else if (!seqs.length) verdict.sealedReason = `not on ${ref}: the witness holds no seal for ledger ${chain || 'none'}`;
-      for (const seq of verdict.sealed === false ? [] : seqs) {
-        const name = `${seq}.dsse.json`;
-        const w = readWitnessed(anchorGit, ref, `${chain}/${name}`, env);
-        let ws;
-        try { ws = decodeSeal(w.text); } catch (e) { verdict.sealed = false; verdict.sealedReason = `the witnessed ${name} is not a seal: ${e.message}`; break; }
-        const a = agrees(ws, recs);
-        if (!a.ok) { verdict.sealed = false; verdict.sealedReason = `witnessed ${name}: ${a.why}`; break; }
-        const sigs = signaturesOf(ws, allowed);
-        const good = sigs.some((x) => x.valid === true);
-        const bad = sigs.every((x) => x.valid === false);
-        verdict.seals.push({ seal: name, witnessed: true, local: localSeqs.has(seq), length: ws.length, signed: good });
-        if (bad) { verdict.sealed = false; verdict.sealedReason = `witnessed ${name} carries no signature from an allowed signer`; break; }
-        if (good) newestOk = ws;
-      }
-      for (const s of local) if (s.chain === chain && !seqs.includes(s.seq)) verdict.seals.push({ seal: s.name, witnessed: false, reason: `not on ${ref}` });
-      if (verdict.sealed !== false) {
-        if (newestOk) {
-          verdict.sealed = true;
-          verdict.unsealedTail = recs.length - newestOk.length;
-        } else if (!verdict.sealedReason) verdict.sealedReason = allowed ? 'no witnessed seal carries a valid signature' : 'no allowed signers were given';
-      }
-    }
-  } else verdict.sealedReason = 'no witness was named';
+  const accept = accepting(recs, allowed);
+  const results = [];
+  if (anchorGit) results.push(gitWitness({ repo: anchorGit, ref: anchorRef || '@{upstream}', pin: anchorPin, recs, local, accept, allowed, verdict, env }));
+  if (tsr) results.push(tsrWitness({ dir, tsr, ca: tsaCa, local, accept, verdict, env }));
+  if (cosign) results.push(cosignWitness({ ...cosign, local, accept, verdict, env }));
+  const contradicted = results.find((r) => r.sealed === false);
+  const confirmed = results.filter((r) => r.sealed === true);
+  if (contradicted) {
+    verdict.sealed = false;
+    verdict.sealedReason = contradicted.reason;
+  } else if (confirmed.length) {
+    verdict.sealed = true;
+    verdict.unsealedTail = recs.length - Math.max(...confirmed.map((r) => r.seal.length));
+  } else verdict.sealedReason = results.length ? results.map((r) => r.reason).join('; ') : 'no witness was named';
 
   verdict.verified = verdict.broken.length === 0;
   verdict.exit = !verdict.verified || verdict.sealed === false ? 1

package/lib/exec-reading.mjs

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// One reading of an EXEC block for every rule set and the flow engine, and the one the precompiler's
+// table names: each option's argument tokens, every word in order, and for EXEC CICS the command the
+// table names it and the direction each option's data moves. Cached per block, so a worker that
+// rebuilds a program's parse reads each block exactly as the main thread does.
+import { cicsCommand } from './precompile-cics.mjs';
+import { CICS_COMMANDS, CICS_EVERY_COMMAND } from './cics-commands.mjs';
+
+const readings = new WeakMap();
+
+// `opts` maps each option to the tokens inside its parentheses, the first time it is written; `words`
+// is every word of the block. `verb` and `sub` are the command's first two words: the table's name
+// where it has one (SEND MAP however its options are ordered), else the block's first two words.
+export function execReading(exec) {
+  let r = readings.get(exec);
+  if (r) return r;
+  const toks = exec.toks;
+  const opts = new Map();
+  const words = [];
+  const top = [];
+  let depth = 0;
+  for (let i = 0; i < toks.length; i++) {
+    const t = toks[i];
+    if (t.t === 'sep') { depth += t.v === '(' ? 1 : t.v === ')' ? -1 : 0; continue; }
+    if (t.t !== 'word') continue;
+    words.push(t.u);
+    if (depth === 0) top.push({ word: t.u });
+    if (toks[i + 1] && toks[i + 1].t === 'sep' && toks[i + 1].v === '(') {
+      const inner = [];
+      let d = 1;
+      for (let k = i + 2; k < toks.length && d > 0; k++) {
+        if (toks[k].t === 'sep') { d += toks[k].v === '(' ? 1 : -1; if (d === 0) break; continue; }
+        inner.push(toks[k]);
+      }
+      if (!opts.has(t.u)) opts.set(t.u, inner);
+    }
+  }
+  const command = exec.kind === 'CICS' && top.length ? cicsCommand(top) : null;
+  const named = command ? command.split(' ') : [];
+  const entry = command ? CICS_COMMANDS[command] : null;
+  r = {
+    opts, words, command,
+    verb: named[0] || words[0],
+    sub: named.length > 1 ? named[1] : words[1],
+    // The way an option's data moves, as the table records it: sends, receives, both, label or none;
+    // null for an option or a command the table does not hold.
+    direction: (option) => (entry ? entry.options[option] || CICS_EVERY_COMMAND[option] || entry.anyOption || null : null),
+  };
+  readings.set(exec, r);
+  return r;
+}

package/lib/execution.mjs

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 // Execution: whether the estate's own runs entered the paragraph a finding is in, from the
 // reports `ironwork run --coverage` writes. A finding in a paragraph a run entered is code the tests
-// exercise; one in a paragraph no run entered is code they never reach. See docs/spec/evidence.md §13.4 (execution coverage).
+// exercise; one in a paragraph no run entered is code they never reach. See docs/spec/evidence.md §13.5 (execution coverage).
 import { readFileSync } from 'node:fs';
 import { basename, delimiter, join } from 'node:path';
 
@@ -11,7 +11,8 @@ export function executionFeedPaths(opts = {}) {
 }
 
 // One report: per PROGRAM-ID, each paragraph's source line, name and how often a run entered it.
-// Shape (ironwork's): { programs: [{ program, detail: [{ name, line, entered }] }] }.
+// Shape (ironwork's): { programs: [{ program, detail: [{ name, line, entered }] }] }, as
+// schema/cobolwork-execution.schema.json describes it.
 export function loadExecutionFeed(path) {
   const feed = { file: basename(path), programs: new Map(), problem: null };
   let doc;

package/lib/explain.mjs

@@ -8,6 +8,7 @@ import { REGISTRY } from './kernel/registry.mjs';
 import { WHO_ACTS } from './tui/model.mjs';
 import { verificationPlan } from './verify.mjs';
 import { cobolCard, statementCard } from './cards.mjs';
+import { EXPLAIN_SCHEMA_VERSION } from './version.mjs';
 
 const HIDDEN_RULES = new Set(Object.keys(REGISTRY.find((s) => s.name === 'hidden').rules));
 
@@ -151,6 +152,7 @@ export function explainFinding(report, fingerprint, { root }) {
 
   return {
     tool: 'cobolwork-explain',
+    schemaVersion: EXPLAIN_SCHEMA_VERSION,
     carriesSource: true,
     note: NOTE,
     fingerprint,

package/lib/exploitability.mjs

@@ -13,6 +13,7 @@ import { kindsOf } from './consequence.mjs';
 import { WHO } from './sets/flow.mjs';
 import { entryName, accessOfEntry, accessFromEntry, privilegedFromEntry } from './reach.mjs';
 import { verifyEvidence } from './evidence/verify.mjs';
+import { versionProblem, unknownKeys, ignoredKey } from './kernel/version-key.mjs';
 
 export const HANDLING = 'This report joins routes an attacker can drive with the estate\'s own access facts. It holds no source '
   + 'text, but it is a list of what to attack first: keep it where the access records it was built from may go, and do not '
@@ -20,7 +21,7 @@ export const HANDLING = 'This report joins routes an attacker can drive with the
 
 // A system response is not input, but the caller who provokes the failure is the one who reads it back.
 const DRIVER = { ...WHO, 'system-response': 'A web caller, who can provoke the failure and reads the code sent back' };
-const AT_REST = { 'file-record': 'the file record', database: 'the database row' };
+const AT_REST = { 'file-record': 'the file record', 'cics-queue': 'the queue item', database: 'the database row' };
 
 const at = (x) => `${x.file}:${x.line}`;
 
@@ -167,6 +168,9 @@ export function witnessFeedPaths(opts = {}) {
 }
 
 const OUTCOMES = new Set(['reproduced', 'not-reproduced']);
+export const WITNESS_VERSION = 1;
+const WITNESS_KEYS = new Set(['$schema', 'version', 'witness', 'recorded', 'results']);
+const RESULT_KEYS = new Set(['outcome', 'by', 'on', 'system', 'reference', 'evidence']);
 const str = (v) => typeof v === 'string' && v.length > 0;
 const isoDate = (v) => typeof v === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(v);
 
@@ -198,7 +202,7 @@ function witnessedRun(ev, base, verdicts) {
 //   { witness, recorded, results: { FINGERPRINT: { outcome: "reproduced"|"not-reproduced", by, on, system, reference? } } }
 // Only those fields are read. What was sent to the system is not one of them.
 export function loadWitnessFeed(path, { root = null } = {}) {
-  const feed = { file: basename(path), witness: null, recorded: null, results: new Map(), refused: [], problem: null };
+  const feed = { file: basename(path), witness: null, recorded: null, results: new Map(), refused: [], warnings: [], problem: null };
   let real;
   try { real = realpathSync(path); } catch (e) { feed.problem = `could not be read (${e.code || e.name})`; return feed; }
   if (root) {
@@ -207,11 +211,16 @@ export function loadWitnessFeed(path, { root = null } = {}) {
   }
   let doc;
   try { doc = JSON.parse(readFileSync(real, 'utf8')); } catch (e) { feed.problem = `is not JSON (${e.message})`; return feed; }
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) { feed.problem = 'is not a JSON object'; return feed; }
+  feed.problem = versionProblem(doc, WITNESS_VERSION);
+  if (feed.problem) return feed;
   if (!str(doc.witness)) { feed.problem = 'does not say whose tests it holds'; return feed; }
   if (!isoDate(doc.recorded)) { feed.problem = 'does not say when it was recorded'; return feed; }
   if (!doc.results || typeof doc.results !== 'object' || Array.isArray(doc.results)) { feed.problem = 'holds no results'; return feed; }
   feed.witness = doc.witness;
   feed.recorded = doc.recorded;
+  const extra = new Set(Object.values(doc.results).flatMap((r) => (r && typeof r === 'object' ? unknownKeys(r, RESULT_KEYS) : [])));
+  feed.warnings = [...unknownKeys(doc, WITNESS_KEYS).map((k) => ignoredKey(feed.file, k)), ...[...extra].sort().map((k) => ignoredKey(`${feed.file} results`, k))];
   const verdicts = new Map();
   for (const [fingerprint, r] of Object.entries(doc.results)) {
     const why = !r || typeof r !== 'object' ? 'is not an object'

package/lib/hlasm/asm/data.mjs

@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// DC and DS operands, and literals, which are DC operands after an equals sign: duplication factor,
+// type and type extension, program type, length, scale and exponent modifiers, and nominal value.
+// https://www.ibm.com/docs/en/hla-and-tf/1.6.0?topic=statements-dc-instruction
+import { HlasmSyntax, splitOperands } from '../operands.mjs';
+import { parseExpression, readExpression } from '../expr.mjs';
+
+const EXTENSIONS = {
+  C: 'AEU', G: '', X: '', B: '', F: 'D', H: '', E: 'HBD', D: 'HBD', L: 'HBDQ', P: '', Z: '',
+  A: 'D', Y: '', S: 'Y', V: 'D', Q: 'DY', J: 'D', R: 'D',
+};
+const ADDRESS_TYPES = new Set(['A', 'Y', 'S', 'V', 'Q', 'J', 'R']);
+
+// A parenthesised expression or a decimal number, as a duplication factor or a modifier is written.
+function amount(text, pos) {
+  if (text[pos] === '(') {
+    const { e, end } = readExpression(text, pos + 1);
+    if (text[end] !== ')') throw new HlasmSyntax(`expected ) at column ${end + 1} of '${text}'`);
+    return { value: { t: 'paren', e }, end: end + 1 };
+  }
+  const m = /^\d+/.exec(text.slice(pos));
+  if (!m) return null;
+  return { value: { t: 'num', v: Number(m[0]) }, end: pos + m[0].length };
+}
+
+function quotedNominal(text, pos) {
+  let out = '';
+  for (let i = pos + 1; i < text.length; i++) {
+    if (text[i] === "'") {
+      if (text[i + 1] === "'") { out += "'"; i++; continue; }
+      return { value: out, end: i + 1 };
+    }
+    if (text[i] === '&' && text[i + 1] === '&') i++;
+    out += text[i];
+  }
+  throw new HlasmSyntax(`a nominal value is not closed in '${text}'`);
+}
+
+function addressNominal(text, pos) {
+  const items = [];
+  let at = pos + 1;
+  for (;;) {
+    const { e, end } = readExpression(text, at);
+    at = end;
+    if (text[at] === '(') {
+      const close = text.indexOf(')', at);
+      if (close < 0) throw new HlasmSyntax(`a base register is not closed in '${text}'`);
+      items.push({ t: 'address', disp: e, base: text.slice(at + 1, close) });
+      at = close + 1;
+    } else items.push(e);
+    if (text[at] === ',') { at++; continue; }
+    if (text[at] === ')') return { value: items, end: at + 1 };
+    throw new HlasmSyntax(`expected , or ) at column ${at + 1} of '${text}'`);
+  }
+}
+
+// One DC operand starting at pos: the operand, and where it ended. A literal needs a nominal value
+// and a duplication factor that is not zero.
+export function readDataOperand(text, pos = 0, { literal = false, nominalRequired = literal } = {}) {
+  const operand = { dup: null, type: null, ext: null, program: null, length: null, bitLength: false, scale: null, exponent: null, nominal: null };
+  let at = pos;
+  const dup = amount(text, at);
+  if (dup) { operand.dup = dup.value; at = dup.end; }
+  const type = (text[at] || '').toUpperCase();
+  if (!(type in EXTENSIONS)) throw new HlasmSyntax(`'${text.slice(pos)}' has no constant type a DC operand can have`);
+  operand.type = type;
+  at++;
+  const ext = (text[at] || '').toUpperCase();
+  if (ext && EXTENSIONS[type].includes(ext)) { operand.ext = ext; at++; }
+  if ((text[at] || '').toUpperCase() === 'P' && text[at + 1] === '(') {
+    const p = amount(text, at + 1);
+    operand.program = p.value;
+    at = p.end;
+  }
+  for (const [letter, key] of [['L', 'length'], ['S', 'scale'], ['E', 'exponent']]) {
+    if ((text[at] || '').toUpperCase() !== letter) continue;
+    let from = at + 1;
+    if (key === 'length' && text[from] === '.') { operand.bitLength = true; from++; }
+    const sign = key !== 'length' && (text[from] === '-' || text[from] === '+') ? text[from++] : '';
+    const m = amount(text, from);
+    if (!m) throw new HlasmSyntax(`the ${key} modifier in '${text}' has no value`);
+    operand[key] = sign === '-' ? { t: 'unary', op: '-', e: m.value } : m.value;
+    at = m.end;
+  }
+  if (text[at] === "'") {
+    if (ADDRESS_TYPES.has(type)) throw new HlasmSyntax(`a ${type}-type constant takes its value in parentheses, not quotes, in '${text}'`);
+    const n = quotedNominal(text, at);
+    operand.nominal = { quoted: n.value };
+    at = n.end;
+  } else if (text[at] === '(') {
+    if (!ADDRESS_TYPES.has(type)) throw new HlasmSyntax(`a ${type}-type constant takes its value in quotes, not parentheses, in '${text}'`);
+    const n = addressNominal(text, at);
+    operand.nominal = { expressions: n.value };
+    at = n.end;
+  }
+  // A DC operand may omit its nominal value only when its duplication factor is zero.
+  const zeroDup = operand.dup && operand.dup.t === 'num' && operand.dup.v === 0;
+  if (nominalRequired && !operand.nominal && !(zeroDup && !literal)) throw new HlasmSyntax(`'${text.slice(pos, at)}' has no nominal value`);
+  if (literal && operand.dup && operand.dup.t === 'num' && operand.dup.v === 0) throw new HlasmSyntax('a literal cannot have a duplication factor of zero');
+  return { operand, end: at };
+}
+
+function operands(st, nominalRequired) {
+  const list = splitOperands(st.field || '');
+  if (!list.length) throw new HlasmSyntax(`${st.operation} has no operand`);
+  return list.map((text) => {
+    const { operand, end } = readDataOperand(text, 0, { nominalRequired });
+    if (end !== text.length) throw new HlasmSyntax(`unexpected '${text.slice(end)}' after the operand '${text.slice(0, end)}'`);
+    return operand;
+  });
+}
+
+// A channel command word: command code, data address, flags and data count, each an expression.
+// https://www.ibm.com/docs/en/hla-and-tf/1.6.0?topic=statements-ccw-ccw0-instructions
+function ccw(st) {
+  const list = splitOperands(st.field || '');
+  if (list.length !== 4) throw new HlasmSyntax(`${st.operation} takes a command code, data address, flags and data count, not ${list.length} operands`);
+  const [command, address, flags, count] = list.map((text) => parseExpression(text.trim()));
+  return { kind: st.operation, command, address, flags, count };
+}
+
+export const parsers = {
+  DC: (st) => ({ kind: 'DC', operands: operands(st, true) }),
+  DS: (st) => ({ kind: 'DS', operands: operands(st, false) }),
+  CCW: ccw,
+  CCW0: ccw,
+  CCW1: ccw,
+};

package/lib/hlasm/asm/listing.mjs

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Parsers for HLASM listing instructions: PRINT, TITLE, EJECT, SPACE, CEJECT.
+
+import { HlasmSyntax, splitOperands } from '../operands.mjs';
+import { parseExpression } from '../expr.mjs';
+
+const PRINT_OPTS = new Set(['ON', 'OFF', 'GEN', 'NOGEN', 'DATA', 'NODATA', 'MCALL', 'NOMCALL', 'MSOURCE', 'NOMSOURCE', 'UHEAD', 'NOUHEAD', 'NOPRINT']);
+
+export const parsers = {
+  PRINT(st) {
+    const ops = splitOperands(st.field);
+    if (ops.length === 0) throw new HlasmSyntax('PRINT requires at least one option');
+    const options = ops.map(o => o.trim().toUpperCase());
+    for (const opt of options) {
+      if (!PRINT_OPTS.has(opt)) throw new HlasmSyntax(`unknown PRINT option: ${opt}`);
+    }
+    return { kind: 'PRINT', options };
+  },
+  TITLE(st) {
+    const ops = splitOperands(st.field);
+    if (ops.length !== 1) throw new HlasmSyntax('TITLE requires exactly one operand');
+    const raw = ops[0].trim();
+    if (!raw.startsWith("'") || !raw.endsWith("'") || raw.length < 2) throw new HlasmSyntax('TITLE operand must be a quoted string');
+    const text = raw.slice(1, -1).replace(/''/g, "'").replace(/&&/g, "&");
+    return { kind: 'TITLE', name: st.name, text };
+  },
+  EJECT(st) {
+    if (st.field.trim() !== '') throw new HlasmSyntax('EJECT takes no operand');
+    return { kind: 'EJECT', value: null };
+  },
+  SPACE(st) {
+    const ops = splitOperands(st.field);
+    if (ops.length === 0) return { kind: 'SPACE', value: null };
+    if (ops.length > 1) throw new HlasmSyntax('SPACE takes at most one operand');
+    return { kind: 'SPACE', value: parseExpression(ops[0].trim()) };
+  },
+  CEJECT(st) {
+    const ops = splitOperands(st.field);
+    if (ops.length === 0) return { kind: 'CEJECT', value: null };
+    if (ops.length > 1) throw new HlasmSyntax('CEJECT takes at most one operand');
+    return { kind: 'CEJECT', value: parseExpression(ops[0].trim()) };
+  }
+};

package/lib/hlasm/asm/output.mjs

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Assembler instructions that write messages, copy source in or shape the input records: MNOTE,
+// COPY, PUNCH, REPRO, AINSERT, ICTL and ISEQ.
+// https://www.ibm.com/docs/en/hla-and-tf/1.6.0?topic=instructions-mnote-instruction
+import { HlasmSyntax, NAME, splitOperands } from '../operands.mjs';
+import { parseExpression } from '../expr.mjs';
+
+// A quoted string's text, '' read as one quote and && as one ampersand.
+function quoted(text, what) {
+  const m = /^'((?:[^']|'')*)'$/.exec(text.trim());
+  if (!m) throw new HlasmSyntax(`${what} needs a quoted string, not ${text}`);
+  return m[1].replace(/''/g, "'").replace(/&&/g, '&');
+}
+
+const numbers = (st, min, max) => {
+  const ops = splitOperands(st.field || '');
+  if (ops.length < min || ops.length > max || ops.some((o) => !/^\d+$/.test(o.trim()))) throw new HlasmSyntax(`${st.operation} takes ${min} to ${max} decimal numbers, not ${st.field || 'none'}`);
+  return { kind: st.operation, values: ops.map(Number) };
+};
+
+export const parsers = {
+  // [severity,]'message': severity is an absolute expression, *, or empty before the comma.
+  MNOTE: (st) => {
+    const ops = splitOperands(st.field || '');
+    if (ops.length < 1 || ops.length > 2) throw new HlasmSyntax(`MNOTE takes a message and an optional severity, not ${ops.length} operands`);
+    const [sev, msg] = ops.length === 2 ? ops : [null, ops[0]];
+    const severity = sev === null || sev.trim() === '' ? null : sev.trim() === '*' ? '*' : parseExpression(sev.trim());
+    return { kind: 'MNOTE', severity, text: quoted(msg, 'MNOTE') };
+  },
+  COPY: (st) => {
+    const member = (st.field || '').trim();
+    if (!NAME.test(member)) throw new HlasmSyntax(`COPY names a member, not ${member || 'nothing'}`);
+    return { kind: 'COPY', member: member.toUpperCase() };
+  },
+  PUNCH: (st) => ({ kind: 'PUNCH', text: quoted(st.field || '', 'PUNCH') }),
+  REPRO: () => ({ kind: 'REPRO' }),
+  // 'record'[,FRONT|BACK]: a record put into the assembler's input stream.
+  AINSERT: (st) => {
+    const ops = splitOperands(st.field || '');
+    if (ops.length !== 2 || !/^(FRONT|BACK)$/i.test(ops[1].trim())) throw new HlasmSyntax('AINSERT takes a quoted record and FRONT or BACK');
+    return { kind: 'AINSERT', text: quoted(ops[0], 'AINSERT'), where: ops[1].trim().toUpperCase() };
+  },
+  ICTL: (st) => numbers(st, 1, 3),
+  ISEQ: (st) => (st.field ? numbers(st, 2, 2) : { kind: 'ISEQ', values: [] }),
+};