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

package/src/host-client/steps.ts

@@ -0,0 +1,170 @@
+// The action steps of the step language (D43): write, registers, joystick,
+// type, frames and runUntil. c64-testing scenarios and the c64-unpacker
+// steps file share them; each caller adds its own steps around them.
+
+import { parseC64Address, textToPetscii } from "../c64.ts";
+import { JOYSTICK_DIRECTIONS, MAX_EXECUTION_COUNT, MAX_KEYBOARD_BYTES, MAX_MEMORY_WRITE, MAX_TIMEOUT_FRAMES } from "../protocol/vice.ts";
+import type { RunTarget, RunUntilResult } from "../protocol/vice.ts";
+import type { ViceSessionClient } from "./vice-session.ts";
+
+/** A "$xxxx" address, or a symbol name where the caller resolves names. */
+export type Location = string;
+
+type JoystickDirection = (typeof JOYSTICK_DIRECTIONS)[number];
+
+export type ActionStep =
+  | { write: { at: Location; bytes: number[] } }
+  | { registers: Partial<Record<"pc" | "a" | "x" | "y" | "sp", number | Location>> }
+  | { joystick: { port: 1 | 2; direction: JoystickDirection; fire?: boolean } }
+  | { type: string }
+  | { frames: number }
+  | { runUntil: { at: Location; raster?: number } | { raster: number } | { memory: { at: Location; equals: number } }; timeoutFrames: number };
+
+/** The highest raster line of a PAL frame; an NTSC frame has fewer, which the emulator checks. */
+const MAX_RASTER_LINE = 311;
+
+export const ACTION_STEP_KINDS = ["write", "registers", "joystick", "type", "frames", "runUntil"] as const;
+
+/** The keys a step of each kind can have, when it is more than the kind itself. */
+export const ACTION_STEP_KEYS: Record<string, readonly string[]> = { runUntil: ["runUntil", "timeoutFrames"] };
+
+/** The registers a registers step can set. */
+export const SET_REGISTERS = ["pc", "a", "x", "y", "sp"];
+
+export const isObject = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+export const isInteger = (value: unknown, min: number, max: number): value is number => Number.isInteger(value) && (value as number) >= min && (value as number) <= max;
+
+/** Checks a "$xxxx" address, or also a symbol name when `names` allows it. */
+export function checkLocation(value: unknown, what: string, fail: (message: string) => never, names = true): void {
+  if (typeof value !== "string" || value === "") fail(`${what} must be a $ address${names ? " or a symbol name" : ""}`);
+  if ((value as string).startsWith("$")) {
+    try {
+      parseC64Address(value as string);
+    } catch {
+      fail(`${what} must be $ followed by four hex digits, not ${value as string}`);
+    }
+  } else if (!names) {
+    fail(`${what} must be $ followed by four hex digits, not ${value as string}`);
+  }
+}
+
+/** Checks one action step of the given kind. `names` says whether symbol names may stand for addresses. */
+export function checkActionStep(kind: string, step: Record<string, unknown>, at: string, fail: (message: string) => never, names = true): void {
+  switch (kind) {
+    case "write": {
+      const write = step.write;
+      if (!isObject(write) || Object.keys(write).some((key) => key !== "at" && key !== "bytes")) return fail(`${at}: write needs at and bytes, and nothing else`);
+      checkLocation(write.at, `${at}: write.at`, fail, names);
+      if (!Array.isArray(write.bytes) || write.bytes.length === 0 || write.bytes.length > MAX_MEMORY_WRITE || !write.bytes.every((byte) => isInteger(byte, 0, 0xff))) {
+        fail(`${at}: write.bytes must be a list of 1 to ${MAX_MEMORY_WRITE} numbers from 0 to 255`);
+      }
+      return;
+    }
+    case "registers": {
+      const registers = step.registers;
+      if (!isObject(registers) || Object.keys(registers).length === 0) return fail(`${at}: registers must name at least one of ${SET_REGISTERS.join(", ")}`);
+      for (const [name, value] of Object.entries(registers)) {
+        if (!SET_REGISTERS.includes(name)) fail(`${at}: registers can set only ${SET_REGISTERS.join(", ")}, not ${name}`);
+        if (typeof value === "string") checkLocation(value, `${at}: registers.${name}`, fail, names);
+        else if (!isInteger(value, 0, name === "pc" ? 0xffff : 0xff)) fail(`${at}: registers.${name} must be ${names ? "a symbol name, " : ""}a $ address or a number from 0 to ${name === "pc" ? 65535 : 255}`);
+      }
+      return;
+    }
+    case "joystick": {
+      const joystick = step.joystick;
+      if (!isObject(joystick) || Object.keys(joystick).some((key) => !["port", "direction", "fire"].includes(key))) return fail(`${at}: joystick needs port and direction, and fire is optional`);
+      if (joystick.port !== 1 && joystick.port !== 2) fail(`${at}: joystick.port must be 1 or 2`);
+      if (!(JOYSTICK_DIRECTIONS as readonly unknown[]).includes(joystick.direction)) fail(`${at}: joystick.direction must be one of ${JOYSTICK_DIRECTIONS.join(", ")}`);
+      if (joystick.fire !== undefined && typeof joystick.fire !== "boolean") fail(`${at}: joystick.fire must be true or false`);
+      return;
+    }
+    case "type": {
+      if (typeof step.type !== "string" || step.type === "") return fail(`${at}: type needs text`);
+      let bytes: Uint8Array;
+      try {
+        bytes = textToPetscii(step.type);
+      } catch (error) {
+        return fail(`${at}: ${(error as Error).message}`);
+      }
+      if (bytes.length > MAX_KEYBOARD_BYTES) fail(`${at}: type can have at most ${MAX_KEYBOARD_BYTES} keys`);
+      return;
+    }
+    case "frames":
+      if (!isInteger(step.frames, 1, MAX_EXECUTION_COUNT)) fail(`${at} needs a frame count from 1 to ${MAX_EXECUTION_COUNT}`);
+      return;
+    case "runUntil": {
+      const target = step.runUntil;
+      const keys = isObject(target) ? Object.keys(target).sort().join(",") : "";
+      // at, raster, at with raster (the address only on that line, D46), or memory.
+      if (!["at", "raster", "at,raster", "memory"].includes(keys)) return fail(`${at}: runUntil needs at, raster, at and raster, or memory`);
+      const until = target as Record<string, unknown>;
+      if ("raster" in until && !isInteger(until.raster, 0, MAX_RASTER_LINE)) fail(`${at}: runUntil.raster must be a raster line from 0 to ${MAX_RASTER_LINE}`);
+      if ("at" in until) checkLocation(until.at, `${at}: runUntil.at`, fail, names);
+      else if ("memory" in until) {
+        const memory = until.memory;
+        if (!isObject(memory) || Object.keys(memory).some((key) => key !== "at" && key !== "equals")) return fail(`${at}: runUntil.memory needs at and equals, and nothing else`);
+        checkLocation(memory.at, `${at}: runUntil.memory.at`, fail, names);
+        if (!isInteger(memory.equals, 0, 0xff)) fail(`${at}: runUntil.memory.equals must be a number from 0 to 255`);
+      }
+      if (!isInteger(step.timeoutFrames, 1, MAX_TIMEOUT_FRAMES)) fail(`${at} needs timeoutFrames from 1 to ${MAX_TIMEOUT_FRAMES}`);
+      return;
+    }
+    default:
+      fail(`${at}: ${kind} is not an action step`);
+  }
+}
+
+/** Checks a list of action steps only, with $ addresses only: the steps file of c64-unpacker. */
+export function checkActionSteps(value: unknown, fail: (message: string) => never): ActionStep[] {
+  if (!Array.isArray(value) || value.length === 0) return fail("the steps are a JSON list with at least one step");
+  value.forEach((step: unknown, index) => {
+    const at = `step ${index + 1}`;
+    if (!isObject(step)) return fail(`${at} must be an object`);
+    const kinds = Object.keys(step).filter((key) => (ACTION_STEP_KINDS as readonly string[]).includes(key));
+    if (kinds.length !== 1) return fail(`${at} must have exactly one of ${ACTION_STEP_KINDS.join(", ")}`);
+    const kind = kinds[0]!;
+    const allowed = ACTION_STEP_KEYS[kind] ?? [kind];
+    for (const key of Object.keys(step)) if (!allowed.includes(key)) fail(`${at} has the key ${key}, which a ${kind} step does not have`);
+    checkActionStep(kind, step, at, fail, false);
+  });
+  return value as ActionStep[];
+}
+
+/** Stops the CPU when it runs: a write, a register change or an exact frame count needs it stopped. */
+async function stop(client: ViceSessionClient): Promise<void> {
+  if ((await client.status()).state === "running") await client.execution({ action: "pause", space: "c64" });
+}
+
+/**
+ * Runs one action step. `at` turns a location into an address. A runUntil
+ * step that does not reach its target returns the stop, for the caller to judge.
+ */
+export async function runActionStep(client: ViceSessionClient, step: ActionStep, at: (location: Location) => number): Promise<RunUntilResult | undefined> {
+  if ("write" in step) {
+    await stop(client);
+    await client.memoryWrite({ address: at(step.write.at), data: Buffer.from(step.write.bytes).toString("hex"), space: "c64", view: "cpu" });
+  } else if ("registers" in step) {
+    await stop(client);
+    const values: Record<string, number> = {};
+    for (const [name, value] of Object.entries(step.registers)) values[name] = typeof value === "number" ? value : at(value as Location);
+    await client.registersSet("c64", values);
+  } else if ("joystick" in step) {
+    await client.joystick({ port: step.joystick.port, direction: step.joystick.direction, fire: step.joystick.fire ?? false });
+  } else if ("type" in step) {
+    await client.keyboard(textToPetscii(step.type));
+  } else if ("frames" in step) {
+    await stop(client);
+    await client.execution({ action: "advance-frames", count: step.frames, space: "c64" });
+  } else {
+    const until = step.runUntil;
+    const target: RunTarget =
+      "at" in until
+        ? { kind: "address", address: at(until.at), space: "c64", ...(until.raster === undefined ? {} : { condition: { kind: "raster" as const, line: until.raster } }) }
+        : "raster" in until
+          ? { kind: "raster", line: until.raster }
+          : { kind: "memory", address: at(until.memory.at), operator: "eq", value: until.memory.equals, space: "c64", view: "cpu" };
+    const reached = await client.runUntil({ target, timeoutFrames: step.timeoutFrames });
+    if (!reached.reached) return reached;
+  }
+  return undefined;
+}

