@henols/c64-re-tools 2.0.0-rc.9 → 2.0.0

package/src/host-client/coverage.ts

@@ -1,40 +1,13 @@
-// Reads the emulator's memory access map as coverage bytes (D40): one byte
+// Reads the emulator's memory access map as coverage bytes: one byte
 // per address, RAM, ROM and I/O apart. The MCP tool and the skill scripts share it.
 
 import { COVERAGE, type CodeRange } from "../c64.ts";
 import { MAX_MEMMAP_RANGES, type MemmapRange } from "../protocol/vice.ts";
-import { readProjectFile } from "./transfer.ts";
 import type { ViceSessionClient } from "./vice-session.ts";
 
-/** A full coverage file: offset n is address n (D40). */
+/** A full coverage file: offset n is address n. */
 export const FULL_COVERAGE = 0x10000;
 
-/** Reads full coverage files from the project, one map per file. `fail` refuses a file of another size. */
-export function readCoverageMaps(paths: string[], fail: (message: string) => never): Uint8Array[] {
-  return paths.map((path) => {
-    const { bytes } = readProjectFile(path);
-    if (bytes.length !== FULL_COVERAGE) {
-      fail(`--coverage ${path} has ${bytes.length} bytes; a full coverage file has 65536, one for each address. Write it with c64_memmap action read and out, without start and end.`);
-    }
-    return bytes;
-  });
-}
-
-/** Joins coverage maps: an address has every flag that any run gave it. */
-export function joinCoverage(maps: readonly Uint8Array[]): Uint8Array {
-  const joined = new Uint8Array(FULL_COVERAGE);
-  for (const map of maps) for (let address = 0; address < FULL_COVERAGE; address++) joined[address]! |= map[address]!;
-  return joined;
-}
-
-/**
- * Reads full coverage files from the project and joins them: an address has
- * every flag that any run gave it. `fail` refuses a file of another size.
- */
-export function readCoverageFiles(paths: string[], fail: (message: string) => never): Uint8Array | undefined {
-  return paths.length === 0 ? undefined : joinCoverage(readCoverageMaps(paths, fail));
-}
-
 /** The coverage bytes of start..end, read from the session in parts. */
 export async function readCoverage(session: Pick<ViceSessionClient, "memmap">, start = 0x0000, end = 0xffff): Promise<Uint8Array> {
   const map = new Uint8Array(end - start + 1);

package/src/host-client/image.ts

@@ -0,0 +1,66 @@
+// An image.json of the c64-unpacker skill (a 64 KiB memory and its segments)
+// or a PRG, read from the project to put it into the knowledge.
+
+import { posix } from "node:path";
+
+import { formatC64Address, prgRange } from "../c64.ts";
+import { readProjectFile } from "./transfer.ts";
+
+/** A file that is no image: the scripts report it as a bad call. */
+export class ImageError extends Error {
+  override name = "ImageError";
+}
+
+export interface Image {
+  segments: Array<{ start: number; end: number }>;
+  /** The byte at an address inside a segment. */
+  byteAt: (address: number) => number;
+  entry?: number;
+  /** entry_state.json next to image.json. */
+  statePath?: string;
+  /** The stages of the capture in image.json, as the unpacker wrote them. */
+  stages?: Array<Record<string, unknown>>;
+}
+
+/** Reads an image.json or a PRG, relative to the project folder. */
+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 ImageError(`${path}: ${(error as Error).message}`);
+    }
+    return { segments: [{ start: range.start, end: range.end }], byteAt: (address) => range.body[address - range.start]! };
+  }
+  const fail = (what: string): never => {
+    throw new ImageError(`${path} is not an image.json of the c64-unpacker skill: ${what}`);
+  };
+  const isObject = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(bytes.toString("utf8"));
+  } catch (error) {
+    return fail((error as Error).message);
+  }
+  const manifest = isObject(parsed) ? parsed : fail("it is not a JSON object");
+  const address = (value: unknown, what: string) => (typeof value === "string" && /^\$[0-9a-f]{4}$/i.test(value) ? Number.parseInt(value.slice(1), 16) : fail(`${what} is not a $ address`));
+  if (typeof manifest.image !== "string") fail("it has no image");
+  if (!Array.isArray(manifest.segments) || manifest.segments.length === 0) fail("it has no segments");
+  const segments = (manifest.segments as unknown[])
+    .map((segment, index) => (isObject(segment) ? segment : fail(`segment ${index + 1} is not an object`)))
+    .map((segment, index) => ({ start: address(segment.start, `segment ${index + 1} start`), end: address(segment.end, `segment ${index + 1} end`) }))
+    .sort((a, b) => a.start - b.start);
+  segments.forEach((segment, index) => {
+    if (segment.end < segment.start) fail(`the segment at ${formatC64Address(segment.start)} ends before it starts`);
+    if (index > 0 && segment.start <= segments[index - 1]!.end) fail(`the segments at ${formatC64Address(segments[index - 1]!.start)} and ${formatC64Address(segment.start)} overlap`);
+  });
+  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 image: Image = { segments, byteAt: (at) => memory[at]!, statePath: posix.join(directory, "entry_state.json") };
+  if (manifest.entry !== undefined) image.entry = address(manifest.entry, "entry");
+  if (Array.isArray(manifest.stages)) image.stages = manifest.stages.map((stage, index) => (isObject(stage) ? stage : fail(`stage ${index + 1} is not an object`)));
+  return image;
+}

