@henols/c64-re-tools 1.0.0 → 2.0.0-rc.10

package/skills/c64-provenance/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: c64-provenance
+description: Use this skill to compare two or more releases of a C64 program, for example cracked versions from different groups. It finds the bytes where the releases differ and shows which releases agree there. It can run each release and tell how the program uses each difference. With one release, it gives evidence for each range: the unpack stage, the access, and the code that the entry does not reach. Use the result to separate the content of the application from changes that a release added. Do not use it to analyze the code.
+---
+
+# c64-provenance
+
+## Purpose
+
+Compare releases of a C64 program. Find the bytes where they differ and which releases agree. Use this to find which bytes are probably the original application and which are changes of one release.
+
+This skill does not change project knowledge.
+
+## Inputs
+
+- Two or more releases, relative to the project directory. A release is a PRG file or an `image.json` from c64-unpacker capture. Extract releases from disk images with the c64-disk skill. Unpack packed releases with the c64-unpacker skill first.
+- Optional: an address range to compare.
+- Optional: a shift for a release that loads at a different address.
+- Optional: a number of frames to run each release, and a steps file.
+- For one release: the release, coverage files, and the knowledge of the project.
+
+## Tools / execution path
+
+The script compares the files locally. Only `--run` uses the host runtime: each release runs in its own emulator.
+
+```
+node <skill>/scripts/provenance.ts releases/a.prg releases/b.prg releases/c.prg
+node <skill>/scripts/provenance.ts releases/a.prg releases/b.prg --shift 2:-256 --from '$0900' --to '$09ff'
+node <skill>/scripts/provenance.ts releases/a.prg unpacked/b/image.json --run 600 --steps steps/start-game.json
+node <skill>/scripts/provenance.ts separate unpacked/image.json --coverage coverage/attract.bin --coverage coverage/level1.bin --out notes/separate.json
+```
+
+| Option | Meaning |
+|---|---|
+| `--shift 2:-256` | Move release 2 (the first release is 1) by -256 bytes. Use it again for more releases. |
+| `--from '$0900'` | Compare from this address. |
+| `--to '$09ff'` | Compare up to this address. |
+| `--run 600` | Run each release for this many frames, and give each listed difference its runtime evidence. |
+| `--steps steps/start-game.json` | With `--run`: the action steps of the c64-unpacker steps file to run before the frames, for example a key to start the game. |
+
+The script puts each PRG at its load address. An image has bytes only in its segments. The script compares the addresses where all releases have bytes. It prints one JSON object.
+
+With `--shift`, the addresses of `segments`, `common` and `differences` are the release addresses plus the `shift` of the release. The `start` and `end` of `runtime` are the addresses in the release itself, without the shift.
+
+With `--run`, a PRG starts with autostart and RUN. An image starts from its bytes: the script writes the segments and the entry state from `entry_state.json` into the emulator, and starts at the entry. Watchpoints on each difference stop the run at its first access.
+
+## Workflow
+
+1. Run the script on the releases.
+2. Read `identicalShare`. If it is low and `suggestedShifts` is present, the releases are at different addresses. Run the script again with a `--shift` of `suggestedShifts`. `shiftsNotSuggested` tells why a found shift does not fit in `$0000-$ffff`.
+
+   `suggestedShifts` has at most 3 shifts for each release. The shift with the most `matchingSequences` is first. Data that did not move and code that moved give different shifts. Try each shift. `current: true` marks the shift of this run.
+3. Read `differences`. Each one has an address range, the bytes of each release, and `groups`: the releases that have the same bytes there.
+4. To know how the program uses the differences, run the script again with `--run` and the frames that get the program to the part you examine. Read `runtime` of each difference:
+   - `first`: the first access in that release: `read`, `write`, `execute` or `none`. An instruction that reads and then writes the same byte, for example INC, counts as `read`. The operand bytes of an executed instruction count as `execute`, for example the value of `LDA #$03`.
+   - `changed`: `true` when the bytes at the end of the run are not the bytes of the release.
+   - A range that each release writes before it reads is probably runtime state, not a difference of the releases.
+   - A range with `none` in each release is not used in this run. Run more frames or other steps before you decide.
+   - `run.skipped`: the releases have no differences, so no release ran.
+5. Examine each important difference:
+   - Disassemble the bytes of each release with the c64-emulator skill, or analyze them with the c64-static-analysis skill.
+   - Find what the change does, for example a trainer, a removed copy protection, or a changed text.
+6. Decide which bytes are probably the original application. Use more than the byte comparison: the code, the text, and the history of the releases.
+7. Record the conclusion as a comment or a region with the c64-knowledge skill.
+
+## One release
+
+Use `separate` when you have only one release. It gives evidence, not a decision:
+
+- `ranges`: the image in ranges with the same stage and access. `stage` is the last unpack stage that wrote the range. In `image.json`, the last stage is the program. An earlier stage is a depacker, an intro or a loader. Only an image from c64-unpacker `capture` has stages. For an image from `loads`, `noStages` tells this.
+- `access`: from the joined `--coverage` files: `executed`, `read`, `written`, `read-written` or `untouched`. `untouched` bytes did not take part in the runs.
+- `codeRegions.total`: the number of code regions in the knowledge.
+- `codeRegions.unreachable`: code regions of the knowledge that no chain of call and jump references reaches from the entry. Run c64-static-analysis first, so that the knowledge has the code regions and the references.
+- `outside`: RAM outside the image that the program `read` or `executed` but did not write, and code it `generated`. A loader or an earlier stage put the bytes that the program did not write. A `generated` range can have gaps of two bytes or less: these are operand bytes.
+
+Each list has `count` and `listed`. `listed` has the first ranges, at most `--max-listed`. `--out` writes all of them. Run more coverage runs for parts that are `untouched` before you decide.
+
+## Knowledge
+
+Automatic write:
+- none.
+
+Record a confirmed conclusion as a normal comment, region or symbol with the c64-knowledge skill. Do not record the full comparison.
+
+## Result
+
+The differing ranges with the bytes of each release and the groups that agree, and the share of identical bytes. `common` gives the ranges where all releases have bytes. `releases` gives the segments and the `shift` of each release. With `--run`, each difference also has `runtime`, and `run` tells if each release started, or why not.
+
+The runtime evidence is evidence only. The script does not decide which bytes are original.
+
+The exit status is 0 for a result. The exit status is 1 for an error. The exit status is 2 for a wrong argument.
+
+## Failure and conflicts
+
+- Do not call releases independent when you do not know their relation. Two cracks can come from the same source.
+- Do not call a byte original only because one release has it. A majority of releases is also not proof.
+- `common` is empty: the releases do not cover the same addresses. Use `--shift`, or compare a range that all releases cover.
+- `run.releases` shows `started: false`: a PRG without a BASIC start, or an image without `entry_state.json`. The reason tells which. The other releases still give evidence.
+- `installation-incomplete`, or `machine-unavailable` with a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own emulator script.
+- `moreDifferences: true`: the script shows only the first differences. Use `--from` and `--to` to see the others.
+- `not-found`: the project has no file at that path.
+- `invalid-input`: a file, an address or a shift is wrong. A path that goes out of the project directory is also wrong, also through a link. Read the message.
+
+## Handoffs
+
+- Get releases from disk images → c64-disk
+- Unpack a packed release → c64-unpacker
+- Run or examine the different code → c64-emulator
+- Analyze the different code → c64-static-analysis
+- Record a conclusion → c64-knowledge

