@henols/c64-re-tools 2.1.0-rc.1 → 2.1.0

package/src/knowledge/expression.ts

@@ -6,10 +6,7 @@
 // << >> >>>, unary < and >, &, XOR, |. A unary < or > takes everything of a
 // higher priority after it, so <a+1 is the low byte of a+1.
 
-/** An expression that does not parse, or that names a symbol with no value. */
-export class ExpressionError extends Error {
-  override name = "ExpressionError";
-}
+import { Refusal } from "../errors.ts";
 
 /** The selectors of an operand expression: a byte of a symbol, its value, or free expression text. */
 export const OPERAND_SELECTS = ["lo", "hi", "value", "expr"] as const;
@@ -54,7 +51,7 @@ function tokenize(text: string): Token[] {
     }
     const number: RegExpExecArray | null = operandNext ? /^(\$[0-9A-Fa-f]+|%[01]+|[0-9]+)/.exec(rest) : null;
     const match: RegExpExecArray | null = number ?? /^(>>>|<<|>>|XOR\b)/.exec(rest) ?? NAME.exec(rest) ?? /^[-+*/%&|!<>()]/.exec(rest);
-    if (!match) throw new ExpressionError(`"${text}" has an unknown character at position ${at + 1}: "${rest[0]}".`);
+    if (!match) throw new Refusal("invalid-input", `"${text}" has an unknown character at position ${at + 1}: "${rest[0]}".`);
     const token: string = match[0];
     tokens.push({ text: token, at });
     at += token.length;
