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

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

@@ -0,0 +1,316 @@
+// The long-lived Host Runtime connection an MCP process owns: one connection,
+// one VICE. Exposes C64-domain operations only.
+
+import { ProtocolError, WireFailure, type VideoStandard } from "../protocol/messages.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";
+
+const HOST_LOST =
+  "The connection to the c64-re-tools host runtime was lost. The emulator and its machine state are gone: memory, registers, breakpoints, snapshots and the loaded program. " +
+  "The next call starts a new machine when the Host Runtime (c64-re-tools-host) runs. Load the program again and set the breakpoints again.";
+const SESSION_CLOSED = "The C64 session is closed because the c64-re-tools MCP server stops.";
+const LOST_BEFORE_ANSWER = "The connection to the c64-re-tools host runtime was lost before the emulator answered. No machine state was lost. Do the call again.";
+
+/**
+ * The loss of a session that never answered (D57): it had no machine state,
+ * so the caller can do the call again on a new session.
+ */
+export class LostBeforeAnswer extends WireFailure {
+  constructor() {
+    super("machine-unavailable", LOST_BEFORE_ANSWER);
+  }
+}
+
+interface Pending {
+  op: ViceOperation;
+  resolve: (value: unknown, attachments: Buffer[]) => void;
+  reject: (error: Error) => void;
+}
+
+export class ViceSessionClient {
+  /** Settles when the session is gone, whether we closed it or the host went away. */
+  readonly closed: Promise<void>;
+  readonly #connection: HostConnection;
+  readonly #pending = new Map<number, Pending>();
+  #nextId = 1;
+  #lost: WireFailure | undefined;
+  #answered = false;
+  #lossReported = false;
+
+  private constructor(connection: HostConnection) {
+    this.#connection = connection;
+    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);
+      if (pending === undefined) return; // not ours; ignore
+      this.#pending.delete(message.id);
+      this.#answered = true;
+      if ("error" in message) {
+        pending.reject(new WireFailure(message.error.code, message.error.message));
+        return;
+      }
+      try {
+        pending.resolve(validateViceResult(pending.op, message.result), attachments);
+      } catch (error) {
+        pending.reject(
+          new WireFailure(
+            "operation-failed",
+            error instanceof ProtocolError ? "The c64-re-tools host runtime sent an invalid reply." : "The c64-re-tools MCP server could not read the reply of the host runtime.",
+          ),
+        );
+        this.#fail();
+      }
+    });
+    this.closed = connection.closed.then(() => {
+      this.#lost ??= this.#answered ? new WireFailure("machine-state-lost", HOST_LOST) : new LostBeforeAnswer();
+      this.#lossReported = this.#pending.size > 0;
+      for (const pending of this.#pending.values()) pending.reject(this.#lost);
+      this.#pending.clear();
+    });
+  }
+
+  /** Connects and waits until the host has started this session's emulator; `signal` stops the wait at once. */
+  static async open(options: { videoStandard: VideoStandard; env?: NodeJS.ProcessEnv; signal?: AbortSignal }): Promise<ViceSessionClient> {
+    const connection = await HostConnection.open({
+      role: "vice-session",
+      videoStandard: options.videoStandard,
+      ...(options.env === undefined ? {} : { env: options.env }),
+      ...(options.signal === undefined ? {} : { signal: options.signal }),
+    });
+    return new ViceSessionClient(connection);
+  }
+
+  status(): Promise<MachineStatus> {
+    return this.#request("status", {});
+  }
+
+  memoryRead(params: MemoryReadParams): Promise<MemoryReadResult> {
+    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 });
+  }
+
+  memoryWrite(params: MemoryWriteParams): Promise<{ address: number; bytesWritten: number }> {
+    return this.#request("memoryWrite", params);
+  }
+
+  memorySearch(params: ViceOperations["memorySearch"]["params"]): Promise<{ matches: number[] }> {
+    return this.#request("memorySearch", params);
+  }
+
+  memoryCompare(params: ViceOperations["memoryCompare"]["params"]): Promise<ViceOperations["memoryCompare"]["result"]> {
+    return this.#request("memoryCompare", params);
+  }
+
+  disassemble(params: ViceOperations["disassemble"]["params"]): Promise<ViceOperations["disassemble"]["result"]> {
+    return this.#request("disassemble", params);
+  }
+
+  registersSet(space: Space, values: RegisterValues): Promise<Registers> {
+    return this.#request("registersSet", { space, values });
+  }
+
+  execution(params: ExecutionParams): Promise<ExecutionResult> {
+    return this.#request("execution", params);
+  }
+
+  runUntil(params: { target: RunTarget; timeoutFrames: number }): Promise<RunUntilResult> {
+    return this.#request("runUntil", params);
+  }
+
+  /** Loads a project PRG into memory without reset or start; finishes stopped. */
+  async programLoad(params: { path: string; address?: number }): Promise<{ state: RunState; loadAddress: number; size: number }> {
+    const file = readProjectFile(params.path);
+    return this.#request("programLoad", params.address === undefined ? {} : { address: params.address }, [file.bytes]);
+  }
+
+  /** Autostarts a project program or image, as VICE's autostart does. */
+  async autostart(params: { path: string; index: number; run: boolean }): Promise<{ state: RunState; emulatorFlaw?: string }> {
+    const file = readProjectFile(params.path);
+    return this.#request("autostart", { type: file.type, index: params.index, run: params.run }, [file.bytes]);
+  }
+
+  /** Attaches a project disk image to drive 8. */
+  async diskAttach(params: { path: string }): Promise<{ attached: boolean }> {
+    const file = readProjectFile(params.path);
+    return this.#request("diskAttach", { type: file.type }, [file.bytes]);
+  }
+
+  reset(params: { mode: ResetMode; run: boolean }): Promise<{ state: RunState; pc?: number }> {
+    return this.#request("reset", params);
+  }
+
+  /** Queues PETSCII bytes for the C64 keyboard. */
+  keyboard(petscii: Uint8Array): Promise<{ queuedBytes: number }> {
+    return this.#request("keyboard", { data: Buffer.from(petscii).toString("hex") });
+  }
+
+  joystick(state: JoystickState): Promise<JoystickState> {
+    return this.#request("joystick", state);
+  }
+
+  /** 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: 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, remove gives `{removed, id}`; add, enable and disable give the one watchpoint. */
+  watchpoint(params: Extract<WatchpointParams, { action: "list" }>): Promise<{ 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);
+  }
+
+  cpuHistory(params: ViceOperations["cpuHistory"]["params"]): Promise<ViceOperations["cpuHistory"]["result"]> {
+    return this.#request("cpuHistory", params);
+  }
+
+  backtrace(params: ViceOperations["backtrace"]["params"]): Promise<ViceOperations["backtrace"]["result"]> {
+    return this.#request("backtrace", params);
+  }
+
+  timing(action: ViceOperations["timing"]["params"]["action"]): Promise<ViceOperations["timing"]["result"]> {
+    return this.#request("timing", { action });
+  }
+
+  profile(limit: number): Promise<ViceOperations["profile"]["result"]> {
+    return this.#request("profile", { limit });
+  }
+
+  /** Action read gives the ranges; action clear gives cleared. */
+  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);
+  }
+
+  vicii(): Promise<ViceOperations["vicii"]["result"]> {
+    return this.#request("vicii", {});
+  }
+
+  /** Empty `indexes` means all eight sprites. */
+  sprites(indexes: number[]): Promise<ViceOperations["sprites"]["result"]> {
+    return this.#request("sprites", { indexes });
+  }
+
+  cia(which: ViceOperations["cia"]["params"]["which"]): Promise<ViceOperations["cia"]["result"]> {
+    return this.#request("cia", { which });
+  }
+
+  sid(): Promise<ViceOperations["sid"]["result"]> {
+    return this.#request("sid", {});
+  }
+
+  observe(params: ViceOperations["observe"]["params"]): Promise<ViceOperations["observe"]["result"]> {
+    return this.#request("observe", params);
+  }
+
+  /** The last frame the VIC-II drew, as a base64 PNG with its size. */
+  screenCapture(baseline?: string): Promise<ViceOperations["screenCapture"]["result"]> {
+    return this.#request("screenCapture", baseline === undefined ? {} : { baseline });
+  }
+
+  screenCompare(params: ViceOperations["screenCompare"]["params"]): Promise<ViceOperations["screenCompare"]["result"]> {
+    return this.#request("screenCompare", params);
+  }
+
+  snapshot(params: ViceOperations["snapshot"]["params"]): Promise<ViceOperations["snapshot"]["result"]> {
+    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", {});
+  }
+
+  screenDiscard(baseline: string): Promise<{ discarded: boolean }> {
+    return this.#request("screenDiscard", { baseline });
+  }
+
+  warp(enabled: boolean): Promise<{ enabled: boolean }> {
+    return this.#request("warp", { enabled });
+  }
+
+  /** Moves the machine into a VICE with a window (open) or back into a headless one (close). */
+  window(action: ViceOperations["window"]["params"]["action"]): Promise<ViceOperations["window"]["result"]> {
+    return this.#request("window", { action });
+  }
+
+  /** True when the connection to the host is gone, whatever the reason. */
+  get lost(): boolean {
+    return this.#lost !== undefined;
+  }
+
+  /** True when the emulator answered a request: then the session had machine state to lose (D57). */
+  get answered(): boolean {
+    return this.#answered;
+  }
+
+  /** The loss of a lost session, when no request got it; undefined while the session lives (D57). */
+  get unreportedLoss(): WireFailure | undefined {
+    return this.#lost?.code === "machine-state-lost" && !this.#lossReported ? this.#lost : undefined;
+  }
+
+  /** Ends the session; the host stops its emulator. Open and later requests fail as closed. */
+  async close(): Promise<void> {
+    this.#lost ??= new WireFailure("machine-unavailable", SESSION_CLOSED);
+    await this.#connection.close();
+    await this.closed;
+  }
+
+  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) {
+      this.#lossReported = true;
+      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: (result, received) => resolve({ result: result as ViceOperations[O]["result"], attachments: received }), reject });
+      this.#connection.send({ type: "request", id, op, params }, attachments);
+    });
+  }
+
+  /** Drops a connection whose host broke the protocol; pending work fails as lost. */
+  #fail(): void {
+    void this.#connection.close();
+  }
+}

