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

package/src/knowledge/import.ts

@@ -0,0 +1,344 @@
+// Analyzer import: reconciles one analyzer's normalized findings with
+// current knowledge as one revision in one transaction.
+//
+// An import is a snapshot of what the analyzer asserts inside its coverage.
+// In an authoritative category, the analyzer's own current rows in coverage
+// that the snapshot no longer holds are closed. Rows of the user, the LLM or
+// another analyzer are never replaced: a finding that contradicts one is
+// reported as a conflict. Code against data is a contradiction; a different
+// name or a finer data type for the same kind of memory is not.
+
+import { createHash } from "node:crypto";
+import type { DatabaseSync } from "node:sqlite";
+
+import { KnowledgeError, transaction } from "./database.ts";
+import {
+  REFERENCE_COLUMNS,
+  regionsOverlapping,
+  SYMBOL_COLUMNS,
+  symbolAt,
+  symbolNamed,
+  toReference,
+  toSymbol,
+  type ReferenceRow,
+  type RegionRow,
+  type SymbolRow,
+} from "./read.ts";
+import { REFERENCE_KINDS, REGION_TYPES, SYMBOL_KINDS, type Origin, type ReferenceKind, type RegionType, type SymbolKind } from "./schema.ts";
+import { Change, checkAddress, hex, SYMBOL_NAME } from "./write.ts";
+
+export const ANALYZERS = ["dxa", "ghidra"] as const satisfies readonly Origin[];
+export type Analyzer = (typeof ANALYZERS)[number];
+
+export interface AddressRange {
+  start: number;
+  end: number;
+}
+
+export interface NormalizedFindings {
+  analyzer: Analyzer;
+  /** The address ranges the analyzer examined; it makes claims only there. */
+  coverage: AddressRange[];
+  /** A category is authoritative when its findings are complete in coverage, so absence means "no longer asserted". */
+  authoritative: { symbols: boolean; regions: boolean; references: boolean };
+  symbols: Array<{ address: number; name: string; kind: SymbolKind }>;
+  regions: Array<{ start: number; end: number; type: RegionType }>;
+  /** Owned and covered by their source address. */
+  references: Array<{ from: number; to: number; kind: ReferenceKind }>;
+}
+
+export interface ImportContext {
+  /** The revision the caller read; the import is refused if knowledge changed since. */
+  expectedRevision?: number;
+  description?: string;
+  /** The SHA-256 of the analyzed image, as lowercase hex. */
+  inputHash?: string;
+  /** The analyzer's own version line. */
+  toolVersion?: string;
+}
+
+/** What a revision records about one analyzer run: the hash of the image bytes and, when the analyzer tells it, its version. */
+export function runProvenance(image: Uint8Array, toolVersion: string | undefined): Pick<ImportContext, "inputHash" | "toolVersion"> {
+  const inputHash = createHash("sha256").update(image).digest("hex");
+  return toolVersion === undefined ? { inputHash } : { inputHash, toolVersion };
+}
+
+export type ImportConflict =
+  | {
+      category: "symbol";
+      address: number;
+      reason: "kind" | "name-taken";
+      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 } };
+
+export interface ImportCounts {
+  added: number;
+  changed: number;
+  retired: number;
+  unchanged: number;
+}
+
+export interface ImportResult {
+  /** The new revision, or null when nothing changed. */
+  revision: number | null;
+  symbols: ImportCounts;
+  regions: ImportCounts;
+  references: ImportCounts;
+  conflicts: ImportConflict[];
+}
+
+const isCode = (value: SymbolKind | RegionType) => value === "label" || value === "routine" || value === "code";
+
+const counts = (): ImportCounts => ({ added: 0, changed: 0, retired: 0, unchanged: 0 });
+
+function invalid(message: string): never {
+  throw new KnowledgeError("invalid-input", `The analyzer result is not usable: ${message} Nothing was imported.`);
+}
+
+/** Sorted, merged coverage ranges. */
+function mergeCoverage(coverage: AddressRange[]): AddressRange[] {
+  const sorted = [...coverage].sort((a, b) => a.start - b.start);
+  const merged: AddressRange[] = [];
+  for (const range of sorted) {
+    const last = merged.at(-1);
+    if (last !== undefined && range.start <= last.end + 1) last.end = Math.max(last.end, range.end);
+    else merged.push({ ...range });
+  }
+  return merged;
+}
+
+/** Parts of `range` that no range in `holes` covers. */
+function subtract(range: AddressRange, holes: AddressRange[]): AddressRange[] {
+  let pieces = [range];
+  for (const hole of holes) {
+    pieces = pieces.flatMap((piece) => {
+      if (hole.end < piece.start || hole.start > piece.end) return [piece];
+      const left = hole.start > piece.start ? [{ start: piece.start, end: hole.start - 1 }] : [];
+      const right = hole.end < piece.end ? [{ start: hole.end + 1, end: piece.end }] : [];
+      return [...left, ...right];
+    });
+  }
+  return pieces;
+}
+
+/**
+ * Checks complete findings before anything is written. Every finding
+ * lies in coverage, names are valid and unique, regions do not overlap.
+ * Returns the merged coverage.
+ */
+export function validateFindings(findings: NormalizedFindings): AddressRange[] {
+  if (!(ANALYZERS as readonly string[]).includes(findings.analyzer)) invalid(`the analyzer must be one of ${ANALYZERS.join(", ")}.`);
+  if (!Array.isArray(findings.coverage) || findings.coverage.length === 0) invalid("the result has no coverage.");
+  for (const range of findings.coverage) {
+    checkAddress(range.start, "coverage start");
+    checkAddress(range.end, "coverage end");
+    if (range.end < range.start) invalid(`coverage ${hex(range.start)}-${hex(range.end)} ends before it starts.`);
+  }
+  const coverage = mergeCoverage(findings.coverage);
+  const covering = (start: number, end: number) => coverage.some((range) => range.start <= start && end <= range.end);
+
+  const addresses = new Set<number>();
+  const names = new Set<string>();
+  for (const symbol of findings.symbols) {
+    checkAddress(symbol.address);
+    if (!covering(symbol.address, symbol.address)) invalid(`the symbol at ${hex(symbol.address)} is outside the coverage.`);
+    if (!SYMBOL_NAME.test(symbol.name)) invalid(`the symbol name ${JSON.stringify(symbol.name)} is not valid.`);
+    if (!(SYMBOL_KINDS as readonly string[]).includes(symbol.kind)) invalid(`the symbol kind ${symbol.kind} is not known.`);
+    if (addresses.has(symbol.address)) invalid(`two symbols are at ${hex(symbol.address)}.`);
+    if (names.has(symbol.name)) invalid(`the name ${symbol.name} is at two addresses.`);
+    addresses.add(symbol.address);
+    names.add(symbol.name);
+  }
+  const regions = [...findings.regions].sort((a, b) => a.start - b.start);
+  regions.forEach((region, index) => {
+    checkAddress(region.start, "region start");
+    checkAddress(region.end, "region end");
+    if (region.end < region.start) invalid(`the region ${hex(region.start)}-${hex(region.end)} ends before it starts.`);
+    if (!covering(region.start, region.end)) invalid(`the region ${hex(region.start)}-${hex(region.end)} is not inside the coverage.`);
+    if (!(REGION_TYPES as readonly string[]).includes(region.type)) invalid(`the region type ${region.type} is not known.`);
+    const previous = regions[index - 1];
+    if (previous !== undefined && region.start <= previous.end) invalid(`the regions at ${hex(previous.start)} and ${hex(region.start)} overlap.`);
+  });
+  for (const reference of findings.references) {
+    checkAddress(reference.from, "reference source");
+    checkAddress(reference.to, "reference target");
+    if (!covering(reference.from, reference.from)) invalid(`the reference from ${hex(reference.from)} is outside the coverage.`);
+    if (!(REFERENCE_KINDS as readonly string[]).includes(reference.kind)) invalid(`the reference kind ${reference.kind} is not known.`);
+  }
+  return coverage;
+}
+
+function ownSymbols(db: DatabaseSync, analyzer: Analyzer, range: AddressRange): SymbolRow[] {
+  return db
+    .prepare(`SELECT ${SYMBOL_COLUMNS} FROM current_symbols WHERE origin = ? AND address BETWEEN ? AND ? ORDER BY address`)
+    .all(analyzer, range.start, range.end)
+    .map((row) => toSymbol(row as Record<string, unknown>));
+}
+
+function ownReferences(db: DatabaseSync, analyzer: Analyzer, range: AddressRange): ReferenceRow[] {
+  return db
+    .prepare(`SELECT ${REFERENCE_COLUMNS} FROM current_references WHERE origin = ? AND from_address BETWEEN ? AND ? ORDER BY from_address`)
+    .all(analyzer, range.start, range.end)
+    .map((row) => toReference(row as Record<string, unknown>));
+}
+
+function importSymbols(db: DatabaseSync, change: Change, findings: NormalizedFindings, coverage: AddressRange[], result: ImportResult): void {
+  const { analyzer } = findings;
+  const wanted = new Map(findings.symbols.map((symbol) => [symbol.address, symbol]));
+  const settled = new Set<number>();
+  const replaced = new Set<number>();
+  // Close first, so a name can move between addresses within one import.
+  for (const range of coverage) {
+    for (const own of ownSymbols(db, analyzer, range)) {
+      const finding = wanted.get(own.address);
+      if (finding === undefined) {
+        if (!findings.authoritative.symbols) continue;
+        change.close("symbols", "address = ?", own.address);
+        result.symbols.retired++;
+      } else if (finding.name === own.name && finding.kind === own.kind) {
+        settled.add(own.address);
+        result.symbols.unchanged++;
+      } else {
+        change.close("symbols", "address = ?", own.address);
+        replaced.add(own.address);
+      }
+    }
+  }
+  for (const finding of findings.symbols) {
+    if (settled.has(finding.address)) continue;
+    const current = symbolAt(db, finding.address);
+    if (current !== undefined) {
+      // A semantic or other-analyzer row stays; only a code/data disagreement matters.
+      if (isCode(current.kind) !== isCode(finding.kind)) {
+        result.conflicts.push({ category: "symbol", address: finding.address, reason: "kind", current, finding: { name: finding.name, kind: finding.kind } });
+      }
+      continue;
+    }
+    const owner = symbolNamed(db, finding.name);
+    if (owner?.origin === analyzer) {
+      // The analyzer moved its own name: its newer finding replaces its own older row.
+      change.close("symbols", "address = ?", owner.address);
+      result.symbols.retired++;
+    } else if (owner !== undefined) {
+      result.conflicts.push({ category: "symbol", address: finding.address, reason: "name-taken", current: owner, finding: { name: finding.name, kind: finding.kind } });
+      if (replaced.has(finding.address)) result.symbols.retired++;
+      continue;
+    }
+    change.insertSymbol({ address: finding.address, name: finding.name, kind: finding.kind, origin: analyzer });
+    if (replaced.has(finding.address)) result.symbols.changed++;
+    else result.symbols.added++;
+  }
+}
+
+function importRegions(db: DatabaseSync, change: Change, findings: NormalizedFindings, coverage: AddressRange[], result: ImportResult): void {
+  const { analyzer } = findings;
+  const conflictWith = (row: RegionRow, region: { start: number; end: number; type: RegionType }) => {
+    if (isCode(row.type) === isCode(region.type)) return;
+    result.conflicts.push({
+      category: "region",
+      start: Math.max(row.start, region.start),
+      end: Math.min(row.end, region.end),
+      current: { type: row.type, origin: row.origin },
+      finding: { type: region.type },
+    });
+  };
+
+  if (!findings.authoritative.regions) {
+    // Retire nothing the snapshot leaves out. Fill addresses that no region covers yet, and
+    // give the analyzer's own regions under a finding the type that the analyzer finds now.
+    for (const region of findings.regions) {
+      const current = regionsOverlapping(db, region.start, region.end);
+      const protectedRows = current.filter((row) => row.origin !== analyzer);
+      for (const row of protectedRows) conflictWith(row, region);
+      const own = current.filter((row) => row.origin === analyzer);
+      const kept = own.filter((row) => row.type === region.type);
+      result.regions.unchanged += kept.length;
+      for (const row of own.filter((candidate) => candidate.type !== region.type)) {
+        // Close the row and keep its parts outside the finding.
+        change.close("regions", "start_address = ? AND end_address = ? AND origin = ?", row.start, row.end, analyzer);
+        if (row.start < region.start) change.insertRegion({ start: row.start, end: region.start - 1, type: row.type, origin: analyzer });
+        if (row.end > region.end) change.insertRegion({ start: region.end + 1, end: row.end, type: row.type, origin: analyzer });
+        result.regions.changed++;
+      }
+      const empty = subtract(region, current);
+      for (const piece of subtract(region, [...protectedRows, ...kept])) {
+        change.insertRegion({ ...piece, type: region.type, origin: analyzer });
+      }
+      result.regions.added += empty.length;
+    }
+    return;
+  }
+
+  for (const range of coverage) {
+    const current = regionsOverlapping(db, range.start, range.end);
+    const protectedRows = current.filter((row) => row.origin !== analyzer);
+    const own = current.filter((row) => row.origin === analyzer);
+    // What the analyzer may own here: its regions minus protected rows.
+    const desired = new Map<string, { start: number; end: number; type: RegionType }>();
+    for (const region of findings.regions.filter((candidate) => candidate.start >= range.start && candidate.end <= range.end)) {
+      for (const row of protectedRows) if (row.start <= region.end && row.end >= region.start) conflictWith(row, region);
+      for (const piece of subtract(region, protectedRows)) desired.set(`${piece.start}-${piece.end}`, { ...piece, type: region.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) };
+      const key = `${inside.start}-${inside.end}`;
+      if (desired.get(key)?.type === row.type) {
+        desired.delete(key);
+        result.regions.unchanged++;
+        continue;
+      }
+      // Close the row and keep its parts outside the coverage.
+      change.close("regions", "start_address = ? AND end_address = ? AND origin = ?", row.start, row.end, analyzer);
+      if (row.start < range.start) change.insertRegion({ start: row.start, end: range.start - 1, type: row.type, origin: analyzer });
+      if (row.end > range.end) change.insertRegion({ start: range.end + 1, end: row.end, type: row.type, origin: analyzer });
+      retiredRanges.add(key);
+    }
+    for (const [key, piece] of desired) {
+      change.insertRegion({ ...piece, origin: analyzer });
+      if (retiredRanges.delete(key)) result.regions.changed++;
+      else result.regions.added++;
+    }
+    result.regions.retired += retiredRanges.size;
+  }
+}
+
+function importReferences(db: DatabaseSync, change: Change, findings: NormalizedFindings, coverage: AddressRange[], result: ImportResult): void {
+  const { analyzer } = findings;
+  const key = (reference: { from: number; to: number; kind: ReferenceKind }) => `${reference.from}|${reference.to}|${reference.kind}`;
+  const wanted = new Map(findings.references.map((reference) => [key(reference), reference]));
+  for (const range of coverage) {
+    for (const own of ownReferences(db, analyzer, range)) {
+      if (wanted.has(key(own))) continue;
+      if (!findings.authoritative.references) continue;
+      change.close('"references"', "from_address = ? AND to_address = ? AND kind = ? AND origin = ?", own.from, own.to, own.kind, analyzer);
+      result.references.retired++;
+    }
+  }
+  const existing = db.prepare('SELECT origin FROM current_references WHERE from_address = ? AND to_address = ? AND kind = ?');
+  for (const reference of wanted.values()) {
+    const rows = existing.all(reference.from, reference.to, reference.kind) as Array<{ origin: Origin }>;
+    if (rows.some((row) => row.origin === analyzer)) result.references.unchanged++;
+    // The same fact from the user, the LLM or another analyzer already holds.
+    else if (rows.length === 0) {
+      change.insertReference({ ...reference, origin: analyzer });
+      result.references.added++;
+    }
+  }
+}
+
+/** Imports one analyzer result as one revision. Nothing is written when validation fails. */
+export function importFindings(db: DatabaseSync, findings: NormalizedFindings, context: ImportContext = {}): ImportResult {
+  const coverage = validateFindings(findings);
+  return transaction(db, () => {
+    const change = new Change(db, { origin: findings.analyzer, ...context }, `import-${findings.analyzer}`);
+    const result: ImportResult = { revision: null, symbols: counts(), regions: counts(), references: counts(), conflicts: [] };
+    importSymbols(db, change, findings, coverage, result);
+    importRegions(db, change, findings, coverage, result);
+    importReferences(db, change, findings, coverage, result);
+    result.revision = change.revision;
+    return result;
+  });
+}