@@ -65,13 +62,13 @@ function tokenize(text: string): Token[] {
 }
 
 function parse(text: string): Node {
-  if (text.trim().length === 0) throw new ExpressionError("An expression is empty.");
-  if (text.length > MAX_TEXT) throw new ExpressionError(`An expression has at most ${MAX_TEXT} characters.`);
+  if (text.trim().length === 0) throw new Refusal("invalid-input", "An expression is empty.");
+  if (text.length > MAX_TEXT) throw new Refusal("invalid-input", `An expression has at most ${MAX_TEXT} characters.`);
   const tokens = tokenize(text);
   let index = 0;
   const peek = () => tokens[index]?.text;
   const fail = (what: string): never => {
-    throw new ExpressionError(`"${text}" ${what}.`);
+    throw new Refusal("invalid-input", `"${text}" ${what}.`);
   };
 
   const operand = (): Node => {
@@ -122,7 +119,7 @@ function value(node: Node, resolve: (name: string) => number | undefined): numbe
       return node.value;
     case "name": {
       const found = resolve(node.name);
-      if (found === undefined) throw new ExpressionError(`"${node.name}" is no symbol of the knowledge and no platform name.`);
+      if (found === undefined) throw new Refusal("invalid-input", `"${node.name}" is no symbol of the knowledge and no platform name.`);
       return found;
     }
     case "unary": {
@@ -139,7 +136,7 @@ function value(node: Node, resolve: (name: string) => number | undefined): numbe
           return left * right;
         case "/":
         case "%":
-          if (right === 0) throw new ExpressionError("An expression divides by zero.");
+          if (right === 0) throw new Refusal("invalid-input", "An expression divides by zero.");
           return node.operator === "/" ? Math.trunc(left / right) : left % right;
         case "+":
           return left + right;
@@ -162,7 +159,7 @@ function value(node: Node, resolve: (name: string) => number | undefined): numbe
   }
 }
 
-/** Throws ExpressionError when the text is no expression of this syntax. */
+/** Throws an invalid-input Refusal when the text is no expression of this syntax. */
 export function checkExpression(text: string): void {
   parse(text);
 }

package/src/knowledge/history.ts

@@ -3,7 +3,7 @@
 
 import type { DatabaseSync } from "node:sqlite";
 
-import { KnowledgeError } from "./database.ts";
+import { Refusal } from "../errors.ts";
 import {
   COMMENT_COLUMNS,
   MACRO_COLUMNS,
@@ -182,7 +182,7 @@ export interface RevisionChanges {
 export function revision(db: DatabaseSync | undefined, text: string): RevisionChanges {
   const id = resolveRevision(db, text);
   const raw = db?.prepare("SELECT * FROM revisions WHERE id = ?").get(id) as Raw | undefined;
-  if (db === undefined || raw === undefined) throw new KnowledgeError("not-found", `There is no revision ${id}.`);
+  if (db === undefined || raw === undefined) throw new Refusal("not-found", `There is no revision ${id}.`);
   const tables = [
     ["symbol", "symbols", SYMBOL_COLUMNS, toSymbol],
     ["analyzer-name", "analyzer_names", SYMBOL_COLUMNS, toSymbol],

package/src/knowledge/import.ts

@@ -13,7 +13,9 @@
 import { createHash } from "node:crypto";
 import type { DatabaseSync } from "node:sqlite";
 
-import { KnowledgeError, transaction } from "./database.ts";
+import { type AddressRange, formatC64Address } from "../c64.ts";
+import { Refusal } from "../errors.ts";
+import { transaction } from "./database.ts";
 import {
   analyzerNamed,
   REFERENCE_COLUMNS,
@@ -28,13 +30,10 @@ import {
   type RegionRow,
   type SymbolRow,
 } from "./read.ts";
-import { CODE_REGION_TYPES, DEFAULT_SPACE, POINTER_KIND, REFERENCE_KINDS, REGION_TYPES, SYMBOL_KINDS, type Origin, type ReferenceKind, type RegionType, type Space, type SymbolKind } from "./schema.ts";
-import { Change, checkAddress, checkSpace, hex, subtract, SYMBOL_NAME, type AddressRange, type Evidence } from "./write.ts";
+import { ANALYZERS, CODE_REGION_TYPES, DEFAULT_SPACE, POINTER_KIND, REFERENCE_KINDS, REGION_TYPES, SYMBOL_KINDS, type Analyzer, type Origin, type ReferenceKind, type RegionType, type Space, type SymbolKind } from "./schema.ts";
+import { Change, checkAddress, checkSpace, subtract, SYMBOL_NAME, type Evidence } from "./write.ts";
 
-export type { AddressRange };
 
-export const ANALYZERS = ["dxa", "ghidra", "heuristic"] as const satisfies readonly Origin[];
-export type Analyzer = (typeof ANALYZERS)[number];
 
 export interface NormalizedFindings {
   analyzer: Analyzer;
@@ -106,7 +105,7 @@ const isCode = (value: SymbolKind | RegionType) => value === "label" || value ==
 const counts = (): ImportCounts => ({ added: 0, changed: 0, retired: 0, unchanged: 0, suppressed: 0 });
 
 function invalid(message: string): never {
-  throw new KnowledgeError("invalid-input", `The analyzer result is not usable: ${message} Nothing was imported.`);
+  throw new Refusal("invalid-input", `The analyzer result is not usable: ${message} Nothing was imported.`);
 }
 
 /** Sorted, merged coverage ranges. */
@@ -133,7 +132,7 @@ export function validateFindings(findings: NormalizedFindings): AddressRange[] {
   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.`);
+    if (range.end < range.start) invalid(`coverage ${formatC64Address(range.start)}-${formatC64Address(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);
@@ -142,10 +141,10 @@ export function validateFindings(findings: NormalizedFindings): AddressRange[] {
   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 (!covering(symbol.address, symbol.address)) invalid(`the symbol at ${formatC64Address(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 (addresses.has(symbol.address)) invalid(`two symbols are at ${formatC64Address(symbol.address)}.`);
     if (names.has(symbol.name)) invalid(`the name ${symbol.name} is at two addresses.`);
     addresses.add(symbol.address);
     names.add(symbol.name);
@@ -154,16 +153,16 @@ export function validateFindings(findings: NormalizedFindings): AddressRange[] {
   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.end < region.start) invalid(`the region ${formatC64Address(region.start)}-${formatC64Address(region.end)} ends before it starts.`);
+    if (!covering(region.start, region.end)) invalid(`the region ${formatC64Address(region.start)}-${formatC64Address(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.`);
+    if (previous !== undefined && region.start <= previous.end) invalid(`the regions at ${formatC64Address(previous.start)} and ${formatC64Address(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 (!covering(reference.from, reference.from)) invalid(`the reference from ${formatC64Address(reference.from)} is outside the coverage.`);
     if (!(REFERENCE_KINDS as readonly string[]).includes(reference.kind)) invalid(`the reference kind ${reference.kind} is not known.`);
     if (reference.kind === POINTER_KIND) invalid(`only an operand expression writes a pointer reference, not an analyzer.`);
   }

package/src/knowledge/names.ts

@@ -0,0 +1,50 @@
+// Names as addresses: the one place where a name in a command line, a step
+// or a scenario becomes an address. A symbol comes first. An analyzer name
+// counts when no symbol has the name and the analyzers that give it give it
+// to one address.
+
+import type { DatabaseSync } from "node:sqlite";
+
+import { c64AddressOf, formatC64Address } from "../c64.ts";
+import { Refusal } from "../errors.ts";
+import { openForRead } from "./database.ts";
+import { analyzerNamed, listAnalyzerNames, listSymbols, symbolNamed } from "./read.ts";
+import { DEFAULT_SPACE, type Space, type SymbolKind } from "./schema.ts";
+
+/** The address of a name in a space. Refuses a name that no symbol and no analyzer has, and an analyzer name at two addresses. */
+export function addressOfName(db: DatabaseSync | undefined, name: string, space: Space = DEFAULT_SPACE): number {
+  const symbol = symbolNamed(db, name, space);
+  if (symbol !== undefined) return symbol.address;
+  const rows = analyzerNamed(db, name, space);
+  const addresses = [...new Set(rows.map((row) => row.address))];
+  if (addresses.length === 1) return addresses[0]!;
+  const where = space === DEFAULT_SPACE ? "" : ` in ${space}`;
+  if (addresses.length > 1) throw new Refusal("invalid-input", `the analyzers give ${name} to ${rows.map((row) => `${formatC64Address(row.address)} (${row.origin})`).join(" and ")}${where}. Give the address`);
+  throw new Refusal("not-found", `no symbol or analyzer name${where} is ${name}`);
+}
+
+/** Every name of a space with its address: the symbols, and each analyzer name that addressOfName accepts. With kinds, only names of those kinds. */
+export function nameTable(db: DatabaseSync | undefined, space: Space = DEFAULT_SPACE, kinds?: readonly SymbolKind[]): Map<string, number> {
+  const fits = (row: { kind: SymbolKind }) => kinds === undefined || kinds.includes(row.kind);
+  const names = new Map<string, number>();
+  for (const symbol of listSymbols(db, undefined, undefined, undefined, space)) if (fits(symbol)) names.set(symbol.name, symbol.address);
+  const analyzer = new Map<string, Set<number>>();
+  for (const row of listAnalyzerNames(db, undefined, undefined, undefined, space)) if (fits(row)) analyzer.set(row.name, (analyzer.get(row.name) ?? new Set()).add(row.address));
+  for (const [name, addresses] of analyzer) if (!names.has(name) && addresses.size === 1) names.set(name, [...addresses][0]!);
+  return names;
+}
+
+/** addressOfName on the knowledge of the project: the name resolver of the scripts. */
+export function knowledgeNames(name: string, space: string): number {
+  const db = openForRead();
+  try {
+    return addressOfName(db, name, space);
+  } finally {
+    db?.close();
+  }
+}
+
+/** An address of a step or a file: $ and 1 to 4 hex digits, else a name of the knowledge in the space. */
+export function knowledgeAt(space: Space = DEFAULT_SPACE): (location: string) => number {
+  return (location) => c64AddressOf(location) ?? knowledgeNames(location, space);
+}

package/src/knowledge/program.ts

@@ -6,10 +6,11 @@
 import { createHash } from "node:crypto";
 import type { DatabaseSync } from "node:sqlite";
 
-import { COVERAGE } from "../c64.ts";
-import { KnowledgeError } from "./database.ts";
+import { Refusal } from "../errors.ts";
+import { type AddressRange, COVERAGE, formatC64Address } from "../c64.ts";
+
 import { COVERAGE_KINDS, DEFAULT_SPACE, MEMORY_ROW, type CoverageKind, type Space } from "./schema.ts";
-import { checkSpace, hex, write, type AddressRange, type Evidence, type WriteContext } from "./write.ts";
+import { checkSpace, write, type Evidence, type WriteContext } from "./write.ts";
 
 /** The 64 KiB of one space: offset n is address n. */
 const SIZE = 0x10000;
@@ -84,13 +85,13 @@ function memoryRows(segments: readonly AddressRange[], byteAt: (address: number)
 }
 
 function checkSegments(segments: readonly AddressRange[]): void {
-  if (segments.length === 0) throw new KnowledgeError("invalid-input", "An image has at least one segment.");
+  if (segments.length === 0) throw new Refusal("invalid-input", "An image has at least one segment.");
   const sorted = [...segments].sort((a, b) => a.start - b.start);
   sorted.forEach((segment, index) => {
     if (!Number.isInteger(segment.start) || !Number.isInteger(segment.end) || segment.start < 0 || segment.end > 0xffff || segment.end < segment.start) {
-      throw new KnowledgeError("invalid-input", `The segment ${hex(segment.start)}-${hex(segment.end)} is not a range from $0000 to $ffff.`);
+      throw new Refusal("invalid-input", `The segment ${formatC64Address(segment.start)}-${formatC64Address(segment.end)} is not a range from $0000 to $ffff.`);
     }
-    if (index > 0 && segment.start <= sorted[index - 1]!.end) throw new KnowledgeError("invalid-input", `The segments at ${hex(sorted[index - 1]!.start)} and ${hex(segment.start)} overlap.`);
+    if (index > 0 && segment.start <= sorted[index - 1]!.end) throw new Refusal("invalid-input", `The segments at ${formatC64Address(sorted[index - 1]!.start)} and ${formatC64Address(segment.start)} overlap.`);
   });
 }
 
@@ -102,8 +103,8 @@ function checkSegments(segments: readonly AddressRange[]): void {
 export function setImage(db: DatabaseSync, context: WriteContext, request: ImageRequest): { revision: string | null; current: { space: Space; bytes: number; rowsAdded: number; rowsClosed: number; entry: boolean } } {
   checkSpace(request);
   checkSegments(request.segments);
-  if (request.entry !== undefined && (!Number.isInteger(request.entry) || request.entry < 0 || request.entry > 0xffff)) throw new KnowledgeError("invalid-input", "The entry must be from $0000 to $ffff.");
-  if (request.entry === undefined && (request.state !== undefined || request.stages !== undefined)) throw new KnowledgeError("invalid-input", "A machine state or stages need an entry.");
+  if (request.entry !== undefined && (!Number.isInteger(request.entry) || request.entry < 0 || request.entry > 0xffff)) throw new Refusal("invalid-input", "The entry must be from $0000 to $ffff.");
+  if (request.entry === undefined && (request.state !== undefined || request.stages !== undefined)) throw new Refusal("invalid-input", "A machine state or stages need an entry.");
   const space = request.space ?? DEFAULT_SPACE;
   const wanted = memoryRows(request.segments, request.byteAt);
   return write(db, context, "image", (change) => {
@@ -177,7 +178,7 @@ export function addCoverage(
   checkSpace(request);
   const space = request.space ?? DEFAULT_SPACE;
   for (const map of request.maps) {
-    if (map.bytes.length !== SIZE) throw new KnowledgeError("invalid-input", `${map.name} has ${map.bytes.length} bytes; a coverage map has 65536, one for each address.`);
+    if (map.bytes.length !== SIZE) throw new Refusal("invalid-input", `${map.name} has ${map.bytes.length} bytes; a coverage map has 65536, one for each address.`);
   }
   const hashed = request.maps.map((map) => ({ ...map, sha256: createHash("sha256").update(map.bytes).digest("hex") }));
   const known = new Set(coverageRuns(db).filter((run) => run.space === space).map((run) => `${run.name}\n${run.sha256}`));
@@ -235,7 +236,7 @@ export function requireProgram(db: DatabaseSync | undefined, space: Space = DEFA
   if (image !== undefined) return image;
   const where = space === DEFAULT_SPACE ? "" : ` in ${space}`;
   const option = space === DEFAULT_SPACE ? "" : ` --space ${space}`;
-  throw new KnowledgeError("not-found", `The knowledge has no program${where}. Put it in with knowledge.ts image <image.json|prg>${option} of the c64-knowledge skill.`);
+  throw new Refusal("not-found", `The knowledge has no program${where}. Put it in with knowledge.ts image <image.json|prg>${option} of the c64-knowledge skill.`);
 }
 
 /** The bytes for an analyzer: a PRG for one segment without an entry state, else the 64 KiB. */

package/src/knowledge/read.ts

@@ -4,7 +4,8 @@
 
 import type { DatabaseSync } from "node:sqlite";
 
-import { KnowledgeError } from "./database.ts";
+import type { AddressRange } from "../c64.ts";
+import { Refusal } from "../errors.ts";
 import { DEFAULT_SPACE, type CommentPlacement, type OperandSelect, type Origin, type ReferenceKind, type RegionType, type Space, type SuppressionEntity, type SymbolKind } from "./schema.ts";
 import { NO_REVISION } from "./text.ts";
 
@@ -251,12 +252,12 @@ const NAMED_REVISIONS = 5;
  */
 export function resolveRevision(db: DatabaseSync | undefined, text: string): string {
   if (text === NO_REVISION) return NO_REVISION;
-  if (!/^[0-9a-zT.-]+$/.test(text)) throw new KnowledgeError("invalid-input", `${JSON.stringify(text)} is not a revision id. A revision id looks like 20261015T214501.123-k3f9qz; its start is enough when only one revision has it.`);
+  if (!/^[0-9a-zT.-]+$/.test(text)) throw new Refusal("invalid-input", `${JSON.stringify(text)} is not a revision id. A revision id looks like 20261015T214501.123-k3f9qz; its start is enough when only one revision has it.`);
   const found = (db?.prepare("SELECT id FROM revisions WHERE substr(id, 1, ?) = ? ORDER BY id LIMIT ?").all(text.length, text, NAMED_REVISIONS + 1) ?? []) as Array<{ id: string }>;
-  if (found.length === 0) throw new KnowledgeError("not-found", `There is no revision ${text}.`);
+  if (found.length === 0) throw new Refusal("not-found", `There is no revision ${text}.`);
   if (found.length > 1) {
     const named = found.slice(0, NAMED_REVISIONS).map((row) => row.id).join(", ");
-    throw new KnowledgeError("invalid-input", `${text} is the start of more than one revision: ${named}${found.length > NAMED_REVISIONS ? ", ..." : ""}. Give more of the id.`);
+    throw new Refusal("invalid-input", `${text} is the start of more than one revision: ${named}${found.length > NAMED_REVISIONS ? ", ..." : ""}. Give more of the id.`);
   }
   return found[0]!.id;
 }
@@ -288,7 +289,7 @@ export const ANALYZER_NAME_ORDER: readonly Origin[] = ["heuristic", "ghidra", "d
 const byAnalyzer = (a: SymbolRow, b: SymbolRow) => a.address - b.address || ANALYZER_NAME_ORDER.indexOf(a.origin) - ANALYZER_NAME_ORDER.indexOf(b.origin);
 
 /** Current analyzer names in a range, in address order and then heuristic, Ghidra, DXA. */
-export function listAnalyzerNames(db: DatabaseSync | undefined, range: Range = ALL, kind?: SymbolKind, origins?: OriginFilter, space: Space = DEFAULT_SPACE): SymbolRow[] {
+export function listAnalyzerNames(db: DatabaseSync | undefined, range: AddressRange = ALL, kind?: SymbolKind, origins?: OriginFilter, space: Space = DEFAULT_SPACE): SymbolRow[] {
   if (db === undefined) return [];
   return (db.prepare(`SELECT ${SYMBOL_COLUMNS} FROM current_analyzer_names WHERE space = ? AND address BETWEEN ? AND ?`).all(space, range.start, range.end) as Raw[])
     .map(toSymbol)
@@ -442,19 +443,13 @@ export function at(db: DatabaseSync | undefined, address: number, space: Space =
   return result;
 }
 
-export interface Range {
-  start: number;
-  end: number;
-}
-
-const ALL: Range = { start: 0x0000, end: 0xffff };
+const ALL: AddressRange = { start: 0x0000, end: 0xffff };
 
 /** Rows of these origins only; undefined keeps every origin. */
 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[] {
+export function listSymbols(db: DatabaseSync | undefined, range: AddressRange = ALL, kind?: SymbolKind, origins?: OriginFilter, space: Space = DEFAULT_SPACE): SymbolRow[] {
   if (db === undefined) return [];
   const rows =
     kind === undefined
@@ -463,11 +458,11 @@ export function listSymbols(db: DatabaseSync | undefined, range: Range = ALL, ki
   return rows.map((row) => toSymbol(row as Raw)).filter(kept(origins));
 }
 
-export function listRegions(db: DatabaseSync | undefined, range: Range = ALL, type?: RegionType, origins?: OriginFilter, space: Space = DEFAULT_SPACE): RegionRow[] {
+export function listRegions(db: DatabaseSync | undefined, range: AddressRange = 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, origins?: OriginFilter, space: Space = DEFAULT_SPACE): CommentRow[] {
+export function listComments(db: DatabaseSync | undefined, range: AddressRange = ALL, origins?: OriginFilter, space: Space = DEFAULT_SPACE): CommentRow[] {
   if (db === undefined) return [];
   return db
     .prepare(`SELECT ${COMMENT_COLUMNS} FROM current_comments WHERE space = ? AND address BETWEEN ? AND ? ORDER BY address, placement`)
@@ -477,7 +472,7 @@ export function listComments(db: DatabaseSync | undefined, range: Range = ALL, o
 }
 
 /** Current references whose source or target lies in the range. */
-export function listReferences(db: DatabaseSync | undefined, range: Range = ALL, kind?: ReferenceKind, origins?: OriginFilter, space: Space = DEFAULT_SPACE): ReferenceRow[] {
+export function listReferences(db: DatabaseSync | undefined, range: AddressRange = ALL, kind?: ReferenceKind, origins?: OriginFilter, space: Space = DEFAULT_SPACE): ReferenceRow[] {
   if (db === undefined) return [];
   return db
     .prepare(
@@ -489,7 +484,7 @@ export function listReferences(db: DatabaseSync | undefined, range: Range = ALL,
 }
 
 /** 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[] {
+export function listSuppressions(db: DatabaseSync | undefined, range: AddressRange = ALL, space: Space = DEFAULT_SPACE): SuppressionRow[] {
   if (db === undefined) return [];
   return db
     .prepare(
@@ -500,7 +495,7 @@ export function listSuppressions(db: DatabaseSync | undefined, range: Range = AL
 }
 
 /** 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[] {
+export function listModules(db: DatabaseSync | undefined, range: AddressRange = 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`)
@@ -510,7 +505,7 @@ export function listModules(db: DatabaseSync | undefined, range: Range = ALL, or
 }
 
 /** Current operand expressions of instructions in the range, in address order. */
-export function listOperands(db: DatabaseSync | undefined, range: Range = ALL, origins?: OriginFilter, space: Space = DEFAULT_SPACE): OperandRow[] {
+export function listOperands(db: DatabaseSync | undefined, range: AddressRange = ALL, origins?: OriginFilter, space: Space = DEFAULT_SPACE): OperandRow[] {
   if (db === undefined) return [];
   return db
     .prepare(`SELECT ${OPERAND_COLUMNS} FROM current_operands WHERE space = ? AND address BETWEEN ? AND ? ORDER BY address`)
@@ -520,7 +515,7 @@ export function listOperands(db: DatabaseSync | undefined, range: Range = ALL, o
 }
 
 /** Current patches that share an address with the range, of one switch or of all, in address order. */
-export function listPatches(db: DatabaseSync | undefined, range: Range = ALL, switchName?: string, origins?: OriginFilter, space: Space = DEFAULT_SPACE): PatchRow[] {
+export function listPatches(db: DatabaseSync | undefined, range: AddressRange = ALL, switchName?: string, origins?: OriginFilter, space: Space = DEFAULT_SPACE): PatchRow[] {
   return patchesOverlapping(db, range.start, range.end, space).filter((patch) => (switchName === undefined || patch.switch === switchName) && kept(origins)(patch));
 }
 
@@ -535,7 +530,7 @@ export function listMacros(db: DatabaseSync | undefined, origins?: OriginFilter,
 }
 
 /** Current macro uses that share an address with the range, of one macro or of all, in address order. */
-export function listMacroUses(db: DatabaseSync | undefined, range: Range = ALL, macro?: string, origins?: OriginFilter, space: Space = DEFAULT_SPACE): MacroUseRow[] {
+export function listMacroUses(db: DatabaseSync | undefined, range: AddressRange = ALL, macro?: string, origins?: OriginFilter, space: Space = DEFAULT_SPACE): MacroUseRow[] {
   return macroUsesOverlapping(db, range.start, range.end, space).filter((use) => (macro === undefined || use.macro === macro) && kept(origins)(use));
 }
 

package/src/knowledge/schema.ts

@@ -10,6 +10,13 @@ import { OPERAND_SELECTS } from "./expression.ts";
 /** heuristic: 6502 idioms that the static analysis finds by pattern; an analyzer origin. */
 export const ORIGINS = ["user", "llm", "dxa", "ghidra", "heuristic"] as const;
 export type Origin = (typeof ORIGINS)[number];
+/** The origins of semantic knowledge: what the user or the LLM decided. It wins over analyzer facts. */
+export const SEMANTIC_ORIGINS = ["user", "llm"] as const satisfies readonly Origin[];
+/** The analyzers: their facts and names give way to semantic knowledge. */
+export const ANALYZERS = ["dxa", "ghidra", "heuristic"] as const satisfies readonly Origin[];
+export type Analyzer = (typeof ANALYZERS)[number];
+export const isSemantic = (origin: string | undefined): boolean => (SEMANTIC_ORIGINS as readonly (string | undefined)[]).includes(origin);
+export const isAnalyzer = (origin: string | undefined): boolean => (ANALYZERS as readonly (string | undefined)[]).includes(origin);
 export const SYMBOL_KINDS = ["label", "routine", "variable", "data", "vector"] as const;
 export type SymbolKind = (typeof SYMBOL_KINDS)[number];
 export const REGION_TYPES = [
@@ -76,10 +83,9 @@ export function isGeneratedFile(file: string): boolean {
 }
 
 /**
- * The address space of a knowledge row: the C64, the 1541 drive, or a
- * cartridge bank. Drive code and banks reuse C64 addresses.
+ * The address space of a knowledge row: a name that SPACE_PATTERN of c64.ts
+ * accepts. 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]'";

package/src/knowledge/text.ts

@@ -10,8 +10,8 @@ import { readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "no
 import type { DatabaseSync } from "node:sqlite";
 import { join } from "node:path";
 
+import { Refusal } from "../errors.ts";
 import { isoCet } from "../time.ts";
-import { KnowledgeError } from "./database.ts";
 
 /** The value of "no revision": empty knowledge. It sorts before every revision id. */
 export const NO_REVISION = "0";
@@ -248,7 +248,7 @@ export function readText(directory: string): Map<string, { text: string; sha256:
   const files = new Map<string, { text: string; sha256: string }>();
   for (const name of readdirSync(directory).sort()) {
     if (!name.endsWith(".jsonl")) continue;
-    if (!known.has(name)) throw new KnowledgeError("invalid-database", `.c64-re-tools/knowledge/${name} is not a knowledge file. Knowledge files are ${[...known].join(", ")}.`);
+    if (!known.has(name)) throw new Refusal("invalid-database", `.c64-re-tools/knowledge/${name} is not a knowledge file. Knowledge files are ${[...known].join(", ")}.`);
     const bytes = readFileSync(join(directory, name));
     files.set(name, { text: bytes.toString("utf8"), sha256: sha256(bytes) });
   }
@@ -269,7 +269,7 @@ export function writeAtomic(path: string, text: string): void {
 
 /** One line of a knowledge file that cannot be read. */
 function bad(file: string, line: number, message: string): never {
-  throw new KnowledgeError("invalid-database", `.c64-re-tools/knowledge/${file}:${line}: ${message}`);
+  throw new Refusal("invalid-database", `.c64-re-tools/knowledge/${file}:${line}: ${message}`);
 }
 
 function parseLines(file: string, text: string): Array<{ line: number; value: Raw }> {
@@ -396,7 +396,7 @@ export function loadText(db: DatabaseSync, files: ReadonlyMap<string, { text: st
       insertRevision.run(...(REVISION_FIELDS.map((item) => revision.columns[item.column]) as Array<string | null>));
       for (const item of revision.evidence) insertEvidence.run(revision.id, item.kind as string, item.ref as string, item.sha256 as string | null, item.space as string | null);
     } catch (error) {
-      throw new KnowledgeError("invalid-database", `.c64-re-tools/knowledge/${REVISIONS_FILE}: the revision ${revision.id} is not valid: ${(error as Error).message}`);
+      throw new Refusal("invalid-database", `.c64-re-tools/knowledge/${REVISIONS_FILE}: the revision ${revision.id} is not valid: ${(error as Error).message}`);
     }
   }
   for (const spec of TABLES) {
@@ -408,7 +408,7 @@ export function loadText(db: DatabaseSync, files: ReadonlyMap<string, { text: st
       try {
         insert.run(...(columns.map((column) => row.columns[column]) as Array<string | number | null>));
       } catch (error) {
-        throw new KnowledgeError("invalid-database", `.c64-re-tools/knowledge/${spec.file}: the row ${row.id} is not valid: ${(error as Error).message}`);
+        throw new Refusal("invalid-database", `.c64-re-tools/knowledge/${spec.file}: the row ${row.id} is not valid: ${(error as Error).message}`);
       }
     }
   }