@henols/c64-re-tools 2.1.1 → 2.1.2

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

@@ -9,7 +9,6 @@
 import { type AddressRange, COVERAGE, EXECUTE, formatC64Address, READ, WRITE } from "#src/c64.ts";
 import { autostartLoaded, LOAD_LIMIT_FRAMES, RUN_LIMIT_FRAMES, typeRun } from "#src/host-client/autostart.ts";
 import { readCoverage, writtenBlocks } from "#src/host-client/coverage.ts";
-import { resetToReady } from "#src/host-client/entry-state.ts";
 import { readActionSteps, runActionStep, type ActionStep } from "#src/host-client/steps.ts";
 import { WireFailure } from "#src/host-client/tools.ts";
 import { readPrg } from "#src/host-client/image.ts";
@@ -20,7 +19,7 @@ import { listed, OPTIONS, runScript, UsageError, type Call, type CommandSpec, ty
 import { basicStart, inspect, readMemoryMap, underRom, writtenThenExecuted } from "./lib/evidence.ts";
 import { loads, readLoadSteps } from "./lib/loads.ts";
 import { callReturn, captureSegments, executedIn, inRanges, mergeMaps, stageCandidates, stagePoints, withoutRanges } from "./lib/stages.ts";
-import { entryState, IO_AREAS, json, machineState, readRam, vectorsOf } from "./lib/machine.ts";
+import { entryStateFile, machineState, readRam, readyState, vectorsOf } from "./lib/machine.ts";
 
 /** Written-then-executed bytes from this many on are unpacking, decrypting or relocating, not self-changing code. */
 const UNPACKED_BYTES = 256;
@@ -165,6 +164,13 @@ async function firstPcAfterBasic(client: ViceSessionClient, from: number, to: nu
   return from > to ? undefined : firstPcIn(client, [{ start: from, end: to }]);
 }
 
+/**
+ * What a stage wrote: every written block, also a small one. --min-stage
+ * decides only where a stage starts; the wrote list and the capture segments
+ * keep each byte that a stage wrote.
+ */
+const stageWrote = (map: Uint8Array) => writtenBlocks(map, 1);
+
 /** Frames between two looks at the memory map while stages are followed. */
 const STAGE_CHUNK_FRAMES = 25;
 const MAX_STAGES = 16;
@@ -238,7 +244,7 @@ async function follow(
   let stage = { map: new Uint8Array(0x10000), own: new Set<number>(), called: [] as AddressRange[] };
   const startStage = async (next: number, last: Uint8Array) => {
     mergeMaps(stage.map, last);
-    found.push({ entry, firstFrame, frames: total - firstFrame, wrote: writtenBlocks(stage.map, options.minStage), next });
+    found.push({ entry, firstFrame, frames: total - firstFrame, wrote: stageWrote(stage.map), next });
     entry = next;
     firstFrame = total;
     stage = { map: new Uint8Array(0x10000), own: new Set<number>(), called: [] };
@@ -428,7 +434,7 @@ async function follow(
   else reached = await trackTo(options.until, left);
   await client.snapshot({ action: "remove", name: STAGE_SNAPSHOT }).catch(() => undefined);
   mergeMaps(stage.map, await readCoverage(client));
-  found.push({ entry, firstFrame, frames: total - firstFrame, wrote: writtenBlocks(stage.map, options.minStage) });
+  found.push({ entry, firstFrame, frames: total - firstFrame, wrote: stageWrote(stage.map) });
   return { stages: found, frames: total, reached, ...(halted === undefined ? {} : { halted }) };
 }
 
@@ -529,14 +535,8 @@ async function capture(
       ),
     );
     // A clean machine at the READY prompt shows what the loader and the stages changed.
-    await resetToReady(client);
-    const clean = await machineState(client);
-    const differs: Array<{ address: string; entry: number; reset: number }> = [];
-    const compare = (base: number, entry: Buffer, reset: Buffer) => entry.forEach((value, offset) => value !== reset[offset] && differs.push({ address: formatC64Address(base + offset), entry: value, reset: reset[offset]! }));
-    compare(0x0000, state.port, clean.port);
-    compare(0x0002, state.pages.subarray(2), clean.pages.subarray(2));
-    for (const [name, [address]] of Object.entries(IO_AREAS)) compare(address, state.io[name as keyof typeof IO_AREAS], clean.io[name as keyof typeof IO_AREAS]);
-    write("entry_state.json", json(entryState(registers, state, vectors, differs)));
+    const entry = entryStateFile(registers, state, vectors, await readyState(client));
+    write("entry_state.json", entry.bytes);
     return {
       output: {
         captured: true,
@@ -546,7 +546,7 @@ async function capture(
         segments: segments.map(showRange),
         ...(options.exclude.length === 0 ? {} : { excluded: options.exclude.map(showRange) }),
         stages: followed.stages.length,
-        differsFromReset: differs.length,
+        differsFromReset: entry.differsFromReset,
       },
       failed: false,
     };
@@ -569,7 +569,7 @@ const entryOf = (call: Call) => {
 };
 const stepsOf = (call: Call) => {
   const path = call.string("steps");
-  return path === undefined ? [] : readActionSteps(path, "--steps");
+  return path === undefined ? [] : readActionSteps(path, "--steps", knowledgeAt());
 };
 
 const COMMANDS: CommandSpec[] = [
@@ -595,7 +595,8 @@ const COMMANDS: CommandSpec[] = [
     run: async (call) => {
       const steps = stepsOf(call);
       // A runUntil step to a raster line or a memory value cannot be tracked in chunks of frames; capture takes it.
-      if (steps.some((step) => "runUntil" in step && !trackedRunUntil(step))) throw new UsageError("stages takes a runUntil step only with an address target without a condition. Use frames steps, or capture");
+      const untracked = steps.findIndex((step) => "runUntil" in step && !trackedRunUntil(step));
+      if (untracked >= 0) throw new UsageError(`--steps ${call.string("steps")!}: step ${untracked + 1}: stages takes a runUntil step only with an address target without a condition. Use frames steps, or capture`);
       return outcome(await stages(call.subject(0), { frames: call.count("frames")!, steps, minStage: call.count("min-stage")!, ...entryOf(call) }));
     },
   },
@@ -605,7 +606,7 @@ const COMMANDS: CommandSpec[] = [
     subjects: [PROGRAM],
     options: {
       until: { kind: "address", value: "<address>", required: true, help: "the unpacked entry point" },
-      out: { ...OPTIONS.out, value: "<dir>", required: true, help: "the folder for the capture, relative to the project folder" },
+      out: { ...OPTIONS.out, output: "folder", value: "<dir>", required: true, help: "the folder for the capture, relative to the project folder" },
       range: { ...OPTIONS.range, help: "one segment in place of the found ones" },
       exclude: { kind: "range", value: "<start>-<end>", multiple: true, help: "a range to leave out of the segments, for example bytes that a crack left and the program never reads" },
       "timeout-frames": { ...OPTIONS["timeout-frames"], max: 30_000, default: 3000, help: "stop the wait for --until after n frames (default 3000)" },
@@ -632,7 +633,7 @@ const COMMANDS: CommandSpec[] = [
     subjects: [{ name: "<program>", help: "a PRG, or a disk, tape or cartridge image, relative to the project folder" }],
     options: {
       steps: { ...STEPS, required: true, help: "action steps and capture steps (JSON)" },
-      out: { ...OPTIONS.out, value: "<dir>", required: true, help: "the folder for the captures, relative to the project folder" },
+      out: { ...OPTIONS.out, output: "folder", value: "<dir>", required: true, help: "the folder for the captures, relative to the project folder" },
       drive: { kind: "flag", help: "also write the 2 KiB drive RAM as drive8.prg, for knowledge space drive8" },
       "min-block": { kind: "count", value: "<bytes>", min: 1, max: 0x10000, default: 64, help: "write a changed block of at least this many bytes (default 64)" },
     },

package/src/host/vice/adapter.ts

@@ -59,7 +59,10 @@ export function conditionExpression(condition: Condition, space: Space): string
     }
     case "memory": {
       if (condition.space !== "c64") {
-        throw new WireFailure("unsupported-in-space", "A memory condition can test only space c64 memory.");
+        throw new WireFailure(
+          "unsupported-in-space",
+          "A memory target or a memory condition tests only space c64 memory. For the drive, use a watchpoint in space drive8, or a c64_run_until address target in space drive8.",
+        );
       }
       return `(@${condition.view}:${formatC64Address(condition.address)} ${operator(condition.operator)} ${formatC64Byte(condition.value)})`;
     }

package/src/host/vice/session.ts

@@ -30,6 +30,8 @@ import {
 import { decodeProgramCounter, MonitorConnectionError, MonitorError, MonitorTimeoutError, ResponseType, type MonitorResponse } from "./binary-monitor.ts";
 import { decodeCia, decodeSid, decodeSprite, decodeVicii } from "./chips.ts";
 import { compareFrames, differenceImage } from "./screen.ts";
+import { isRefusal } from "../../errors.ts";
+import { checkMedia } from "../../media.ts";
 import { launchVice, startErrorLines, type ViceMode, type ViceProcess } from "./process.ts";
 import { TextMonitorError, TextMonitorTimeoutError } from "./text-monitor.ts";
 
@@ -193,6 +195,13 @@ export class ViceSession implements ViceSessionHandle {
    * pc write, and reports the JAM only once.
    */
   #jammed: number | undefined;
+  /**
+   * An autostart can still be loading: VICE goes on with it after a snapshot
+   * restore and writes the program over the restored memory. Only a reset stops it.
+   */
+  #autostarting = false;
+  /** The C64 clock just after the last snapshot restore: VICE keeps the history of before it. */
+  #historySince: bigint | undefined;
   /** VICE records no CPU history after a JAM until the next reset. */
   #historyStopped = false;
   /** The CPU ran again after a JAM without a reset: the CPU history that VICE gives is old. */
@@ -396,6 +405,7 @@ export class ViceSession implements ViceSessionHandle {
       case "autostart": {
         const { type, index, run } = params as ViceOperations["autostart"]["params"];
         const bytes = onlyAttachment(attachments);
+        checkMedia(type, bytes);
         if (index > 0 && this.#directory !== undefined && isOneOf(DISK_IMAGE_TYPES, type)) checkDirectoryEntry(await this.#directory(type, bytes), index);
         const file = this.#stage(bytes, type);
         // VICE keeps a cartridge through every reset and autostart, as a real C64 does.
@@ -415,6 +425,7 @@ export class ViceSession implements ViceSessionHandle {
         }
         await this.#runningCommand(() => this.#machine.autostart(file, index, run));
         this.#clearJam();
+        this.#autostarting = true;
         if (type === "crt") this.#cartridge = true;
         this.#replaceStaged(stagedKind(type), file);
         // A reset sets the CPU clock back, so the stopwatch starts again.
@@ -423,7 +434,9 @@ export class ViceSession implements ViceSessionHandle {
       }
       case "diskAttach": {
         const { type } = params as ViceOperations["diskAttach"]["params"];
-        const file = this.#stage(onlyAttachment(attachments), type);
+        const bytes = onlyAttachment(attachments);
+        checkMedia(type, bytes);
+        const file = this.#stage(bytes, type);
         await this.#observe(() => this.#machine.attachDisk(file));
         this.#replaceStaged("disk", file);
         return { attached: true };
@@ -543,11 +556,18 @@ export class ViceSession implements ViceSessionHandle {
       // VICE 3.9 sends no JAM event: the opcode at the pc tells.
       const stop = this.#lastStop ?? ((await this.#jamAt(status.pc)) ? { stopReason: "jam" as const } : undefined);
       if (stop !== undefined) Object.assign(status, stop);
+      // A point in the drive stopped it: the pc is the drive's, as advance-frames and run-until give it.
+      const point = status.pointId === undefined ? undefined : (status.stopReason === "watchpoint" ? this.#watchpoints : this.#breakpoints).get(status.pointId);
+      status.space = point?.space === "drive8" ? "drive8" : "c64";
+      if (status.space === "drive8") status.pc = (await this.#machine.readRegisters("drive8")).pc;
     }
     return status;
   }
 
   async #execution(params: ExecutionParams): Promise<ExecutionResult> {
+    if (params.space === "drive8" && (params.action === "pause" || params.action === "resume")) {
+      throw new WireFailure("unsupported-in-space", `${params.action} stops or runs the whole machine, the computer and the disk drive together: use space c64.`);
+    }
     if (params.action === "resume") {
       if (this.#state === "stopped") {
         await this.#refuseJammed("resume");
@@ -896,6 +916,9 @@ export class ViceSession implements ViceSessionHandle {
 
   /** A reset or an autostart starts a jammed CPU and the CPU history again. */
   #clearJam(): void {
+    this.#autostarting = false;
+    // A reset sets the clock back to 0: the history from before it is of this run again.
+    this.#historySince = undefined;
     this.#jammed = undefined;
     this.#historyStopped = false;
     this.#historyOld = false;
@@ -1121,9 +1144,10 @@ export class ViceSession implements ViceSessionHandle {
       );
     }
     return this.#observe(async () => {
-      const raw = await this.#machine.history(params.limit, params.space);
-      if (params.space === "drive8") return { entries: raw.map(({ clock: _clock, ...entry }) => entry) };
+      const all = await this.#machine.history(params.limit, params.space);
+      if (params.space === "drive8") return { entries: all.map(({ clock: _clock, ...entry }) => entry) };
       const now = await this.#machine.clock();
+      const raw = entriesSince(all, this.#historySince, now);
       const position = await this.#machine.rasterPosition();
       const { lines, cycles } = RASTER[this.#videoStandard];
       const frame = BigInt(lines * cycles);
@@ -1218,7 +1242,10 @@ export class ViceSession implements ViceSessionHandle {
   async #restoreFrom(file: string): Promise<{ restored: true; state: "stopped" }> {
     await this.#stop();
     const elapsed = (await this.#machine.clock()) - this.#timingStart;
+    // The restore replaces the whole machine state, so the reset that stops the autostart leaves no trace.
+    if (this.#autostarting) await this.#reset({ mode: "soft", run: false });
     await this.#machine.restoreSnapshot(file);
+    this.#historySince = await this.#machine.clock();
     // A restore starts a jammed CPU again, but VICE still records no CPU history.
     this.#jammed = undefined;
     if (this.#historyStopped) this.#historyOld = true;
@@ -1534,6 +1561,8 @@ export class ViceSession implements ViceSessionHandle {
 
   async #translate(error: unknown, runningBefore: boolean, halts: number): Promise<unknown> {
     if (error instanceof WireFailure) return error;
+    // A refusal of a shared module (for example the media check) goes on the wire as the host's own.
+    if (isRefusal(error)) return new WireFailure(error.code, error.message);
     if (this.#closed) return new WireFailure("machine-unavailable", "The emulator session is closed.");
     if (error instanceof MonitorConnectionError || error instanceof TextMonitorError || error instanceof StepTimeout) {
       this.#log(error.message);
@@ -1614,6 +1643,23 @@ export class ViceSession implements ViceSessionHandle {
   }
 }
 
+/**
+ * The history entries (oldest first) that the CPU executed after a restore at
+ * clock `since`, with the clock at `now`: the last entries, back to the first
+ * one outside since to now or the first one whose clock does not go up to the
+ * next. The others are of before the restore.
+ */
+export function entriesSince<T extends { clock: bigint }>(entries: readonly T[], since: bigint | undefined, now: bigint): T[] {
+  if (since === undefined) return [...entries];
+  let first = entries.length;
+  while (first > 0) {
+    const entry = entries[first - 1]!;
+    if (entry.clock < since || entry.clock > now || (first < entries.length && entry.clock >= entries[first]!.clock)) break;
+    first--;
+  }
+  return entries.slice(first);
+}
+
 /** The one attachment of an operation that takes a file (see attachmentCount); refuses any other count. */
 function onlyAttachment(attachments: Buffer[]): Buffer {
   const [bytes] = attachments;

package/src/host-client/image.ts

@@ -36,6 +36,12 @@ const MEDIA_KINDS: Record<string, string> = {
 /** The remedy for a disk, tape or cartridge file where a PRG must be: get the PRG out of it. */
 export const MEDIA_REMEDY = "Get the PRG out of it with disk.ts read (or disk.ts crt for a cartridge) of the c64-disk skill";
 
+/** Refuses a disk, tape or cartridge file by its extension (`type`, lowercase, without the dot): invalid-input with `remedy`. */
+function refuseMedia(path: string, type: string, remedy: string): void {
+  const media = MEDIA_KINDS[type];
+  if (media !== undefined) throw new Refusal("invalid-input", `${path} is ${media} (.${type}), not a PRG. ${remedy}.`);
+}
+
 /**
  * Reads a PRG of the project: a 2-byte load address, and bytes that end at
  * $ffff or before. Refuses a disk, tape or cartridge file and any other file
@@ -43,8 +49,7 @@ export const MEDIA_REMEDY = "Get the PRG out of it with disk.ts read (or disk.ts
  */
 export function readPrg(path: string, remedy = MEDIA_REMEDY): { bytes: Buffer; start: number; end: number; body: Uint8Array } {
   const { bytes, type } = readProjectFile(path);
-  const media = MEDIA_KINDS[type];
-  if (media !== undefined) throw new Refusal("invalid-input", `${path} is ${media} (.${type}), not a PRG. ${remedy}.`);
+  refuseMedia(path, type, remedy);
   try {
     return { bytes, ...prgRange(bytes) };
   } catch (error) {
@@ -53,18 +58,13 @@ export function readPrg(path: string, remedy = MEDIA_REMEDY): { bytes: Buffer; s
   }
 }
 
-/** Reads an image.json or a PRG, relative to the project folder. */
+/** Reads an image.json or a PRG, relative to the project folder. Refuses a disk, tape or cartridge file as readPrg does. */
 export function readImage(path: string): Image {
-  const { bytes } = readProjectFile(path);
   if (!path.endsWith(".json")) {
-    let range: ReturnType<typeof prgRange>;
-    try {
-      range = prgRange(bytes);
-    } catch (error) {
-      throw new Refusal("invalid-input", `${path}: ${(error as Error).message}`);
-    }
+    const range = readPrg(path);
     return { segments: [{ start: range.start, end: range.end }], byteAt: (address) => range.body[address - range.start]! };
   }
+  const { bytes } = readProjectFile(path);
   const fail = (what: string): never => {
     throw new Refusal("invalid-input", `${path} is not an image.json of the c64-unpacker skill: ${what}`);
   };

package/src/host-client/steps.ts

@@ -384,8 +384,42 @@ export function checkActionSteps(value: unknown, fail: (message: string) => neve
   });
 }
 
-/** Reads a steps file of the project: a JSON list of action steps. `option` names the option of the file in a refusal. */
-export function readActionSteps(path: string, option: string): ActionStep[] {
+/** The names and addresses of an action step: each location that the step resolves when it runs. */
+export function stepLocations(step: ActionStep): Location[] {
+  if ("write" in step) return [step.write.address];
+  if ("registers" in step) return step.registers.pc === undefined ? [] : [step.registers.pc];
+  if (!("runUntil" in step)) return [];
+  const { target } = step.runUntil;
+  if (target.kind === "raster") return [];
+  if (target.kind === "memory") return [target.address];
+  return [target.address, ...(target.condition?.kind === "memory" ? [target.condition.address] : [])];
+}
+
+/**
+ * Resolves every name of the steps with `at` before the steps run, so that an
+ * unknown name stops the call before the emulator starts. A refusal of `at` becomes
+ * invalid-input that names `where` (for example the option and the file) and the step.
+ * `first` is the number of the first of the steps in the file.
+ */
+export function checkStepNames(steps: readonly ActionStep[], at: (location: Location) => number, where: string, first = 1): void {
+  steps.forEach((step, index) => {
+    for (const location of stepLocations(step)) {
+      try {
+        at(location);
+      } catch (error) {
+        if (isRefusal(error)) throw new Refusal("invalid-input", `${where}: step ${index + first}: ${error.message}`);
+        throw error;
+      }
+    }
+  });
+}
+
+/**
+ * Reads a steps file of the project: a JSON list of action steps. `option`
+ * names the option of the file in a refusal. With `at`, every name of the
+ * steps must resolve (checkStepNames).
+ */
+export function readActionSteps(path: string, option: string, at?: (location: Location) => number): ActionStep[] {
   const fail = (message: string): never => {
     throw new Refusal("invalid-input", `${option} ${path}: ${message}`);
   };
@@ -396,7 +430,9 @@ export function readActionSteps(path: string, option: string): ActionStep[] {
     if (error instanceof SyntaxError) return fail(`it is not JSON: ${error.message}`);
     throw error;
   }
-  return checkActionSteps(value, fail);
+  const steps = checkActionSteps(value, fail);
+  if (at !== undefined) checkStepNames(steps, at, `${option} ${path}`);
+  return steps;
 }
 
 /** Stops the CPU when it runs: a write, a register change or an exact frame count needs it stopped. */

package/src/host-client/transfer.ts

@@ -2,10 +2,10 @@
 // The host never sees a client path: only bytes and the file's type.
 
 import { createHash } from "node:crypto";
-import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import { dirname, extname, join, relative, sep } from "node:path";
 
-import { isInside, projectRoot, resolveProject, resolveProjectFile, resolveProjectPath } from "../project.ts";
+import { checkOutputPath, isInside, projectRoot, resolveProject, resolveProjectFile, writeProblem } from "../project.ts";
 import { isRefusal } from "../errors.ts";
 import { MAX_ATTACHMENT_BYTES } from "../protocol/framing.ts";
 import { WireFailure } from "../protocol/messages.ts";
@@ -58,49 +58,37 @@ export function readProjectFile(path: string, options: { root?: string } = {}):
   return { bytes: readFileSync(real), type: extname(path).slice(1).toLowerCase() };
 }
 
-/** Why a file cannot be written, by the error code of the file system; the codes that are a fault of the path. */
-const WRITE_PROBLEMS: Record<string, string> = {
-  EISDIR: "is a folder. Give the path of a file",
-  EEXIST: "has a file where a folder must be. Give a path whose folders are folders",
-  ENOTDIR: "has a file where a folder must be. Give a path whose folders are folders",
-  ENOENT: "is in a folder that does not exist",
-  EACCES: "cannot be written: there is no permission. Give a path that you can write",
-  EPERM: "cannot be written: there is no permission. Give a path that you can write",
-  EROFS: "is on a file system that is read-only. Give another path",
-  ENAMETOOLONG: "is too long. Give a shorter path",
-};
-
 /**
  * The refusal for a write that the file system refused because of the path
  * (a folder, a file in place of a folder, no permission): invalid-input with
  * the path. Undefined for another error, which is no fault of the path.
  */
 export function writeRefusal(error: unknown, path: string, what?: string): WireFailure | undefined {
-  const problem = WRITE_PROBLEMS[(error as NodeJS.ErrnoException | undefined)?.code ?? ""];
-  return problem === undefined ? undefined : new WireFailure("invalid-input", `${what === undefined ? "" : `${what}: `}${path} ${problem}.`);
+  const message = writeProblem(error, path, what);
+  return message === undefined ? undefined : new WireFailure("invalid-input", message);
 }
 
 /**
  * Writes bytes to a project file on the client side, making its directories
- * and overwriting it. Throws WireFailure(invalid-input) for a path outside the
- * project, also one that leaves it through a symbolic link, and for a path
- * that the file system refuses: a folder, a file in place of a folder, no permission.
+ * and overwriting it. First the check of checkOutputPath, which a script also
+ * does on its output options before any work. Throws WireFailure(invalid-input)
+ * for a path outside the project, also one that leaves it through a symbolic
+ * link, for a path in the knowledge, and for a path that the file system
+ * refuses: a folder, a file in place of a folder, no permission.
  */
 export function writeProjectFile(path: string, bytes: Uint8Array, options: { root?: string; what?: string } = {}): void {
   const root = options.root ?? currentProject();
   const refuse = () => new WireFailure("invalid-input", `${options.what ?? path}: give a path relative to the project folder that stays inside it, not ${path}.`);
   let file: string;
   try {
-    file = resolveProjectPath(path, root);
-  } catch {
-    throw refuse();
+    file = checkOutputPath(path, "file", { root, ...(options.what === undefined ? {} : { what: options.what }) });
+  } catch (error) {
+    if (isRefusal(error)) throw new WireFailure(error.code, error.message);
+    throw error;
   }
-  // The nearest folder that exists must be inside the project before a folder is made below it.
-  let existing = dirname(file);
-  while (!existsSync(existing)) existing = dirname(existing);
-  if (!isInside(realpathSync(root), realpathSync(existing))) throw refuse();
   try {
     mkdirSync(dirname(file), { recursive: true });
+    // Again after the folders are made: another process can change the folders between the check and the write.
     if (!isInside(realpathSync(root), realpathSync(dirname(file)))) throw refuse();
     let link = false;
     try {

package/src/knowledge/history.ts

@@ -37,7 +37,7 @@ import {
   type SuppressionRow,
   type SymbolRow,
 } from "./read.ts";
-import { DEFAULT_SPACE, type EvidenceKind, type Origin, type Space } from "./schema.ts";
+import { DEFAULT_SPACE, type CoverageKind, type EvidenceKind, type Origin, type Space } from "./schema.ts";
 import { compareText, NO_REVISION } from "./text.ts";
 import type { Evidence } from "./write.ts";
 
@@ -51,12 +51,47 @@ export interface Revision {
   toolVersion?: string;
   /** A revert: the revision whose knowledge it restored. */
   restores?: string;
+  /** A revert of one space: that space. A revert without it restored every space. */
+  restoresSpace?: Space;
   /** What the change rests on. */
   evidence?: Evidence[];
 }
 
+/** A memory row of the program: the bytes from an address. */
+export interface MemoryRow {
+  space: Space;
+  address: number;
+  /** The count of bytes in the row. */
+  bytes: number;
+  origin: Origin;
+  revision: string;
+}
+
+/** The entry of the program, and whether it has a machine state and stages. */
+export interface EntryRow {
+  space: Space;
+  address: number;
+  state: boolean;
+  stages: number;
+  origin: Origin;
+  revision: string;
+}
+
+/** A coverage range of one kind. */
+export interface CoverageRow {
+  space: Space;
+  kind: CoverageKind;
+  start: number;
+  end: number;
+  origin: Origin;
+  revision: string;
+}
+
 /** One knowledge row with its validity: from its first revision until the revision that closed it. */
 export type HistoryEntry =
+  | { entity: "memory"; row: MemoryRow; from: string; to?: string }
+  | { entity: "entry"; row: EntryRow; from: string; to?: string }
+  | { entity: "coverage"; row: CoverageRow; from: string; to?: string }
   | { entity: "symbol"; row: SymbolRow; from: string; to?: string }
   | { entity: "analyzer-name"; row: SymbolRow; from: string; to?: string }
   | { entity: "region"; row: RegionRow; from: string; to?: string }
@@ -82,6 +117,7 @@ function toRevision(row: Raw): Revision {
   if (row.input_hash !== null) revision.inputHash = row.input_hash as string;
   if (row.tool_version !== null) revision.toolVersion = row.tool_version as string;
   if (row.restored_revision !== null) revision.restores = row.restored_revision as string;
+  if (row.restored_space !== null && row.restored_space !== undefined) revision.restoresSpace = row.restored_space as Space;
   return revision;
 }
 
@@ -183,6 +219,7 @@ export interface InitialRevision {
   inputHash?: undefined;
   toolVersion?: undefined;
   restores?: undefined;
+  restoresSpace?: undefined;
   evidence?: undefined;
 }
 
@@ -213,9 +250,25 @@ export function revision(db: DatabaseSync | undefined, text: string): RevisionCh
     ["macro", "macros", MACRO_COLUMNS, toMacro],
     ["macro-use", "macro_uses", MACRO_USE_COLUMNS, toMacroUse],
   ] as const;
+  // The program: its memory, its entry and its coverage.
+  const program = [
+    ["memory", "memory", "space, address, length(bytes) / 2 AS bytes, origin, valid_from_revision", (row: Raw): MemoryRow => ({ space: row.space as Space, address: row.address as number, bytes: row.bytes as number, origin: row.origin as Origin, revision: row.valid_from_revision as string })],
+    [
+      "entry",
+      "entries",
+      "space, address, state IS NOT NULL AS has_state, json_array_length(coalesce(stages, '[]')) AS stage_count, origin, valid_from_revision",
+      (row: Raw): EntryRow => ({ space: row.space as Space, address: row.address as number, state: row.has_state === 1, stages: row.stage_count as number, origin: row.origin as Origin, revision: row.valid_from_revision as string }),
+    ],
+    [
+      "coverage",
+      "coverage",
+      "space, kind, start_address, end_address, origin, valid_from_revision",
+      (row: Raw): CoverageRow => ({ space: row.space as Space, kind: row.kind as CoverageKind, start: row.start_address as number, end: row.end_address as number, origin: row.origin as Origin, revision: row.valid_from_revision as string }),
+    ],
+  ] as const;
   const added: HistoryEntry[] = [];
   const closed: HistoryEntry[] = [];
-  for (const [entity, table, columns, map] of tables) {
+  for (const [entity, table, columns, map] of [...tables, ...program]) {
     for (const row of db.prepare(`SELECT ${columns}, valid_to_revision FROM ${table} WHERE valid_from_revision = ?`).all(id) as Raw[]) {
       added.push(entry(entity, map(row), row));
     }

package/src/knowledge/import.ts

@@ -77,7 +77,18 @@ export type ImportConflict =
       current: { address: number; name: string; kind: SymbolKind; origin: Origin };
       finding: { name: string; kind: SymbolKind };
     }
-  | { category: "region"; start: number; end: number; current: { type: RegionType; origin: Origin }; finding: { type: RegionType } };
+  | { category: "region"; start: number; end: number; current: { type: RegionType; origin: Origin }; finding: { type: RegionType } }
+  | {
+      /** A data finding over code that a run executed or that the user or the LLM named: the finding is not imported. */
+      category: "code-evidence";
+      start: number;
+      end: number;
+      finding: { type: RegionType };
+      /** The first executed instruction start in the range. */
+      executed?: number;
+      /** The first code name (label or routine) of the user or the LLM in the range. */
+      symbol?: { address: number; name: string; kind: SymbolKind; origin: Origin };
+    };
 
 export interface ImportCounts {
   added: number;
@@ -252,16 +263,53 @@ const YIELDS_TO_HEURISTIC = new Set<Origin>(["dxa", "ghidra"]);
 /** Analyzers whose data gives way to a code finding over an executed instruction start. */
 const YIELDS_TO_EXECUTED_CODE = new Set<Origin>(["dxa", "ghidra"]);
 
+/** The first address in the range that is an executed instruction start, or undefined. */
+function firstExecuted(findings: NormalizedFindings, start: number, end: number): number | undefined {
+  if (findings.executed === undefined) return undefined;
+  for (let address = start; address <= end; address++) if (findings.executed(address)) return address;
+  return undefined;
+}
+
 /** True when an address in the range is an executed instruction start. */
 function holdsExecuted(findings: NormalizedFindings, start: number, end: number): boolean {
-  if (findings.executed === undefined) return false;
-  for (let address = start; address <= end; address++) if (findings.executed(address)) return true;
-  return false;
+  return firstExecuted(findings, start, end) !== undefined;
 }
 
-function importRegions(db: DatabaseSync, change: Change, findings: NormalizedFindings, coverage: AddressRange[], result: ImportResult): void {
-  const { analyzer } = findings;
-  const space = findings.space ?? DEFAULT_SPACE;
+/**
+ * The data findings of DXA or Ghidra that code evidence contradicts: an
+ * executed instruction start, or a code name (label or routine) of the user or
+ * the LLM, in the range. Evidence wins over an analyzer guess: such a finding
+ * is not imported, and the analyzer's own code there stays.
+ */
+function contradictedData(db: DatabaseSync, findings: NormalizedFindings, space: Space): Array<ImportConflict & { category: "code-evidence" }> {
+  if (!YIELDS_TO_EXECUTED_CODE.has(findings.analyzer)) return [];
+  const names = db.prepare(`SELECT ${SYMBOL_COLUMNS} FROM current_symbols WHERE space = ? AND origin IN ('user', 'llm') AND kind IN ('label', 'routine') AND address BETWEEN ? AND ? ORDER BY address LIMIT 1`);
+  const found: Array<ImportConflict & { category: "code-evidence" }> = [];
+  for (const region of findings.regions) {
+    if (isCode(region.type) || region.type === "dual-use") continue;
+    const executed = firstExecuted(findings, region.start, region.end);
+    const raw = names.get(space, region.start, region.end) as Record<string, unknown> | undefined;
+    if (executed === undefined && raw === undefined) continue;
+    const symbol = raw === undefined ? undefined : toSymbol(raw);
+    found.push({
+      category: "code-evidence",
+      start: region.start,
+      end: region.end,
+      finding: { type: region.type },
+      ...(executed === undefined ? {} : { executed }),
+      ...(symbol === undefined ? {} : { symbol: { address: symbol.address, name: symbol.name, kind: symbol.kind, origin: symbol.origin } }),
+    });
+  }
+  return found;
+}
+
+function importRegions(db: DatabaseSync, change: Change, given: NormalizedFindings, coverage: AddressRange[], result: ImportResult): void {
+  const { analyzer } = given;
+  const space = given.space ?? DEFAULT_SPACE;
+  // Data findings over code evidence are conflicts, not facts.
+  const contradicted = contradictedData(db, given, space);
+  result.conflicts.push(...contradicted);
+  const findings = { ...given, regions: given.regions.filter((region) => !contradicted.some((item) => item.start === region.start && item.end === region.end)) };
   if (analyzer === "heuristic") {
     // An idiom is specific evidence about its bytes: the DXA or Ghidra region there gives way, its parts outside stay.
     for (const region of findings.regions) {
@@ -333,6 +381,14 @@ function importRegions(db: DatabaseSync, change: Change, findings: NormalizedFin
       if (suppressed.length > 0) result.regions.suppressed++;
       for (const piece of subtract(region, [...protectedRows, ...suppressed])) desired.set(`${piece.start}-${piece.end}`, { ...piece, type: region.type });
     }
+    // Under a contradicted data finding, the analyzer's own regions stay: they join the findings of the same type next to them.
+    for (const row of own) {
+      for (const item of contradicted) {
+        const inside = { start: Math.max(row.start, item.start, range.start), end: Math.min(row.end, item.end, range.end) };
+        if (inside.start > inside.end) continue;
+        for (const piece of subtract(inside, [...protectedRows, ...suppressionsOverlapping(db, "region", inside.start, inside.end, space)])) keepPiece(desired, { ...piece, type: row.type });
+      }
+    }
     const retiredRanges = new Set<string>();
     for (const row of own) {
       const inside = { start: Math.max(row.start, range.start), end: Math.min(row.end, range.end) };
@@ -357,6 +413,22 @@ function importRegions(db: DatabaseSync, change: Change, findings: NormalizedFin
   }
 }
 
+/** Puts a kept piece into the desired regions, joined with the pieces of the same type that touch or overlap it. */
+function keepPiece(desired: Map<string, { start: number; end: number; type: RegionType }>, piece: { start: number; end: number; type: RegionType }): void {
+  let joined = { ...piece };
+  for (let found = true; found; ) {
+    found = false;
+    for (const [key, other] of desired) {
+      if (other.type !== joined.type || other.end + 1 < joined.start || joined.end + 1 < other.start) continue;
+      desired.delete(key);
+      joined = { start: Math.min(joined.start, other.start), end: Math.max(joined.end, other.end), type: joined.type };
+      found = true;
+      break;
+    }
+  }
+  desired.set(`${joined.start}-${joined.end}`, joined);
+}
+
 function importReferences(db: DatabaseSync, change: Change, findings: NormalizedFindings, coverage: AddressRange[], result: ImportResult): void {
   const { analyzer } = findings;
   const space = findings.space ?? DEFAULT_SPACE;