package/skills/c64-provenance/scripts/compare.ts

@@ -0,0 +1,152 @@
+// Byte comparison of releases for the c64-provenance script. Each release
+// has bytes in one or more segments: a PRG at its load address plus an
+// optional shift, or the segments of an unpacker image (D50). The comparison
+// covers the addresses where every release has bytes, and reports where the
+// releases differ and which releases agree there. It never decides which
+// bytes are original: that needs evidence beyond one comparison.
+
+export interface Range {
+  start: number;
+  end: number;
+}
+
+export interface Release {
+  name: string;
+  /** Where the release has bytes, after the shift, in address order. */
+  segments: Range[];
+  /** The byte at an address inside a segment. */
+  byteAt: (address: number) => number;
+}
+
+export interface DifferingRange {
+  start: number;
+  end: number;
+  /** The bytes of each release in this range, by release name. */
+  values: Record<string, number[]>;
+  /** Releases with the same bytes here, largest group first. */
+  groups: string[][];
+}
+
+export interface Comparison {
+  /** The addresses where every release has bytes. */
+  common: Range[];
+  identicalBytes: number;
+  differingBytes: number;
+  differences: DifferingRange[];
+  /** True when more differing ranges exist than the limit allowed. */
+  moreDifferences: boolean;
+}
+
+/** Joins differing addresses that are at most this far apart into one range. */
+const JOIN_GAP = 4;
+
+export const covers = (release: Release, address: number) => release.segments.some((segment) => address >= segment.start && address <= segment.end);
+
+/** The ranges where every release has bytes, inside from..to. */
+export function commonRanges(releases: Release[], from = 0x0000, to = 0xffff): Range[] {
+  const ranges: Range[] = [];
+  for (let address = from; address <= to; address++) {
+    if (!releases.every((release) => covers(release, address))) continue;
+    const last = ranges.at(-1);
+    if (last !== undefined && last.end + 1 === address) last.end = address;
+    else ranges.push({ start: address, end: address });
+  }
+  return ranges;
+}
+
+export function compareReleases(releases: Release[], options: { from?: number; to?: number; maxRanges?: number } = {}): Comparison {
+  const common = commonRanges(releases, options.from, options.to);
+  let identicalBytes = 0;
+  const differing: number[] = [];
+  for (const range of common) {
+    for (let address = range.start; address <= range.end; address++) {
+      const first = releases[0]!.byteAt(address);
+      if (releases.every((release) => release.byteAt(address) === first)) identicalBytes++;
+      else differing.push(address);
+    }
+  }
+  // A joined range stays inside one common range, so every release has all of its bytes.
+  const inSameCommon = (a: number, b: number) => common.some((range) => a >= range.start && b <= range.end);
+  const ranges: Range[] = [];
+  for (const address of differing) {
+    const last = ranges.at(-1);
+    if (last !== undefined && address - last.end <= JOIN_GAP && inSameCommon(last.start, address)) last.end = address;
+    else ranges.push({ start: address, end: address });
+  }
+  const limit = options.maxRanges ?? 64;
+  const differences = ranges.slice(0, limit).map((range) => {
+    const values: Record<string, number[]> = {};
+    const groups = new Map<string, string[]>();
+    for (const release of releases) {
+      const bytes = Array.from({ length: range.end - range.start + 1 }, (_, offset) => release.byteAt(range.start + offset));
+      values[release.name] = bytes;
+      const key = bytes.join(",");
+      groups.set(key, [...(groups.get(key) ?? []), release.name]);
+    }
+    return { ...range, values, groups: [...groups.values()].sort((a, b) => b.length - a.length) };
+  });
+  return { common, identicalBytes, differingBytes: differing.length, differences, moreDifferences: ranges.length > limit };
+}
+
+/** The addresses of a release in order, so that a window of bytes can run over its segments. */
+function addressesOf(release: Release): number[] {
+  return release.segments.flatMap((segment) => Array.from({ length: segment.end - segment.start + 1 }, (_, offset) => segment.start + offset));
+}
+
+/** Most shifts that suggestShifts gives: data that did not move can outvote code that did (b2/04). */
+export const MAX_SUGGESTED_SHIFTS = 3;
+
+/**
+ * The shifts that put `other` over `base` best: the most common address
+ * differences between equal 8-byte sequences, most votes first. A shift with
+ * less than a tenth of the best one's votes is chance. Empty when nothing matches.
+ */
+export function suggestShifts(base: Release, other: Release): Array<{ shift: number; matches: number }> {
+  const WINDOW = 8;
+  const key = (release: Release, addresses: number[], at: number) =>
+    String.fromCharCode(...addresses.slice(at, at + WINDOW).map((address) => release.byteAt(address)));
+  const baseAddresses = addressesOf(base);
+  const otherAddresses = addressesOf(other);
+  const positions = new Map<string, number[]>();
+  for (let at = 0; at + WINDOW <= baseAddresses.length; at++) {
+    const found = positions.get(key(base, baseAddresses, at));
+    // Very common sequences (fill bytes) say nothing about the alignment.
+    if (found === undefined) positions.set(key(base, baseAddresses, at), [baseAddresses[at]!]);
+    else if (found.length < 8) found.push(baseAddresses[at]!);
+  }
+  const votes = new Map<number, number>();
+  for (let at = 0; at + WINDOW <= otherAddresses.length; at++) {
+    for (const address of positions.get(key(other, otherAddresses, at)) ?? []) {
+      const shift = address - otherAddresses[at]!;
+      votes.set(shift, (votes.get(shift) ?? 0) + 1);
+    }
+  }
+  const ranked = [...votes].map(([shift, matches]) => ({ shift, matches })).sort((a, b) => b.matches - a.matches || Math.abs(a.shift) - Math.abs(b.shift));
+  return ranked.filter((found) => found.matches * 10 >= ranked[0]!.matches).slice(0, MAX_SUGGESTED_SHIFTS);
+}
+
+export type ShiftSuggestion = { release: number; shift: number; matchingSequences: number } | { release: number; matchingSequences: number; reason: string };
+
+/**
+ * The --shift to suggest for release `index` (0 = the first) from `found`,
+ * the best shift of that release over the first one (F-25). The shift is the
+ * full value for --shift: `applied` holds the shifts already given. A shift
+ * that moves a segment out of $0000-$ffff is not suggested: with two releases,
+ * the opposite shift of the first release is suggested when it fits, else the
+ * result gives the reason.
+ */
+export function shiftSuggestion(releases: Release[], applied: number[], index: number, found: { shift: number; matches: number }): ShiftSuggestion {
+  const outside = (release: Release, by: number) => release.segments.find((segment) => segment.start + by < 0 || segment.end + by > 0xffff);
+  const hex = (value: number) => `$${value.toString(16).padStart(4, "0")}`;
+  const why = (number: number, by: number, segment: Range) =>
+    `release ${number} moved by ${by} puts ${hex(segment.start)}-${hex(segment.end)} ${segment.start + by < 0 ? "below $0000" : "past $ffff"}`;
+  const own = outside(releases[index]!, found.shift);
+  if (own === undefined) return { release: index + 1, shift: applied[index]! + found.shift, matchingSequences: found.matches };
+  const reasons = [why(index + 1, found.shift, own)];
+  if (releases.length === 2) {
+    const base = outside(releases[0]!, -found.shift);
+    if (base === undefined) return { release: 1, shift: applied[0]! - found.shift, matchingSequences: found.matches };
+    reasons.push(why(1, -found.shift, base));
+  }
+  return { release: index + 1, matchingSequences: found.matches, reason: `No shift fits: ${reasons.join(", and ")}.` };
+}

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

