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

package/src/knowledge/history.ts

@@ -6,42 +6,72 @@ import type { DatabaseSync } from "node:sqlite";
 import { KnowledgeError } from "./database.ts";
 import {
   COMMENT_COLUMNS,
+  MACRO_COLUMNS,
+  MACRO_USE_COLUMNS,
+  MODULE_COLUMNS,
+  OPERAND_COLUMNS,
+  PATCH_COLUMNS,
   REFERENCE_COLUMNS,
   REGION_COLUMNS,
+  resolveRevision,
+  SUPPRESSION_COLUMNS,
   SYMBOL_COLUMNS,
   toComment,
+  toMacro,
+  toMacroUse,
+  toModule,
+  toOperand,
+  toPatch,
   toReference,
   toRegion,
+  toSuppression,
   toSymbol,
   type CommentRow,
+  type MacroRow,
+  type MacroUseRow,
+  type ModuleRow,
+  type OperandRow,
+  type PatchRow,
   type ReferenceRow,
   type RegionRow,
+  type SuppressionRow,
   type SymbolRow,
 } from "./read.ts";
-import type { Origin } from "./schema.ts";
+import { DEFAULT_SPACE, type EvidenceKind, type Origin, type Space } from "./schema.ts";
+import { compareText } from "./text.ts";
+import type { Evidence } from "./write.ts";
 
 export interface Revision {
-  id: number;
+  id: string;
   createdAt: string;
   origin: Origin;
   operation: string;
   description?: string;
   inputHash?: string;
   toolVersion?: string;
+  /** What the change rests on (D42). */
+  evidence?: Evidence[];
 }
 
 /** One knowledge row with its validity: from its first revision until the revision that closed it. */
 export type HistoryEntry =