package/src/knowledge/read.ts

@@ -0,0 +1,191 @@
+// Current-state knowledge queries. A project without a database
+// reads as empty knowledge.
+
+import type { DatabaseSync } from "node:sqlite";
+
+import type { CommentPlacement, Origin, ReferenceKind, RegionType, SymbolKind } from "./schema.ts";
+
+export interface SymbolRow {
+  address: number;
+  name: string;
+  kind: SymbolKind;
+  origin: Origin;
+  revision: number;
+}
+
+export interface RegionRow {
+  start: number;
+  end: number;
+  type: RegionType;
+  origin: Origin;
+  revision: number;
+}
+
+export interface CommentRow {
+  address: number;
+  placement: CommentPlacement;
+  text: string;
+  origin: Origin;
+  revision: number;
+}
+
+export interface ReferenceRow {
+  from: number;
+  to: number;
+  kind: ReferenceKind;
+  origin: Origin;
+  revision: number;
+}
+
+type Raw = Record<string, unknown>;
+
+export const SYMBOL_COLUMNS = "address, name, kind, origin, valid_from_revision";
+export const REGION_COLUMNS = "start_address, end_address, type, origin, valid_from_revision";
+export const COMMENT_COLUMNS = "address, placement, text, origin, valid_from_revision";
+export const REFERENCE_COLUMNS = "from_address, to_address, kind, origin, valid_from_revision";
+
+export function toSymbol(row: Raw): SymbolRow {
+  return { address: row.address as number, name: row.name as string, kind: row.kind as SymbolKind, origin: row.origin as Origin, revision: row.valid_from_revision as number };
+}
+
+export function toRegion(row: Raw): RegionRow {
+  return { start: row.start_address as number, end: row.end_address as number, type: row.type as RegionType, origin: row.origin as Origin, revision: row.valid_from_revision as number };
+}
+
+export function toComment(row: Raw): CommentRow {
+  return { address: row.address as number, placement: row.placement as CommentPlacement, text: row.text as string, origin: row.origin as Origin, revision: row.valid_from_revision as number };
+}
+
+export function toReference(row: Raw): ReferenceRow {
+  return { from: row.from_address as number, to: row.to_address as number, kind: row.kind as ReferenceKind, origin: row.origin as Origin, revision: row.valid_from_revision as number };
+}
+
+export function currentRevision(db: DatabaseSync | undefined): number {
+  if (db === undefined) return 0;
+  return Number((db.prepare("SELECT value FROM meta WHERE key = 'current_revision'").get() as { value: string }).value);
+}
+
+export function symbolAt(db: DatabaseSync | undefined, address: number): SymbolRow | undefined {
+  const row = db?.prepare(`SELECT ${SYMBOL_COLUMNS} FROM current_symbols WHERE address = ?`).get(address) as Raw | undefined;
+  return row === undefined ? undefined : toSymbol(row);
+}
+
+export function symbolNamed(db: DatabaseSync | undefined, name: string): SymbolRow | undefined {
+  const row = db?.prepare(`SELECT ${SYMBOL_COLUMNS} FROM current_symbols WHERE name = ?`).get(name) as Raw | undefined;
+  return row === undefined ? undefined : toSymbol(row);
+}
+
+/** Current regions that share at least one address with [start, end], in address order. */
+export function regionsOverlapping(db: DatabaseSync | undefined, start: number, end: number): RegionRow[] {
+  if (db === undefined) return [];
+  return db
+    .prepare(`SELECT ${REGION_COLUMNS} FROM current_regions WHERE start_address <= ? AND end_address >= ? ORDER BY start_address`)
+    .all(end, start)
+    .map((row) => toRegion(row as Raw));
+}
+
+export function commentsAt(db: DatabaseSync | undefined, address: number): CommentRow[] {
+  if (db === undefined) return [];
+  return db
+    .prepare(`SELECT ${COMMENT_COLUMNS} FROM current_comments WHERE address = ? ORDER BY placement`)
+    .all(address)
+    .map((row) => toComment(row as Raw));
+}
+
+export function referencesFrom(db: DatabaseSync | undefined, address: number): ReferenceRow[] {
+  if (db === undefined) return [];
+  return db
+    .prepare(`SELECT ${REFERENCE_COLUMNS} FROM current_references WHERE from_address = ? ORDER BY to_address, kind`)
+    .all(address)
+    .map((row) => toReference(row as Raw));
+}
+
+export function referencesTo(db: DatabaseSync | undefined, address: number): ReferenceRow[] {
+  if (db === undefined) return [];
+  return db
+    .prepare(`SELECT ${REFERENCE_COLUMNS} FROM current_references WHERE to_address = ? ORDER BY from_address, kind`)
+    .all(address)
+    .map((row) => toReference(row as Raw));
+}
+
+/** Everything currently known at one address: the main lookup for skills. */
+export interface AddressKnowledge {
+  address: number;
+  symbol?: SymbolRow;
+  /** The current region that contains the address. */
+  region?: RegionRow;
+  comments: CommentRow[];
+  referencesFrom: ReferenceRow[];
+  referencesTo: ReferenceRow[];
+  revision: number;
+}
+
+export function at(db: DatabaseSync | undefined, address: number): AddressKnowledge {
+  const result: AddressKnowledge = {
+    address,
+    comments: commentsAt(db, address),
+    referencesFrom: referencesFrom(db, address),
+    referencesTo: referencesTo(db, address),
+    revision: currentRevision(db),
+  };
+  const symbol = symbolAt(db, address);
+  if (symbol !== undefined) result.symbol = symbol;
+  const [region] = regionsOverlapping(db, address, address);
+  if (region !== undefined) result.region = region;
+  return result;
+}
+
+export interface Range {
+  start: number;
+  end: number;
+}
+
+const ALL: Range = { start: 0x0000, end: 0xffff };
+
+export function listSymbols(db: DatabaseSync | undefined, range: Range = ALL, kind?: SymbolKind): SymbolRow[] {
+  if (db === undefined) return [];
+  const rows =
+    kind === undefined
+      ? db.prepare(`SELECT ${SYMBOL_COLUMNS} FROM current_symbols WHERE address BETWEEN ? AND ? ORDER BY address`).all(range.start, range.end)
+      : db.prepare(`SELECT ${SYMBOL_COLUMNS} FROM current_symbols WHERE address BETWEEN ? AND ? AND kind = ? ORDER BY address`).all(range.start, range.end, kind);
+  return rows.map((row) => toSymbol(row as Raw));
+}
+
+export function listRegions(db: DatabaseSync | undefined, range: Range = ALL, type?: RegionType): RegionRow[] {
+  return regionsOverlapping(db, range.start, range.end).filter((region) => type === undefined || region.type === type);
+}
+
+export function listComments(db: DatabaseSync | undefined, range: Range = ALL): CommentRow[] {
+  if (db === undefined) return [];
+  return db
+    .prepare(`SELECT ${COMMENT_COLUMNS} FROM current_comments WHERE address BETWEEN ? AND ? ORDER BY address, placement`)
+    .all(range.start, range.end)
+    .map((row) => toComment(row as Raw));
+}
+
+/** Current references whose source or target lies in the range. */
+export function listReferences(db: DatabaseSync | undefined, range: Range = ALL, kind?: ReferenceKind): ReferenceRow[] {
+  if (db === undefined) return [];
+  return db
+    .prepare(
+      `SELECT ${REFERENCE_COLUMNS} FROM current_references WHERE (from_address BETWEEN ? AND ? OR to_address BETWEEN ? AND ?) ORDER BY from_address, to_address, kind`,
+    )
+    .all(range.start, range.end, range.start, range.end)
+    .map((row) => toReference(row as Raw))
+    .filter((reference) => kind === undefined || reference.kind === kind);
+}
+
+/** Case-insensitive text search in current symbol names and comment texts. */
+export function search(db: DatabaseSync | undefined, text: string, limit = 50): { symbols: SymbolRow[]; comments: CommentRow[] } {
+  if (db === undefined || text.length === 0) return { symbols: [], comments: [] };
+  const pattern = `%${text.replace(/[\\%_]/g, (character) => `\\${character}`)}%`;
+  const symbols = db
+    .prepare(`SELECT ${SYMBOL_COLUMNS} FROM current_symbols WHERE name LIKE ? ESCAPE '\\' ORDER BY address LIMIT ?`)
+    .all(pattern, limit)
+    .map((row) => toSymbol(row as Raw));
+  const comments = db
+    .prepare(`SELECT ${COMMENT_COLUMNS} FROM current_comments WHERE text LIKE ? ESCAPE '\\' ORDER BY address, placement LIMIT ?`)
+    .all(pattern, limit)
+    .map((row) => toComment(row as Raw));
+  return { symbols, comments };
+}