@@ -0,0 +1,334 @@
+// The c64-provenance script: compares two or more releases byte by byte at
+// their addresses and reports where they differ and which releases agree. A
+// release is a PRG or an unpacker image.json (D50). With --run, each release
+// runs in its own emulator, and each listed difference gets its first access
+// and whether the run changed it. The separate command gives evidence from
+// one release (D51).
+
+import { posix } from "node:path";
+import { parseArgs } from "node:util";
+
+import { formatC64Address, parseC64Address } from "#src/c64.ts";
+import { readCoverageFiles } from "#src/host-client/coverage.ts";
+import { checkActionSteps, type ActionStep } from "#src/host-client/steps.ts";
+import { MAX_EXECUTION_COUNT, WireFailure } from "#src/host-client/tools.ts";
+import { readProjectFile, writeProjectFile } from "#src/host-client/transfer.ts";
+import { ViceSessionClient } from "#src/host-client/vice-session.ts";
+import { KnowledgeError, openForRead } from "#src/knowledge/database.ts";
+import { listReferences, listRegions } from "#src/knowledge/read.ts";
+import { CODE_REGION_TYPES } from "#src/knowledge/schema.ts";
+import { runScript, UsageError } from "#src/script.ts";
+import { compareReleases, shiftSuggestion, suggestShifts, type Range, type Release } from "./compare.ts";
+import { watchRelease, type ImageState, type Start } from "./runtime.ts";
+import { separate } from "./separate.ts";
+
+const USAGE = `provenance.ts <release> <release> [<release> ...] [options]
+provenance.ts separate <release> [--coverage <file> ...] [--out <file>] [--max-listed <n>]
+
+  --shift <n>:<bytes>   move release n (1 = the first) by a number of bytes, for example 2:-256
+  --from <address>      compare from this address
+  --to <address>        compare up to this address
+  --run <frames>        run each release in its own emulator for this many frames, and
+                        give each listed difference its first access and whether it changed
+  --steps <file>        with --run: action steps (JSON) to run before the frames
+
+separate gives evidence from one release: the unpack stage that wrote each range,
+its access in the --coverage files (64 KiB each, repeatable), whether call and
+jump references in knowledge reach each code region from the entry, and what the
+program reads or executes outside the image. --out writes all ranges to a file;
+the result lists at most --max-listed of each list (default 50) and its count.
+
+A release is a PRG, placed at its load address, or an image.json of the
+c64-unpacker skill, compared inside its segments. Paths are relative to the
+project directory. The result is one JSON object.`;
+
+function address(text: string, option: string): number {
+  try {
+    return parseC64Address(text);
+  } catch {
+    throw new UsageError(`${option} must be $ followed by four hex digits, not ${text}`);
+  }
+}
+
+const hexBytes = (bytes: number[]) => Buffer.from(bytes).toString("hex").replace(/(..)(?!$)/g, "$1 ");
+
+interface LoadedRelease {
+  release: Release;
+  shift: number;
+  start: Start | { kind: "none"; reason: string };
+  /** 64 KiB with the release bytes at their own addresses. */
+  memory: Uint8Array;
+  entry?: number;
+  stages?: Array<{ entry: number; wrote: Range[] }>;
+}
+
+/** Reads entry_state.json of the c64-unpacker skill for a start by writes. */
+function entryState(path: string): ImageState | string {
+  let value: Record<string, any>;
+  try {
+    value = JSON.parse(readProjectFile(path).bytes.toString("utf8")) as Record<string, any>;
+  } catch (error) {
+    if (error instanceof WireFailure && error.code === "not-found") return `It has no ${path}; capture it with c64-unpacker.`;
+    if (error instanceof WireFailure) throw error;
+    return `${path} is not JSON: ${(error as Error).message}`;
+  }
+  const registers = value.registers ?? {};
+  const byte = (item: unknown) => Number.isInteger(item) && (item as number) >= 0 && (item as number) <= 0xff;
+  const pages = ["$0000", "$0100", "$0200", "$0300"].map((page) => value.pages?.[page]);
+  const ok =
+    typeof registers.pc === "string" &&
+    /^\$[0-9a-f]{4}$/i.test(registers.pc) &&
+    ["a", "x", "y", "sp"].every((name) => byte(registers[name])) &&
+    typeof registers.flags === "object" &&
+    byte(value.cpuPort?.$00) &&
+    byte(value.cpuPort?.$01) &&
+    pages.every((page) => typeof page === "string" && /^[0-9a-f]{512}$/i.test(page));
+  if (!ok) return `${path} is not an entry_state.json of the c64-unpacker skill.`;
+  const flag = (name: string) => registers.flags[name] === true;
+  return {
+    pc: Number.parseInt(registers.pc.slice(1), 16),
+    a: registers.a,
+    x: registers.x,
+    y: registers.y,
+    sp: registers.sp,
+    flags: { n: flag("n"), v: flag("v"), d: flag("d"), i: flag("i"), z: flag("z"), c: flag("c") },
+    port: [value.cpuPort.$00, value.cpuPort.$01],
+    pages: Buffer.from(pages.join(""), "hex"),
+  };
+}
+
+function readRelease(path: string, shift: number): LoadedRelease {
+  const { bytes } = readProjectFile(path);
+  const moved = (range: Range) => ({ start: range.start + shift, end: range.end + shift });
+  const inside = (range: Range) => range.start >= 0 && range.end <= 0xffff;
+  if (!path.endsWith(".json")) {
+    if (bytes.length < 3) throw new UsageError(`${path} is too short for a PRG`);
+    const load = bytes.readUInt16LE(0);
+    const segment = moved({ start: load, end: load + bytes.length - 3 });
+    if (!inside(segment)) throw new UsageError(`the shift moves ${path} outside $0000-$ffff`);
+    const memory = new Uint8Array(0x10000);
+    memory.set(bytes.subarray(2), load);
+    return { release: { name: path, segments: [segment], byteAt: (at) => bytes[2 + at - segment.start]! }, shift, start: { kind: "program", path }, memory };
+  }
+  const fail = (what: string): never => {
+    throw new UsageError(`${path} is not an image.json of the c64-unpacker skill: ${what}`);
+  };
+  let manifest: Record<string, unknown>;
+  try {
+    manifest = JSON.parse(bytes.toString("utf8")) as Record<string, unknown>;
+  } catch (error) {
+    return fail((error as Error).message);
+  }
+  const parse = (value: unknown) => (typeof value === "string" && /^\$[0-9a-f]{4}$/i.test(value) ? Number.parseInt(value.slice(1), 16) : fail("a segment needs start and end as $ addresses"));
+  if (typeof manifest.image !== "string" || !Array.isArray(manifest.segments) || manifest.segments.length === 0) fail("it needs image and segments");
+  const own = (manifest.segments as Array<Record<string, unknown>>).map((segment) => ({ start: parse(segment.start), end: parse(segment.end) })).sort((a, b) => a.start - b.start);
+  const directory = posix.dirname(path);
+  const memory = readProjectFile(posix.join(directory, manifest.image as string)).bytes;
+  if (memory.length !== 0x10000) fail(`its image has ${memory.length} bytes, not 65536`);
+  const segments = own.map(moved);
+  if (!segments.every(inside)) throw new UsageError(`the shift moves ${path} outside $0000-$ffff`);
+  const state = entryState(posix.join(directory, "entry_state.json"));
+  const stages = Array.isArray(manifest.stages)
+    ? (manifest.stages as Array<Record<string, unknown>>).map((stage) => ({
+        entry: parse(stage.entry),
+        wrote: (Array.isArray(stage.wrote) ? (stage.wrote as Array<Record<string, unknown>>) : []).map((range) => ({ start: parse(range.start), end: parse(range.end) })),
+      }))
+    : undefined;
+  return {
+    release: { name: path, segments, byteAt: (at) => memory[at - shift]! },
+    shift,
+    start: typeof state === "string" ? { kind: "none", reason: state } : { kind: "image", segments: own, byteAt: (at) => memory[at]!, state },
+    memory,
+    ...(manifest.entry === undefined ? {} : { entry: parse(manifest.entry) }),
+    ...(stages === undefined ? {} : { stages }),
+  };
+}
+
+async function run(argv: string[]): Promise<unknown> {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    strict: true,
+    allowPositionals: true,
+    options: {
+      shift: { type: "string", multiple: true },
+      from: { type: "string" },
+      to: { type: "string" },
+      run: { type: "string" },
+      steps: { type: "string" },
+      coverage: { type: "string", multiple: true },
+      out: { type: "string" },
+      "max-listed": { type: "string" },
+      help: { type: "boolean" },
+    },
+  });
+  if (values.help) throw new UsageError("");
+  if (positionals[0] === "separate") {
+    const used = ["shift", "from", "to", "run", "steps"].filter((option) => values[option as keyof typeof values] !== undefined);
+    if (used.length > 0) throw new UsageError(`separate does not take --${used.join(", --")}`);
+    if (positionals.length !== 2) throw new UsageError("separate needs one release");
+    return separateCommand(positionals[1]!, values.coverage ?? [], values.out, values["max-listed"]);
+  }
+  if (values.coverage !== undefined || values.out !== undefined || values["max-listed"] !== undefined) throw new UsageError("--coverage, --out and --max-listed work only with separate");
+  if (positionals.length < 2) throw new UsageError("give two or more releases");
+  const shifts = new Map<number, number>();
+  for (const text of values.shift ?? []) {
+    const match = /^(\d+):([+-]?\d+)$/.exec(text);
+    if (match === null || Number(match[1]) < 1 || Number(match[1]) > positionals.length) throw new UsageError(`--shift must be <release number>:<bytes>, not ${text}`);
+    shifts.set(Number(match[1]), Number(match[2]));
+  }
+  if (values.steps !== undefined && values.run === undefined) throw new UsageError("--steps works only with --run");
+  let frames: number | undefined;
+  if (values.run !== undefined) {
+    if (!/^\d{1,6}$/.test(values.run) || Number(values.run) < 1 || Number(values.run) > MAX_EXECUTION_COUNT) throw new UsageError(`--run needs a frame count from 1 to ${MAX_EXECUTION_COUNT}, not ${values.run}`);
+    frames = Number(values.run);
+  }
+  let steps: ActionStep[] = [];
+  if (values.steps !== undefined) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(readProjectFile(values.steps).bytes.toString("utf8"));
+    } catch (error) {
+      if (error instanceof WireFailure) throw error;
+      throw new UsageError(`the steps file ${values.steps} is not JSON: ${(error as Error).message}`);
+    }
+    steps = checkActionSteps(parsed, (message) => {
+      throw new UsageError(`steps file ${values.steps}: ${message}`);
+    });
+  }
+  const loaded = positionals.map((path, index) => readRelease(path, shifts.get(index + 1) ?? 0));
+  const releases = loaded.map((item) => item.release);
+  const comparison = compareReleases(releases, {
+    ...(values.from === undefined ? {} : { from: address(values.from, "--from") }),
+    ...(values.to === undefined ? {} : { to: address(values.to, "--to") }),
+  });
+  const compared = comparison.identicalBytes + comparison.differingBytes;
+  const identicalShare = compared === 0 ? 0 : comparison.identicalBytes / compared;
+  // A poor match at the load addresses can mean that the releases are placed differently.
+  // Each release gets its best shifts: data that stayed can outvote code that moved, so one is not enough (b2/04).
+  const applied = loaded.map((item) => item.shift);
+  const suggestions =
+    identicalShare < 0.5
+      ? releases.slice(1).flatMap((release, index) =>
+          suggestShifts(releases[0]!, release).map((found) => {
+            const suggestion = shiftSuggestion(releases, applied, index + 1, found);
+            // The shift that the run already has: its votes tell how good the present alignment is.
+            return "shift" in suggestion && suggestion.shift === applied[suggestion.release - 1] ? { ...suggestion, current: true } : suggestion;
+          }),
+        )
+      : [];
+  const suggested = suggestions.filter((suggestion) => "shift" in suggestion);
+  const notSuggested = suggestions.filter((suggestion) => "reason" in suggestion);
+
+  // The runtime evidence: one emulator for each release, the differences at the release's own addresses.
+  const runtime = new Map<string, Array<Range & { first: string; changed: boolean }>>();
+  const runs: Record<string, unknown> = {};
+  if (frames !== undefined && comparison.differences.length > 0) {
+    for (const item of loaded) {
+      const name = item.release.name;
+      if (item.start.kind === "none") {
+        runs[name] = { started: false, reason: item.start.reason };
+        continue;
+      }
+      const ranges = comparison.differences.map((difference) => ({ start: difference.start - item.shift, end: difference.end - item.shift }));
+      const client = await ViceSessionClient.open({ videoStandard: "pal" });
+      try {
+        const watched = await watchRelease(client, item.start, ranges, (at) => item.release.byteAt(at + item.shift), { frames, steps });
+        if (!watched.started) runs[name] = { started: false, reason: watched.reason };
+        else {
+          runs[name] = { started: true };
+          runtime.set(name, watched.accesses.map((access, index) => ({ ...ranges[index]!, ...access })));
+        }
+      } finally {
+        await client.close();
+      }
+    }
+  }
+
+  return {
+    releases: loaded.map((item) => ({ name: item.release.name, shift: item.shift, segments: item.release.segments.map((segment) => ({ start: formatC64Address(segment.start), end: formatC64Address(segment.end) })) })),
+    common: comparison.common.map((range) => ({ start: formatC64Address(range.start), end: formatC64Address(range.end) })),
+    identicalBytes: comparison.identicalBytes,
+    differingBytes: comparison.differingBytes,
+    identicalShare: Number(identicalShare.toFixed(3)),
+    differences: comparison.differences.map((difference, index) => ({
+      start: formatC64Address(difference.start),
+      end: formatC64Address(difference.end),
+      values: Object.fromEntries(Object.entries(difference.values).map(([name, bytes]) => [name, hexBytes(bytes.slice(0, 32)) + (bytes.length > 32 ? " ..." : "")])),
+      groups: difference.groups,
+      // runtime gives the release's own addresses: with a shift, they are not the addresses of the difference (F-24).
+      ...(runtime.size === 0
+        ? {}
+        : {
+            runtime: Object.fromEntries(
+              [...runtime].map(([name, accesses]) => {
+                const { start, end, first, changed } = accesses[index]!;
+                return [name, { start: formatC64Address(start), end: formatC64Address(end), first, changed }];
+              }),
+            ),
+          }),
+    })),
+    ...(comparison.moreDifferences ? { moreDifferences: true } : {}),
+    ...(suggested.length > 0 ? { suggestedShifts: suggested } : {}),
+    ...(notSuggested.length > 0 ? { shiftsNotSuggested: notSuggested } : {}),
+    ...(frames === undefined
+      ? {}
+      : { run: { frames, steps: steps.length, releases: runs, ...(comparison.differences.length === 0 ? { skipped: "The releases have no differences, so no release ran." } : {}) } }),
+  };
+}
+
+/** separate: evidence from one release (D51), with all ranges in --out and the first ones in the result. */
+function separateCommand(path: string, coveragePaths: string[], out: string | undefined, maxListed: string | undefined): unknown {
+  const max = maxListed ?? "50";
+  if (!/^\d{1,5}$/.test(max)) throw new UsageError(`--max-listed must be a whole number, not ${max}`);
+  const loaded = readRelease(path, 0);
+  const coverage = readCoverageFiles(coveragePaths, (message) => {
+    throw new UsageError(message);
+  });
+  const db = openForRead();
+  let regions: ReturnType<typeof listRegions>;
+  let references: ReturnType<typeof listReferences>;
+  try {
+    regions = listRegions(db).filter((region) => CODE_REGION_TYPES.includes(region.type));
+    references = listReferences(db);
+  } finally {
+    db?.close();
+  }
+  const found = separate({
+    segments: loaded.release.segments,
+    memory: loaded.memory,
+    ...(loaded.entry === undefined ? {} : { entry: loaded.entry }),
+    ...(loaded.stages === undefined ? {} : { stages: loaded.stages }),
+    ...(coverage === undefined ? {} : { coverage }),
+    codeRegions: regions,
+    references,
+  });
+  const show = (range: Range) => ({ start: formatC64Address(range.start), end: formatC64Address(range.end) });
+  const ranges = found.ranges.map((range) => ({ ...show(range), ...(range.stage === undefined ? {} : { stage: range.stage }), ...(range.access === undefined ? {} : { access: range.access }) }));
+  const codeRegions = found.codeRegions.map((region) => ({ ...show(region), type: region.type, ...(region.reachable === undefined ? {} : { reachable: region.reachable }), ...(region.executed === undefined ? {} : { executed: region.executed }) }));
+  const outside = { read: found.outside.read.map(show), executed: found.outside.executed.map(show), generated: found.outside.generated.map(show) };
+  const listed = <T>(items: T[]) => ({ count: items.length, listed: items.slice(0, Number(max)) });
+  if (out !== undefined) writeProjectFile(out, Buffer.from(`${JSON.stringify({ release: path, ranges, codeRegions, outside }, null, 1)}\n`), { what: "--out" });
+  const bytes = (filter: (range: (typeof found.ranges)[number]) => boolean) => found.ranges.filter(filter).reduce((sum, range) => sum + range.end - range.start + 1, 0);
+  const lastStage = loaded.stages === undefined ? undefined : loaded.stages.length - 1;
+  return {
+    release: path,
+    ...(loaded.entry === undefined ? {} : { entry: formatC64Address(loaded.entry) }),
+    ...(lastStage === undefined
+      ? { noStages: "image.json has no stage log. Only a capture of c64-unpacker writes one. A capture of loads holds one part of a program and has none." }
+      : {
+          stages: lastStage + 1,
+          bytesByStage: Object.fromEntries([...[...Array(lastStage + 1).keys()].map((stage): [string, number] => [String(stage), bytes((range) => range.stage === stage)]), ["none", bytes((range) => range.stage === undefined)]]),
+        }),
+    ...(coverage === undefined ? {} : { bytesByAccess: Object.fromEntries((["executed", "read", "written", "read-written", "untouched"] as const).map((access) => [access, bytes((range) => range.access === access)])) }),
+    ranges: listed(ranges),
+    // total counts every code region; unreachable is a list like the others (b2/08).
+    codeRegions: {
+      total: codeRegions.length,
+      ...(loaded.entry === undefined ? {} : { unreachable: listed(codeRegions.filter((region) => region.reachable === false)) }),
+    },
+    ...(coverage === undefined ? {} : { outside: { read: listed(outside.read), executed: listed(outside.executed), generated: listed(outside.generated) } }),
+    ...(out === undefined ? {} : { out }),
+  };
+}
+
+await runScript(() => run(process.argv.slice(2)), { usage: USAGE, refusals: [KnowledgeError] });