package/src/host-client/transfer.ts

@@ -1,10 +1,10 @@
 // Reads project files on the client side for transfer to the Host Runtime.
 // The host never sees a client path: only bytes and the file's type.
 
-import { readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
-import { extname, join, relative, sep } from "node:path";
+import { lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { dirname, extname, join, relative, sep } from "node:path";
 
-import { isInside, projectRoot, resolveProjectFile } from "../project.ts";
+import { isInside, projectRoot, resolveProjectFile, resolveProjectPath } from "../project.ts";
 import { MAX_ATTACHMENT_BYTES } from "../protocol/framing.ts";
 import { WireFailure } from "../protocol/messages.ts";
 import { MAX_TREE_FILES, type SourceTree } from "../protocol/tools.ts";
@@ -42,6 +42,32 @@ export function readProjectFile(path: string, options: { root?: string } = {}):
   return { bytes: readFileSync(real), type: extname(path).slice(1).toLowerCase() };
 }
 
+/**
+ * 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.
+ */
+export function writeProjectFile(path: string, bytes: Uint8Array, options: { root?: string; what?: string } = {}): void {
+  const root = options.root ?? projectRoot();
+  const refuse = () => new WireFailure("invalid-input", `${options.what ?? path}: give a path relative to the project directory that stays inside it, not ${path}.`);
+  let file: string;
+  try {
+    file = resolveProjectPath(path, root);
+  } catch {
+    throw refuse();
+  }
+  mkdirSync(dirname(file), { recursive: true });
+  if (!isInside(realpathSync(root), realpathSync(dirname(file)))) throw refuse();
+  let link = false;
+  try {
+    link = lstatSync(file).isSymbolicLink();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  if (link) throw refuse();
+  writeFileSync(file, bytes);
+}
+
 /** Directories never staged: version control and the toolkit's own project state. */
 const SKIPPED_DIRECTORIES = new Set([".git", ".hg", ".svn", ".c64-re-tools"]);
 

package/src/host-client/vice-session.ts

@@ -2,7 +2,7 @@
 // one VICE. Exposes C64-domain operations only.
 
 import { ProtocolError, WireFailure, type VideoStandard } from "../protocol/messages.ts";
-import { validateViceResult, type Breakpoint, type BreakpointParams, type Watchpoint, type WatchpointParams, type ExecutionParams, type ExecutionResult, type JoystickState, type MachineStatus, type MemmapRange, type MemoryWriteParams, type RegisterValues, type ResetMode, type RunState, type RunTarget, type RunUntilResult, type MemoryReadParams, type MemoryReadResult, type Registers, type Space, type ViceOperation, type ViceOperations } from "../protocol/vice.ts";
+import { validateViceResult, type Breakpoint, type BreakpointParams, type PointRemoved, type Watchpoint, type WatchpointParams, type ExecutionParams, type ExecutionResult, type JoystickState, type MachineStatus, type MemmapRange, type MemoryWriteParams, type RegisterValues, type ResetMode, type RunState, type RunTarget, type RunUntilResult, type MemoryReadParams, type MemoryReadResult, type Registers, type Space, type ViceOperation, type ViceOperations } from "../protocol/vice.ts";
 import { HostConnection } from "./connect.ts";
 import { readProjectFile } from "./transfer.ts";
 
@@ -13,7 +13,7 @@ const SESSION_CLOSED = "The C64 session is closed because the c64-re-tools MCP s
 
 interface Pending {
   op: ViceOperation;
-  resolve: (value: unknown) => void;
+  resolve: (value: unknown, attachments: Buffer[]) => void;
   reject: (error: Error) => void;
 }
 
@@ -27,7 +27,7 @@ export class ViceSessionClient {
 
   private constructor(connection: HostConnection) {
     this.#connection = connection;
-    connection.onMessage((message) => {
+    connection.onMessage((message, attachments) => {
       // Anything but a reply after the handshake breaks the contract.
       if (message.type !== "reply") return this.#fail();
       const pending = this.#pending.get(message.id);
@@ -38,7 +38,7 @@ export class ViceSessionClient {
         return;
       }
       try {
-        pending.resolve(validateViceResult(pending.op, message.result));
+        pending.resolve(validateViceResult(pending.op, message.result), attachments);
       } catch (error) {
         pending.reject(
           new WireFailure(
@@ -75,6 +75,11 @@ export class ViceSessionClient {
     return this.#request("memoryRead", params);
   }
 
+  /** The I/O registers at $d000-$dfff as the chips hold them, without side effects. */
+  ioRead(address: number, size: number): Promise<MemoryReadResult> {
+    return this.#request("ioRead", { address, size });
+  }
+
   registersGet(space: Space): Promise<Registers> {
     return this.#request("registersGet", { space });
   }
@@ -138,17 +143,19 @@ export class ViceSessionClient {
     return this.#request("joystick", state);
   }
 
-  /** Action list gives all breakpoints; every other action gives the one breakpoint it added or changed. */
+  /** Action list gives all breakpoints, remove gives `{removed, id}`; add, enable and disable give the one breakpoint. */
   breakpoint(params: Extract<BreakpointParams, { action: "list" }>): Promise<{ breakpoints: Breakpoint[] }>;
-  breakpoint(params: Exclude<BreakpointParams, { action: "list" }>): Promise<Breakpoint>;
-  breakpoint(params: BreakpointParams): Promise<Breakpoint | { breakpoints: Breakpoint[] }> {
+  breakpoint(params: Extract<BreakpointParams, { action: "remove" }>): Promise<PointRemoved>;
+  breakpoint(params: Exclude<BreakpointParams, { action: "list" | "remove" }>): Promise<Breakpoint>;
+  breakpoint(params: BreakpointParams): Promise<Breakpoint | PointRemoved | { breakpoints: Breakpoint[] }> {
     return this.#request("breakpoint", params);
   }
 
-  /** Action list gives all watchpoints; every other action gives the one watchpoint it added or changed. */
+  /** Action list gives all watchpoints, remove gives `{removed, id}`; add, enable and disable give the one watchpoint. */
   watchpoint(params: Extract<WatchpointParams, { action: "list" }>): Promise<{ watchpoints: Watchpoint[] }>;
-  watchpoint(params: Exclude<WatchpointParams, { action: "list" }>): Promise<Watchpoint>;
-  watchpoint(params: WatchpointParams): Promise<Watchpoint | { watchpoints: Watchpoint[] }> {
+  watchpoint(params: Extract<WatchpointParams, { action: "remove" }>): Promise<PointRemoved>;
+  watchpoint(params: Exclude<WatchpointParams, { action: "list" | "remove" }>): Promise<Watchpoint>;
+  watchpoint(params: WatchpointParams): Promise<Watchpoint | PointRemoved | { watchpoints: Watchpoint[] }> {
     return this.#request("watchpoint", params);
   }
 
@@ -169,7 +176,7 @@ export class ViceSessionClient {
   }
 
   /** Action read gives the ranges; action clear gives cleared. */
-  memmap(params: Extract<ViceOperations["memmap"]["params"], { action: "read" }>): Promise<{ ranges: MemmapRange[] }>;
+  memmap(params: Extract<ViceOperations["memmap"]["params"], { action: "read" }>): Promise<{ ranges: MemmapRange[]; next?: number }>;
   memmap(params: { action: "clear" }): Promise<{ cleared: boolean }>;
   memmap(params: ViceOperations["memmap"]["params"]): Promise<ViceOperations["memmap"]["result"]> {
     return this.#request("memmap", params);
@@ -209,6 +216,19 @@ export class ViceSessionClient {
     return this.#request("snapshot", params);
   }
 
+  /** The bytes of a named snapshot, as a .vsf file holds them (D41). */
+  async snapshotExport(name: string): Promise<Buffer> {
+    const { attachments } = await this.#requestWithAttachments("snapshotFile", { action: "export", name });
+    const [bytes] = attachments;
+    if (bytes === undefined || attachments.length !== 1) throw new WireFailure("operation-failed", "The c64-re-tools host runtime sent no snapshot file.");
+    return bytes;
+  }
+
+  /** Restores the machine from the bytes of a .vsf file; the CPU stays stopped. */
+  snapshotRestore(bytes: Uint8Array): Promise<ViceOperations["snapshotFile"]["result"]> {
+    return this.#request("snapshotFile", { action: "restore" }, [bytes]);
+  }
+
   screenBaselines(): Promise<{ baselines: string[] }> {
     return this.#request("screenBaselines", {});
   }
@@ -233,16 +253,25 @@ export class ViceSessionClient {
     await this.closed;
   }
 
-  #request<O extends ViceOperation>(
+  async #request<O extends ViceOperation>(
     op: O,
     params: ViceOperations[O]["params"],
     attachments: readonly Uint8Array[] = [],
   ): Promise<ViceOperations[O]["result"]> {
+    return (await this.#requestWithAttachments(op, params, attachments)).result;
+  }
+
+  /** One request; the reply's result and the attachments that came with it. */
+  #requestWithAttachments<O extends ViceOperation>(
+    op: O,
+    params: ViceOperations[O]["params"],
+    attachments: readonly Uint8Array[] = [],
+  ): Promise<{ result: ViceOperations[O]["result"]; attachments: Buffer[] }> {
     if (this.#lost !== undefined) return Promise.reject(this.#lost);
     const id = this.#nextId;
     this.#nextId = this.#nextId >= 0xffff_ffff ? 1 : this.#nextId + 1;
     return new Promise((resolve, reject) => {
-      this.#pending.set(id, { op, resolve: resolve as (value: unknown) => void, reject });
+      this.#pending.set(id, { op, resolve: (result, received) => resolve({ result: result as ViceOperations[O]["result"], attachments: received }), reject });
       this.#connection.send({ type: "request", id, op, params }, attachments);
     });
   }

package/src/knowledge/history.ts

@@ -6,19 +6,26 @@ import type { DatabaseSync } from "node:sqlite";
 import { KnowledgeError } from "./database.ts";
 import {
   COMMENT_COLUMNS,
+  MODULE_COLUMNS,
   REFERENCE_COLUMNS,
   REGION_COLUMNS,
+  SUPPRESSION_COLUMNS,
   SYMBOL_COLUMNS,
   toComment,
+  toModule,
   toReference,
   toRegion,
+  toSuppression,
   toSymbol,
   type CommentRow,
+  type ModuleRow,
   type ReferenceRow,
   type RegionRow,
+  type SuppressionRow,
   type SymbolRow,
 } from "./read.ts";
-import type { Origin } from "./schema.ts";
+import { DEFAULT_SPACE, type EvidenceKind, type Origin, type Space } from "./schema.ts";
+import type { Evidence } from "./write.ts";
 
 export interface Revision {
   id: number;
@@ -28,6 +35,8 @@ export interface Revision {
   description?: string;
   inputHash?: string;
   toolVersion?: string;
+  /** What the change rests on (D42). */
+  evidence?: Evidence[];
 }
 
 /** One knowledge row with its validity: from its first revision until the revision that closed it. */
@@ -35,7 +44,9 @@ export type HistoryEntry =
   | { entity: "symbol"; row: SymbolRow; from: number; to?: number }
   | { entity: "region"; row: RegionRow; from: number; to?: number }
   | { entity: "comment"; row: CommentRow; from: number; to?: number }
-  | { entity: "reference"; row: ReferenceRow; from: number; to?: number };
+  | { entity: "reference"; row: ReferenceRow; from: number; to?: number }
+  | { entity: "suppression"; row: SuppressionRow; from: number; to?: number }
+  | { entity: "module"; row: ModuleRow; from: number; to?: number };
 
 type Raw = Record<string, unknown>;
 
@@ -62,30 +73,44 @@ function bySequence(a: HistoryEntry, b: HistoryEntry): number {
   return a.from - b.from || (a.to ?? Infinity) - (b.to ?? Infinity);
 }
 
-/** Every row, current or closed, that concerns one address, oldest first. */
-export function historyAt(db: DatabaseSync | undefined, address: number): HistoryEntry[] {
+/** Every row, current or closed, that concerns one address of a space, oldest first. */
+export function historyAt(db: DatabaseSync | undefined, address: number, space: Space = DEFAULT_SPACE): HistoryEntry[] {
   if (db === undefined) return [];
   const validity = ", valid_to_revision";
   const entries: HistoryEntry[] = [];
-  for (const raw of db.prepare(`SELECT ${SYMBOL_COLUMNS}${validity} FROM symbols WHERE address = ?`).all(address) as Raw[]) entries.push(entry("symbol", toSymbol(raw), raw));
-  for (const raw of db.prepare(`SELECT ${REGION_COLUMNS}${validity} FROM regions WHERE start_address <= ? AND end_address >= ?`).all(address, address) as Raw[]) {
+  for (const raw of db.prepare(`SELECT ${SYMBOL_COLUMNS}${validity} FROM symbols WHERE space = ? AND address = ?`).all(space, address) as Raw[]) entries.push(entry("symbol", toSymbol(raw), raw));
+  for (const raw of db.prepare(`SELECT ${REGION_COLUMNS}${validity} FROM regions WHERE space = ? AND start_address <= ? AND end_address >= ?`).all(space, address, address) as Raw[]) {
     entries.push(entry("region", toRegion(raw), raw));
   }
-  for (const raw of db.prepare(`SELECT ${COMMENT_COLUMNS}${validity} FROM comments WHERE address = ?`).all(address) as Raw[]) entries.push(entry("comment", toComment(raw), raw));
-  for (const raw of db.prepare(`SELECT ${REFERENCE_COLUMNS}${validity} FROM "references" WHERE from_address = ? OR to_address = ?`).all(address, address) as Raw[]) {
+  for (const raw of db.prepare(`SELECT ${COMMENT_COLUMNS}${validity} FROM comments WHERE space = ? AND address = ?`).all(space, address) as Raw[]) entries.push(entry("comment", toComment(raw), raw));
+  for (const raw of db.prepare(`SELECT ${REFERENCE_COLUMNS}${validity} FROM "references" WHERE space = ? AND (from_address = ? OR to_address = ?)`).all(space, address, address) as Raw[]) {
     entries.push(entry("reference", toReference(raw), raw));
   }
+  for (const raw of db
+    .prepare(`SELECT ${SUPPRESSION_COLUMNS}${validity} FROM suppressions WHERE space = ? AND ((start_address <= ? AND end_address >= ?) OR to_address = ?)`)
+    .all(space, address, address, address) as Raw[]) {
+    entries.push(entry("suppression", toSuppression(raw), raw));
+  }
+  for (const raw of db.prepare(`SELECT ${MODULE_COLUMNS}${validity} FROM modules WHERE space = ? AND start_address = ?`).all(space, address) as Raw[]) entries.push(entry("module", toModule(raw), raw));
   return entries.sort(bySequence);
 }
 
-/** Every symbol row that ever had this name, oldest first: a name can move between addresses. */
-export function historyNamed(db: DatabaseSync | undefined, name: string): HistoryEntry[] {
+/** Every symbol row of a space that ever had this name, oldest first: a name can move between addresses. */
+export function historyNamed(db: DatabaseSync | undefined, name: string, space: Space = DEFAULT_SPACE): HistoryEntry[] {
   if (db === undefined) return [];
-  return (db.prepare(`SELECT ${SYMBOL_COLUMNS}, valid_to_revision FROM symbols WHERE name = ?`).all(name) as Raw[])
+  return (db.prepare(`SELECT ${SYMBOL_COLUMNS}, valid_to_revision FROM symbols WHERE space = ? AND name = ?`).all(space, name) as Raw[])
     .map((raw) => entry("symbol", toSymbol(raw), raw))
     .sort(bySequence);
 }
 
+/** The revision with its evidence, when it has any. */
+function withEvidence(db: DatabaseSync, revision: Revision): Revision {
+  const rows = db.prepare("SELECT kind, ref, sha256 FROM evidence WHERE revision = ? ORDER BY id").all(revision.id) as Raw[];
+  if (rows.length === 0) return revision;
+  const evidence = rows.map((row): Evidence => ({ kind: row.kind as EvidenceKind, ref: row.ref as string, ...(row.sha256 === null ? {} : { sha256: row.sha256 as string }) }));
+  return { ...revision, evidence };
+}
+
 /** Revisions, newest first; with `before`, only revisions older than it. */
 export function revisions(db: DatabaseSync | undefined, options: { limit?: number; before?: number } = {}): Revision[] {
   if (db === undefined) return [];
@@ -93,7 +118,7 @@ export function revisions(db: DatabaseSync | undefined, options: { limit?: numbe
     db
       .prepare("SELECT * FROM revisions WHERE id < ? ORDER BY id DESC LIMIT ?")
       .all(options.before ?? Number.MAX_SAFE_INTEGER, options.limit ?? 50) as Raw[]
-  ).map(toRevision);
+  ).map((row) => withEvidence(db, toRevision(row)));
 }
 
 export interface RevisionChanges {
@@ -113,6 +138,8 @@ export function revision(db: DatabaseSync | undefined, id: number): RevisionChan
     ["region", "regions", REGION_COLUMNS, toRegion],
     ["comment", "comments", COMMENT_COLUMNS, toComment],
     ["reference", '"references"', REFERENCE_COLUMNS, toReference],
+    ["suppression", "suppressions", SUPPRESSION_COLUMNS, toSuppression],
+    ["module", "modules", MODULE_COLUMNS, toModule],
   ] as const;
   const added: HistoryEntry[] = [];
   const closed: HistoryEntry[] = [];
@@ -124,5 +151,5 @@ export function revision(db: DatabaseSync | undefined, id: number): RevisionChan
       closed.push(entry(entity, map(row), row));
     }
   }
-  return { revision: toRevision(raw), added, closed };
+  return { revision: withEvidence(db, toRevision(raw)), added, closed };
 }