@henols/c64-re-tools 2.0.0-rc.9 → 2.0.1

package/skills/c64-knowledge/scripts/knowledge.ts

@@ -1,28 +1,51 @@
-// The c64-knowledge script: reads and writes .c64-re-tools/knowledge.db in the
-// project directory (the working directory) and prints one compact JSON result.
+// The c64-knowledge script: reads and writes .c64-re-tools/knowledge/ in the
+// project folder (--project, or the one found from the working directory) and
+// prints one compact JSON result.
 
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
+import { join } from "node:path";
 import type { DatabaseSync } from "node:sqlite";
 import { parseArgs } from "node:util";
 
-import { formatC64Address, parseC64Address } from "#src/c64.ts";
+import { formatC64Address, parseC64Address, SYMBOL_NAME } from "#src/c64.ts";
+import { ImageError, readImage } from "#src/host-client/image.ts";
 import { readProjectFile, writeProjectFile } from "#src/host-client/transfer.ts";
+import { CONFLICT_RULES, conflicts, type Conflict } from "#src/knowledge/conflicts.ts";
+import { joinBatches, type Batch, type JoinChoice, type JoinClash } from "#src/knowledge/join.ts";
 import { KnowledgeError, openForRead, withWrite } from "#src/knowledge/database.ts";
