@henols/c64-re-tools 2.0.0-rc.3 → 2.0.0-rc.4

package/skills/c64-provenance/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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. Use the result to separate the content of the application from changes that a release added. Do not use it to run or analyze the code.
+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
@@ -13,17 +13,21 @@ This skill does not change project knowledge.
 
 ## Inputs
 
-- Two or more releases: PRG files, relative to the project directory. Extract them from disk images with the c64-disk skill. Unpack packed releases with the c64-unpacker skill first.
+- 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. It does not use the host runtime.
+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 |
@@ -31,19 +35,39 @@ node <skill>/scripts/provenance.ts releases/a.prg releases/b.prg --shift 2:-256
 | `--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 release at its load address and compares the addresses that all releases cover. It prints one JSON object.
+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 `--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 `--shift`.
 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. Examine each important difference:
+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`.
+   - `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.
+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.
-5. Decide which bytes are probably the original application. Use more than the byte comparison: the code, the text, and the history of the releases.
-6. Record the conclusion as a comment or a region with the c64-knowledge skill.
+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.
+- `access`: from the joined `--coverage` files: `executed`, `read`, `written`, `read-written` or `untouched`. `untouched` bytes did not take part in the runs.
+- `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.
+
+The result lists the first ranges. `--out` writes all of them. Run more coverage runs for parts that are `untouched` before you decide.
 
 ## Knowledge
 
@@ -54,7 +78,9 @@ Record a confirmed conclusion as a normal comment, region or symbol with the c64
 
 ## Result
 
-The differing ranges with the bytes of each release and the groups that agree, and the share of identical bytes.
+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. 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.
 
@@ -62,7 +88,9 @@ The exit status is 0 for a result. The exit status is 1 for an error. The exit s
 
 - 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: null`: the releases do not cover the same addresses. Use `--shift`, or compare a range that all releases cover.
+- `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 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.

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

@@ -1,13 +1,21 @@
-// Byte comparison of releases for the c64-provenance script. Each release is
-// placed at its load address plus an optional shift; the comparison reports
-// where the releases differ and which releases agree there. It never decides
-// which bytes are original: that needs evidence beyond one comparison.
+// 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;
-  /** Address of the first byte after the shift. */
-  start: number;
-  bytes: Uint8Array;
+  /** 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 {
@@ -20,8 +28,8 @@ export interface DifferingRange {
 }
 
 export interface Comparison {
-  /** The addresses that every release covers. */
-  common: { start: number; end: number } | null;
+  /** The addresses where every release has bytes. */
+  common: Range[];
   identicalBytes: number;
   differingBytes: number;
   differences: DifferingRange[];
@@ -32,22 +40,37 @@ export interface Comparison {
 /** 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 start = Math.max(options.from ?? 0, ...releases.map((release) => release.start));
-  const end = Math.min(options.to ?? 0xffff, ...releases.map((release) => release.start + release.bytes.length - 1));
-  if (start > end) return { common: null, identicalBytes: 0, differingBytes: 0, differences: [], moreDifferences: false };
-  const at = (release: Release, address: number) => release.bytes[address - release.start]!;
+  const common = commonRanges(releases, options.from, options.to);
   let identicalBytes = 0;
   const differing: number[] = [];
-  for (let address = start; address <= end; address++) {
-    const first = at(releases[0]!, address);
-    if (releases.every((release) => at(release, address) === first)) identicalBytes++;
-    else differing.push(address);
+  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);
+    }
   }
-  const ranges: Array<{ start: number; end: number }> = [];
+  // 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) last.end = address;
+    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;
@@ -55,14 +78,19 @@ export function compareReleases(releases: Release[], options: { from?: number; t
     const values: Record<string, number[]> = {};
     const groups = new Map<string, string[]>();
     for (const release of releases) {
-      const bytes = Array.from(release.bytes.subarray(range.start - release.start, range.end - release.start + 1));
+      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: { start, end }, identicalBytes, differingBytes: differing.length, differences, moreDifferences: ranges.length > limit };
+  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));
 }
 
 /**
@@ -71,18 +99,21 @@ export function compareReleases(releases: Release[], options: { from?: number; t
  */
 export function suggestShift(base: Release, other: Release): { shift: number; matches: number } | undefined {
   const WINDOW = 8;
-  const key = (bytes: Uint8Array, at: number) => Buffer.from(bytes.subarray(at, at + WINDOW)).toString("latin1");
+  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 <= base.bytes.length; at++) {
-    const positionsOfKey = positions.get(key(base.bytes, at));
+  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 (positionsOfKey === undefined) positions.set(key(base.bytes, at), [at]);
-    else if (positionsOfKey.length < 8) positionsOfKey.push(at);
+    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 <= other.bytes.length; at++) {
-    for (const position of positions.get(key(other.bytes, at)) ?? []) {
-      const shift = base.start + position - (other.start + at);
+  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);
     }
   }

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

@@ -1,21 +1,46 @@
 // The c64-provenance script: compares two or more releases byte by byte at
-// their addresses and reports where they differ and which releases agree.
+// 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 { readProjectFile } from "#src/host-client/transfer.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, suggestShift, type Release } from "./compare.ts";
+import { compareReleases, suggestShift, 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.prg> <release.prg> [<release.prg> ...] [options]
+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
 
-Each release is a PRG file relative to the project directory, placed at its
-load address. The result is one JSON object.`;
+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 them (default 50).
+
+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 {
@@ -27,14 +52,123 @@ function address(text: string, option: string): number {
 
 const hexBytes = (bytes: number[]) => Buffer.from(bytes).toString("hex").replace(/(..)(?!$)/g, "$1 ");
 
-function run(argv: string[]): unknown {
+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" }, help: { type: "boolean" } },
+    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 ?? []) {
@@ -42,13 +176,27 @@ function run(argv: string[]): unknown {
     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]));
   }
