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

package/src/knowledge/read.ts

@@ -1,11 +1,13 @@
 // Current-state knowledge queries. A project without a database
-// reads as empty knowledge.
+// reads as empty knowledge. Each query reads one address space (D53); the
+// default is the C64.
 
 import type { DatabaseSync } from "node:sqlite";
 
-import type { CommentPlacement, Origin, ReferenceKind, RegionType, SymbolKind } from "./schema.ts";
+import { DEFAULT_SPACE, type CommentPlacement, type Origin, type ReferenceKind, type RegionType, type Space, type SuppressionEntity, type SymbolKind } from "./schema.ts";
 
 export interface SymbolRow {
+  space: Space;
   address: number;
   name: string;
   kind: SymbolKind;
@@ -14,14 +16,18 @@ export interface SymbolRow {
 }
 
 export interface RegionRow {
+  space: Space;
   start: number;
   end: number;
   type: RegionType;
+  /** Bytes per element of a table; the length is a multiple of it (D42). */
+  element?: number;
   origin: Origin;
   revision: number;
 }
 
 export interface CommentRow {
+  space: Space;
   address: number;
   placement: CommentPlacement;
   text: string;
@@ -30,6 +36,7 @@ export interface CommentRow {
 }
 
 export interface ReferenceRow {
+  space: Space;
   from: number;
   to: number;
   kind: ReferenceKind;
@@ -37,27 +44,87 @@ export interface ReferenceRow {
   revision: number;
 }
 
+/** A place that a user/LLM removal blocks for every analyzer (D36). `to` and `kind` are set for a reference only. */
+export interface SuppressionRow {
+  space: Space;
+  entity: SuppressionEntity;
+  start: number;
+  end: number;
+  to?: number;
+  kind?: ReferenceKind;
+  origin: Extract<Origin, "user" | "llm">;
+  revision: number;
+}
+
+/** Where a file of the generated source starts (D48): it runs to the next module or the end of its segment. */
+export interface ModuleRow {
+  space: Space;
+  start: number;
+  file: string;
+  title?: string;
+  origin: Extract<Origin, "user" | "llm">;
+  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 const SYMBOL_COLUMNS = "space, address, name, kind, origin, valid_from_revision";
+export const REGION_COLUMNS = "space, start_address, end_address, type, element, origin, valid_from_revision";
+export const COMMENT_COLUMNS = "space, address, placement, text, origin, valid_from_revision";
+export const REFERENCE_COLUMNS = "space, from_address, to_address, kind, origin, valid_from_revision";
+export const SUPPRESSION_COLUMNS = "space, entity, start_address, end_address, to_address, kind, origin, valid_from_revision";
+export const MODULE_COLUMNS = "space, start_address, file, title, 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 };
+  return { space: row.space as Space, 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 };
+  const region: RegionRow = {
+    space: row.space as Space,
+    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,
+  };
+  if (row.element !== null && row.element !== undefined) region.element = row.element as number;
+  return region;
 }
 
 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 };
+  return {
+    space: row.space as Space,
+    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 };
+  return { space: row.space as Space, 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 toSuppression(row: Raw): SuppressionRow {
+  const suppression: SuppressionRow = {
+    space: row.space as Space,
+    entity: row.entity as SuppressionEntity,
+    start: row.start_address as number,
+    end: row.end_address as number,
+    origin: row.origin as SuppressionRow["origin"],
+    revision: row.valid_from_revision as number,
+  };
+  if (row.to_address !== null) suppression.to = row.to_address as number;
+  if (row.kind !== null) suppression.kind = row.kind as ReferenceKind;
+  return suppression;
+}
+
+export function toModule(row: Raw): ModuleRow {
+  const module: ModuleRow = { space: row.space as Space, start: row.start_address as number, file: row.file as string, origin: row.origin as ModuleRow["origin"], revision: row.valid_from_revision as number };
+  if (row.title !== null && row.title !== undefined) module.title = row.title as string;
+  return module;
 }
 
 export function currentRevision(db: DatabaseSync | undefined): number {
@@ -65,51 +132,90 @@ export function currentRevision(db: DatabaseSync | undefined): number {
   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;
+export function symbolAt(db: DatabaseSync | undefined, address: number, space: Space = DEFAULT_SPACE): SymbolRow | undefined {
+  const row = db?.prepare(`SELECT ${SYMBOL_COLUMNS} FROM current_symbols WHERE space = ? AND address = ?`).get(space, 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;
+export function symbolNamed(db: DatabaseSync | undefined, name: string, space: Space = DEFAULT_SPACE): SymbolRow | undefined {
+  const row = db?.prepare(`SELECT ${SYMBOL_COLUMNS} FROM current_symbols WHERE space = ? AND name = ?`).get(space, 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[] {
+export function regionsOverlapping(db: DatabaseSync | undefined, start: number, end: number, space: Space = DEFAULT_SPACE): 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)
+    .prepare(`SELECT ${REGION_COLUMNS} FROM current_regions WHERE space = ? AND start_address <= ? AND end_address >= ? ORDER BY start_address`)
+    .all(space, end, start)
     .map((row) => toRegion(row as Raw));
 }
 
-export function commentsAt(db: DatabaseSync | undefined, address: number): CommentRow[] {
+export function commentsAt(db: DatabaseSync | undefined, address: number, space: Space = DEFAULT_SPACE): CommentRow[] {
   if (db === undefined) return [];
   return db
-    .prepare(`SELECT ${COMMENT_COLUMNS} FROM current_comments WHERE address = ? ORDER BY placement`)
-    .all(address)
+    .prepare(`SELECT ${COMMENT_COLUMNS} FROM current_comments WHERE space = ? AND address = ? ORDER BY placement`)
+    .all(space, address)
     .map((row) => toComment(row as Raw));
 }
 
-export function referencesFrom(db: DatabaseSync | undefined, address: number): ReferenceRow[] {
+export function referencesFrom(db: DatabaseSync | undefined, address: number, space: Space = DEFAULT_SPACE): ReferenceRow[] {
   if (db === undefined) return [];
   return db
-    .prepare(`SELECT ${REFERENCE_COLUMNS} FROM current_references WHERE from_address = ? ORDER BY to_address, kind`)
-    .all(address)
+    .prepare(`SELECT ${REFERENCE_COLUMNS} FROM current_references WHERE space = ? AND from_address = ? ORDER BY to_address, kind`)
+    .all(space, address)
     .map((row) => toReference(row as Raw));
 }
 
-export function referencesTo(db: DatabaseSync | undefined, address: number): ReferenceRow[] {
+export function referencesTo(db: DatabaseSync | undefined, address: number, space: Space = DEFAULT_SPACE): ReferenceRow[] {
   if (db === undefined) return [];
   return db
-    .prepare(`SELECT ${REFERENCE_COLUMNS} FROM current_references WHERE to_address = ? ORDER BY from_address, kind`)
-    .all(address)
+    .prepare(`SELECT ${REFERENCE_COLUMNS} FROM current_references WHERE space = ? AND to_address = ? ORDER BY from_address, kind`)
+    .all(space, address)
     .map((row) => toReference(row as Raw));
 }
 
+/** Current suppressions of one entity that share at least one address with [start, end], in address order. */
+export function suppressionsOverlapping(db: DatabaseSync | undefined, entity: SuppressionEntity, start: number, end: number, space: Space = DEFAULT_SPACE): SuppressionRow[] {
+  if (db === undefined) return [];
+  return db
+    .prepare(`SELECT ${SUPPRESSION_COLUMNS} FROM current_suppressions WHERE space = ? AND entity = ? AND start_address <= ? AND end_address >= ? ORDER BY start_address, to_address, kind`)
+    .all(space, entity, end, start)
+    .map((row) => toSuppression(row as Raw));
+}
+
+export function symbolSuppressed(db: DatabaseSync | undefined, address: number, space: Space = DEFAULT_SPACE): boolean {
+  return suppressionsOverlapping(db, "symbol", address, address, space).length > 0;
+}
+
+export function referenceSuppressed(db: DatabaseSync | undefined, reference: { from: number; to: number; kind: ReferenceKind }, space: Space = DEFAULT_SPACE): boolean {
+  return suppressionsOverlapping(db, "reference", reference.from, reference.from, space).some((row) => row.to === reference.to && row.kind === reference.kind);
+}
+
+/** Current suppressions at an address: its symbol, the region range that holds it, references from or to it. */
+export function suppressionsAt(db: DatabaseSync | undefined, address: number, space: Space = DEFAULT_SPACE): SuppressionRow[] {
+  if (db === undefined) return [];
+  return db
+    .prepare(
+      `SELECT ${SUPPRESSION_COLUMNS} FROM current_suppressions WHERE space = ? AND ((start_address <= ? AND end_address >= ?) OR to_address = ?) ORDER BY entity, start_address, to_address, kind`,
+    )
+    .all(space, address, address, address)
+    .map((row) => toSuppression(row as Raw));
+}
+
+export function moduleAt(db: DatabaseSync | undefined, start: number, space: Space = DEFAULT_SPACE): ModuleRow | undefined {
+  const row = db?.prepare(`SELECT ${MODULE_COLUMNS} FROM current_modules WHERE space = ? AND start_address = ?`).get(space, start) as Raw | undefined;
+  return row === undefined ? undefined : toModule(row);
+}
+
+export function moduleWithFile(db: DatabaseSync | undefined, file: string, space: Space = DEFAULT_SPACE): ModuleRow | undefined {
+  const row = db?.prepare(`SELECT ${MODULE_COLUMNS} FROM current_modules WHERE space = ? AND file = ?`).get(space, file) as Raw | undefined;
+  return row === undefined ? undefined : toModule(row);
+}
+
 /** Everything currently known at one address: the main lookup for skills. */
 export interface AddressKnowledge {
+  space: Space;
   address: number;
   symbol?: SymbolRow;
   /** The current region that contains the address. */
@@ -117,20 +223,24 @@ export interface AddressKnowledge {
   comments: CommentRow[];
   referencesFrom: ReferenceRow[];
   referencesTo: ReferenceRow[];
+  /** What user/LLM removals block here for the analyzers. */
+  suppressions: SuppressionRow[];
   revision: number;
 }
 
-export function at(db: DatabaseSync | undefined, address: number): AddressKnowledge {
+export function at(db: DatabaseSync | undefined, address: number, space: Space = DEFAULT_SPACE): AddressKnowledge {
   const result: AddressKnowledge = {
+    space,
     address,
-    comments: commentsAt(db, address),
-    referencesFrom: referencesFrom(db, address),
-    referencesTo: referencesTo(db, address),
+    comments: commentsAt(db, address, space),
+    referencesFrom: referencesFrom(db, address, space),
+    referencesTo: referencesTo(db, address, space),
+    suppressions: suppressionsAt(db, address, space),
     revision: currentRevision(db),
   };
-  const symbol = symbolAt(db, address);
+  const symbol = symbolAt(db, address, space);
   if (symbol !== undefined) result.symbol = symbol;
-  const [region] = regionsOverlapping(db, address, address);
+  const [region] = regionsOverlapping(db, address, address, space);
   if (region !== undefined) result.region = region;
   return result;
 }
@@ -142,50 +252,91 @@ export interface Range {
 
 const ALL: Range = { start: 0x0000, end: 0xffff };
 
-export function listSymbols(db: DatabaseSync | undefined, range: Range = ALL, kind?: SymbolKind): SymbolRow[] {
+/** Rows of these origins only; undefined keeps every origin (D42). */
+export type OriginFilter = readonly Origin[] | undefined;
+const kept = (origins: OriginFilter) => (row: { origin: Origin }) => origins === undefined || origins.includes(row.origin);
+
+
+export function listSymbols(db: DatabaseSync | undefined, range: Range = ALL, kind?: SymbolKind, origins?: OriginFilter, space: Space = DEFAULT_SPACE): 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));
+      ? db.prepare(`SELECT ${SYMBOL_COLUMNS} FROM current_symbols WHERE space = ? AND address BETWEEN ? AND ? ORDER BY address`).all(space, range.start, range.end)
+      : db.prepare(`SELECT ${SYMBOL_COLUMNS} FROM current_symbols WHERE space = ? AND address BETWEEN ? AND ? AND kind = ? ORDER BY address`).all(space, range.start, range.end, kind);
+  return rows.map((row) => toSymbol(row as Raw)).filter(kept(origins));
 }
 
-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 listRegions(db: DatabaseSync | undefined, range: Range = ALL, type?: RegionType, origins?: OriginFilter, space: Space = DEFAULT_SPACE): RegionRow[] {
+  return regionsOverlapping(db, range.start, range.end, space).filter((region) => (type === undefined || region.type === type) && kept(origins)(region));
 }
 
-export function listComments(db: DatabaseSync | undefined, range: Range = ALL): CommentRow[] {
+export function listComments(db: DatabaseSync | undefined, range: Range = ALL, origins?: OriginFilter, space: Space = DEFAULT_SPACE): 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));
+    .prepare(`SELECT ${COMMENT_COLUMNS} FROM current_comments WHERE space = ? AND address BETWEEN ? AND ? ORDER BY address, placement`)
+    .all(space, range.start, range.end)
+    .map((row) => toComment(row as Raw))
+    .filter(kept(origins));
 }
 
 /** Current references whose source or target lies in the range. */
-export function listReferences(db: DatabaseSync | undefined, range: Range = ALL, kind?: ReferenceKind): ReferenceRow[] {
+export function listReferences(db: DatabaseSync | undefined, range: Range = ALL, kind?: ReferenceKind, origins?: OriginFilter, space: Space = DEFAULT_SPACE): 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`,
+      `SELECT ${REFERENCE_COLUMNS} FROM current_references WHERE space = ? AND (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)
+    .all(space, range.start, range.end, range.start, range.end)
     .map((row) => toReference(row as Raw))
-    .filter((reference) => kind === undefined || reference.kind === kind);
+    .filter((reference) => (kind === undefined || reference.kind === kind) && kept(origins)(reference));
+}
+
+/** Current suppressions whose place lies in the range: a reference by its source or target. */
+export function listSuppressions(db: DatabaseSync | undefined, range: Range = ALL, space: Space = DEFAULT_SPACE): SuppressionRow[] {
+  if (db === undefined) return [];
+  return db
+    .prepare(
+      `SELECT ${SUPPRESSION_COLUMNS} FROM current_suppressions WHERE space = ? AND ((start_address <= ? AND end_address >= ?) OR to_address BETWEEN ? AND ?) ORDER BY start_address, entity, to_address, kind`,
+    )
+    .all(space, range.end, range.start, range.start, range.end)
+    .map((row) => toSuppression(row as Raw));
+}
+
+/** Current modules that start in the range, in address order. */
+export function listModules(db: DatabaseSync | undefined, range: Range = ALL, origins?: OriginFilter, space: Space = DEFAULT_SPACE): ModuleRow[] {
+  if (db === undefined) return [];
+  return db
+    .prepare(`SELECT ${MODULE_COLUMNS} FROM current_modules WHERE space = ? AND start_address BETWEEN ? AND ? ORDER BY start_address`)
+    .all(space, range.start, range.end)
+    .map((row) => toModule(row as Raw))
+    .filter(kept(origins));
+}
+
+/** The spaces that hold current knowledge, the C64 first. */
+export function listSpaces(db: DatabaseSync | undefined): Space[] {
+  if (db === undefined) return [];
+  const rows = db
+    .prepare(
+      `SELECT space FROM current_symbols UNION SELECT space FROM current_regions UNION SELECT space FROM current_comments UNION SELECT space FROM current_references UNION SELECT space FROM current_suppressions UNION SELECT space FROM current_modules`,
+    )
+    .all() as Array<{ space: Space }>;
+  const order = (space: Space) => (space === "c64" ? -2 : space === "drive8" ? -1 : Number(space.slice(4)));
+  return rows.map((row) => row.space).sort((a, b) => order(a) - order(b));
 }
 
-/** 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[] } {
+/** Case-insensitive text search in current symbol names and comment texts of one space. */
+export function search(db: DatabaseSync | undefined, text: string, limit = 50, origins?: OriginFilter, space: Space = DEFAULT_SPACE): { symbols: SymbolRow[]; comments: CommentRow[] } {
   if (db === undefined || text.length === 0) return { symbols: [], comments: [] };
   const pattern = `%${text.replace(/[\\%_]/g, (character) => `\\${character}`)}%`;
+  const only = origins === undefined ? "" : ` AND origin IN (${origins.map(() => "?").join(", ")})`;
+  const values = origins ?? [];
   const symbols = db
-    .prepare(`SELECT ${SYMBOL_COLUMNS} FROM current_symbols WHERE name LIKE ? ESCAPE '\\' ORDER BY address LIMIT ?`)
-    .all(pattern, limit)
+    .prepare(`SELECT ${SYMBOL_COLUMNS} FROM current_symbols WHERE space = ? AND name LIKE ? ESCAPE '\\'${only} ORDER BY address LIMIT ?`)
+    .all(space, pattern, ...values, 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)
+    .prepare(`SELECT ${COMMENT_COLUMNS} FROM current_comments WHERE space = ? AND text LIKE ? ESCAPE '\\'${only} ORDER BY address, placement LIMIT ?`)
+    .all(space, pattern, ...values, limit)
     .map((row) => toComment(row as Raw));
   return { symbols, comments };
 }

package/src/knowledge/schema.ts

@@ -5,20 +5,60 @@ 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;
+/** heuristic: 6502 idioms that the static analysis finds by pattern (D44); an analyzer origin. */
+export const ORIGINS = ["user", "llm", "dxa", "ghidra", "heuristic"] 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 const REGION_TYPES = [
+  "code",
+  "bytes",
+  "words",
+  "addresses",
+  "addresses-split",
+  "rts-addresses",
+  "rts-addresses-split",
+  "jumps",
+  "petscii",
+  "screen",
+  "bitmap",
+  "sprite",
+  "workspace",
+  "unused",
+  "dual-use",
+] as const;
 export type RegionType = (typeof REGION_TYPES)[number];
+/** Region types that are code: a JMP table is code too. dual-use is neither code nor data (D42). */
+export const CODE_REGION_TYPES: readonly RegionType[] = ["code", "jumps"];
+/** Region types that take no element size: their elements are instructions. */
+export const NO_ELEMENT_TYPES: readonly RegionType[] = ["code", "jumps"];
+export const MAX_ELEMENT = 256;
+/** What a revision can name as its evidence (D42): a coverage run, a test, any project file, or a note. */
+export const EVIDENCE_KINDS = ["coverage", "test", "file", "note"] as const;
+export type EvidenceKind = (typeof EVIDENCE_KINDS)[number];
 export const COMMENT_PLACEMENTS = ["line", "side"] as const;
 export type CommentPlacement = (typeof COMMENT_PLACEMENTS)[number];
 export { REFERENCE_KINDS, type ReferenceKind };
+/** What a suppression blocks: a symbol address, a region range or one reference (D36). */
+export const SUPPRESSION_ENTITIES = ["symbol", "region", "reference"] as const;
+export type SuppressionEntity = (typeof SUPPRESSION_ENTITIES)[number];
+
+/** A module file of the generated source (D48): a plain name that ends in .asm, no directory. */
+export const MODULE_FILE = /^[A-Za-z0-9_][A-Za-z0-9_-]{0,59}\.asm$/;
+
+/**
+ * The address space of a knowledge row (D53): the C64, the 1541 drive, or a
+ * cartridge bank. Drive code and banks reuse C64 addresses.
+ */
+export const SPACE = /^(c64|drive8|bank(0|[1-9][0-9]?|1[0-9]{2}|2[0-4][0-9]|25[0-5]))$/;
+export type Space = string;
+export const DEFAULT_SPACE: Space = "c64";
+const SPACE_CHECK = "space IN ('c64', 'drive8') OR space GLOB 'bank[0-9]' OR space GLOB 'bank[1-9][0-9]' OR space GLOB 'bank[12][0-9][0-9]'";
 
 const list = (values: readonly string[]) => values.map((value) => `'${value}'`).join(", ");
 
 /** The schema version this build reads and writes. */
-export const SCHEMA_VERSION = 1;
+export const SCHEMA_VERSION = 6;
 
 /**
  * Creates the schema in an empty database. Knowledge rows are temporal: a
@@ -42,6 +82,7 @@ function createSchema(db: DatabaseSync): void {
       );
       CREATE TABLE symbols (
         id                  INTEGER PRIMARY KEY,
+        space               TEXT NOT NULL DEFAULT 'c64' CHECK (${SPACE_CHECK}),
         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)})),
@@ -49,21 +90,32 @@ function createSchema(db: DatabaseSync): void {
         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 UNIQUE INDEX symbols_current_address ON symbols (space, address) WHERE valid_to_revision IS NULL;
+      CREATE UNIQUE INDEX symbols_current_name ON symbols (space, name) WHERE valid_to_revision IS NULL;
+      CREATE INDEX symbols_address ON symbols (space, address);
       CREATE TABLE regions (
         id                  INTEGER PRIMARY KEY,
+        space               TEXT NOT NULL DEFAULT 'c64' CHECK (${SPACE_CHECK}),
         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)})),
+        element             INTEGER CHECK (element BETWEEN 1 AND ${MAX_ELEMENT}),
         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 INDEX regions_start ON regions (space, start_address);
+      CREATE TABLE evidence (
+        id       INTEGER PRIMARY KEY,
+        revision INTEGER NOT NULL REFERENCES revisions (id),
+        kind     TEXT NOT NULL CHECK (kind IN (${list(EVIDENCE_KINDS)})),
+        ref      TEXT NOT NULL CHECK (length(ref) > 0),
+        sha256   TEXT CHECK (sha256 IS NULL OR length(sha256) = 64)
+      );
+      CREATE INDEX evidence_revision ON evidence (revision);
       CREATE TABLE comments (
         id                  INTEGER PRIMARY KEY,
+        space               TEXT NOT NULL DEFAULT 'c64' CHECK (${SPACE_CHECK}),
         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),
@@ -71,10 +123,11 @@ function createSchema(db: DatabaseSync): void {
         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 UNIQUE INDEX comments_current ON comments (space, address, placement) WHERE valid_to_revision IS NULL;
+      CREATE INDEX comments_address ON comments (space, address);
       CREATE TABLE "references" (
         id                  INTEGER PRIMARY KEY,
+        space               TEXT NOT NULL DEFAULT 'c64' CHECK (${SPACE_CHECK}),
         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)})),
@@ -82,13 +135,42 @@ function createSchema(db: DatabaseSync): void {
         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 UNIQUE INDEX references_current ON "references" (space, from_address, to_address, kind) WHERE valid_to_revision IS NULL;
+      CREATE INDEX references_from ON "references" (space, from_address);
+      CREATE INDEX references_to ON "references" (space, to_address);
+      CREATE TABLE suppressions (
+        id                  INTEGER PRIMARY KEY,
+        space               TEXT NOT NULL DEFAULT 'c64' CHECK (${SPACE_CHECK}),
+        entity              TEXT NOT NULL CHECK (entity IN (${list(SUPPRESSION_ENTITIES)})),
+        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),
+        to_address          INTEGER CHECK (to_address BETWEEN 0 AND 65535),
+        kind                TEXT CHECK (kind IN (${list(REFERENCE_KINDS)})),
+        origin              TEXT NOT NULL CHECK (origin IN ('user', 'llm')),
+        valid_from_revision INTEGER NOT NULL REFERENCES revisions (id),
+        valid_to_revision   INTEGER REFERENCES revisions (id),
+        CHECK ((entity = 'reference') = (to_address IS NOT NULL AND kind IS NOT NULL)),
+        CHECK (entity = 'region' OR start_address = end_address)
+      );
+      CREATE INDEX suppressions_start ON suppressions (space, start_address);
+      CREATE TABLE modules (
+        id                  INTEGER PRIMARY KEY,
+        space               TEXT NOT NULL DEFAULT 'c64' CHECK (${SPACE_CHECK}),
+        start_address       INTEGER NOT NULL CHECK (start_address BETWEEN 0 AND 65535),
+        file                TEXT NOT NULL CHECK (length(file) > 0),
+        title               TEXT CHECK (title IS NULL OR length(title) > 0),
+        origin              TEXT NOT NULL CHECK (origin IN ('user', 'llm')),
+        valid_from_revision INTEGER NOT NULL REFERENCES revisions (id),
+        valid_to_revision   INTEGER REFERENCES revisions (id)
+      );
+      CREATE UNIQUE INDEX modules_current_start ON modules (space, start_address) WHERE valid_to_revision IS NULL;
+      CREATE UNIQUE INDEX modules_current_file ON modules (space, file) WHERE valid_to_revision IS NULL;
       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;
+      CREATE VIEW current_suppressions AS SELECT * FROM suppressions WHERE valid_to_revision IS NULL;
+      CREATE VIEW current_modules AS SELECT * FROM modules WHERE valid_to_revision IS NULL;
       INSERT INTO meta (key, value) VALUES ('current_revision', '0');
     `);
 }