-import { historyAt, historyNamed, revision, revisionNote, revisions, type HistoryEntry } from "#src/knowledge/history.ts";
+import { operandText } from "#src/knowledge/expression.ts";
+import { historyAt, historyNamed, historyOfMacro, revision, revisionNote, revisions, type HistoryEntry } from "#src/knowledge/history.ts";
 import {
   at,
+  analyzerNamed,
+  analyzerNamesAt,
+  commentsAt,
   currentRevision,
+  listAnalyzerNames,
   listComments,
+  listMacros,
+  listMacroUses,
   listModules,
+  listOperands,
+  listPatches,
   listSpaces,
   listReferences,
   listRegions,
   listSuppressions,
   listSymbols,
+  operandAt,
+  referencesFrom,
+  referencesTo,
   search,
+  symbolAt,
+  symbolNamed,
   type CommentRow,
+  type MacroRow,
+  type MacroUseRow,
   type ModuleRow,
+  type OperandRow,
+  type PatchRow,
   type ReferenceRow,
   type RegionRow,
   type SuppressionRow,
@@ -32,12 +55,14 @@ import {
   COMMENT_PLACEMENTS,
   DEFAULT_SPACE,
   EVIDENCE_KINDS,
+  OPERAND_SELECTS,
   ORIGINS,
   REFERENCE_KINDS,
   REGION_TYPES,
   SPACE,
   SYMBOL_KINDS,
   type CommentPlacement,
+  type OperandSelect,
   type Origin,
   type ReferenceKind,
   type RegionType,
@@ -47,37 +72,70 @@ import {
   addReference,
   applyBatch,
   classifyRegion,
+  mergeConflicts,
   removeComment,
+  removeMacro,
+  removeMacroUse,
   removeModule,
+  removeOperand,
+  removePatch,
   removeReference,
   removeSymbol,
   renameSymbol,
   revert,
   setComment,
+  setMacro,
+  setMacroUse,
   setModule,
+  setOperand,
+  setPatch,
   unclassifyRegion,
   type BatchOperation,
+  type BatchStep,
   type Evidence,
+  type MergeChoice,
+  type OperandImage,
   type WriteContext,
 } from "#src/knowledge/write.ts";
+import { platformNames } from "#src/platform.ts";
+import { addCoverage, coverageRuns, programCoverage, programImage, requireProgram, setImage, type ImageRequest } from "#src/knowledge/program.ts";
+import { WireFailure } from "#src/host-client/tools.ts";
+import { isInside, LOCAL_DIRECTORY, PROJECT_DIRECTORY, projectRelative, projectRoot, resolveProjectPath } from "#src/project.ts";
+import { listing, listingText, type ListingSource } from "./lib/listing.ts";
 import { runScript, UsageError } from "#src/script.ts";
 
 const USAGE = `knowledge.ts <command> [arguments] [options]
 
 Read (no database needed):
   at <address>                        everything known at one address
-  search <text>                       symbol names and comment texts
-  symbols [--start A --end A --kind K --origin O]
+  search <text>                       symbol names, analyzer names and comment texts
+  symbols [--start A --end A --kind K --origin O] [--analyzer]
+                                      --analyzer: the second names that DXA, Ghidra
+                                      and the idioms gave
   regions [--start A --end A --type T --origin O]
   comments [--start A --end A --origin O]
   references [--start A --end A --kind K --origin O]
   suppressions [--start A --end A]   places that removals keep free of analyzer facts
   modules [--start A --end A --origin O]   where the files of generated source start
+  operands [--start A --end A --origin O]  operand expressions of instructions
+  patches [--start A --end A --switch S --origin O]   code that a switch puts in
+  switches                            each switch with the ranges of its patches
+  macros [--origin O]                 the macros of the generated source
+  uses [--start A --end A --macro M --origin O]   instructions written as a macro
   spaces                              the address spaces that hold knowledge
-  history <address> | history --name <name>
-  revisions [--limit N --before N]
-  revision <id>
+  program                             the program in the knowledge: its
+                                      segments and entry, and the coverage maps
+                                      that coverage imported, with the ranges
+  history <address> | history --name <name> | history --macro <name>
+  revisions [--limit N --before R]
+  revision <revision>
   export --out <file> [--start A --end A --origin O]   all current knowledge to a project file
+  listing <start> <end> [--out <file>]
+                                      the program as ACME lines with names, operand
+                                      expressions, comments, the access of each line
+                                      in the coverage (x executed, r read, w written)
+                                      and the references in and out; --out writes it
+                                      as text
 
 Every command takes --space S: c64 (the default), drive8 for code in the 1541
 drive, or bank0 to bank255 for cartridge banks. A write in a batch can name its
@@ -86,7 +144,7 @@ own space.
 Read option --origin O: user, llm, dxa, ghidra, heuristic, semantic (user and
 llm) or analyzer (dxa, ghidra and heuristic), or a comma list. search takes it too.
 
-Write (one revision each; creates the database when needed):
+Write (one revision each; creates .c64-re-tools/knowledge/ when needed):
   rename <address> <name> [--kind K]
   remove-symbol <address>
   classify <start> <end> <type> [--element N]
@@ -97,25 +155,86 @@ Write (one revision each; creates the database when needed):
   unreference <from> <to> <kind>
   module <start> <file.asm> [--title T]   a file of generated source starts here
   unmodule <start>
+  operand <address> --lo|--hi|--value <symbol> [--offset N]
+  operand <address> --expr <text>
+                           write the operand of the instruction at <address> as
+                           an expression: the low or high byte of symbol + N, the
+                           value symbol + N, or ACME expression text; refused when
+                           it does not give the operand in the program of the
+                           knowledge; give a negative offset as --offset=-1
+  unoperand <address>
+  patch <start> <end> <SWITCH> --code <text>|--code-file <file>|--nop [--comment T]
+                           ACME code that replaces <start>-<end> when the build
+                           defines SWITCH as 1 (c64-assembler --define SWITCH=1);
+                           NOP fills the rest of the range; --nop puts only NOP
+  unpatch <start>
+  macro <name> [--params a,b] --body <text>|--body-file <file> [--comment T]
+                           an ACME macro; the body names a param with a dot: .a
+  unmacro <name>
+  use <start> <end> <macro> [--args "x, y"]
+                           write the instructions <start>-<end> as one use of
+                           the macro, with one expression for each param
+  unuse <start>
+  image <image.json|prg>   put the program into the knowledge: its bytes, and
+                           for an image.json of c64-unpacker capture also the
+                           entry, the entry state and the stages; with --space for
+                           drive code or a cartridge bank. Only changed bytes write
+  coverage <map.bin>...    join coverage maps of c64_memmap or a run into the
+                           coverage of the knowledge; each map is evidence
+                           of the revision, named by its path
   revert <revision>
+  merge                    decide the conflicts that a git merge of two
+                           computers' work left: of the rows of one conflict,
+                           the newest stays; one revision for all
+  join <batch>... --out <file>
+                           join the batches of agents that worked in parallel into
+                           one batch for apply; writes no knowledge. A batch is a
+                           list of writes, or {"owner": "$1000-$1fff", "ops": [...]}:
+                           at an address in its owner range its name, comment,
+                           operand and module win, and its regions come last
   apply <file>             many writes from a JSON file ('-' reads standard input),
-                           all as one revision, or none when one is refused
+                           all as one revision, or none when one is refused;
+                           operand, patch and use writes are checked against the
+                           program of --space in the knowledge
 
 Write options:
   --reason <text>          why, kept with the revision
-  --evidence <kind:ref>    what the change rests on: coverage:<file>, test:<file>,
-                           file:<file> or note:<text> (repeatable)
-  --expect-revision <N>    refuse the write if knowledge changed after revision N
+  --evidence <kind:ref>    what the change rests on: coverage:<map> (a map that
+                           coverage imported), test:<file>, file:<file> or
+                           note:<text> (repeatable)
+  --expect-revision <R>    refuse the write if knowledge changed after revision R
   --origin user|llm        who decided (default llm)
 
-Addresses are $ and four hex digits; quote them in a shell: '$2100'.`;
+Addresses are $ and four hex digits; quote them in a shell: '$2100'. A name
+also gives an address: a symbol name first, then an analyzer name.
+A revision is its id, for example 20261015T214501.123-k3f9qz, or a start of
+the id that only one revision has; 0 is the knowledge before every revision.`;
 
+/** The space whose names give addresses: the --space of the command. */
+let nameSpace = DEFAULT_SPACE;
+
+/** An address as $ and four hex digits, or the address of a symbol name, else of an analyzer name. */
 function address(value: string | undefined, what = "address"): number {
   if (value === undefined) throw new UsageError(`${what} is missing`);
+  if (SYMBOL_NAME.test(value)) return addressOfName(value, what);
   try {
     return parseC64Address(value);
   } catch {
-    throw new UsageError(`${what} must be $ followed by four hex digits, for example '$2100', not ${value}`);
+    throw new UsageError(`${what} must be $ followed by four hex digits, for example '$2100', or a name, not ${value}`);
+  }
+}
+
+function addressOfName(name: string, what: string): number {
+  const db = openForRead();
+  try {
+    const symbol = symbolNamed(db, name, nameSpace);
+    if (symbol !== undefined) return symbol.address;
+    const second = analyzerNamed(db, name, nameSpace);
+    if (second.length === 1) return second[0]!.address;
+    if (second.length > 1) throw new UsageError(`${what}: the analyzers give ${name} to ${second.map((row) => `${formatC64Address(row.address)} (${row.origin})`).join(" and ")}; give the address`);
+    throw new UsageError(`${what}: no symbol or analyzer name is ${name}`);
+  } finally {
+    db?.close();
   }
 }
 
@@ -130,7 +249,7 @@ function integer(value: string | undefined, what: string): number {
 }
 
 // Output shapes: addresses as $xxxx, nothing internal.
-/** The space of a row, shown only when it is not the C64 (D53). */
+/** The space of a row, shown only when it is not the C64. */
 const spaceOf = (row: { space: string }) => (row.space === "c64" ? {} : { space: row.space });
 const symbol = (row: SymbolRow) => ({ ...spaceOf(row), address: formatC64Address(row.address), name: row.name, kind: row.kind, origin: row.origin, revision: row.revision });
 const region = (row: RegionRow) => ({
@@ -144,6 +263,39 @@ const region = (row: RegionRow) => ({
 });
 const comment = (row: CommentRow) => ({ ...spaceOf(row), address: formatC64Address(row.address), placement: row.placement, text: row.text, origin: row.origin, revision: row.revision });
 const module = (row: ModuleRow) => ({ ...spaceOf(row), start: formatC64Address(row.start), file: row.file, ...(row.title === undefined ? {} : { title: row.title }), origin: row.origin, revision: row.revision });
+const operand = (row: OperandRow) => ({
+  ...spaceOf(row),
+  address: formatC64Address(row.address),
+  select: row.select,
+  ...(row.symbol === undefined ? {} : { symbol: row.symbol }),
+  ...(row.offset === 0 ? {} : { offset: row.offset }),
+  ...(row.expression === undefined ? {} : { expression: row.expression }),
+  text: operandText(row),
+  origin: row.origin,
+  revision: row.revision,
+});
+const patch = (row: PatchRow) => ({
+  ...spaceOf(row),
+  start: formatC64Address(row.start),
+  end: formatC64Address(row.end),
+  bytes: row.end - row.start + 1,
+  switch: row.switch,
+  code: row.code,
+  ...(row.comment === undefined ? {} : { comment: row.comment }),
+  origin: row.origin,
+  revision: row.revision,
+});
+const macro = (row: MacroRow) => ({ ...spaceOf(row), name: row.name, params: row.params, body: row.body, ...(row.comment === undefined ? {} : { comment: row.comment }), origin: row.origin, revision: row.revision });
+const macroUse = (row: MacroUseRow) => ({
+  ...spaceOf(row),
+  start: formatC64Address(row.start),
+  end: formatC64Address(row.end),
+  macro: row.macro,
+  args: row.args,
+  text: `+${row.macro}${row.args.length === 0 ? "" : ` ${row.args.join(", ")}`}`,
+  origin: row.origin,
+  revision: row.revision,
+});
 const reference = (row: ReferenceRow) => ({ ...spaceOf(row), from: formatC64Address(row.from), to: formatC64Address(row.to), kind: row.kind, origin: row.origin, revision: row.revision });
 function suppression(row: SuppressionRow) {
   const place =
@@ -157,7 +309,7 @@ function suppression(row: SuppressionRow) {
 
 function historyEntry(entry: HistoryEntry) {
   const shown =
-    entry.entity === "symbol"
+    entry.entity === "symbol" || entry.entity === "analyzer-name"
       ? symbol(entry.row)
       : entry.entity === "region"
         ? region(entry.row)
@@ -167,14 +319,32 @@ function historyEntry(entry: HistoryEntry) {
             ? reference(entry.row)
             : entry.entity === "module"
               ? module(entry.row)
-              : suppression(entry.row);
+              : entry.entity === "operand"
+                ? operand(entry.row)
+                : entry.entity === "patch"
+                  ? patch(entry.row)
+                  : entry.entity === "macro"
+                    ? macro(entry.row)
+                    : entry.entity === "macro-use"
+                      ? macroUse(entry.row)
+                      : suppression(entry.row);
   const { revision: _revision, ...row } = shown;
   return { entity: entry.entity, ...row, fromRevision: entry.from, ...(entry.to === undefined ? {} : { toRevision: entry.to }) };
 }
 
+/** A conflict of a git merge: what is wrong, and the rows, oldest first. */
+function showConflict(conflict: Conflict) {
+  return { conflict: CONFLICT_RULES[conflict.rule], ...spaceOf(conflict), rows: conflict.rows.map(historyEntry) };
+}
+
+/** What merge decided for one conflict: the row that stays and the rows it closed. */
+function showChoice(choice: MergeChoice) {
+  return { conflict: CONFLICT_RULES[choice.rule], ...spaceOf(choice), kept: historyEntry(choice.kept), closed: choice.closed.map(historyEntry) };
+}
+
 /** The reason of each revision that wrote one of the rows. */
-function reasonsOf(db: DatabaseSync | undefined, rows: SuppressionRow[]): Map<number, string> {
-  const reasons = new Map<number, string>();
+function reasonsOf(db: DatabaseSync | undefined, rows: SuppressionRow[]): Map<string, string> {
+  const reasons = new Map<string, string>();
   const query = db?.prepare("SELECT description FROM revisions WHERE id = ?");
   for (const { revision } of rows) {
     if (query === undefined || reasons.has(revision)) continue;
@@ -205,17 +375,36 @@ function run(argv: string[]): unknown {
       out: { type: "string" },
       title: { type: "string" },
       space: { type: "string" },
+      lo: { type: "string" },
+      hi: { type: "string" },
+      value: { type: "string" },
+      expr: { type: "string" },
+      offset: { type: "string" },
+      code: { type: "string" },
+      "code-file": { type: "string" },
+      nop: { type: "boolean" },
+      comment: { type: "string" },
+      params: { type: "string" },
+      body: { type: "string" },
+      "body-file": { type: "string" },
+      args: { type: "string" },
+      switch: { type: "string" },
+      macro: { type: "string" },
+      analyzer: { type: "boolean" },
       help: { type: "boolean" },
     },
   });
   const [command, ...args] = positionals;
   if (values.help || command === undefined) throw new UsageError("");
-  const range = { start: values.start === undefined ? 0x0000 : address(values.start, "--start"), end: values.end === undefined ? 0xffff : address(values.end, "--end") };
   if (values.space !== undefined && !SPACE.test(values.space)) throw new UsageError("--space must be c64, drive8, or bank0 to bank255");
   const space = values.space ?? DEFAULT_SPACE;
+  nameSpace = space;
+  const range = { start: values.start === undefined ? 0x0000 : address(values.start, "--start"), end: values.end === undefined ? 0xffff : address(values.end, "--end") };
 
-  const read = new Set(["at", "search", "symbols", "regions", "comments", "references", "suppressions", "modules", "spaces", "history", "revisions", "revision", "export"]);
-  const write = new Set(["rename", "remove-symbol", "classify", "unclassify", "comment", "uncomment", "reference", "unreference", "module", "unmodule", "revert", "apply"]);
+  const read = new Set(["at", "search", "symbols", "regions", "comments", "references", "suppressions", "modules", "operands", "patches", "switches", "macros", "uses", "spaces", "program", "history", "revisions", "revision", "export", "listing"]);
+  const write = new Set(["rename", "remove-symbol", "classify", "unclassify", "comment", "uncomment", "reference", "unreference", "module", "unmodule", "operand", "unoperand", "patch", "unpatch", "macro", "unmacro", "use", "unuse", "revert", "apply", "merge", "image", "coverage"]);
+  // join reads batch files and writes one: no knowledge opens.
+  if (command === "join") return joinCommand(args, values.out, space);
   // Refuse a mistyped command before anything opens, so no database appears by accident.
   if (!read.has(command) && !write.has(command)) throw new UsageError(`unknown command: ${command}`);
   if (read.has(command)) {
@@ -223,79 +412,10 @@ function run(argv: string[]): unknown {
     if (command === "export" && values.out === undefined) throw new UsageError("export needs --out <file>");
     const db = openForRead();
     try {
-      switch (command) {
-        case "at": {
-          const known = at(db, address(args[0]), space);
-          return {
-            ...(space === DEFAULT_SPACE ? {} : { space }),
-            address: formatC64Address(known.address),
-            ...(known.symbol === undefined ? {} : { symbol: symbol(known.symbol) }),
-            ...(known.region === undefined ? {} : { region: region(known.region) }),
-            comments: known.comments.map(comment),
-            referencesFrom: known.referencesFrom.map(reference),
-            referencesTo: known.referencesTo.map(reference),
-            ...(known.suppressions.length === 0 ? {} : { suppressions: known.suppressions.map(suppression) }),
-            revision: known.revision,
-          };
-        }
-        case "search": {
-          if (args[0] === undefined || args[0] === "") throw new UsageError("search needs text");
-          const found = search(db, args[0], values.limit === undefined ? 50 : integer(values.limit, "--limit"), origins, space);
-          return { symbols: found.symbols.map(symbol), comments: found.comments.map(comment) };
-        }
-        case "symbols":
-          return { symbols: listSymbols(db, range, values.kind === undefined ? undefined : oneOf(SYMBOL_KINDS, values.kind, "--kind"), origins, space).map(symbol) };
-        case "regions":
-          return { regions: listRegions(db, range, values.type === undefined ? undefined : oneOf(REGION_TYPES, values.type, "--type"), origins, space).map(region) };
-        case "comments":
-          return { comments: listComments(db, range, origins, space).map(comment) };
-        case "references":
-          return { references: listReferences(db, range, values.kind === undefined ? undefined : oneOf(REFERENCE_KINDS, values.kind, "--kind"), origins, space).map(reference) };
-        case "export": {
-          const exported = {
-            revision: currentRevision(db),
-            ...(space === DEFAULT_SPACE ? {} : { space }),
-            symbols: listSymbols(db, range, undefined, origins, space).map(symbol),
-            regions: listRegions(db, range, undefined, origins, space).map(region),
-            comments: listComments(db, range, origins, space).map(comment),
-            references: listReferences(db, range, undefined, origins, space).map(reference),
-            suppressions: listSuppressions(db, range, space).map(suppression),
-            modules: listModules(db, range, origins, space).map(module),
-          };
-          const bytes = Buffer.from(`${JSON.stringify(exported, null, 2)}\n`, "utf8");
-          writeProjectFile(values.out!, bytes, { what: "--out" });
-          return {
-            out: values.out,
-            bytes: bytes.length,
-            counts: { symbols: exported.symbols.length, regions: exported.regions.length, comments: exported.comments.length, references: exported.references.length, suppressions: exported.suppressions.length, modules: exported.modules.length },
-            revision: exported.revision,
-          };
-        }
-        case "suppressions": {
-          const rows = listSuppressions(db, range, space);
-          const reasons = reasonsOf(db, rows);
-          return { suppressions: rows.map((row) => ({ ...suppression(row), ...(reasons.has(row.revision) ? { reason: reasons.get(row.revision) } : {}) })) };
-        }
-        case "modules":
-          return { modules: listModules(db, range, origins, space).map(module) };
-        case "spaces":
-          return { spaces: listSpaces(db) };
-        case "history":
-          // Each row with the reason and the evidence of the revision that wrote it (F-26).
-          return {
-            history: (values.name === undefined ? historyAt(db, address(args[0]), space) : historyNamed(db, values.name, space)).map((entry) => ({ ...historyEntry(entry), ...revisionNote(db, entry.from) })),
-          };
-        case "revisions": {
-          const options: { limit?: number; before?: number } = {};
-          if (values.limit !== undefined) options.limit = integer(values.limit, "--limit");
-          if (values.before !== undefined) options.before = integer(values.before, "--before");
-          return { revisions: revisions(db, options) };
-        }
-        default: {
-          const changes = revision(db, integer(args[0], "revision"));
-          return { revision: changes.revision, added: changes.added.map(historyEntry), closed: changes.closed.map(historyEntry) };
-        }
-      }
+      const answer = readAnswer(db, command, args, values, range, origins, space);
+      const found = conflicts(db);
+      // A git merge can leave conflicts: every read shows them until merge decides them.
+      return found.length === 0 ? answer : { ...answer, conflicts: found.map(showConflict) };
     } finally {
       db?.close();
     }
@@ -303,14 +423,216 @@ function run(argv: string[]): unknown {
 
   const context: WriteContext = { origin: values.origin === undefined ? "llm" : oneOf(["user", "llm"] as const, values.origin, "--origin") };
   if (values.reason !== undefined) context.description = values.reason;
-  if (values["expect-revision"] !== undefined) context.expectedRevision = integer(values["expect-revision"], "--expect-revision");
-  if (values.evidence !== undefined) context.evidence = values.evidence.map(evidenceOf);
+  if (values["expect-revision"] !== undefined) context.expectedRevision = values["expect-revision"];
+  if (values.evidence !== undefined) context.evidence = values.evidence.map((value) => evidenceOf(value, space));
   // Every argument is checked before the database opens: a refused write creates no database.
   if (values.title !== undefined && command !== "module") throw new UsageError("--title works only with module");
-  const operation = command === "apply" ? applyOperation(args, context, space) : writeOperation(command, args, values.kind, values.element, context, values.title, space);
+  for (const option of ["lo", "hi", "value", "expr", "offset"] as const) {
+    if (values[option] !== undefined && command !== "operand") throw new UsageError(`--${option} works only with operand`);
+  }
+  const only: Array<[keyof typeof values, readonly string[]]> = [
+    ["code", ["patch"]],
+    ["code-file", ["patch"]],
+    ["nop", ["patch"]],
+    ["comment", ["patch", "macro"]],
+    ["params", ["macro"]],
+    ["body", ["macro"]],
+    ["body-file", ["macro"]],
+    ["args", ["use"]],
+  ];
+  for (const [option, commands] of only) {
+    if (values[option] !== undefined && !commands.includes(command)) throw new UsageError(`--${option} works only with ${commands.join(", ")}`);
+  }
+  const operation =
+    command === "image" || command === "coverage"
+      ? programOperation(command, args, context, space)
+      : command === "apply"
+      ? applyOperation(args, context, space)
+      : command === "operand"
+        ? operandOperation(args, values, context, space)
+        : command === "patch" || command === "macro" || command === "use"
+          ? sourceOperation(command, args, values, context, space)
+          : writeOperation(command, args, values.kind, values.element, context, values.title, space);
   return withWrite(operation);
 }
 
+type ReadValues = {
+  analyzer?: boolean | undefined;
+  kind?: string | undefined;
+  type?: string | undefined;
+  name?: string | undefined;
+  limit?: string | undefined;
+  before?: string | undefined;
+  out?: string | undefined;
+  switch?: string | undefined;
+  macro?: string | undefined;
+};
+
+/** The lookups of a listing: the program and the coverage in the knowledge, the knowledge of the space and the platform names of the C64. */
+function listingSource(db: DatabaseSync | undefined, space: string): ListingSource {
+  const image = requireProgram(db, space);
+  const coverage = programCoverage(db, space)?.map;
+  const inside = (at: number) => image.segments.some((segment) => at >= segment.start && at <= segment.end);
+  const platform = new Map(space === DEFAULT_SPACE ? platformNames().map((entry) => [entry.address, entry.name]) : []);
+  return {
+    byteAt: (at) => (inside(at) ? image.byteAt(at) : undefined),
+    // A user or LLM name, else the platform name; an analyzer name in symbols (knowledge from an older version) gives way to it.
+    nameOf: (at) => {
+      const own = symbolAt(db, at, space);
+      return own !== undefined && (own.origin === "user" || own.origin === "llm") ? own.name : (platform.get(at) ?? own?.name);
+    },
+    secondNames: (at) => analyzerNamesAt(db, at, space).map((row) => row.name),
+    regions: listRegions(db, undefined, undefined, undefined, space),
+    comments: (at) => {
+      const rows = commentsAt(db, at, space);
+      const side = rows.find((row) => row.placement === "side")?.text;
+      return { line: rows.filter((row) => row.placement === "line").flatMap((row) => row.text.split(/\r?\n/)), ...(side === undefined ? {} : { side }) };
+    },
+    operand: (at) => {
+      const row = operandAt(db, at, space);
+      return row === undefined ? undefined : operandText(row);
+    },
+    references: (at) => ({ in: referencesTo(db, at, space).length, out: referencesFrom(db, at, space).length }),
+    ...(coverage === undefined ? {} : { coverage }),
+  };
+}
+
+/** The answer of one read command. */
+function readAnswer(db: DatabaseSync | undefined, command: string, args: string[], values: ReadValues, range: { start: number; end: number }, origins: Origin[] | undefined, space: string): Record<string, unknown> {
+  switch (command) {
+    case "listing": {
+      if (args.length !== 2) throw new UsageError("listing needs <start> <end>");
+      const start = address(args[0], "start");
+      const end = address(args[1], "end");
+      if (end < start) throw new UsageError("the end must not be before the start");
+      const source = listingSource(db, space);
+      const lines = listing(source, start, end);
+      if (values.out !== undefined) {
+        writeProjectFile(values.out, Buffer.from(listingText(lines), "utf8"), { what: "--out" });
+        return { out: values.out, lines: lines.length };
+      }
+      return { lines: lines.map((row) => ({ ...row, address: formatC64Address(row.address) })) };
+    }
+    case "at": {
+      const known = at(db, address(args[0]), space);
+      return {
+        ...(space === DEFAULT_SPACE ? {} : { space }),
+        address: formatC64Address(known.address),
+        ...(known.symbol === undefined ? {} : { symbol: symbol(known.symbol) }),
+        ...(known.analyzerNames.length === 0 ? {} : { analyzerNames: known.analyzerNames.map(symbol) }),
+        ...(known.region === undefined ? {} : { region: region(known.region) }),
+        comments: known.comments.map(comment),
+        referencesFrom: known.referencesFrom.map(reference),
+        referencesTo: known.referencesTo.map(reference),
+        ...(known.operand === undefined ? {} : { operand: operand(known.operand) }),
+        ...(known.patch === undefined ? {} : { patch: patch(known.patch) }),
+        ...(known.macroUse === undefined ? {} : { macroUse: macroUse(known.macroUse) }),
+        ...(known.suppressions.length === 0 ? {} : { suppressions: known.suppressions.map(suppression) }),
+        revision: known.revision,
+      };
+    }
+    case "search": {
+      if (args[0] === undefined || args[0] === "") throw new UsageError("search needs text");
+      const found = search(db, args[0], values.limit === undefined ? 50 : integer(values.limit, "--limit"), origins, space);
+      return { symbols: found.symbols.map(symbol), analyzerNames: found.analyzerNames.map(symbol), comments: found.comments.map(comment) };
+    }
+    case "symbols": {
+      const kind = values.kind === undefined ? undefined : oneOf(SYMBOL_KINDS, values.kind, "--kind");
+      if (values.analyzer) return { analyzerNames: listAnalyzerNames(db, range, kind, origins, space).map(symbol) };
+      return { symbols: listSymbols(db, range, kind, origins, space).map(symbol) };
+    }
+    case "regions":
+      return { regions: listRegions(db, range, values.type === undefined ? undefined : oneOf(REGION_TYPES, values.type, "--type"), origins, space).map(region) };
+    case "comments":
+      return { comments: listComments(db, range, origins, space).map(comment) };
+    case "references":
+      return { references: listReferences(db, range, values.kind === undefined ? undefined : oneOf(REFERENCE_KINDS, values.kind, "--kind"), origins, space).map(reference) };
+    case "program": {
+      const image = programImage(db, space);
+      const ranges = db === undefined ? [] : (db.prepare("SELECT kind, count(*) AS count FROM current_coverage WHERE space = ? GROUP BY kind ORDER BY kind").all(space) as Array<{ kind: string; count: number }>);
+      return {
+        ...(space === DEFAULT_SPACE ? {} : { space }),
+        image:
+          image === undefined
+            ? null
+            : {
+                segments: image.segments.map((segment) => ({ start: formatC64Address(segment.start), end: formatC64Address(segment.end) })),
+                bytes: image.segments.reduce((sum, segment) => sum + segment.end - segment.start + 1, 0),
+                ...(image.entry === undefined ? {} : { entry: formatC64Address(image.entry) }),
+                state: image.state !== undefined,
+                stages: image.stages?.length ?? 0,
+              },
+        coverage: { maps: [...new Set(coverageRuns(db).filter((run) => run.space === space).map((run) => run.name))], ranges: Object.fromEntries(ranges.map((row) => [row.kind, row.count])) },
+      };
+    }
+    case "export": {
+      const exported = {
+        revision: currentRevision(db),
+        ...(space === DEFAULT_SPACE ? {} : { space }),
+        symbols: listSymbols(db, range, undefined, origins, space).map(symbol),
+        analyzerNames: listAnalyzerNames(db, range, undefined, origins, space).map(symbol),
+        regions: listRegions(db, range, undefined, origins, space).map(region),
+        comments: listComments(db, range, origins, space).map(comment),
+        references: listReferences(db, range, undefined, origins, space).map(reference),
+        suppressions: listSuppressions(db, range, space).map(suppression),
+        modules: listModules(db, range, origins, space).map(module),
+        operands: listOperands(db, range, origins, space).map(operand),
+        patches: listPatches(db, range, undefined, origins, space).map(patch),
+        macros: listMacros(db, origins, space).map(macro),
+        macroUses: listMacroUses(db, range, undefined, origins, space).map(macroUse),
+      };
+      const bytes = Buffer.from(`${JSON.stringify(exported, null, 2)}\n`, "utf8");
+      writeProjectFile(values.out!, bytes, { what: "--out" });
+      return {
+        out: values.out,
+        bytes: bytes.length,
+        counts: { symbols: exported.symbols.length, analyzerNames: exported.analyzerNames.length, regions: exported.regions.length, comments: exported.comments.length, references: exported.references.length, suppressions: exported.suppressions.length, modules: exported.modules.length, operands: exported.operands.length, patches: exported.patches.length, macros: exported.macros.length, macroUses: exported.macroUses.length },
+        revision: exported.revision,
+      };
+    }
+    case "suppressions": {
+      const rows = listSuppressions(db, range, space);
+      const reasons = reasonsOf(db, rows);
+      return { suppressions: rows.map((row) => ({ ...suppression(row), ...(reasons.has(row.revision) ? { reason: reasons.get(row.revision) } : {}) })) };
+    }
+    case "modules":
+      return { modules: listModules(db, range, origins, space).map(module) };
+    case "operands":
+      return { operands: listOperands(db, range, origins, space).map(operand) };
+    case "patches":
+      return { patches: listPatches(db, range, values.switch, origins, space).map(patch) };
+    case "switches": {
+      const switches = new Map<string, PatchRow[]>();
+      for (const row of listPatches(db, undefined, undefined, undefined, space)) switches.set(row.switch, [...(switches.get(row.switch) ?? []), row]);
+      return {
+        switches: [...switches].sort(([a], [b]) => (a < b ? -1 : 1)).map(([name, rows]) => ({ name, define: `--define ${name}=1`, patches: rows.map((row) => ({ start: formatC64Address(row.start), end: formatC64Address(row.end) })) })),
+      };
+    }
+    case "macros":
+      return { macros: listMacros(db, origins, space).map(macro) };
+    case "uses":
+      return { uses: listMacroUses(db, range, values.macro, origins, space).map(macroUse) };
+    case "spaces":
+      return { spaces: listSpaces(db) };
+    case "history":
+      // Each row with the reason and the evidence of the revision that wrote it.
+      return {
+        history: (values.macro !== undefined ? historyOfMacro(db, values.macro, space) : values.name === undefined ? historyAt(db, address(args[0]), space) : historyNamed(db, values.name, space)).map((entry) => ({ ...historyEntry(entry), ...revisionNote(db, entry.from) })),
+      };
+    case "revisions": {
+      const options: { limit?: number; before?: string } = {};
+      if (values.limit !== undefined) options.limit = integer(values.limit, "--limit");
+      if (values.before !== undefined) options.before = values.before;
+      return { revisions: revisions(db, options) };
+    }
+    default: {
+      if (args[0] === undefined) throw new UsageError("revision is missing");
+      const changes = revision(db, args[0]);
+      return { revision: changes.revision, added: changes.added.map(historyEntry), closed: changes.closed.map(historyEntry) };
+    }
+  }
+}
+
 /** --origin for reads: one origin, semantic (user and llm), analyzer (dxa and ghidra), or a comma list. */
 function originFilter(value: string): Origin[] {
   const origins = new Set<Origin>();
@@ -322,14 +644,185 @@ function originFilter(value: string): Origin[] {
   return [...origins];
 }
 
-/** --evidence kind:ref. A file kind names a project file and keeps its SHA-256, so a later change of the file shows. */
-function evidenceOf(value: string): Evidence {
+/** A project path as the knowledge names it: one spelling for each file, so ./runs/a.bin and runs/a.bin are the same file. */
+function knowledgePath(path: string, what: string): string {
+  try {
+    return projectRelative(path);
+  } catch {
+    throw new UsageError(`${what} must be a path relative to the project folder that stays inside it, not ${path}`);
+  }
+}
+
+/**
+ * --evidence kind:ref. A file kind names a project file and keeps its SHA-256, so a later change of the file shows.
+ * A file in .c64-re-tools/local/ is refused: git ignores it, and the move that keeps it changes the path.
+ */
+function evidenceOf(value: string, space: string): Evidence {
   const colon = value.indexOf(":");
   const kind = oneOf(EVIDENCE_KINDS, colon < 0 ? value : value.slice(0, colon), "--evidence kind");
-  const ref = colon < 0 ? "" : value.slice(colon + 1);
-  if (ref === "") throw new UsageError(`--evidence needs ${kind}:<${kind === "note" ? "text" : "file"}>`);
-  if (kind === "note") return { kind, ref };
-  return { kind, ref, sha256: createHash("sha256").update(readProjectFile(ref).bytes).digest("hex") };
+  const given = colon < 0 ? "" : value.slice(colon + 1);
+  if (given === "") throw new UsageError(`--evidence needs ${kind}:<${kind === "note" ? "text" : "file"}>`);
+  if (kind === "note") return { kind, ref: given };
+  const ref = knowledgePath(given, `--evidence ${kind}:<file>`);
+  // A coverage map is evidence by the name that coverage imported it with: the latest import into the space of the write.
+  if (kind === "coverage") {
+    const db = openForRead();
+    try {
+      const run = coverageRuns(db).filter((item) => item.name === ref && item.space === space).at(-1);
+      const where = space === DEFAULT_SPACE ? "" : ` in ${space}`;
+      if (run === undefined) throw new UsageError(`--evidence coverage:${given} names no coverage map of the knowledge${where}: import the map with coverage${space === DEFAULT_SPACE ? "" : ` --space ${space}`} first`);
+      return { kind, ref, sha256: run.sha256, ...(run.space === DEFAULT_SPACE ? {} : { space: run.space }) };
+    } finally {
+      db?.close();
+    }
+  }
+  const bytes = readProjectFile(ref).bytes;
+  const root = projectRoot();
+  if (isInside(join(root, PROJECT_DIRECTORY, LOCAL_DIRECTORY), resolveProjectPath(ref, root))) {
+    throw new UsageError(`--evidence ${kind}:${ref} is in ${PROJECT_DIRECTORY}/${LOCAL_DIRECTORY}/, which git ignores: move it to a folder that git keeps (a run folder to runs/<name>/) and give the new path`);
+  }
+  return { kind, ref, sha256: createHash("sha256").update(bytes).digest("hex") };
+}
+
+/** An image.json of c64-unpacker capture or a PRG as a write of the program. */
+function imageRequest(path: string, space: string): ImageRequest {
+  let image: ReturnType<typeof readImage>;
+  try {
+    image = readImage(path);
+  } catch (error) {
+    if (error instanceof ImageError) throw new UsageError(error.message);
+    throw error;
+  }
+  const request: ImageRequest = { space, segments: image.segments, byteAt: image.byteAt };
+  if (image.entry !== undefined) request.entry = image.entry;
+  if (image.stages !== undefined) request.stages = image.stages;
+  if (image.statePath !== undefined) {
+    let bytes: Buffer | undefined;
+    try {
+      bytes = readProjectFile(image.statePath).bytes;
+    } catch (error) {
+      if (!(error instanceof WireFailure && error.code === "not-found")) throw error;
+    }
+    if (bytes !== undefined) {
+      let state: unknown;
+      try {
+        state = JSON.parse(bytes.toString("utf8"));
+      } catch (error) {
+        throw new UsageError(`${image.statePath} is not JSON: ${(error as Error).message}`);
+      }
+      if (typeof state !== "object" || state === null || Array.isArray(state)) throw new UsageError(`${image.statePath} is not an entry state of c64-unpacker capture`);
+      // The comparison with a clean reset only tells the capture what it found.
+      const { differsFromReset: _differs, ...kept } = state as Record<string, unknown>;
+      request.state = kept;
+    }
+  }
+  return request;
+}
+
+/** image and coverage: the program and what the runs did go into the knowledge, so no project file is made again. */
+function programOperation(command: "image" | "coverage", args: string[], context: WriteContext, space: string): WriteOperation {
+  if (command === "image") {
+    if (args.length !== 1) throw new UsageError("image needs one image.json or PRG");
+    const request = imageRequest(args[0]!, space);
+    return (db) => {
+      const { revision, current } = setImage(db, context, request);
+      return { revision, ...spaceOf(current), bytes: current.bytes, rowsAdded: current.rowsAdded, rowsClosed: current.rowsClosed, entryChanged: current.entry };
+    };
+  }
+  if (args.length === 0) throw new UsageError("coverage needs one or more coverage maps");
+  const maps = args.map((path) => ({ bytes: readProjectFile(path).bytes, name: knowledgePath(path, "coverage <map>") }));
+  return (db) => {
+    const { revision, current } = addCoverage(db, context, { space, maps });
+    return { revision, ...spaceOf(current), imported: current.imported, known: current.known, ranges: current.ranges };
+  };
+}
+
+/**
+ * The program in the knowledge that operand, patch and macro use writes
+ * are checked against, with the platform names. A byte outside
+ * the segments of the program is not in it.
+ */
+function operandImage(db: DatabaseSync, space: string): OperandImage {
+  const image = requireProgram(db, space);
+  const inside = (at: number) => image.segments.some((segment) => at >= segment.start && at <= segment.end);
+  return { byteAt: (at) => (inside(at) ? image.byteAt(at) : undefined), platform: new Map(platformNames().map((entry) => [entry.name, entry.address])) };
+}
+
+/** An offset: a whole number in decimal or $ hex, with an optional minus sign. */
+function offsetOf(value: unknown, what: string): number {
+  if (typeof value === "number" && Number.isInteger(value)) return value;
+  const match = typeof value === "string" ? /^(-?)(\$[0-9A-Fa-f]{1,4}|[0-9]{1,5})$/.exec(value) : null;
+  if (match === null) throw new UsageError(`${what} must be a whole number such as 1, -1 or '$1000'`);
+  const size = match[2]!.startsWith("$") ? Number.parseInt(match[2]!.slice(1), 16) : Number(match[2]);
+  return match[1] === "-" ? -size : size;
+}
+
+/** operand <address> with one of --lo, --hi, --value or --expr. */
+function operandOperation(args: string[], values: Record<string, unknown>, context: WriteContext, space: string): WriteOperation {
+  const given = (["lo", "hi", "value", "expr"] as const).filter((option) => values[option] !== undefined);
+  if (given.length !== 1) throw new UsageError("operand needs exactly one of --lo, --hi, --value or --expr");
+  const select: OperandSelect = given[0]!;
+  const request: { space: string; address: number; select: OperandSelect; symbol?: string; offset?: number; expression?: string } = { space, address: address(args[0]), select };
+  if (select === "expr") {
+    if (values.offset !== undefined) throw new UsageError("--offset works with --lo, --hi and --value, not with --expr");
+    request.expression = values.expr as string;
+  } else {
+    request.symbol = values[select] as string;
+    if (values.offset !== undefined) request.offset = offsetOf(values.offset, "--offset");
+  }
+  return (db) => {
+    const result = setOperand(db, { ...context, image: operandImage(db, space) }, request);
+    return { revision: result.revision, operand: operand(result.current), ...(result.previous === undefined ? {} : { previous: operand(result.previous) }) };
+  };
+}
+
+/** A comma list of params or args; an empty text is an empty list. */
+const commaList = (value: string) => (value.trim() === "" ? [] : value.split(",").map((item) => item.trim()));
+
+/** The text of an option, or of the project file that a --*-file option names; exactly one of them. */
+function textOrFile(values: Record<string, unknown>, option: string, what: string): string | undefined {
+  const inline = values[option] as string | undefined;
+  const file = values[`${option}-file`] as string | undefined;
+  if (inline !== undefined && file !== undefined) throw new UsageError(`give --${option} or --${option}-file, not both`);
+  if (file !== undefined) return readProjectFile(file).bytes.toString("utf8");
+  if (inline === undefined) return undefined;
+  if (inline === "") throw new UsageError(`${what} is empty`);
+  return inline;
+}
+
+/** patch, macro and use: the writes of the generated source. */
+function sourceOperation(command: "patch" | "macro" | "use", args: string[], values: Record<string, unknown>, context: WriteContext, space: string): WriteOperation {
+  const comment = values.comment as string | undefined;
+  switch (command) {
+    case "patch": {
+      if (args[2] === undefined) throw new UsageError("the switch name is missing");
+      const code = textOrFile(values, "code", "--code");
+      if ((code === undefined) === (values.nop !== true)) throw new UsageError("patch needs exactly one of --code, --code-file or --nop");
+      const request = { space, start: address(args[0], "start"), end: address(args[1], "end"), switch: args[2], code: code ?? "", ...(comment === undefined ? {} : { comment }) };
+      return (db) => {
+        const result = setPatch(db, { ...context, image: operandImage(db, space) }, request);
+        return { revision: result.revision, patch: patch(result.current), ...(result.previous === undefined ? {} : { previous: patch(result.previous) }) };
+      };
+    }
+    case "macro": {
+      if (args[0] === undefined) throw new UsageError("the macro name is missing");
+      const body = textOrFile(values, "body", "--body");
+      if (body === undefined) throw new UsageError("macro needs --body or --body-file");
+      const request = { space, name: args[0], params: commaList((values.params as string | undefined) ?? ""), body, ...(comment === undefined ? {} : { comment }) };
+      return (db) => {
+        const result = setMacro(db, context, request);
+        return { revision: result.revision, macro: macro(result.current), ...(result.previous === undefined ? {} : { previous: macro(result.previous) }) };
+      };
+    }
+    case "use": {
+      if (args[2] === undefined) throw new UsageError("the macro name is missing");
+      const request = { space, start: address(args[0], "start"), end: address(args[1], "end"), macro: args[2], args: commaList((values.args as string | undefined) ?? "") };
+      return (db) => {
+        const result = setMacroUse(db, { ...context, image: operandImage(db, space) }, request);
+        return { revision: result.revision, use: macroUse(result.current), ...(result.previous === undefined ? {} : { previous: macroUse(result.previous) }) };
+      };
+    }
+  }
 }
 
 /** apply <file>: the batch as BatchOperation values, checked before the database opens. */
@@ -344,16 +837,29 @@ function applyOperation(args: string[], context: WriteContext, space: string): W
   }
   if (!Array.isArray(parsed)) throw new UsageError("the batch is a JSON list of writes, for example [{\"op\": \"rename\", \"address\": \"$2100\", \"name\": \"update_player\"}]");
   const operations = parsed.map((item, index) => batchOperation(item, `write ${index + 1}`, space));
+  const checked = operations.some((operation) => operation.op === "operand" || operation.op === "patch" || operation.op === "use");
   return (db) => {
-    const applied = applyBatch(db, context, operations);
-    // replaced: each write that replaced a row of another origin, with that row as previous gives it for one write (b2/07).
+    const applied = applyBatch(db, checked ? { ...context, image: operandImage(db, space) } : context, operations);
+    // replaced: each write that replaced a row of another origin, with that row as previous gives it for one write.
     const replaced = applied.steps.flatMap((step, index) =>
-      step.previous === undefined ? [] : [{ write: index + 1, op: operations[index]!.op, previous: Array.isArray(step.previous) ? step.previous.map(region) : symbol(step.previous) }],
+      step.previous === undefined
+        ? []
+        : [{ write: index + 1, op: operations[index]!.op, previous: shownPrevious(step.previous) }],
     );
     return { revision: applied.revision, writes: applied.steps.length, replaced };
   };
 }
 
+/** A row that a write of a batch replaced, in its output shape. */
+function shownPrevious(row: NonNullable<BatchStep["previous"]>) {
+  if (Array.isArray(row)) return row.map(region);
+  if ("select" in row) return operand(row);
+  if ("switch" in row) return patch(row);
+  if ("body" in row) return macro(row);
+  if ("macro" in row) return macroUse(row);
+  return symbol(row);
+}
+
 const BATCH_FIELDS: Record<BatchOperation["op"], string[]> = {
   rename: ["address", "name", "kind"],
   "remove-symbol": ["address"],
@@ -365,8 +871,67 @@ const BATCH_FIELDS: Record<BatchOperation["op"], string[]> = {
   unreference: ["from", "to", "kind"],
   module: ["start", "file", "title"],
   unmodule: ["start"],
+  operand: ["address", "select", "symbol", "offset", "expression"],
+  unoperand: ["address"],
+  patch: ["start", "end", "switch", "code", "comment"],
+  unpatch: ["start"],
+  macro: ["name", "params", "body", "comment"],
+  unmacro: ["name"],
+  use: ["start", "end", "macro", "args"],
+  unuse: ["start"],
 };
 
+/** A write of a batch as JSON again: addresses as $ and four hex digits, the C64 space left out. */
+function batchJson(write: BatchOperation): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(write)) {
+    if (key === "space" && value === DEFAULT_SPACE) continue;
+    out[key] = ["address", "start", "end", "from", "to"].includes(key) && typeof value === "number" ? formatC64Address(value) : value;
+  }
+  return out;
+}
+
+/** Reads the batches, joins them, and writes the joined batch to --out. One name or one module file at two addresses writes nothing. */
+function joinCommand(files: string[], out: string | undefined, space: string): Record<string, unknown> {
+  if (files.length < 2) throw new UsageError("join needs two or more batch files");
+  if (out === undefined) throw new UsageError("join needs --out <file>");
+  const batches: Batch[] = files.map((file) => {
+    let value: unknown;
+    try {
+      value = JSON.parse(readProjectFile(file).bytes.toString("utf8"));
+    } catch (error) {
+      throw new UsageError(`${file}: ${(error as Error).message}`);
+    }
+    const shaped = Array.isArray(value) ? { ops: value } : (value as { owner?: unknown; ops?: unknown });
+    if (typeof shaped !== "object" || shaped === null || !Array.isArray(shaped.ops)) throw new UsageError(`${file}: a batch is a list of writes, or {"owner": "$1000-$1fff", "ops": [...]}`);
+    let owner: Batch["owner"];
+    if (shaped.owner !== undefined) {
+      const parts = typeof shaped.owner === "string" ? shaped.owner.split("-") : [];
+      if (parts.length !== 2) throw new UsageError(`${file}: owner must be "<start>-<end>", for example "$1000-$1fff"`);
+      owner = { start: address(parts[0], `${file}: owner`), end: address(parts[1], `${file}: owner`) };
+      if (owner.end < owner.start) throw new UsageError(`${file}: the owner range ends before it starts`);
+    }
+    const ops = (shaped.ops as unknown[]).map((item, index) => batchOperation(item, `${file}: write ${index + 1}`, space));
+    return { file, ...(owner === undefined ? {} : { owner }), ops };
+  });
+  const owned = batches.filter((batch) => batch.owner !== undefined);
+  for (const [index, batch] of owned.entries()) {
+    const other = owned.slice(index + 1).find((next) => next.owner!.start <= batch.owner!.end && batch.owner!.start <= next.owner!.end);
+    if (other !== undefined) throw new UsageError(`the owner ranges of ${batch.file} and ${other.file} overlap; give each address one owner`);
+  }
+  const joined = joinBatches(batches);
+  const choice = (item: JoinChoice) => ({ ...item, at: typeof item.at === "number" ? formatC64Address(item.at) : item.at, ...(item.space === DEFAULT_SPACE ? { space: undefined } : {}) });
+  const clash = (item: JoinClash) => ({ ...item, ...(item.space === DEFAULT_SPACE ? { space: undefined } : {}), places: item.places.map((place) => ({ address: formatC64Address(place.address), file: place.file })) });
+  const choices = joined.choices.map(choice);
+  if (joined.clashes.length > 0) {
+    process.exitCode = 1;
+    return { joined: false, clashes: joined.clashes.map(clash), choices, remedy: "Give each name and each module file one address in the batches, then join again." };
+  }
+  const bytes = Buffer.from(`${JSON.stringify(joined.ops.map(batchJson), null, 1)}\n`, "utf8");
+  writeProjectFile(out, bytes, { what: "--out" });
+  return { joined: true, out, writes: joined.ops.length, repeated: joined.repeated, choices, apply: `knowledge.ts apply ${out}` };
+}
+
 /** One write of a batch. A write names its own space, or takes the one of --space. */
 function batchOperation(item: unknown, at: string, space: string): BatchOperation {
   const operation = batchFields(item, at);
@@ -387,6 +952,15 @@ function batchFields(item: unknown, at: string): BatchOperation {
     return fields[key] as string;
   };
   const place = (key: string) => address(text(key), `${at}: ${key}`);
+  // A list is a JSON list of strings or a comma list.
+  const list = (key: string) => {
+    const value = fields[key];
+    if (value === undefined) return [];
+    if (typeof value === "string") return commaList(value);
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) throw new UsageError(`${at}: ${key} must be a list of strings or a comma list`);
+    return (value as string[]).map((item) => item.trim());
+  };
+  const optional = (key: string) => (fields[key] === undefined ? {} : { [key]: text(key) });
   switch (op) {
     case "rename":
       return { op, address: place("address"), name: text("name"), ...(fields.kind === undefined ? {} : { kind: oneOf(SYMBOL_KINDS, text("kind"), `${at}: kind`) }) };
@@ -406,7 +980,32 @@ function batchFields(item: unknown, at: string): BatchOperation {
       return { op, start: place("start"), file: text("file"), ...(fields.title === undefined ? {} : { title: text("title") }) };
     case "unmodule":
       return { op, start: place("start") };
-    default:
+    case "operand": {
+      const select = oneOf(OPERAND_SELECTS, text("select"), `${at}: select`);
+      return {
+        op,
+        address: place("address"),
+        select,
+        ...(fields.symbol === undefined ? {} : { symbol: text("symbol") }),
+        ...(fields.offset === undefined ? {} : { offset: offsetOf(fields.offset, `${at}: offset`) }),
+        ...(fields.expression === undefined ? {} : { expression: text("expression") }),
+      };
+    }
+    case "unoperand":
+      return { op, address: place("address") };
+    case "patch":
+      return { op, start: place("start"), end: place("end"), switch: text("switch"), code: fields.code === undefined ? "" : text("code"), ...optional("comment") };
+    case "macro":
+      return { op, name: text("name"), params: list("params"), body: text("body"), ...optional("comment") };
+    case "unmacro":
+      return { op, name: text("name") };
+    case "use":
+      return { op, start: place("start"), end: place("end"), macro: text("macro"), args: list("args") };
+    case "unpatch":
+    case "unuse":
+      return { op, start: place("start") };
+    case "reference":
+    case "unreference":
       return { op, from: place("from"), to: place("to"), kind: oneOf(REFERENCE_KINDS, text("kind"), `${at}: kind`) };
   }
 }
@@ -480,8 +1079,34 @@ function writeOperation(command: string, args: string[], kind: string | undefine
       const request = { space, start: address(args[0], "start") };
       return (db) => ({ revision: removeModule(db, context, request).revision });
     }
+    case "unoperand": {
+      const request = { space, address: address(args[0]) };
+      return (db) => ({ revision: removeOperand(db, context, request).revision });
+    }
+    case "unpatch": {
+      const request = { space, start: address(args[0], "start") };
+      return (db) => ({ revision: removePatch(db, context, request).revision });
+    }
+    case "unmacro": {
+      if (args[0] === undefined) throw new UsageError("the macro name is missing");
+      const request = { space, name: args[0] };
+      return (db) => ({ revision: removeMacro(db, context, request).revision });
+    }
+    case "unuse": {
+      const request = { space, start: address(args[0], "start") };
+      return (db) => ({ revision: removeMacroUse(db, context, request).revision });
+    }
+    case "merge": {
+      if (args.length > 0) throw new UsageError("merge takes no arguments");
+      const platform = new Map(platformNames().map((entry) => [entry.name, entry.address]));
+      return (db) => {
+        const merged = mergeConflicts(db, context, platform);
+        return { revision: merged.revision, choices: merged.current.map(showChoice) };
+      };
+    }
     case "revert": {
-      const request = { revision: integer(args[0], "revision") };
+      if (args[0] === undefined) throw new UsageError("revision is missing");
+      const request = { revision: args[0] };
       return (db) => ({ revision: revert(db, context, request).revision });
     }
     default:
@@ -489,4 +1114,4 @@ function writeOperation(command: string, args: string[], kind: string | undefine
   }
 }
 
-await runScript(() => run(process.argv.slice(2)), { usage: USAGE, refusals: [KnowledgeError] });
+await runScript((argv) => run(argv), { usage: USAGE, refusals: [KnowledgeError] });