-  const releases: Release[] = positionals.map((path, index) => {
-    const { bytes } = readProjectFile(path);
-    if (bytes.length < 3) throw new UsageError(`${path} is too short for a PRG`);
-    const start = bytes.readUInt16LE(0) + (shifts.get(index + 1) ?? 0);
-    if (start < 0 || start + bytes.length - 3 > 0xffff) throw new UsageError(`the shift moves ${path} outside $0000-$ffff`);
-    return { name: path, start, bytes: bytes.subarray(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") }),
@@ -63,21 +211,102 @@ function run(argv: string[]): unknown {
           return best === undefined || best.shift === 0 ? [] : [{ release: index + 2, shift: best.shift, matchingSequences: best.matches }];
         })
       : [];
+
+  // The runtime evidence: one emulator for each release, the differences at the release's own addresses.
+  const runtime = new Map<string, Array<{ 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);
+        }
+      } finally {
+        await client.close();
+      }
+    }
+  }
+
   return {
-    releases: releases.map((release) => ({ name: release.name, start: formatC64Address(release.start), end: formatC64Address(release.start + release.bytes.length - 1) })),
-    common: comparison.common === null ? null : { start: formatC64Address(comparison.common.start), end: formatC64Address(comparison.common.end) },
+    releases: loaded.map((item) => ({ name: item.release.name, 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) => ({
+    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.size === 0 ? {} : { runtime: Object.fromEntries([...runtime].map(([name, accesses]) => [name, accesses[index]!])) }),
     })),
     ...(comparison.moreDifferences ? { moreDifferences: true } : {}),
     ...(suggestions.length > 0 ? { suggestedShifts: suggestions } : {}),
+    ...(frames === undefined ? {} : { run: { frames, steps: steps.length, releases: runs } }),
+  };
+}
+
+/** 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) };
+  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
+      ? {}
+      : {
+          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: { count: ranges.length, listed: ranges.slice(0, Number(max)) },
+    codeRegions: {
+      count: codeRegions.length,
+      ...(loaded.entry === undefined ? {} : { unreachable: codeRegions.filter((region) => region.reachable === false) }),
+    },
+    ...(coverage === undefined ? {} : { outside }),
+    ...(out === undefined ? {} : { out }),
   };
 }
 
-await runScript(() => run(process.argv.slice(2)), { usage: USAGE });
+await runScript(() => run(process.argv.slice(2)), { usage: USAGE, refusals: [KnowledgeError] });