package/src/knowledge/database.ts

@@ -0,0 +1,132 @@
+// The one place that opens .c64-re-tools/knowledge.db.
+
+import { existsSync, mkdirSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { join } from "node:path";
+
+import { projectRoot } from "../project.ts";
+import { checkVersion, ensureSchema, schemaVersion } from "./schema.ts";
+
+export const KNOWLEDGE_DIRECTORY = ".c64-re-tools";
+export const KNOWLEDGE_FILE = "knowledge.db";
+
+export const KNOWLEDGE_ERROR_CODES = [
+  "invalid-input",
+  "not-found",
+  "conflict",
+  "stale-revision",
+  "invalid-database",
+  "unsupported-schema",
+] as const;
+export type KnowledgeErrorCode = (typeof KNOWLEDGE_ERROR_CODES)[number];
+
+/** A refused knowledge operation, with a stable code and an actionable message. */
+export class KnowledgeError extends Error {
+  override name = "KnowledgeError";
+  readonly code: KnowledgeErrorCode;
+
+  constructor(code: KnowledgeErrorCode, message: string) {
+    super(message);
+    this.code = code;
+  }
+}
+
+export function knowledgePath(root: string = projectRoot()): string {
+  return join(root, KNOWLEDGE_DIRECTORY, KNOWLEDGE_FILE);
+}
+
+function configure(db: DatabaseSync): void {
+  // A committed write must be complete in knowledge.db itself: rollback journal, never WAL.
+  db.exec("PRAGMA journal_mode = DELETE; PRAGMA foreign_keys = ON; PRAGMA busy_timeout = 5000;");
+}
+
+function open(path: string, readOnly: boolean): DatabaseSync {
+  let db: DatabaseSync;
+  try {
+    db = new DatabaseSync(path, { readOnly });
+    configure(db);
+    db.prepare("SELECT count(*) FROM sqlite_master").get();
+  } catch (error) {
+    throw new KnowledgeError("invalid-database", `${KNOWLEDGE_DIRECTORY}/${KNOWLEDGE_FILE} is not a readable SQLite database: ${(error as Error).message}`);
+  }
+  return db;
+}
+
+/**
+ * Opens the project's knowledge database read-only, as it is: a read never
+ * migrates and never writes. Returns undefined when the database does not
+ * exist or has no schema yet: that reads as empty knowledge, and a read
+ * creates nothing. Refuses a schema version other than this build's.
+ */
+export function openForRead(root: string = projectRoot()): DatabaseSync | undefined {
+  const path = knowledgePath(root);
+  if (!existsSync(path)) return undefined;
+  const db = open(path, true);
+  try {
+    const version = schemaVersion(db);
+    if (version === 0) {
+      db.close();
+      return undefined;
+    }
+    checkVersion(version);
+  } catch (error) {
+    db.close();
+    throw error;
+  }
+  return db;
+}
+
+/**
+ * Opens the project's knowledge database for a write, creating
+ * .c64-re-tools/knowledge.db and its schema when needed. Refuses a schema
+ * version other than this build's.
+ */
+export function openForWrite(root: string = projectRoot()): DatabaseSync {
+  mkdirSync(join(root, KNOWLEDGE_DIRECTORY), { recursive: true });
+  const db = open(knowledgePath(root), false);
+  try {
+    ensureSchema(db);
+  } catch (error) {
+    db.close();
+    throw error;
+  }
+  return db;
+}
+
+/**
+ * Runs one write on the project's knowledge database and closes it. When the
+ * project has no knowledge.db yet, `work` first runs on an empty database in
+ * memory: a write that is refused there creates no .c64-re-tools/. `work`
+ * must change nothing outside the database it gets.
+ */
+export function withWrite<T>(work: (db: DatabaseSync) => T, root: string = projectRoot()): T {
+  if (!existsSync(knowledgePath(root))) {
+    const trial = new DatabaseSync(":memory:");
+    try {
+      configure(trial);
+      ensureSchema(trial);
+      work(trial);
+    } finally {
+      trial.close();
+    }
+  }
+  const db = openForWrite(root);
+  try {
+    return work(db);
+  } finally {
+    db.close();
+  }
+}
+
+/** Runs `work` in one immediate transaction: all of it commits, or none of it does. */
+export function transaction<T>(db: DatabaseSync, work: () => T): T {
+  db.exec("BEGIN IMMEDIATE");
+  try {
+    const result = work();
+    db.exec("COMMIT");
+    return result;
+  } catch (error) {
+    db.exec("ROLLBACK");
+    throw error;
+  }
+}

package/src/knowledge/history.ts

@@ -0,0 +1,163 @@
+// Knowledge history: what used to be known, which revision changed
+// it, who changed it and why. History rows are never deleted.
+
+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 { DEFAULT_SPACE, type EvidenceKind, type Origin, type Space } from "./schema.ts";
+import type { Evidence } from "./write.ts";
+
+export interface Revision {
+  id: number;
+  createdAt: string;
+  origin: Origin;
+  operation: string;
+  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. */
+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: "suppression"; row: SuppressionRow; from: number; to?: number }
+  | { entity: "module"; row: ModuleRow; from: number; to?: number };
+
+type Raw = Record<string, unknown>;
+
+function toRevision(row: Raw): Revision {
+  const revision: Revision = {
+    id: row.id as number,
+    createdAt: row.created_at as string,
+    origin: row.origin as Origin,
+    operation: row.operation as string,
+  };
+  if (row.description !== null) revision.description = row.description as string;
+  if (row.input_hash !== null) revision.inputHash = row.input_hash as string;
+  if (row.tool_version !== null) revision.toolVersion = row.tool_version as string;
+  return revision;
+}
+
+function entry<E extends HistoryEntry["entity"]>(entity: E, row: unknown, raw: Raw): HistoryEntry {
+  const result = { entity, row, from: raw.valid_from_revision as number } as HistoryEntry;
+  if (raw.valid_to_revision !== null) result.to = raw.valid_to_revision as number;
+  return result;
+}
+
+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 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 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 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 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 space = ? AND name = ?`).all(space, name) as Raw[])
+    .map((raw) => entry("symbol", toSymbol(raw), raw))
+    .sort(bySequence);
+}
+
+/** Why a revision was written and what it rests on: its description and its evidence, when it has them. */
+export function revisionNote(db: DatabaseSync | undefined, id: number): { reason?: string; evidence?: Evidence[] } {
+  const raw = db?.prepare("SELECT * FROM revisions WHERE id = ?").get(id) as Raw | undefined;
+  if (db === undefined || raw === undefined) return {};
+  const { description, evidence } = withEvidence(db, toRevision(raw));
+  return { ...(description === undefined ? {} : { reason: description }), ...(evidence === undefined ? {} : { evidence }) };
+}
+
+/** 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 [];
+  return (
+    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((row) => withEvidence(db, toRevision(row)));
+}
+
+export interface RevisionChanges {
+  revision: Revision;
+  /** Rows this revision made current. */
+  added: HistoryEntry[];
+  /** Rows this revision closed. */
+  closed: HistoryEntry[];
+}
+
+/** One revision and exactly what it changed. */
+export function revision(db: DatabaseSync | undefined, id: number): RevisionChanges {
+  const raw = db?.prepare("SELECT * FROM revisions WHERE id = ?").get(id) as Raw | undefined;
+  if (db === undefined || raw === undefined) throw new KnowledgeError("not-found", `There is no revision ${id}.`);
+  const tables = [
+    ["symbol", "symbols", SYMBOL_COLUMNS, toSymbol],
+    ["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[] = [];
+  for (const [entity, table, columns, map] of tables) {
+    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));
+    }
+    for (const row of db.prepare(`SELECT ${columns}, valid_to_revision FROM ${table} WHERE valid_to_revision = ?`).all(id) as Raw[]) {
+      closed.push(entry(entity, map(row), row));
+    }
+  }
+  return { revision: withEvidence(db, toRevision(raw)), added, closed };
+}