-  | { entity: "symbol"; row: SymbolRow; from: number; to?: number }
-  | { entity: "region"; row: RegionRow; from: number; to?: number }
-  | { entity: "comment"; row: CommentRow; from: number; to?: number }
-  | { entity: "reference"; row: ReferenceRow; from: number; to?: number };
+  | { entity: "symbol"; row: SymbolRow; from: string; to?: string }
+  | { entity: "analyzer-name"; row: SymbolRow; from: string; to?: string }
+  | { entity: "region"; row: RegionRow; from: string; to?: string }
+  | { entity: "comment"; row: CommentRow; from: string; to?: string }
+  | { entity: "reference"; row: ReferenceRow; from: string; to?: string }
+  | { entity: "suppression"; row: SuppressionRow; from: string; to?: string }
+  | { entity: "module"; row: ModuleRow; from: string; to?: string }
+  | { entity: "operand"; row: OperandRow; from: string; to?: string }
+  | { entity: "patch"; row: PatchRow; from: string; to?: string }
+  | { entity: "macro"; row: MacroRow; from: string; to?: string }
+  | { entity: "macro-use"; row: MacroUseRow; from: string; to?: string };
 
 type Raw = Record<string, unknown>;
 
 function toRevision(row: Raw): Revision {
   const revision: Revision = {
-    id: row.id as number,
+    id: row.id as string,
     createdAt: row.created_at as string,
     origin: row.origin as Origin,
     operation: row.operation as string,
@@ -53,47 +83,86 @@ function toRevision(row: Raw): Revision {
 }
 
 function entry<E extends HistoryEntry["entity"]>(entity: E, row: unknown, raw: Raw): HistoryEntry {
-  const result = { entity, row, from: raw.valid_from_revision as number } as HistoryEntry;
-  if (raw.valid_to_revision !== null) result.to = raw.valid_to_revision as number;
+  const result = { entity, row, from: raw.valid_from_revision as string } as HistoryEntry;
+  if (raw.valid_to_revision !== null) result.to = raw.valid_to_revision as string;
   return result;
 }
 
+/** Revision ids sort in time order as text (D69); a current row sorts after every closed one. */
 function bySequence(a: HistoryEntry, b: HistoryEntry): number {
-  return a.from - b.from || (a.to ?? Infinity) - (b.to ?? Infinity);
+  return compareText(a.from, b.from) || compareText(a.to ?? "~", b.to ?? "~");
 }
 
-/** Every row, current or closed, that concerns one address, oldest first. */
-export function historyAt(db: DatabaseSync | undefined, address: number): HistoryEntry[] {
+/** Every row, current or closed, that concerns one address of a space, oldest first. */
+export function historyAt(db: DatabaseSync | undefined, address: number, space: Space = DEFAULT_SPACE): HistoryEntry[] {
   if (db === undefined) return [];
   const validity = ", valid_to_revision";
   const entries: HistoryEntry[] = [];
-  for (const raw of db.prepare(`SELECT ${SYMBOL_COLUMNS}${validity} FROM symbols WHERE address = ?`).all(address) as Raw[]) entries.push(entry("symbol", toSymbol(raw), raw));
-  for (const raw of db.prepare(`SELECT ${REGION_COLUMNS}${validity} FROM regions WHERE start_address <= ? AND end_address >= ?`).all(address, address) as Raw[]) {
+  for (const raw of db.prepare(`SELECT ${SYMBOL_COLUMNS}${validity} FROM symbols WHERE space = ? AND address = ?`).all(space, address) as Raw[]) entries.push(entry("symbol", toSymbol(raw), raw));
+  for (const raw of db.prepare(`SELECT ${SYMBOL_COLUMNS}${validity} FROM analyzer_names WHERE space = ? AND address = ?`).all(space, address) as Raw[]) entries.push(entry("analyzer-name", toSymbol(raw), raw));
+  for (const raw of db.prepare(`SELECT ${REGION_COLUMNS}${validity} FROM regions WHERE space = ? AND start_address <= ? AND end_address >= ?`).all(space, address, address) as Raw[]) {
     entries.push(entry("region", toRegion(raw), raw));
   }
-  for (const raw of db.prepare(`SELECT ${COMMENT_COLUMNS}${validity} FROM comments WHERE address = ?`).all(address) as Raw[]) entries.push(entry("comment", toComment(raw), raw));
-  for (const raw of db.prepare(`SELECT ${REFERENCE_COLUMNS}${validity} FROM "references" WHERE from_address = ? OR to_address = ?`).all(address, address) as Raw[]) {
+  for (const raw of db.prepare(`SELECT ${COMMENT_COLUMNS}${validity} FROM comments WHERE space = ? AND address = ?`).all(space, address) as Raw[]) entries.push(entry("comment", toComment(raw), raw));
+  for (const raw of db.prepare(`SELECT ${REFERENCE_COLUMNS}${validity} FROM "references" WHERE space = ? AND (from_address = ? OR to_address = ?)`).all(space, address, address) as Raw[]) {
     entries.push(entry("reference", toReference(raw), raw));
   }
+  for (const raw of db
+    .prepare(`SELECT ${SUPPRESSION_COLUMNS}${validity} FROM suppressions WHERE space = ? AND ((start_address <= ? AND end_address >= ?) OR to_address = ?)`)
+    .all(space, address, address, address) as Raw[]) {
+    entries.push(entry("suppression", toSuppression(raw), raw));
+  }
+  for (const raw of db.prepare(`SELECT ${MODULE_COLUMNS}${validity} FROM modules WHERE space = ? AND start_address = ?`).all(space, address) as Raw[]) entries.push(entry("module", toModule(raw), raw));
+  for (const raw of db.prepare(`SELECT ${OPERAND_COLUMNS}${validity} FROM operands WHERE space = ? AND address = ?`).all(space, address) as Raw[]) entries.push(entry("operand", toOperand(raw), raw));
+  for (const raw of db.prepare(`SELECT ${PATCH_COLUMNS}${validity} FROM patches WHERE space = ? AND start_address <= ? AND end_address >= ?`).all(space, address, address) as Raw[]) {
+    entries.push(entry("patch", toPatch(raw), raw));
+  }
+  for (const raw of db.prepare(`SELECT ${MACRO_USE_COLUMNS}${validity} FROM macro_uses WHERE space = ? AND start_address <= ? AND end_address >= ?`).all(space, address, address) as Raw[]) {
+    entries.push(entry("macro-use", toMacroUse(raw), raw));
+  }
   return entries.sort(bySequence);
 }
 
-/** Every symbol row that ever had this name, oldest first: a name can move between addresses. */
-export function historyNamed(db: DatabaseSync | undefined, name: string): HistoryEntry[] {
+/** Every row of a macro with this name, and every use of it, oldest first. */
+export function historyOfMacro(db: DatabaseSync | undefined, name: string, space: Space = DEFAULT_SPACE): HistoryEntry[] {
+  if (db === undefined) return [];
+  const macros = (db.prepare(`SELECT ${MACRO_COLUMNS}, valid_to_revision FROM macros WHERE space = ? AND name = ?`).all(space, name) as Raw[]).map((raw) => entry("macro", toMacro(raw), raw));
+  const uses = (db.prepare(`SELECT ${MACRO_USE_COLUMNS}, valid_to_revision FROM macro_uses WHERE space = ? AND macro = ?`).all(space, name) as Raw[]).map((raw) => entry("macro-use", toMacroUse(raw), raw));
+  return [...macros, ...uses].sort(bySequence);
+}
+
+/** Every symbol row of a space that ever had this name, oldest first: a name can move between addresses. */
+export function historyNamed(db: DatabaseSync | undefined, name: string, space: Space = DEFAULT_SPACE): HistoryEntry[] {
   if (db === undefined) return [];
-  return (db.prepare(`SELECT ${SYMBOL_COLUMNS}, valid_to_revision FROM symbols WHERE name = ?`).all(name) as Raw[])
+  return (db.prepare(`SELECT ${SYMBOL_COLUMNS}, valid_to_revision FROM symbols WHERE space = ? AND name = ?`).all(space, name) as Raw[])
     .map((raw) => entry("symbol", toSymbol(raw), raw))
     .sort(bySequence);
 }
 
+/** Why a revision was written and what it rests on: its description and its evidence, when it has them. */
+export function revisionNote(db: DatabaseSync | undefined, id: string): { reason?: string; evidence?: Evidence[] } {
+  const raw = db?.prepare("SELECT * FROM revisions WHERE id = ?").get(id) as Raw | undefined;
+  if (db === undefined || raw === undefined) return {};
+  const { description, evidence } = withEvidence(db, toRevision(raw));
+  return { ...(description === undefined ? {} : { reason: description }), ...(evidence === undefined ? {} : { evidence }) };
+}
+
+/** The revision with its evidence, when it has any. */
+function withEvidence(db: DatabaseSync, revision: Revision): Revision {
+  const rows = db.prepare("SELECT kind, ref, sha256 FROM evidence WHERE revision = ? ORDER BY id").all(revision.id) as Raw[];
+  if (rows.length === 0) return revision;
+  const evidence = rows.map((row): Evidence => ({ kind: row.kind as EvidenceKind, ref: row.ref as string, ...(row.sha256 === null ? {} : { sha256: row.sha256 as string }) }));
+  return { ...revision, evidence };
+}
+
 /** Revisions, newest first; with `before`, only revisions older than it. */
-export function revisions(db: DatabaseSync | undefined, options: { limit?: number; before?: number } = {}): Revision[] {
+export function revisions(db: DatabaseSync | undefined, options: { limit?: number; before?: string } = {}): Revision[] {
   if (db === undefined) return [];
-  return (
-    db
-      .prepare("SELECT * FROM revisions WHERE id < ? ORDER BY id DESC LIMIT ?")
-      .all(options.before ?? Number.MAX_SAFE_INTEGER, options.limit ?? 50) as Raw[]
-  ).map(toRevision);
+  const rows =
+    options.before === undefined
+      ? db.prepare("SELECT * FROM revisions ORDER BY id DESC LIMIT ?").all(options.limit ?? 50)
+      : db.prepare("SELECT * FROM revisions WHERE id < ? ORDER BY id DESC LIMIT ?").all(resolveRevision(db, options.before), options.limit ?? 50);
+  return (rows as Raw[]).map((row) => withEvidence(db, toRevision(row)));
 }
 
 export interface RevisionChanges {
@@ -105,14 +174,22 @@ export interface RevisionChanges {
 }
 
 /** One revision and exactly what it changed. */
-export function revision(db: DatabaseSync | undefined, id: number): 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}.`);
   const tables = [
     ["symbol", "symbols", SYMBOL_COLUMNS, toSymbol],
+    ["analyzer-name", "analyzer_names", SYMBOL_COLUMNS, toSymbol],
     ["region", "regions", REGION_COLUMNS, toRegion],
     ["comment", "comments", COMMENT_COLUMNS, toComment],
     ["reference", '"references"', REFERENCE_COLUMNS, toReference],
+    ["suppression", "suppressions", SUPPRESSION_COLUMNS, toSuppression],
+    ["module", "modules", MODULE_COLUMNS, toModule],
+    ["operand", "operands", OPERAND_COLUMNS, toOperand],
+    ["patch", "patches", PATCH_COLUMNS, toPatch],
+    ["macro", "macros", MACRO_COLUMNS, toMacro],
+    ["macro-use", "macro_uses", MACRO_USE_COLUMNS, toMacroUse],
   ] as const;
   const added: HistoryEntry[] = [];
   const closed: HistoryEntry[] = [];
@@ -124,5 +201,6 @@ export function revision(db: DatabaseSync | undefined, id: number): RevisionChan
       closed.push(entry(entity, map(row), row));
     }
   }
-  return { revision: toRevision(raw), added, closed };
+  return { revision: withEvidence(db, toRevision(raw)), added, closed };
 }
+

package/src/knowledge/import.ts

@@ -6,37 +6,40 @@
 // 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.
+// name or a finer data type for the same kind of memory is not. One exception
+// (D58): where a run executed an instruction start, a code finding replaces
+// the data of another analyzer, never of the user, the LLM or a heuristic.
 
 import { createHash } from "node:crypto";
 import type { DatabaseSync } from "node:sqlite";
 
 import { KnowledgeError, transaction } from "./database.ts";
 import {
+  analyzerNamed,
   REFERENCE_COLUMNS,
+  referenceSuppressed,
   regionsOverlapping,
+  suppressionsOverlapping,
   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";
+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";
 
-export const ANALYZERS = ["dxa", "ghidra"] as const satisfies readonly Origin[];
-export type Analyzer = (typeof ANALYZERS)[number];
+export type { AddressRange };
 
-export interface AddressRange {
-  start: number;
-  end: number;
-}
+export const ANALYZERS = ["dxa", "ghidra", "heuristic"] as const satisfies readonly Origin[];
+export type Analyzer = (typeof ANALYZERS)[number];
 
 export interface NormalizedFindings {
   analyzer: Analyzer;
+  /** The address space that the analyzed image belongs to (D53); the C64 when absent. */
+  space?: Space;
   /** 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". */
@@ -45,16 +48,20 @@ export interface NormalizedFindings {
   regions: Array<{ start: number; end: number; type: RegionType }>;
   /** Owned and covered by their source address. */
   references: Array<{ from: number; to: number; kind: ReferenceKind }>;
+  /** True for an address where a coverage run executed an instruction start (D58). */
+  executed?: (address: number) => boolean;
 }
 
 export interface ImportContext {
   /** The revision the caller read; the import is refused if knowledge changed since. */
-  expectedRevision?: number;
+  expectedRevision?: string;
   description?: string;
   /** The SHA-256 of the analyzed image, as lowercase hex. */
   inputHash?: string;
   /** The analyzer's own version line. */
   toolVersion?: string;
+  /** What the import rests on besides the image, for example the coverage files. */
+  evidence?: Evidence[];
 }
 
 /** What a revision records about one analyzer run: the hash of the image bytes and, when the analyzer tells it, its version. */
@@ -78,20 +85,25 @@ export interface ImportCounts {
   changed: number;
   retired: number;
   unchanged: number;
+  /** Findings at a place that a user/LLM removal blocks (D36); not written. */
+  suppressed: number;
 }
 
 export interface ImportResult {
   /** The new revision, or null when nothing changed. */
-  revision: number | null;
+  revision: string | null;
+  /** The analyzer names (D74). */
+  names: ImportCounts;
+  /** The analyzer's own rows from before D74 that the run closed in symbols: only `retired` counts. */
   symbols: ImportCounts;
   regions: ImportCounts;
   references: ImportCounts;
   conflicts: ImportConflict[];
 }
 
-const isCode = (value: SymbolKind | RegionType) => value === "label" || value === "routine" || value === "code";
+const isCode = (value: SymbolKind | RegionType) => value === "label" || value === "routine" || (CODE_REGION_TYPES as readonly string[]).includes(value);
 
-const counts = (): ImportCounts => ({ added: 0, changed: 0, retired: 0, unchanged: 0 });
+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.`);
@@ -109,20 +121,6 @@ function mergeCoverage(coverage: AddressRange[]): AddressRange[] {
   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.
@@ -130,6 +128,7 @@ function subtract(range: AddressRange, holes: AddressRange[]): AddressRange[] {
  */
 export function validateFindings(findings: NormalizedFindings): AddressRange[] {
   if (!(ANALYZERS as readonly string[]).includes(findings.analyzer)) invalid(`the analyzer must be one of ${ANALYZERS.join(", ")}.`);
+  checkSpace(findings);
   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");
@@ -166,76 +165,126 @@ export function validateFindings(findings: NormalizedFindings): AddressRange[] {
     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.`);
+    if (reference.kind === POINTER_KIND) invalid(`only an operand expression writes a pointer reference (D65), not an analyzer.`);
   }
   return coverage;
 }
 
-function ownSymbols(db: DatabaseSync, analyzer: Analyzer, range: AddressRange): SymbolRow[] {
+function ownSymbols(db: DatabaseSync, analyzer: Analyzer, range: AddressRange, space: Space): 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)
+    .prepare(`SELECT ${SYMBOL_COLUMNS} FROM current_symbols WHERE space = ? AND origin = ? AND address BETWEEN ? AND ? ORDER BY address`)
+    .all(space, analyzer, range.start, range.end)
     .map((row) => toSymbol(row as Record<string, unknown>));
 }
 
-function ownReferences(db: DatabaseSync, analyzer: Analyzer, range: AddressRange): ReferenceRow[] {
+function ownReferences(db: DatabaseSync, analyzer: Analyzer, range: AddressRange, space: Space): 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)
+    .prepare(`SELECT ${REFERENCE_COLUMNS} FROM current_references WHERE space = ? AND origin = ? AND from_address BETWEEN ? AND ? ORDER BY from_address`)
+    .all(space, 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 {
+function ownNames(db: DatabaseSync, analyzer: Analyzer, range: AddressRange, space: Space): SymbolRow[] {
+  return db
+    .prepare(`SELECT ${SYMBOL_COLUMNS} FROM current_analyzer_names WHERE space = ? AND origin = ? AND address BETWEEN ? AND ? ORDER BY address`)
+    .all(space, analyzer, range.start, range.end)
+    .map((row) => toSymbol(row as Record<string, unknown>));
+}
+
+/**
+ * The names of an analyzer are second names (D74): they go to analyzer_names,
+ * one for each analyzer at an address, and never to symbols. A run replaces
+ * the analyzer's own names in its coverage, and closes the analyzer's old rows
+ * in symbols there (knowledge from before D74). A name that the user or the LLM
+ * gave the address already is not kept twice. A code or data kind that
+ * disagrees with the name of the address is a conflict.
+ */
+function importNames(db: DatabaseSync, change: Change, findings: NormalizedFindings, coverage: AddressRange[], result: ImportResult): void {
   const { analyzer } = findings;
+  const space = findings.space ?? DEFAULT_SPACE;
+  for (const range of coverage) {
+    for (const own of ownSymbols(db, analyzer, range, space)) {
+      change.close("symbols", "space = ? AND address = ? AND origin = ?", space, own.address, analyzer);
+      result.symbols.retired++;
+    }
+  }
   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)) {
+    for (const own of ownNames(db, analyzer, range, space)) {
       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) {
+      // A seeded run gives back the name of the user or the LLM: the analyzer's own name there stays.
+      const echo = finding !== undefined && symbolAt(db, own.address, space)?.name === finding.name;
+      if (echo || (finding !== undefined && 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);
+        result.names.unchanged++;
+        continue;
       }
+      change.close("analyzer_names", "space = ? AND address = ? AND origin = ?", space, own.address, analyzer);
+      if (finding === undefined) result.names.retired++;
+      else replaced.add(own.address);
     }
   }
   for (const finding of findings.symbols) {
+    const current = symbolAt(db, finding.address, space);
+    if (current !== undefined && isCode(current.kind) !== isCode(finding.kind)) {
+      result.conflicts.push({ category: "symbol", address: finding.address, reason: "kind", current, finding: { name: finding.name, kind: finding.kind } });
+    }
     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 } });
-      }
+    if (current?.name === finding.name) {
+      // The analyzer only gives back the name of the address.
+      if (replaced.has(finding.address)) result.names.retired++;
       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;
+    // The analyzer moved its own name from an address outside the coverage.
+    for (const moved of analyzerNamed(db, finding.name, space).filter((row) => row.origin === analyzer)) {
+      change.close("analyzer_names", "space = ? AND address = ? AND origin = ?", space, moved.address, analyzer);
+      result.names.retired++;
     }
-    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++;
+    change.insertAnalyzerName({ space, address: finding.address, name: finding.name, kind: finding.kind, origin: analyzer });
+    if (replaced.has(finding.address)) result.names.changed++;
+    else result.names.added++;
   }
 }
 
+/** Analyzers whose regions a heuristic finding replaces where it lies (D44): user/LLM > heuristic > DXA/Ghidra. */
+const YIELDS_TO_HEURISTIC = new Set<Origin>(["dxa", "ghidra"]);
+/** Analyzers whose data gives way to a code finding over an executed instruction start (D58). */
+const YIELDS_TO_EXECUTED_CODE = new Set<Origin>(["dxa", "ghidra"]);
+
+/** True when an address in the range is an executed instruction start. */
+function holdsExecuted(findings: NormalizedFindings, start: number, end: number): boolean {
+  if (findings.executed === undefined) return false;
+  for (let address = start; address <= end; address++) if (findings.executed(address)) return true;
+  return false;
+}
+
 function importRegions(db: DatabaseSync, change: Change, findings: NormalizedFindings, coverage: AddressRange[], result: ImportResult): void {
   const { analyzer } = findings;
+  const space = findings.space ?? DEFAULT_SPACE;
+  if (analyzer === "heuristic") {
+    // An idiom is specific evidence about its bytes: the DXA or Ghidra region there gives way, its parts outside stay.
+    for (const region of findings.regions) {
+      for (const row of regionsOverlapping(db, region.start, region.end, space).filter((candidate) => YIELDS_TO_HEURISTIC.has(candidate.origin))) {
+        change.close("regions", "space = ? AND start_address = ? AND end_address = ? AND origin = ?", space, row.start, row.end, row.origin);
+        for (const piece of subtract(row, [region])) change.insertRegion({ space, ...piece, type: row.type, ...(row.element === undefined ? {} : { element: row.element }), origin: row.origin });
+      }
+    }
+  }
+  // Executed code is evidence about its bytes (D58): another analyzer's data region under a code finding gives way where a run executed an instruction start.
+  for (const region of findings.regions.filter((candidate) => isCode(candidate.type))) {
+    for (const row of regionsOverlapping(db, region.start, region.end, space)) {
+      if (row.origin === analyzer || !YIELDS_TO_EXECUTED_CODE.has(row.origin) || isCode(row.type) || row.type === "dual-use") continue;
+      if (!holdsExecuted(findings, Math.max(row.start, region.start), Math.min(row.end, region.end))) continue;
+      change.close("regions", "space = ? AND start_address = ? AND end_address = ? AND origin = ?", space, row.start, row.end, row.origin);
+      for (const piece of subtract(row, [region])) change.insertRegion({ space, ...piece, type: row.type, ...(row.element === undefined ? {} : { element: row.element }), origin: row.origin });
+      result.regions.retired++;
+    }
+  }
   const conflictWith = (row: RegionRow, region: { start: number; end: number; type: RegionType }) => {
-    if (isCode(row.type) === isCode(region.type)) return;
+    // dual-use bytes are code at one time and data at another: neither finding contradicts them (D42).
+    if (isCode(row.type) === isCode(region.type) || row.type === "dual-use") return;
     result.conflicts.push({
       category: "region",
       start: Math.max(row.start, region.start),
@@ -249,7 +298,9 @@ function importRegions(db: DatabaseSync, change: Change, findings: NormalizedFin
     // 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 suppressed = suppressionsOverlapping(db, "region", region.start, region.end, space);
+      if (suppressed.length > 0) result.regions.suppressed++;
+      const current = regionsOverlapping(db, region.start, region.end, space);
       const protectedRows = current.filter((row) => row.origin !== analyzer);
       for (const row of protectedRows) conflictWith(row, region);
       const own = current.filter((row) => row.origin === analyzer);
@@ -257,14 +308,14 @@ function importRegions(db: DatabaseSync, change: Change, findings: NormalizedFin
       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 });
+        change.close("regions", "space = ? AND start_address = ? AND end_address = ? AND origin = ?", space, row.start, row.end, analyzer);
+        if (row.start < region.start) change.insertRegion({ space, start: row.start, end: region.start - 1, type: row.type, origin: analyzer });
+        if (row.end > region.end) change.insertRegion({ space, 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 });
+      const empty = subtract(region, [...current, ...suppressed]);
+      for (const piece of subtract(region, [...protectedRows, ...kept, ...suppressed])) {
+        change.insertRegion({ space, ...piece, type: region.type, origin: analyzer });
       }
       result.regions.added += empty.length;
     }
@@ -272,14 +323,16 @@ function importRegions(db: DatabaseSync, change: Change, findings: NormalizedFin
   }
 
   for (const range of coverage) {
-    const current = regionsOverlapping(db, range.start, range.end);
+    const current = regionsOverlapping(db, range.start, range.end, space);
     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 suppressed = suppressionsOverlapping(db, "region", region.start, region.end, space);
+      if (suppressed.length > 0) result.regions.suppressed++;
+      for (const piece of subtract(region, [...protectedRows, ...suppressed])) desired.set(`${piece.start}-${piece.end}`, { ...piece, type: region.type });
     }
     const retiredRanges = new Set<string>();
     for (const row of own) {
@@ -291,13 +344,13 @@ function importRegions(db: DatabaseSync, change: Change, findings: NormalizedFin
         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 });
+      change.close("regions", "space = ? AND start_address = ? AND end_address = ? AND origin = ?", space, row.start, row.end, analyzer);
+      if (row.start < range.start) change.insertRegion({ space, start: row.start, end: range.start - 1, type: row.type, origin: analyzer });
+      if (row.end > range.end) change.insertRegion({ space, 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 });
+      change.insertRegion({ space, ...piece, origin: analyzer });
       if (retiredRanges.delete(key)) result.regions.changed++;
       else result.regions.added++;
     }
@@ -307,23 +360,25 @@ function importRegions(db: DatabaseSync, change: Change, findings: NormalizedFin
 
 function importReferences(db: DatabaseSync, change: Change, findings: NormalizedFindings, coverage: AddressRange[], result: ImportResult): void {
   const { analyzer } = findings;
+  const space = findings.space ?? DEFAULT_SPACE;
   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)) {
+    for (const own of ownReferences(db, analyzer, range, space)) {
       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);
+      change.close('"references"', "space = ? AND from_address = ? AND to_address = ? AND kind = ? AND origin = ?", space, 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 = ?');
+  const existing = db.prepare("SELECT origin FROM current_references WHERE space = ? AND 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 }>;
+    const rows = existing.all(space, reference.from, reference.to, reference.kind) as Array<{ origin: Origin }>;
     if (rows.some((row) => row.origin === analyzer)) result.references.unchanged++;
+    else if (rows.length === 0 && referenceSuppressed(db, reference, space)) result.references.suppressed++;
     // The same fact from the user, the LLM or another analyzer already holds.
     else if (rows.length === 0) {
-      change.insertReference({ ...reference, origin: analyzer });
+      change.insertReference({ space, ...reference, origin: analyzer });
       result.references.added++;
     }
   }
@@ -334,10 +389,11 @@ export function importFindings(db: DatabaseSync, findings: NormalizedFindings, c
   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);
+    const result: ImportResult = { revision: null, names: counts(), symbols: counts(), regions: counts(), references: counts(), conflicts: [] };
+    importNames(db, change, findings, coverage, result);
     importRegions(db, change, findings, coverage, result);
     importReferences(db, change, findings, coverage, result);
+    change.check();
     result.revision = change.revision;
     return result;
   });