@henols/c64-re-tools 2.1.1 → 2.1.3

package/src/host-client/image.ts

@@ -37,14 +37,33 @@ const MEDIA_KINDS: Record<string, string> = {
 export const MEDIA_REMEDY = "Get the PRG out of it with disk.ts read (or disk.ts crt for a cartridge) of the c64-disk skill";
 
 /**
- * Reads a PRG of the project: a 2-byte load address, and bytes that end at
- * $ffff or before. Refuses a disk, tape or cartridge file and any other file
- * that is no PRG with invalid-input; `remedy` tells what to do in its place.
+ * Refuses a file that is no PRG by its extension (`type`, lowercase, without
+ * the dot): invalid-input. A disk, tape or cartridge file gets `remedy`. A PRG
+ * ends in .prg in any letter case, or has no extension, as c1541 writes the
+ * names of the files that it reads from a disk; every other extension is
+ * refused. `accepted` names what the reader takes, for the message.
  */
-export function readPrg(path: string, remedy = MEDIA_REMEDY): { bytes: Buffer; start: number; end: number; body: Uint8Array } {
-  const { bytes, type } = readProjectFile(path);
+export function refuseNotPrg(path: string, type: string, remedy = MEDIA_REMEDY, accepted = "a PRG"): void {
   const media = MEDIA_KINDS[type];
   if (media !== undefined) throw new Refusal("invalid-input", `${path} is ${media} (.${type}), not a PRG. ${remedy}.`);
+  if (type !== "prg" && type !== "") {
+    throw new Refusal("invalid-input", `${path} is not ${accepted}: a PRG has the extension .prg or no extension, not .${type}. Give the PRG of the program, or rename the file to .prg when it is a PRG.`);
+  }
+}
+
+/**
+ * Reads a PRG of the project: a 2-byte load address, and bytes that end at
+ * $ffff or before. Refuses with invalid-input a file that is no PRG by its
+ * extension (refuseNotPrg) or by its bytes; `remedy` tells what to do in place
+ * of a disk, tape or cartridge file. A file of fewer than 3 bytes is refused
+ * as too short: no remedy applies.
+ */
+export function readPrg(path: string, remedy = MEDIA_REMEDY, accepted = "a PRG"): { bytes: Buffer; start: number; end: number; body: Uint8Array } {
+  const { bytes, type } = readProjectFile(path);
+  refuseNotPrg(path, type, remedy, accepted);
+  if (bytes.length < 3) {
+    throw new Refusal("invalid-input", `${path} is too short for a PRG: it has ${bytes.length} ${bytes.length === 1 ? "byte" : "bytes"}, and a PRG has a 2-byte load address and at least one byte. Give the complete PRG file.`);
+  }
   try {
     return { bytes, ...prgRange(bytes) };
   } catch (error) {
@@ -53,18 +72,13 @@ export function readPrg(path: string, remedy = MEDIA_REMEDY): { bytes: Buffer; s
   }
 }
 
-/** Reads an image.json or a PRG, relative to the project folder. */
+/** Reads an image.json or a PRG, relative to the project folder. Refuses every other file as readPrg does. */
 export function readImage(path: string): Image {
-  const { bytes } = readProjectFile(path);
   if (!path.endsWith(".json")) {
-    let range: ReturnType<typeof prgRange>;
-    try {
-      range = prgRange(bytes);
-    } catch (error) {
-      throw new Refusal("invalid-input", `${path}: ${(error as Error).message}`);
-    }
+    const range = readPrg(path, MEDIA_REMEDY, "an image.json of the c64-unpacker skill or a PRG");
     return { segments: [{ start: range.start, end: range.end }], byteAt: (address) => range.body[address - range.start]! };
   }
+  const { bytes } = readProjectFile(path);
   const fail = (what: string): never => {
     throw new Refusal("invalid-input", `${path} is not an image.json of the c64-unpacker skill: ${what}`);
   };

package/src/host-client/steps.ts

@@ -228,8 +228,8 @@ function checkTarget(value: unknown, where: string, fail: (message: string) => n
   return fail(`${where}.kind must be one of address, memory, raster`);
 }
 
-/** What a step of a script without the replay core gets for press. */
-const PRESS_REMEDY = "press pushes keys of the keyboard matrix, and only the record and replay commands of c64-testing have them. Use type for the KERNAL keyboard queue, or open the window and ask the user to press the key";
+/** What a step of a script without the replay core gets for press: the scripts that read these steps run without a window. */
+const PRESS_REMEDY = "press pushes keys of the keyboard matrix, and only the replay core of c64-testing has them. Use type for the KERNAL keyboard queue, or put the press step in a record file and play it with testing.ts record of c64-testing";
 
 /** Checks the input of one step kind and returns it with the defaults of its MCP tool. */
 function checkInput(kind: ActionStepKind, value: unknown, at: string, fail: (message: string) => never): ActionStep {
@@ -384,8 +384,42 @@ export function checkActionSteps(value: unknown, fail: (message: string) => neve
   });
 }
 
-/** Reads a steps file of the project: a JSON list of action steps. `option` names the option of the file in a refusal. */
-export function readActionSteps(path: string, option: string): ActionStep[] {
+/** The names and addresses of an action step: each location that the step resolves when it runs. */
+export function stepLocations(step: ActionStep): Location[] {
+  if ("write" in step) return [step.write.address];
+  if ("registers" in step) return step.registers.pc === undefined ? [] : [step.registers.pc];
+  if (!("runUntil" in step)) return [];
+  const { target } = step.runUntil;
+  if (target.kind === "raster") return [];
+  if (target.kind === "memory") return [target.address];
+  return [target.address, ...(target.condition?.kind === "memory" ? [target.condition.address] : [])];
+}
+
+/**
+ * Resolves every name of the steps with `at` before the steps run, so that an
+ * unknown name stops the call before the emulator starts. A refusal of `at` becomes
+ * invalid-input that names `where` (for example the option and the file) and the step.
+ * `first` is the number of the first of the steps in the file.
+ */
+export function checkStepNames(steps: readonly ActionStep[], at: (location: Location) => number, where: string, first = 1): void {
+  steps.forEach((step, index) => {
+    for (const location of stepLocations(step)) {
+      try {
+        at(location);
+      } catch (error) {
+        if (isRefusal(error)) throw new Refusal("invalid-input", `${where}: step ${index + first}: ${error.message}`);
+        throw error;
+      }
+    }
+  });
+}
+
+/**
+ * Reads a steps file of the project: a JSON list of action steps. `option`
+ * names the option of the file in a refusal. With `at`, every name of the
+ * steps must resolve (checkStepNames).
+ */
+export function readActionSteps(path: string, option: string, at?: (location: Location) => number): ActionStep[] {
   const fail = (message: string): never => {
     throw new Refusal("invalid-input", `${option} ${path}: ${message}`);
   };
@@ -396,7 +430,9 @@ export function readActionSteps(path: string, option: string): ActionStep[] {
     if (error instanceof SyntaxError) return fail(`it is not JSON: ${error.message}`);
     throw error;
   }
-  return checkActionSteps(value, fail);
+  const steps = checkActionSteps(value, fail);
+  if (at !== undefined) checkStepNames(steps, at, `${option} ${path}`);
+  return steps;
 }
 
 /** Stops the CPU when it runs: a write, a register change or an exact frame count needs it stopped. */

package/src/host-client/tools.ts

@@ -6,6 +6,7 @@
 import { ProtocolError, WireFailure } from "../protocol/messages.ts";
 import { DISK_IMAGE_TYPES, validateToolResult, type C1541Result, type DiskAction, type DiskImageType, type PetcatResult, type ToolOperation, type ToolOperations, type HostInfo, type ToolStatus } from "../protocol/tools.ts";
 import { HostConnection } from "./connect.ts";
+import { readPrg } from "./image.ts";
 import { readProjectFile } from "./transfer.ts";
 
 export interface ToolCallOptions {
@@ -72,10 +73,10 @@ export async function inspectDisk(request: InspectDiskRequest, options: ToolCall
   return result.action === "read" && result.found ? { ...result, data: attachments[0]! } : result;
 }
 
-/** petcat.decode: the C64 BASIC V2 listing of a project program and its machine-code handoffs. */
+/** petcat.decode: the C64 BASIC V2 listing of a project program and its machine-code handoffs. Refuses a file that is no PRG as readPrg does. */
 export async function decodeBasic(request: { program: string }, options: ToolCallOptions = {}): Promise<PetcatResult> {
-  const file = readProjectFile(request.program);
-  return (await callTool("petcat.decode", {}, [file.bytes], options)).result;
+  const { bytes } = readPrg(request.program);
+  return (await callTool("petcat.decode", {}, [bytes], options)).result;
 }
 
 /** host.status: the Host Runtime, and each native tool on the host, found and run once. */

package/src/host-client/transfer.ts

@@ -2,10 +2,10 @@
 // The host never sees a client path: only bytes and the file's type.
 
 import { createHash } from "node:crypto";
-import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import { dirname, extname, join, relative, sep } from "node:path";
 
-import { isInside, projectRoot, resolveProject, resolveProjectFile, resolveProjectPath } from "../project.ts";
+import { checkOutputPath, isInside, projectRoot, resolveProject, resolveProjectFile, writeProblem } from "../project.ts";
 import { isRefusal } from "../errors.ts";
 import { MAX_ATTACHMENT_BYTES } from "../protocol/framing.ts";
 import { WireFailure } from "../protocol/messages.ts";
@@ -20,6 +20,11 @@ export function projectFolder(project: string | undefined): string {
   return resolveProject(project, process.cwd(), { remedy: "Give project: <folder>" });
 }
 
+/** Refuses an MCP `out` before the tool does any work, with the checks that every --out of a script gets. */
+export function checkOut(path: string, project: string | undefined): void {
+  checkOutputPath(path, "file", { root: projectFolder(project), what: "out" });
+}
+
 /** The project folder of this process (--project or the project lookup), or a WireFailure. */
 function currentProject(): string {
   return projectRoot();
@@ -36,17 +41,17 @@ export interface ProjectFile {
  * project rules refuse, not-found when nothing is there, limit-exceeded when
  * the file is too large to transfer.
  */
-export function readProjectFile(path: string, options: { root?: string } = {}): ProjectFile {
+export function readProjectFile(path: string, options: { root?: string; what?: string } = {}): ProjectFile {
   const root = options.root ?? currentProject();
   let real: string;
   try {
     real = resolveProjectFile(path, root);
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-      throw new WireFailure("not-found", `There is no file at ${path} in the project folder.`);
+      throw new WireFailure("not-found", `${options.what === undefined ? "" : `${options.what}: `}There is no file at ${path} in the project folder.`);
     }
     if (isRefusal(error) && error.code === "invalid-input") {
-      throw new WireFailure("invalid-input", `${path}: give a path relative to the project folder that stays inside it.`);
+      throw new WireFailure("invalid-input", `${options.what ?? path}: give a path relative to the project folder that stays inside it, not ${path}.`);
     }
     throw error;
   }
@@ -58,49 +63,37 @@ export function readProjectFile(path: string, options: { root?: string } = {}):
   return { bytes: readFileSync(real), type: extname(path).slice(1).toLowerCase() };
 }
 
-/** Why a file cannot be written, by the error code of the file system; the codes that are a fault of the path. */
-const WRITE_PROBLEMS: Record<string, string> = {
-  EISDIR: "is a folder. Give the path of a file",
-  EEXIST: "has a file where a folder must be. Give a path whose folders are folders",
-  ENOTDIR: "has a file where a folder must be. Give a path whose folders are folders",
-  ENOENT: "is in a folder that does not exist",
-  EACCES: "cannot be written: there is no permission. Give a path that you can write",
-  EPERM: "cannot be written: there is no permission. Give a path that you can write",
-  EROFS: "is on a file system that is read-only. Give another path",
-  ENAMETOOLONG: "is too long. Give a shorter path",
-};
-
 /**
  * The refusal for a write that the file system refused because of the path
  * (a folder, a file in place of a folder, no permission): invalid-input with
  * the path. Undefined for another error, which is no fault of the path.
  */
 export function writeRefusal(error: unknown, path: string, what?: string): WireFailure | undefined {
-  const problem = WRITE_PROBLEMS[(error as NodeJS.ErrnoException | undefined)?.code ?? ""];
-  return problem === undefined ? undefined : new WireFailure("invalid-input", `${what === undefined ? "" : `${what}: `}${path} ${problem}.`);
+  const message = writeProblem(error, path, what);
+  return message === undefined ? undefined : new WireFailure("invalid-input", message);
 }
 
 /**
  * Writes bytes to a project file on the client side, making its directories
- * and overwriting it. Throws WireFailure(invalid-input) for a path outside the
- * project, also one that leaves it through a symbolic link, and for a path
- * that the file system refuses: a folder, a file in place of a folder, no permission.
+ * and overwriting it. First the check of checkOutputPath, which a script also
+ * does on its output options before any work. Throws WireFailure(invalid-input)
+ * for a path outside the project, also one that leaves it through a symbolic
+ * link, for a path in the knowledge, and for a path that the file system
+ * refuses: a folder, a file in place of a folder, no permission.
  */
 export function writeProjectFile(path: string, bytes: Uint8Array, options: { root?: string; what?: string } = {}): void {
   const root = options.root ?? currentProject();
   const refuse = () => new WireFailure("invalid-input", `${options.what ?? path}: give a path relative to the project folder that stays inside it, not ${path}.`);
   let file: string;
   try {
-    file = resolveProjectPath(path, root);
-  } catch {
-    throw refuse();
+    file = checkOutputPath(path, "file", { root, ...(options.what === undefined ? {} : { what: options.what }) });
+  } catch (error) {
+    if (isRefusal(error)) throw new WireFailure(error.code, error.message);
+    throw error;
   }
-  // The nearest folder that exists must be inside the project before a folder is made below it.
-  let existing = dirname(file);
-  while (!existsSync(existing)) existing = dirname(existing);
-  if (!isInside(realpathSync(root), realpathSync(existing))) throw refuse();
   try {
     mkdirSync(dirname(file), { recursive: true });
+    // Again after the folders are made: another process can change the folders between the check and the write.
     if (!isInside(realpathSync(root), realpathSync(dirname(file)))) throw refuse();
     let link = false;
     try {

package/src/knowledge/history.ts

@@ -37,7 +37,7 @@ import {
   type SuppressionRow,
   type SymbolRow,
 } from "./read.ts";
-import { DEFAULT_SPACE, type EvidenceKind, type Origin, type Space } from "./schema.ts";
+import { DEFAULT_SPACE, type CoverageKind, type EvidenceKind, type Origin, type Space } from "./schema.ts";
 import { compareText, NO_REVISION } from "./text.ts";
 import type { Evidence } from "./write.ts";
 
@@ -51,12 +51,47 @@ export interface Revision {
   toolVersion?: string;
   /** A revert: the revision whose knowledge it restored. */
   restores?: string;
+  /** A revert of one space: that space. A revert without it restored every space. */
+  restoresSpace?: Space;
   /** What the change rests on. */
   evidence?: Evidence[];
 }
 
+/** A memory row of the program: the bytes from an address. */
+export interface MemoryRow {
+  space: Space;
+  address: number;
+  /** The count of bytes in the row. */
+  bytes: number;
+  origin: Origin;
+  revision: string;
+}
+
+/** The entry of the program, and whether it has a machine state and stages. */
+export interface EntryRow {
+  space: Space;
+  address: number;
+  state: boolean;
+  stages: number;
+  origin: Origin;
+  revision: string;
+}
+
+/** A coverage range of one kind. */
+export interface CoverageRow {
+  space: Space;
+  kind: CoverageKind;
+  start: number;
+  end: number;
+  origin: Origin;
+  revision: string;
+}
+
 /** One knowledge row with its validity: from its first revision until the revision that closed it. */
 export type HistoryEntry =
+  | { entity: "memory"; row: MemoryRow; from: string; to?: string }
+  | { entity: "entry"; row: EntryRow; from: string; to?: string }
+  | { entity: "coverage"; row: CoverageRow; from: string; to?: string }
   | { 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 }
@@ -82,6 +117,7 @@ function toRevision(row: Raw): Revision {
   if (row.input_hash !== null) revision.inputHash = row.input_hash as string;
   if (row.tool_version !== null) revision.toolVersion = row.tool_version as string;
   if (row.restored_revision !== null) revision.restores = row.restored_revision as string;
+  if (row.restored_space !== null && row.restored_space !== undefined) revision.restoresSpace = row.restored_space as Space;
   return revision;
 }
 
@@ -183,6 +219,7 @@ export interface InitialRevision {
   inputHash?: undefined;
   toolVersion?: undefined;
   restores?: undefined;
+  restoresSpace?: undefined;
   evidence?: undefined;
 }
 
@@ -213,9 +250,25 @@ export function revision(db: DatabaseSync | undefined, text: string): RevisionCh
     ["macro", "macros", MACRO_COLUMNS, toMacro],
     ["macro-use", "macro_uses", MACRO_USE_COLUMNS, toMacroUse],
   ] as const;
+  // The program: its memory, its entry and its coverage.
+  const program = [
+    ["memory", "memory", "space, address, length(bytes) / 2 AS bytes, origin, valid_from_revision", (row: Raw): MemoryRow => ({ space: row.space as Space, address: row.address as number, bytes: row.bytes as number, origin: row.origin as Origin, revision: row.valid_from_revision as string })],
+    [
+      "entry",
+      "entries",
+      "space, address, state IS NOT NULL AS has_state, json_array_length(coalesce(stages, '[]')) AS stage_count, origin, valid_from_revision",
+      (row: Raw): EntryRow => ({ space: row.space as Space, address: row.address as number, state: row.has_state === 1, stages: row.stage_count as number, origin: row.origin as Origin, revision: row.valid_from_revision as string }),
+    ],
+    [
+      "coverage",
+      "coverage",
+      "space, kind, start_address, end_address, origin, valid_from_revision",
+      (row: Raw): CoverageRow => ({ space: row.space as Space, kind: row.kind as CoverageKind, start: row.start_address as number, end: row.end_address as number, origin: row.origin as Origin, revision: row.valid_from_revision as string }),
+    ],
+  ] as const;
   const added: HistoryEntry[] = [];
   const closed: HistoryEntry[] = [];
-  for (const [entity, table, columns, map] of tables) {
+  for (const [entity, table, columns, map] of [...tables, ...program]) {
     for (const row of db.prepare(`SELECT ${columns}, valid_to_revision FROM ${table} WHERE valid_from_revision = ?`).all(id) as Raw[]) {
       added.push(entry(entity, map(row), row));
     }

package/src/knowledge/import.ts

@@ -77,7 +77,18 @@ export type ImportConflict =
       current: { address: number; name: string; kind: SymbolKind; origin: Origin };
       finding: { name: string; kind: SymbolKind };
     }
-  | { category: "region"; start: number; end: number; current: { type: RegionType; origin: Origin }; finding: { type: RegionType } };
+  | { category: "region"; start: number; end: number; current: { type: RegionType; origin: Origin }; finding: { type: RegionType } }
+  | {
+      /** A data finding over code that a run executed or that the user or the LLM named: the finding is not imported. */
+      category: "code-evidence";
+      start: number;
+      end: number;
+      finding: { type: RegionType };
+      /** The first executed instruction start in the range. */
+      executed?: number;
+      /** The first code name (label or routine) of the user or the LLM in the range. */
+      symbol?: { address: number; name: string; kind: SymbolKind; origin: Origin };
+    };
 
 export interface ImportCounts {
   added: number;
@@ -252,16 +263,53 @@ const YIELDS_TO_HEURISTIC = new Set<Origin>(["dxa", "ghidra"]);
 /** Analyzers whose data gives way to a code finding over an executed instruction start. */
 const YIELDS_TO_EXECUTED_CODE = new Set<Origin>(["dxa", "ghidra"]);
 
+/** The first address in the range that is an executed instruction start, or undefined. */
+function firstExecuted(findings: NormalizedFindings, start: number, end: number): number | undefined {
+  if (findings.executed === undefined) return undefined;
+  for (let address = start; address <= end; address++) if (findings.executed(address)) return address;
+  return undefined;
+}
+
 /** 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;
+  return firstExecuted(findings, start, end) !== undefined;
 }
 
-function importRegions(db: DatabaseSync, change: Change, findings: NormalizedFindings, coverage: AddressRange[], result: ImportResult): void {
-  const { analyzer } = findings;
-  const space = findings.space ?? DEFAULT_SPACE;
+/**
+ * The data findings of DXA or Ghidra that code evidence contradicts: an
+ * executed instruction start, or a code name (label or routine) of the user or
+ * the LLM, in the range. Evidence wins over an analyzer guess: such a finding
+ * is not imported, and the analyzer's own code there stays.
+ */
+function contradictedData(db: DatabaseSync, findings: NormalizedFindings, space: Space): Array<ImportConflict & { category: "code-evidence" }> {
+  if (!YIELDS_TO_EXECUTED_CODE.has(findings.analyzer)) return [];
+  const names = db.prepare(`SELECT ${SYMBOL_COLUMNS} FROM current_symbols WHERE space = ? AND origin IN ('user', 'llm') AND kind IN ('label', 'routine') AND address BETWEEN ? AND ? ORDER BY address LIMIT 1`);
+  const found: Array<ImportConflict & { category: "code-evidence" }> = [];
+  for (const region of findings.regions) {
+    if (isCode(region.type) || region.type === "dual-use") continue;
+    const executed = firstExecuted(findings, region.start, region.end);
+    const raw = names.get(space, region.start, region.end) as Record<string, unknown> | undefined;
+    if (executed === undefined && raw === undefined) continue;
+    const symbol = raw === undefined ? undefined : toSymbol(raw);
+    found.push({
+      category: "code-evidence",
+      start: region.start,
+      end: region.end,
+      finding: { type: region.type },
+      ...(executed === undefined ? {} : { executed }),
+      ...(symbol === undefined ? {} : { symbol: { address: symbol.address, name: symbol.name, kind: symbol.kind, origin: symbol.origin } }),
+    });
+  }
+  return found;
+}
+
+function importRegions(db: DatabaseSync, change: Change, given: NormalizedFindings, coverage: AddressRange[], result: ImportResult): void {
+  const { analyzer } = given;
+  const space = given.space ?? DEFAULT_SPACE;
+  // Data findings over code evidence are conflicts, not facts.
+  const contradicted = contradictedData(db, given, space);
+  result.conflicts.push(...contradicted);
+  const findings = { ...given, regions: given.regions.filter((region) => !contradicted.some((item) => item.start === region.start && item.end === region.end)) };
   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) {
@@ -333,6 +381,14 @@ function importRegions(db: DatabaseSync, change: Change, findings: NormalizedFin
       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 });
     }
+    // Under a contradicted data finding, the analyzer's own regions stay: they join the findings of the same type next to them.
+    for (const row of own) {
+      for (const item of contradicted) {
+        const inside = { start: Math.max(row.start, item.start, range.start), end: Math.min(row.end, item.end, range.end) };
+        if (inside.start > inside.end) continue;
+        for (const piece of subtract(inside, [...protectedRows, ...suppressionsOverlapping(db, "region", inside.start, inside.end, space)])) keepPiece(desired, { ...piece, type: row.type });
+      }
+    }
     const retiredRanges = new Set<string>();
     for (const row of own) {
       const inside = { start: Math.max(row.start, range.start), end: Math.min(row.end, range.end) };
@@ -357,6 +413,22 @@ function importRegions(db: DatabaseSync, change: Change, findings: NormalizedFin
   }
 }
 
+/** Puts a kept piece into the desired regions, joined with the pieces of the same type that touch or overlap it. */
+function keepPiece(desired: Map<string, { start: number; end: number; type: RegionType }>, piece: { start: number; end: number; type: RegionType }): void {
+  let joined = { ...piece };
+  for (let found = true; found; ) {
+    found = false;
+    for (const [key, other] of desired) {
+      if (other.type !== joined.type || other.end + 1 < joined.start || joined.end + 1 < other.start) continue;
+      desired.delete(key);
+      joined = { start: Math.min(joined.start, other.start), end: Math.max(joined.end, other.end), type: joined.type };
+      found = true;
+      break;
+    }
+  }
+  desired.set(`${joined.start}-${joined.end}`, joined);
+}
+
 function importReferences(db: DatabaseSync, change: Change, findings: NormalizedFindings, coverage: AddressRange[], result: ImportResult): void {
   const { analyzer } = findings;
   const space = findings.space ?? DEFAULT_SPACE;

package/src/knowledge/program.ts

@@ -224,13 +224,42 @@ export function requireProgram(db: DatabaseSync | undefined, space: Space = DEFA
   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. */
+/** The pages of an entry state: $0000-$03ff as the capture wrote them, 256 bytes as hex for each page. */
+const STATE_PAGES = ["$0000", "$0100", "$0200", "$0300"] as const;
+
+/**
+ * The memory that the program has at its entry: the segments, and below them
+ * $0002-$03ff of the entry state (the zero page, the stack and the system
+ * pages hold code and data that the loader left). $0000 and $0001 are the
+ * CPU port, not memory. A segment byte wins over a state byte.
+ */
+export function entryMemory(image: ProgramImage): Uint8Array {
+  const memory = new Uint8Array(image.memory);
+  const pages = image.state?.pages;
+  if (typeof pages !== "object" || pages === null) return memory;
+  const inSegment = (address: number) => image.segments.some((segment) => address >= segment.start && address <= segment.end);
+  STATE_PAGES.forEach((page, index) => {
+    const hex = (pages as Record<string, unknown>)[page];
+    if (typeof hex !== "string" || !/^(?:[0-9a-fA-F]{2}){1,256}$/.test(hex)) return;
+    Buffer.from(hex, "hex").forEach((byte, offset) => {
+      const address = index * 0x100 + offset;
+      if (address >= 2 && !inSegment(address)) memory[address] = byte;
+    });
+  });
+  return memory;
+}
+
+/**
+ * The bytes for an analyzer: a PRG for one segment without an entry state,
+ * else the 64 KiB with the entry-state pages (entryMemory). DXA, Ghidra and
+ * c64-source get the same bytes.
+ */
 export function analyzedBytes(image: ProgramImage): { bytes: Buffer; kind: "prg" | "flat64k" } {
   if (image.segments.length === 1 && image.state === undefined) {
     const [segment] = image.segments;
     return { bytes: Buffer.concat([Buffer.from([segment!.start & 0xff, segment!.start >> 8]), Buffer.from(image.memory.subarray(segment!.start, segment!.end + 1))]), kind: "prg" };
   }
-  return { bytes: Buffer.from(image.memory), kind: "flat64k" };
+  return { bytes: Buffer.from(entryMemory(image)), kind: "flat64k" };
 }
 
 /**

package/src/knowledge/read.ts

@@ -255,18 +255,19 @@ export interface CoverageRun {
  * The imports of coverage maps that the knowledge has, by name and then oldest
  * first: the last import of a name is the latest. A revert gives back the maps
  * of the revision that it restores, so a map that a revert removed is not known.
+ * A revert of one space gives back only the maps of that space.
  * With `at`, the maps of the knowledge at that revision.
  */
 export function coverageRuns(db: DatabaseSync | undefined, at?: string): CoverageRun[] {
   if (db === undefined || at === NO_REVISION) return [];
   const rows = db
     .prepare(
-      `SELECT r.id AS id, r.operation AS operation, r.restored_revision AS restored, e.ref AS name, e.sha256 AS sha256, coalesce(e.space, '${DEFAULT_SPACE}') AS space
+      `SELECT r.id AS id, r.operation AS operation, r.restored_revision AS restored, r.restored_space AS restoredSpace, e.ref AS name, e.sha256 AS sha256, coalesce(e.space, '${DEFAULT_SPACE}') AS space
        FROM revisions r LEFT JOIN evidence e ON e.revision = r.id AND e.kind = 'coverage'
        WHERE (r.operation = 'coverage' AND e.id IS NOT NULL) OR (r.operation = 'revert' AND r.restored_revision IS NOT NULL)
        ORDER BY r.id, e.id`,
     )
-    .all() as Array<{ id: string; operation: string; restored: string | null; name: string | null; sha256: string | null; space: Space }>;
+    .all() as Array<{ id: string; operation: string; restored: string | null; restoredSpace: Space | null; name: string | null; sha256: string | null; space: Space }>;
   // The maps after each revision that changed them, oldest first.
   const after: Array<{ id: string; runs: CoverageRun[] }> = [];
   let runs: CoverageRun[] = [];
@@ -274,8 +275,10 @@ export function coverageRuns(db: DatabaseSync | undefined, at?: string): Coverag
     if (at !== undefined && row.id > at) break;
     if (row.operation === "revert") {
       const restored = row.restored!;
-      runs = [];
-      for (const item of after) if (item.id <= restored) runs = item.runs;
+      let then: CoverageRun[] = [];
+      for (const item of after) if (item.id <= restored) then = item.runs;
+      const only = row.restoredSpace;
+      runs = only === null ? then : [...runs.filter((run) => run.space !== only), ...then.filter((run) => run.space === only)];
     } else {
       const run: CoverageRun = { name: row.name!, sha256: row.sha256!, space: row.space, revision: row.id };
       if (!runs.some((item) => item.name === run.name && item.sha256 === run.sha256 && item.space === run.space && item.revision === run.revision)) runs = [...runs, run];

package/src/knowledge/schema.ts

@@ -114,7 +114,8 @@ function createSchema(db: DatabaseSync): void {
         input_hash   TEXT,
         tool_version TEXT,
         description  TEXT,
-        restored_revision TEXT
+        restored_revision TEXT,
+        restored_space TEXT
       );
       CREATE TABLE symbols (
         id                  TEXT PRIMARY KEY,
@@ -317,7 +318,7 @@ function createSchema(db: DatabaseSync): void {
 }
 
 /** The version of the index this build makes. An index with another version is emptied and made again. */
-export const INDEX_VERSION = 7;
+export const INDEX_VERSION = 8;
 
 function indexVersion(db: DatabaseSync): number | undefined {
   const hasMeta = db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'meta'").get();

package/src/knowledge/text.ts

@@ -188,6 +188,7 @@ const REVISION_FIELDS: readonly Field[] = [
   field("inputHash", "input_hash", "text", true),
   field("toolVersion", "tool_version", "text", true),
   field("restores", "restored_revision", "text", true),
+  field("restoresSpace", "restored_space", "text", true),
 ];
 
 /** The SQL name of a table: "references" is a keyword. */