package/src/knowledge/schema.ts

@@ -0,0 +1,140 @@
+// The knowledge.db schema: one version, created in an empty database.
+
+import type { DatabaseSync } from "node:sqlite";
+
+import { REFERENCE_KINDS, type ReferenceKind } from "../c64.ts";
+import { KnowledgeError } from "./database.ts";
+
+export const ORIGINS = ["user", "llm", "dxa", "ghidra"] as const;
+export type Origin = (typeof ORIGINS)[number];
+export const SYMBOL_KINDS = ["label", "routine", "variable", "data", "vector"] as const;
+export type SymbolKind = (typeof SYMBOL_KINDS)[number];
+export const REGION_TYPES = ["code", "bytes", "words", "addresses", "addresses-split", "petscii", "screen", "bitmap", "sprite"] as const;
+export type RegionType = (typeof REGION_TYPES)[number];
+export const COMMENT_PLACEMENTS = ["line", "side"] as const;
+export type CommentPlacement = (typeof COMMENT_PLACEMENTS)[number];
+export { REFERENCE_KINDS, type ReferenceKind };
+
+const list = (values: readonly string[]) => values.map((value) => `'${value}'`).join(", ");
+
+/** The schema version this build reads and writes. */
+export const SCHEMA_VERSION = 1;
+
+/**
+ * Creates the schema in an empty database. Knowledge rows are temporal: a
+ * change closes the current row (valid_to_revision) and inserts a new one in
+ * the same revision.
+ */
+function createSchema(db: DatabaseSync): void {
+    db.exec(`
+      CREATE TABLE meta (
+        key   TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      );
+      CREATE TABLE revisions (
+        id           INTEGER PRIMARY KEY,
+        created_at   TEXT NOT NULL,
+        origin       TEXT NOT NULL CHECK (origin IN (${list(ORIGINS)})),
+        operation    TEXT NOT NULL,
+        input_hash   TEXT,
+        tool_version TEXT,
+        description  TEXT
+      );
+      CREATE TABLE symbols (
+        id                  INTEGER PRIMARY KEY,
+        address             INTEGER NOT NULL CHECK (address BETWEEN 0 AND 65535),
+        name                TEXT NOT NULL CHECK (length(name) > 0),
+        kind                TEXT NOT NULL CHECK (kind IN (${list(SYMBOL_KINDS)})),
+        origin              TEXT NOT NULL CHECK (origin IN (${list(ORIGINS)})),
+        valid_from_revision INTEGER NOT NULL REFERENCES revisions (id),
+        valid_to_revision   INTEGER REFERENCES revisions (id)
+      );
+      CREATE UNIQUE INDEX symbols_current_address ON symbols (address) WHERE valid_to_revision IS NULL;
+      CREATE UNIQUE INDEX symbols_current_name ON symbols (name) WHERE valid_to_revision IS NULL;
+      CREATE INDEX symbols_address ON symbols (address);
+      CREATE TABLE regions (
+        id                  INTEGER PRIMARY KEY,
+        start_address       INTEGER NOT NULL CHECK (start_address BETWEEN 0 AND 65535),
+        end_address         INTEGER NOT NULL CHECK (end_address BETWEEN start_address AND 65535),
+        type                TEXT NOT NULL CHECK (type IN (${list(REGION_TYPES)})),
+        origin              TEXT NOT NULL CHECK (origin IN (${list(ORIGINS)})),
+        valid_from_revision INTEGER NOT NULL REFERENCES revisions (id),
+        valid_to_revision   INTEGER REFERENCES revisions (id)
+      );
+      CREATE INDEX regions_start ON regions (start_address);
+      CREATE TABLE comments (
+        id                  INTEGER PRIMARY KEY,
+        address             INTEGER NOT NULL CHECK (address BETWEEN 0 AND 65535),
+        placement           TEXT NOT NULL CHECK (placement IN (${list(COMMENT_PLACEMENTS)})),
+        text                TEXT NOT NULL CHECK (length(text) > 0),
+        origin              TEXT NOT NULL CHECK (origin IN (${list(ORIGINS)})),
+        valid_from_revision INTEGER NOT NULL REFERENCES revisions (id),
+        valid_to_revision   INTEGER REFERENCES revisions (id)
+      );
+      CREATE UNIQUE INDEX comments_current ON comments (address, placement) WHERE valid_to_revision IS NULL;
+      CREATE INDEX comments_address ON comments (address);
+      CREATE TABLE "references" (
+        id                  INTEGER PRIMARY KEY,
+        from_address        INTEGER NOT NULL CHECK (from_address BETWEEN 0 AND 65535),
+        to_address          INTEGER NOT NULL CHECK (to_address BETWEEN 0 AND 65535),
+        kind                TEXT NOT NULL CHECK (kind IN (${list(REFERENCE_KINDS)})),
+        origin              TEXT NOT NULL CHECK (origin IN (${list(ORIGINS)})),
+        valid_from_revision INTEGER NOT NULL REFERENCES revisions (id),
+        valid_to_revision   INTEGER REFERENCES revisions (id)
+      );
+      CREATE UNIQUE INDEX references_current ON "references" (from_address, to_address, kind) WHERE valid_to_revision IS NULL;
+      CREATE INDEX references_from ON "references" (from_address);
+      CREATE INDEX references_to ON "references" (to_address);
+      CREATE VIEW current_symbols AS SELECT * FROM symbols WHERE valid_to_revision IS NULL;
+      CREATE VIEW current_regions AS SELECT * FROM regions WHERE valid_to_revision IS NULL;
+      CREATE VIEW current_comments AS SELECT * FROM comments WHERE valid_to_revision IS NULL;
+      CREATE VIEW current_references AS SELECT * FROM "references" WHERE valid_to_revision IS NULL;
+      INSERT INTO meta (key, value) VALUES ('current_revision', '0');
+    `);
+}
+
+export function schemaVersion(db: DatabaseSync): number {
+  const hasMeta = db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'meta'").get();
+  if (hasMeta === undefined) {
+    const tables = db.prepare("SELECT count(*) AS n FROM sqlite_master WHERE type = 'table'").get() as { n: number };
+    if (tables.n > 0) throw new KnowledgeError("invalid-database", "The knowledge database has tables but no meta table; it is not a c64-re-tools database.");
+    return 0;
+  }
+  const row = db.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get() as { value: unknown } | undefined;
+  if (row === undefined) throw new KnowledgeError("invalid-database", "The knowledge database has no schema version.");
+  const value = String(row.value);
+  if (!/^(0|[1-9][0-9]{0,8})$/.test(value)) throw new KnowledgeError("invalid-database", `The schema version of the knowledge database is not a whole number: ${JSON.stringify(value)}.`);
+  return Number(value);
+}
+
+/** Refuses a database with any schema version other than the one this build reads and writes. */
+export function checkVersion(version: number): void {
+  if (version !== SCHEMA_VERSION) {
+    throw new KnowledgeError(
+      "unsupported-schema",
+      `The knowledge database has schema version ${version}. This c64-re-tools reads and writes only version ${SCHEMA_VERSION}. Use the c64-re-tools release that wrote it.`,
+    );
+  }
+}
+
+/**
+ * Creates the schema in an empty database and refuses any other version. The
+ * version is read again under the write lock, so two processes that open a
+ * new database at the same time create the schema once.
+ */
+export function ensureSchema(db: DatabaseSync): void {
+  if (schemaVersion(db) === 0) {
+    db.exec("BEGIN IMMEDIATE");
+    try {
+      if (schemaVersion(db) === 0) {
+        createSchema(db);
+        db.prepare("INSERT INTO meta (key, value) VALUES ('schema_version', ?)").run(String(SCHEMA_VERSION));
+      }
+      db.exec("COMMIT");
+    } catch (error) {
+      db.exec("ROLLBACK");
+      throw error;
+    }
+  }
+  checkVersion(schemaVersion(db));
+}