package/src/host-client/steps.ts

@@ -1,4 +1,4 @@
-// The action steps of the step language (D43): write, registers, joystick,
+// The action steps of the step language: 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.
 
@@ -90,12 +90,12 @@ export function checkActionStep(kind: string, step: Record<string, unknown>, at:
       return;
     }
     case "frames":
-      if (!isInteger(step.frames, 1, MAX_EXECUTION_COUNT)) fail(`${at} needs a frame count from 1 to ${MAX_EXECUTION_COUNT}`);
+      if (!isInteger(step.frames, 1, MAX_TIMEOUT_FRAMES)) fail(`${at} needs a frame count from 1 to ${MAX_TIMEOUT_FRAMES}`);
       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.
+      // at, raster, at with raster (the address only on that line), 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}`);
@@ -154,7 +154,12 @@ export async function runActionStep(client: ViceSessionClient, step: ActionStep,
     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" });
+    // One advance-frames runs at most MAX_EXECUTION_COUNT frames. Each part ends at the raster position
+    // where it started, so the parts give the same frames as one run; a breakpoint ends them all.
+    for (let left = step.frames; left > 0; left -= MAX_EXECUTION_COUNT) {
+      const part = await client.execution({ action: "advance-frames", count: Math.min(left, MAX_EXECUTION_COUNT), space: "c64" });
+      if (part.stopReason !== "frames") break;
+    }
   } else {
     const until = step.runUntil;
     const target: RunTarget =

package/src/host-client/tools.ts

@@ -87,3 +87,4 @@ export async function hostTools(options: ToolCallOptions = {}): Promise<{ host:
 export { WireFailure } from "../protocol/messages.ts";
 export { DISK_ACTIONS } from "../protocol/tools.ts";
 export { JOYSTICK_DIRECTIONS, MAX_BASELINES, MAX_EXECUTION_COUNT, MAX_KEYBOARD_BYTES, MAX_MASK_RECTANGLES, MAX_MEMORY_READ, MAX_MEMORY_WRITE, MAX_TIMEOUT_FRAMES, maskCoversFrame } from "../protocol/vice.ts";
+export { MAX_TRACE_FRAMES, MAX_TRACE_HITS, MAX_TRACE_POINTS, TRACE_KINDS, type TraceHit, type TraceKind } from "../protocol/vice.ts";

package/src/host-client/transfer.ts

@@ -1,14 +1,38 @@
 // 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 { lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import { dirname, extname, join, relative, sep } from "node:path";
 
-import { isInside, projectRoot, resolveProjectFile, resolveProjectPath } from "../project.ts";
+import { isInside, ProjectError, projectRoot, resolveProject, 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";
 
+/** Runs a project lookup and gives a refusal of the project rules as a WireFailure with the same code and message. */
+function asWireFailure<T>(lookup: () => T): T {
+  try {
+    return lookup();
+  } catch (error) {
+    if (error instanceof ProjectError) throw new WireFailure(error.code, error.message);
+    throw error;
+  }
+}
+
+/**
+ * The project folder of a call that names it with `project` (relative to the
+ * working directory) or not. Throws WireFailure when the rules
+ * refuse it, for example at a folder with several projects below it.
+ */
+export function projectFolder(project: string | undefined): string {
+  return asWireFailure(() => resolveProject(project, process.cwd(), { remedy: "Give project: <folder>" }));
+}
+
+/** The project folder of this process (--project or the project lookup), or a WireFailure. */
+function currentProject(): string {
+  return asWireFailure(projectRoot);
+}
+
 export interface ProjectFile {
   bytes: Buffer;
   /** Lowercase extension without the dot; empty when the file has none. */
@@ -21,16 +45,16 @@ export interface ProjectFile {
  * the file is too large to transfer.
  */
 export function readProjectFile(path: string, options: { root?: string } = {}): ProjectFile {
-  const root = options.root ?? projectRoot();
+  const root = options.root ?? currentProject();
   let real: string;
   try {
     real = resolveProjectFile(path, root);
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-      throw new WireFailure("not-found", `There is no file at ${path} in the project directory.`);
+      throw new WireFailure("not-found", `There is no file at ${path} in the project folder.`);
     }
     if (error instanceof TypeError) {
-      throw new WireFailure("invalid-input", `${path}: give a path relative to the project directory that stays inside it.`);
+      throw new WireFailure("invalid-input", `${path}: give a path relative to the project folder that stays inside it.`);
     }
     throw error;
   }
@@ -48,14 +72,18 @@ export function readProjectFile(path: string, options: { root?: string } = {}):
  * 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}.`);
+  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();
   }
+  // 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();
   mkdirSync(dirname(file), { recursive: true });
   if (!isInside(realpathSync(root), realpathSync(dirname(file)))) throw refuse();
   let link = false;
@@ -72,18 +100,18 @@ export function writeProjectFile(path: string, bytes: Uint8Array, options: { roo
 const SKIPPED_DIRECTORIES = new Set([".git", ".hg", ".svn", ".c64-re-tools"]);
 
 /**
- * Reads a project directory as a source tree for staging: ordinary
+ * Reads a project folder as a source tree for staging: ordinary
  * files with relative POSIX paths. A symbolic link is followed only when its
  * target stays inside the source root; otherwise the tree is refused.
  */
 export function readProjectTree(path: string, options: { root?: string } = {}): { files: SourceTree; contents: Buffer[] } {
-  const projectRootPath = options.root ?? projectRoot();
+  const projectRootPath = options.root ?? currentProject();
   let sourceRoot: string;
   try {
     sourceRoot = resolveProjectFile(path, projectRootPath);
   } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") throw new WireFailure("not-found", `There is no directory ${path} in the project directory.`);
-    if (error instanceof TypeError) throw new WireFailure("invalid-input", `${path}: give a directory relative to the project directory that stays inside it.`);
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") throw new WireFailure("not-found", `There is no directory ${path} in the project folder.`);
+    if (error instanceof TypeError) throw new WireFailure("invalid-input", `${path}: give a directory relative to the project folder that stays inside it.`);
     throw error;
   }
   if (!statSync(sourceRoot).isDirectory()) throw new WireFailure("invalid-input", `${path} is not a directory.`);

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 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 { MAX_MEMORY_READ, validateViceResult, type Breakpoint, type BreakpointParams, type PointRemoved, type Watchpoint, type WatchpointParams, type ExecutionParams, type ExecutionResult, type JoystickState, type MachineStatus, type MemmapRange, type MemoryWriteParams, type ProfileEntry, 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
 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,
+ * The loss of a session that never answered: it had no machine state,
  * so the caller can do the call again on a new session.
  */
 export class LostBeforeAnswer extends WireFailure {
@@ -127,21 +127,21 @@ export class ViceSessionClient {
     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);
+  /** Loads a project PRG into memory without reset or start; finishes stopped. `root` is the project folder; it stays on this side. */
+  async programLoad(params: { path: string; address?: number; root?: string }): Promise<{ state: RunState; loadAddress: number; size: number }> {
+    const file = readProjectFile(params.path, params.root === undefined ? {} : { root: params.root });
     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);
+  /** Autostarts a project program or image, as VICE's autostart does. `root` is the project folder; it stays on this side. */
+  async autostart(params: { path: string; index: number; run: boolean; root?: string }): Promise<{ state: RunState; emulatorFlaw?: string }> {
+    const file = readProjectFile(params.path, params.root === undefined ? {} : { root: params.root });
     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);
+  /** Attaches a project disk image to drive 8. `root` is the project folder; it stays on this side. */
+  async diskAttach(params: { path: string; root?: string }): Promise<{ attached: boolean }> {
+    const file = readProjectFile(params.path, params.root === undefined ? {} : { root: params.root });
     return this.#request("diskAttach", { type: file.type }, [file.bytes]);
   }
 
@@ -178,6 +178,11 @@ export class ViceSessionClient {
     return this.#request("cpuHistory", params);
   }
 
+  /** Records each hit of the points while the program runs on. */
+  trace(params: ViceOperations["trace"]["params"]): Promise<ViceOperations["trace"]["result"]> {
+    return this.#request("trace", params);
+  }
+
   backtrace(params: ViceOperations["backtrace"]["params"]): Promise<ViceOperations["backtrace"]["result"]> {
     return this.#request("backtrace", params);
   }
@@ -186,8 +191,10 @@ export class ViceSessionClient {
     return this.#request("timing", { action });
   }
 
-  profile(limit: number): Promise<ViceOperations["profile"]["result"]> {
-    return this.#request("profile", { limit });
+  profile(params: { action: "read"; limit: number }): Promise<{ entries: ProfileEntry[] }>;
+  profile(params: { action: "clear" }): Promise<{ cleared: boolean }>;
+  profile(params: ViceOperations["profile"]["params"]): Promise<ViceOperations["profile"]["result"]> {
+    return this.#request("profile", params);
   }
 
   /** Action read gives the ranges; action clear gives cleared. */
@@ -231,7 +238,7 @@ export class ViceSessionClient {
     return this.#request("snapshot", params);
   }
 
-  /** The bytes of a named snapshot, as a .vsf file holds them (D41). */
+  /** The bytes of a named snapshot, as a .vsf file holds them. */
   async snapshotExport(name: string): Promise<Buffer> {
     const { attachments } = await this.#requestWithAttachments("snapshotFile", { action: "export", name });
     const [bytes] = attachments;
@@ -266,12 +273,12 @@ export class ViceSessionClient {
     return this.#lost !== undefined;
   }
 
-  /** True when the emulator answered a request: then the session had machine state to lose (D57). */
+  /** True when the emulator answered a request: then the session had machine state to lose. */
   get answered(): boolean {
     return this.#answered;
   }
 
-  /** The loss of a lost session, when no request got it; undefined while the session lives (D57). */
+  /** The loss of a lost session, when no request got it; undefined while the session lives. */
   get unreportedLoss(): WireFailure | undefined {
     return this.#lost?.code === "machine-state-lost" && !this.#lossReported ? this.#lost : undefined;
   }
@@ -314,3 +321,13 @@ export class ViceSessionClient {
     void this.#connection.close();
   }
 }
+
+
+/** Reads `size` bytes from `address` of the C64 in reads of at most 4 KiB, in one view: up to all 64 KiB. */
+export async function readMemoryInParts(client: Pick<ViceSessionClient, "memoryRead">, address: number, size: number, view: "cpu" | "ram"): Promise<Buffer> {
+  const parts: Buffer[] = [];
+  for (let at = address; at < address + size; at += MAX_MEMORY_READ) {
+    parts.push(Buffer.from((await client.memoryRead({ address: at, size: Math.min(MAX_MEMORY_READ, address + size - at), space: "c64", view })).data, "hex"));
+  }
+  return Buffer.concat(parts);
+}

package/src/knowledge/conflicts.ts

@@ -0,0 +1,161 @@
+// Conflicts: current rows that break a current-row rule. One computer
+// never writes them, but git joins the knowledge of two computers line by
+// line, so after a merge two names can be current at one address, or two
+// regions can overlap. Reads show them; writes are refused until a merge
+// revision decides them.
+
+import type { DatabaseSync } from "node:sqlite";
+
+import type { HistoryEntry } from "./history.ts";
+import {
+  COMMENT_COLUMNS,
+  MACRO_COLUMNS,
+  MACRO_USE_COLUMNS,
+  MODULE_COLUMNS,
+  OPERAND_COLUMNS,
+  PATCH_COLUMNS,
+  REFERENCE_COLUMNS,
+  REGION_COLUMNS,
+  SUPPRESSION_COLUMNS,
+  SYMBOL_COLUMNS,
+  toComment,
+  toMacro,
+  toMacroUse,
+  toModule,
+  toOperand,
+  toPatch,
+  toReference,
+  toRegion,
+  toSuppression,
+  toSymbol,
+} from "./read.ts";
+import type { Space } from "./schema.ts";
+import { compareText, sqlName } from "./text.ts";
+
+/** The current-row rules, each with what breaks it. */
+export const CONFLICT_RULES = {
+  "symbol-address": "two symbols at one address",
+  "analyzer-name-address": "two names of one analyzer at one address",
+  "analyzer-name-name": "one analyzer name at two addresses",
+  "symbol-name": "one name at two addresses",
+  region: "regions that overlap",
+  comment: "two comments at one place",
+  reference: "the same reference two times",
+  operand: "two operand expressions at one address",
+  "module-start": "two modules at one address",
+  "module-file": "one module file at two addresses",
+  "suppression-symbol": "the same symbol suppression two times",
+  "suppression-reference": "the same reference suppression two times",
+  "suppression-region": "region suppressions that overlap",
+  patch: "patches that overlap",
+  macro: "two macros with one name",
+  "macro-use": "macro uses that overlap",
+} as const;
+export type ConflictRule = keyof typeof CONFLICT_RULES;
+
+/** One row of a conflict: the row with its revisions and its id. */
+export type ConflictRow = HistoryEntry & { id: string };
+
+/** Current rows that break one rule together, oldest first. */
+export interface Conflict {
+  rule: ConflictRule;
+  space: Space;
+  rows: ConflictRow[];
+}
+
+type Raw = Record<string, unknown>;
+
+interface TableRule {
+  rule: ConflictRule;
+  table: string;
+  entity: HistoryEntry["entity"];
+  columns: string;
+  map: (raw: Raw) => HistoryEntry["row"];
+  /** The columns that must differ between current rows, or "overlap" for address ranges. */
+  key: readonly string[] | "overlap";
+  /** Rows of the table that the rule is about. */
+  where?: string;
+}
+
+const RULES: readonly TableRule[] = [
+  { rule: "symbol-address", table: "symbols", entity: "symbol", columns: SYMBOL_COLUMNS, map: toSymbol, key: ["address"] },
+  { rule: "symbol-name", table: "symbols", entity: "symbol", columns: SYMBOL_COLUMNS, map: toSymbol, key: ["name"] },
+  { rule: "analyzer-name-address", table: "analyzer_names", entity: "analyzer-name", columns: SYMBOL_COLUMNS, map: toSymbol, key: ["address", "origin"] },
+  { rule: "analyzer-name-name", table: "analyzer_names", entity: "analyzer-name", columns: SYMBOL_COLUMNS, map: toSymbol, key: ["name", "origin"] },
+  { rule: "region", table: "regions", entity: "region", columns: REGION_COLUMNS, map: toRegion, key: "overlap" },
+  { rule: "comment", table: "comments", entity: "comment", columns: COMMENT_COLUMNS, map: toComment, key: ["address", "placement"] },
+  { rule: "reference", table: "references", entity: "reference", columns: REFERENCE_COLUMNS, map: toReference, key: ["from_address", "to_address", "kind"] },
+  { rule: "operand", table: "operands", entity: "operand", columns: OPERAND_COLUMNS, map: toOperand, key: ["address"] },
+  { rule: "module-start", table: "modules", entity: "module", columns: MODULE_COLUMNS, map: toModule, key: ["start_address"] },
+  { rule: "module-file", table: "modules", entity: "module", columns: MODULE_COLUMNS, map: toModule, key: ["file"] },
+  { rule: "suppression-symbol", table: "suppressions", entity: "suppression", columns: SUPPRESSION_COLUMNS, map: toSuppression, key: ["start_address"], where: "entity = 'symbol'" },
+  {
+    rule: "suppression-reference",
+    table: "suppressions",
+    entity: "suppression",
+    columns: SUPPRESSION_COLUMNS,
+    map: toSuppression,
+    key: ["start_address", "to_address", "kind"],
+    where: "entity = 'reference'",
+  },
+  { rule: "suppression-region", table: "suppressions", entity: "suppression", columns: SUPPRESSION_COLUMNS, map: toSuppression, key: "overlap", where: "entity = 'region'" },
+  { rule: "patch", table: "patches", entity: "patch", columns: PATCH_COLUMNS, map: toPatch, key: "overlap" },
+  { rule: "macro", table: "macros", entity: "macro", columns: MACRO_COLUMNS, map: toMacro, key: ["name"] },
+  { rule: "macro-use", table: "macro_uses", entity: "macro-use", columns: MACRO_USE_COLUMNS, map: toMacroUse, key: "overlap" },
+];
+
+function conflictRow(rule: TableRule, raw: Raw): ConflictRow {
+  return { entity: rule.entity, row: rule.map(raw), from: raw.valid_from_revision as string, id: raw.id as string } as ConflictRow;
+}
+
+const byAge = (a: ConflictRow, b: ConflictRow) => compareText(a.from, b.from) || compareText(a.id, b.id);
+
+/** The current rows of one rule that share a key, in groups. */
+function sameKey(db: DatabaseSync, rule: TableRule, key: readonly string[]): Conflict[] {
+  const where = `valid_to_revision IS NULL${rule.where === undefined ? "" : ` AND ${rule.where}`}`;
+  const columns = ["space", ...key].join(", ");
+  const rows = db
+    .prepare(`SELECT ${rule.columns}, id FROM ${sqlName(rule.table)} WHERE ${where} AND (${columns}) IN (SELECT ${columns} FROM ${sqlName(rule.table)} WHERE ${where} GROUP BY ${columns} HAVING count(*) > 1)`)
+    .all() as Raw[];
+  const groups = new Map<string, Conflict>();
+  for (const raw of rows) {
+    const id = JSON.stringify(["space", ...key].map((column) => raw[column]));
+    const group = groups.get(id) ?? { rule: rule.rule, space: raw.space as Space, rows: [] };
+    group.rows.push(conflictRow(rule, raw));
+    groups.set(id, group);
+  }
+  return [...groups.values()];
+}
+
+/** The current rows of one rule whose address ranges overlap, in groups of rows that overlap in a chain. */
+function overlapping(db: DatabaseSync, rule: TableRule): Conflict[] {
+  const rows = db
+    .prepare(`SELECT ${rule.columns}, id FROM ${sqlName(rule.table)} WHERE valid_to_revision IS NULL${rule.where === undefined ? "" : ` AND ${rule.where}`} ORDER BY space, start_address, end_address`)
+    .all() as Raw[];
+  const conflicts: Conflict[] = [];
+  let group: Conflict | undefined;
+  let end = -1;
+  for (const raw of rows) {
+    if (group !== undefined && raw.space === group.space && (raw.start_address as number) <= end) {
+      group.rows.push(conflictRow(rule, raw));
+      end = Math.max(end, raw.end_address as number);
+      continue;
+    }
+    if (group !== undefined && group.rows.length > 1) conflicts.push(group);
+    group = { rule: rule.rule, space: raw.space as Space, rows: [conflictRow(rule, raw)] };
+    end = raw.end_address as number;
+  }
+  if (group !== undefined && group.rows.length > 1) conflicts.push(group);
+  return conflicts;
+}
+
+/** Every conflict of the knowledge, rule by rule; the rows of each, oldest first. */
+export function conflicts(db: DatabaseSync | undefined): Conflict[] {
+  if (db === undefined) return [];
+  return RULES.flatMap((rule) => (rule.key === "overlap" ? overlapping(db, rule) : sameKey(db, rule, rule.key))).map((conflict) => ({ ...conflict, rows: conflict.rows.sort(byAge) }));
+}
+
+/** The table of a conflict rule. */
+export function conflictTable(rule: ConflictRule): string {
+  return RULES.find((item) => item.rule === rule)!.table;
+}