@henols/c64-re-tools 2.1.1 → 2.1.3

package/src/knowledge/write.ts

@@ -8,6 +8,7 @@ import { type AddressRange, formatC64Address, instructionLength, SPACE_PATTERN,
 import { isoCet } from "../time.ts";
 import { CONFLICT_RULES, conflicts, conflictTable, type Conflict, type ConflictRow } from "./conflicts.ts";
 import { transaction } from "./database.ts";
+import { labelProblem } from "../opcodes.ts";
 import { checkExpression, evaluate, identifiers, operandText, replaceIdentifiers } from "./expression.ts";
 import {
   COMMENT_COLUMNS,
@@ -61,7 +62,7 @@ import {
   type SuppressionRow,
   type SymbolRow,
 } from "./read.ts";
-import { CODE_REGION_TYPES, COMMENT_PLACEMENTS, EVIDENCE_KINDS, MAX_ELEMENT, MODULE_FILE, DEFAULT_SPACE, GENERATED_FILES, isGeneratedFile, MACRO_NAME, MACRO_PARAM, SWITCH_NAME, NO_ELEMENT_TYPES, OPERAND_SELECTS, POINTER_KIND, REFERENCE_KINDS, REGION_TYPES, SYMBOL_KINDS, type CommentPlacement, type EvidenceKind, type OperandSelect, type Origin, type ReferenceKind, type RegionType, type Space, type SymbolKind } from "./schema.ts";
+import { CODE_REGION_TYPES, COMMENT_PLACEMENTS, EVIDENCE_KINDS, MAX_ELEMENT, MODULE_FILE, DEFAULT_SPACE, GENERATED_FILES, isGeneratedFile, isSemantic, MACRO_NAME, MACRO_PARAM, SWITCH_NAME, NO_ELEMENT_TYPES, OPERAND_SELECTS, POINTER_KIND, REFERENCE_KINDS, REGION_TYPES, SYMBOL_KINDS, type CommentPlacement, type EvidenceKind, type OperandSelect, type Origin, type ReferenceKind, type RegionType, type Space, type SymbolKind } from "./schema.ts";
 import { newRevisionId, rowId, sqlName } from "./text.ts";
 
 /** What a change rests on: a coverage run, a test or another project file with its SHA-256, or a note. */
@@ -140,6 +141,8 @@ export interface ChangeContext {
   evidence?: Evidence[];
   /** A revert: the revision whose knowledge it restores. */
   restores?: string;
+  /** A revert of one space: the space whose knowledge it restores. Without it, a revert restores every space. */
+  restoresSpace?: Space;
 }
 
 /**
@@ -181,8 +184,8 @@ export class Change {
     const now = new Date();
     const id = newRevisionId(currentRevision(this.#db), now);
     this.#db
-      .prepare("INSERT INTO revisions (id, created_at, origin, operation, input_hash, tool_version, description, restored_revision) VALUES (?, ?, ?, ?, ?, ?, ?, ?)")
-      .run(id, isoCet(now), this.#context.origin, this.#operation, this.#context.inputHash ?? null, this.#context.toolVersion ?? null, this.#context.description ?? null, this.#context.restores ?? null);
+      .prepare("INSERT INTO revisions (id, created_at, origin, operation, input_hash, tool_version, description, restored_revision, restored_space) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)")
+      .run(id, isoCet(now), this.#context.origin, this.#operation, this.#context.inputHash ?? null, this.#context.toolVersion ?? null, this.#context.description ?? null, this.#context.restores ?? null, this.#context.restoresSpace ?? null);
     this.revision = id;
     const evidence = this.#db.prepare("INSERT INTO evidence (revision, kind, ref, sha256, space) VALUES (?, ?, ?, ?, ?)");
     for (const item of this.#context.evidence ?? []) evidence.run(id, item.kind, item.ref, item.sha256 ?? null, item.space ?? null);
@@ -350,6 +353,27 @@ const result = <T, P>(written: { revision: string | null; current: Step<T, P> })
 // Each write has a check, which refuses bad input before anything opens, and a
 // step, which runs inside a change. A single write and a batch share both.
 
+/**
+ * True when a write of `origin` over a current row with the same content
+ * records a decision, so it replaces the row: over a row of an analyzer (the
+ * next run of the analyzer can retire its own rows, never a decision), and the
+ * user over the LLM. The LLM over the user changes nothing.
+ */
+function confirms(existing: Origin, origin: Origin): boolean {
+  return existing !== origin && (!isSemantic(existing) || origin === "user");
+}
+
+/**
+ * The bytes of the program of a space in the knowledge, by address: undefined
+ * outside it. A module and a comment are checked against them.
+ */
+function programBytes(db: DatabaseSync, space: Space): (address: number) => number | undefined {
+  const rows = db.prepare("SELECT address, bytes FROM current_memory WHERE space = ?").all(space) as Array<{ address: number; bytes: string }>;
+  const memory = new Map<number, number>();
+  for (const row of rows) Buffer.from(row.bytes, "hex").forEach((byte, offset) => memory.set(row.address + offset, byte));
+  return (address) => memory.get(address);
+}
+
 /** Every request names its space; without one it is the C64. */
 type InSpace = { space?: Space };
 type SymbolRequest = InSpace & { address: number; name: string; kind?: SymbolKind };
@@ -369,9 +393,8 @@ export function checkSpace(request: InSpace): void {
 function checkSymbol(request: SymbolRequest): void {
   checkSpace(request);
   checkAddress(request.address);
-  if (!SYMBOL_NAME.test(request.name)) {
-    throw new Refusal("invalid-input", "A symbol name is a letter or underscore, then letters, digits or underscores (at most 64), with an optional leading dot.");
-  }
+  const problem = labelProblem(request.name);
+  if (problem !== undefined) throw new Refusal("invalid-input", problem);
   if (request.kind !== undefined) checkOneOf(SYMBOL_KINDS, request.kind, "kind");
 }
 
@@ -379,7 +402,7 @@ function renameStep(db: DatabaseSync, change: Change, origin: Origin, request: S
   const space = spaceOf(request);
   const existing = symbolAt(db, request.address, space);
   const kind = request.kind ?? existing?.kind ?? "label";
-  if (existing !== undefined && existing.name === request.name && existing.kind === kind) return { current: existing };
+  if (existing !== undefined && existing.name === request.name && existing.kind === kind && !confirms(existing.origin, origin)) return { current: existing };
   const owner = symbolNamed(db, request.name, space);
   if (owner !== undefined && owner.address !== request.address) {
     throw new Refusal("conflict", `The name ${request.name} already belongs to ${formatC64Address(owner.address)}. Rename or remove that symbol first.`);
@@ -457,7 +480,7 @@ function classifyStep(db: DatabaseSync, change: Change, origin: Origin, request:
   const overlapping = regionsOverlapping(db, request.start, request.end, space);
   const [only] = overlapping;
   const same = overlapping.length === 1 && only!.start === request.start && only!.end === request.end && only!.type === request.type && only!.element === request.element;
-  if (same) return { current: overlapping };
+  if (same && !confirms(only!.origin, origin)) return { current: overlapping };
   clearRange(db, change, request.start, request.end, space);
   change.insertRegion({ space, start: request.start, end: request.end, type: request.type, ...(request.element === undefined ? {} : { element: request.element }), origin });
   liftRegionSuppressions(db, change, request.start, request.end, space);
@@ -488,14 +511,17 @@ function checkComment(request: CommentRequest): string {
   return text;
 }
 
-function commentStep(db: DatabaseSync, change: Change, origin: Origin, request: CommentRequest): Step<CommentRow> {
+function commentStep(db: DatabaseSync, change: Change, origin: Origin, request: CommentRequest): Step<CommentRow, CommentRow> {
   const space = spaceOf(request);
   const text = request.text.trim();
   const existing = commentsAt(db, request.address, space).find((comment) => comment.placement === request.placement);
-  if (existing?.text === text) return { current: existing };
+  if (existing?.text === text && !confirms(existing.origin, origin)) return { current: existing };
+  // A comment belongs to an instruction: the listing and the source show it at the start of the instruction only.
+  checkInstructionStart(db, space, programBytes(db, space), request.address, "comment");
   if (existing !== undefined) change.close("comments", "space = ? AND address = ? AND placement = ?", space, request.address, request.placement);
   change.insertComment({ space, address: request.address, placement: request.placement, text, origin });
-  return { current: commentsAt(db, request.address, space).find((comment) => comment.placement === request.placement)! };
+  const current = commentsAt(db, request.address, space).find((comment) => comment.placement === request.placement)!;
+  return existing !== undefined && existing.origin !== origin ? { current, previous: existing } : { current };
 }
 
 function checkPlacement(request: PlacementRequest): void {
@@ -521,14 +547,16 @@ function checkReference(request: ReferenceRequest): void {
   if (request.kind === POINTER_KIND) throw new Refusal("invalid-input", "Only an operand expression writes a pointer reference: use operand and unoperand.");
 }
 
-function referenceStep(db: DatabaseSync, change: Change, origin: Origin, request: ReferenceRequest): Step<ReferenceRow> {
+function referenceStep(db: DatabaseSync, change: Change, origin: Origin, request: ReferenceRequest): Step<ReferenceRow, ReferenceRow> {
   const space = spaceOf(request);
   const find = () => referencesFrom(db, request.from, space).find((reference) => reference.to === request.to && reference.kind === request.kind);
   const existing = find();
-  if (existing !== undefined) return { current: existing };
+  if (existing !== undefined && !confirms(existing.origin, origin)) return { current: existing };
+  // A confirmation of a reference of an analyzer makes it a reference of the writer: the next run of the analyzer keeps it.
+  if (existing !== undefined) change.close('"references"', "space = ? AND from_address = ? AND to_address = ? AND kind = ?", space, request.from, request.to, request.kind);
   change.insertReference({ space, from: request.from, to: request.to, kind: request.kind, origin });
   change.close("suppressions", "space = ? AND entity = 'reference' AND start_address = ? AND to_address = ? AND kind = ?", space, request.from, request.to, request.kind);
-  return { current: find()! };
+  return existing !== undefined ? { current: find()!, previous: existing } : { current: find()! };
 }
 
 function unreferenceStep(db: DatabaseSync, change: Change, origin: Origin, request: ReferenceRequest): Step<null> {
@@ -579,26 +607,32 @@ const shown = (value: number, size: number) => (value < 0 ? String(value) : `$${
 /**
  * Refuses an address that is not the start of an instruction. The code
  * regions of the knowledge give the instructions: they are decoded from the
- * start of the region, as the listing and the source decode them.
+ * start of the region, as the listing and the source decode them. An operand
+ * expression needs an instruction, so it is refused also outside the code
+ * regions and where the program has no byte. A module and a comment are
+ * refused only at an operand byte of a known instruction: they can start data.
  */
-function checkInstructionStart(db: DatabaseSync, space: Space, image: OperandImage, address: number): void {
+function checkInstructionStart(db: DatabaseSync, space: Space, byteAt: (address: number) => number | undefined, address: number, write: "operand" | "module" | "comment"): void {
   const where = formatC64Address(address);
   const code = regionsOverlapping(db, address, address, space).find((region) => CODE_REGION_TYPES.includes(region.type));
   if (code === undefined) {
+    if (write !== "operand") return;
     throw new Refusal("invalid-input", `${where} is in no code region, so the knowledge does not know an instruction that starts there. Classify the code that holds the instruction first (classify <range> code), then write the operand.`);
   }
   let start = code.start;
   let next = code.start;
   while (next < address) {
-    const opcode = image.byteAt(next);
+    const opcode = byteAt(next);
     if (opcode === undefined) {
+      if (write !== "operand") return;
       throw new Refusal("invalid-input", `The code region ${formatC64Address(code.start)}-${formatC64Address(code.end)} has no program byte at ${formatC64Address(next)}, so its instructions up to ${where} are not known. Correct the region (classify), then write the operand.`);
     }
     start = next;
     next += instructionLength(opcode);
   }
   if (next !== address) {
-    throw new Refusal("invalid-input", `${where} is not the start of an instruction. It is an operand byte of the instruction at ${formatC64Address(start)}, decoded from the start of the code region at ${formatC64Address(code.start)}. Give ${formatC64Address(start)}.`);
+    const what = write === "operand" ? "" : ` A ${write} is at the start of an instruction, as the listing and the source show it.`;
+    throw new Refusal("invalid-input", `${where} is not the start of an instruction. It is an operand byte of the instruction at ${formatC64Address(start)}, decoded from the start of the code region at ${formatC64Address(code.start)}.${what} Give ${formatC64Address(start)}.`);
   }
 }
 
@@ -611,7 +645,7 @@ function checkOperandValue(db: DatabaseSync, space: Space, image: OperandImage,
   const where = formatC64Address(request.address);
   const opcode = image.byteAt(request.address);
   if (opcode === undefined) throw new Refusal("invalid-input", `${where} is outside the image.`);
-  checkInstructionStart(db, space, image, request.address);
+  checkInstructionStart(db, space, (at) => image.byteAt(at), request.address, "operand");
   const length = instructionLength(opcode);
   if (length === 1) throw new Refusal("invalid-input", `The instruction at ${where} (opcode ${shown(opcode, 0x100)}) has no operand.`);
   if ((opcode & 0x1f) === 0x10) throw new Refusal("invalid-input", `The instruction at ${where} is a branch: its operand is a distance, not a value.`);
@@ -644,10 +678,10 @@ function operandStep(db: DatabaseSync, change: Change, context: ChangeContext &
   if (request.expression !== undefined) wanted.expression = request.expression.trim();
   const targets = new Set(checkOperandValue(db, space, context.image, request, operandText(wanted)));
   const existing = operandAt(db, request.address, space);
-  if (existing !== undefined && existing.select === wanted.select && existing.symbol === wanted.symbol && existing.offset === wanted.offset && existing.expression === wanted.expression) {
+  const origin = context.origin as OperandRow["origin"];
+  if (existing !== undefined && existing.select === wanted.select && existing.symbol === wanted.symbol && existing.offset === wanted.offset && existing.expression === wanted.expression && !confirms(existing.origin, origin)) {
     return { current: existing };
   }
-  const origin = context.origin as OperandRow["origin"];
   if (existing !== undefined) change.close("operands", "space = ? AND address = ?", space, request.address);
   change.insertOperand({ space, address: request.address, ...wanted, origin });
   const pointers = referencesFrom(db, request.address, space).filter((reference) => reference.kind === POINTER_KIND);
@@ -681,19 +715,22 @@ function checkModule(request: ModuleRequest): void {
   if (request.title !== undefined && (request.title.trim().length === 0 || request.title.length > MAX_COMMENT)) throw new Refusal("invalid-input", `A module title has 1 to ${MAX_COMMENT} characters.`);
 }
 
-function moduleStep(db: DatabaseSync, change: Change, origin: Origin, request: ModuleRequest): Step<ModuleRow> {
+function moduleStep(db: DatabaseSync, change: Change, origin: Origin, request: ModuleRequest): Step<ModuleRow, ModuleRow> {
   const space = spaceOf(request);
   const existing = moduleAt(db, request.start, space);
   // A module write without a title keeps the title it has.
   const title = request.title === undefined ? existing?.title : request.title.trim();
-  if (existing !== undefined && existing.file === request.file && existing.title === title) return { current: existing };
+  if (existing !== undefined && existing.file === request.file && existing.title === title && !confirms(existing.origin, origin)) return { current: existing };
+  // A file of the source starts at an instruction: a start inside one splits it into bytes.
+  checkInstructionStart(db, space, programBytes(db, space), request.start, "module");
   const owner = moduleWithFile(db, request.file, space);
   if (owner !== undefined && owner.start !== request.start) {
     throw new Refusal("conflict", `The file ${request.file} already belongs to the module at ${formatC64Address(owner.start)}. Give this module another file, or remove that module first.`);
   }
   if (existing !== undefined) change.close("modules", "space = ? AND start_address = ?", space, request.start);
   change.insertModule({ space, start: request.start, file: request.file, ...(title === undefined ? {} : { title }), origin: origin as ModuleRow["origin"] });
-  return { current: moduleAt(db, request.start, space)! };
+  const current = moduleAt(db, request.start, space)!;
+  return existing !== undefined && existing.origin !== origin ? { current, previous: existing } : { current };
 }
 
 function unmoduleStep(db: DatabaseSync, change: Change, _origin: Origin, request: InSpace & { start: number }): Step<null> {
@@ -758,9 +795,10 @@ function patchStep(db: DatabaseSync, change: Change, context: ChangeContext & {
   const symbol = symbolNamed(db, request.switch, space);
   if (symbol !== undefined) throw new Refusal("conflict", `The switch name ${request.switch} is the name of the symbol at ${formatC64Address(symbol.address)}. Give the switch another name.`);
   if (space === DEFAULT_SPACE && context.image.platform.has(request.switch)) throw new Refusal("conflict", `The switch name ${request.switch} is a C64 platform name. Give the switch another name.`);
-  const other = patchesOverlapping(db, request.start, request.end, space).find((row) => row.start !== request.start);
+  // A write at the start of a patch of the same switch changes that patch; every other patch that it overlaps is a conflict.
+  const other = patchesOverlapping(db, request.start, request.end, space).find((row) => row.start !== request.start || row.switch !== request.switch);
   if (other !== undefined) {
-    throw new Refusal("conflict", `The patch ${range} overlaps the patch of ${other.switch} at ${formatC64Address(other.start)}-${formatC64Address(other.end)}. Change or remove that patch first (unpatch).`);
+    throw new Refusal("conflict", `The patch ${range} of ${request.switch} overlaps the patch of ${other.switch} at ${formatC64Address(other.start)}-${formatC64Address(other.end)}. A patch cannot overlap another patch, and only a patch of the same switch at the same start replaces it. Change or remove that patch first (unpatch).`);
   }
   const [use] = macroUsesOverlapping(db, request.start, request.end, space);
   if (use !== undefined) {
@@ -770,8 +808,8 @@ function patchStep(db: DatabaseSync, change: Change, context: ChangeContext & {
   const code = request.code.trimEnd();
   // A patch write without a comment keeps the comment it has, as a module keeps its title.
   const comment = request.comment === undefined ? existing?.comment : request.comment.trim();
-  if (existing !== undefined && existing.end === request.end && existing.switch === request.switch && existing.code === code && existing.comment === comment) return { current: existing };
   const origin = context.origin as PatchRow["origin"];
+  if (existing !== undefined && existing.end === request.end && existing.switch === request.switch && existing.code === code && existing.comment === comment && !confirms(existing.origin, origin)) return { current: existing };
   if (existing !== undefined) change.close("patches", "space = ? AND start_address = ?", space, request.start);
   change.insertPatch({ space, start: request.start, end: request.end, switch: request.switch, code, ...(comment === undefined ? {} : { comment }), origin });
   const current = patchesOverlapping(db, request.start, request.start, space).find((row) => row.start === request.start)!;
@@ -813,7 +851,7 @@ function macroStep(db: DatabaseSync, change: Change, origin: Origin, request: Ma
   const params = request.params ?? [];
   const body = request.body.trimEnd();
   const comment = request.comment === undefined ? existing?.comment : request.comment.trim();
-  if (existing !== undefined && listText(existing.params) === listText(params) && existing.body === body && existing.comment === comment) return { current: existing };
+  if (existing !== undefined && listText(existing.params) === listText(params) && existing.body === body && existing.comment === comment && !confirms(existing.origin, origin)) return { current: existing };
   if (existing !== undefined && existing.params.length !== params.length) {
     const uses = listMacroUses(db, undefined, request.name, undefined, space);
     if (uses.length > 0) {
@@ -899,8 +937,8 @@ function useStep(db: DatabaseSync, change: Change, context: ChangeContext & { im
     throw new Refusal("conflict", `The macro use ${range} overlaps the use of ${other.macro} at ${formatC64Address(other.start)}-${formatC64Address(other.end)}. Remove that use first (unuse).`);
   }
   const existing = macroUsesOverlapping(db, request.start, request.start, space).find((row) => row.start === request.start);
-  if (existing !== undefined && existing.end === request.end && existing.macro === request.macro && listText(existing.args) === listText(args)) return { current: existing };
   const origin = context.origin as MacroUseRow["origin"];
+  if (existing !== undefined && existing.end === request.end && existing.macro === request.macro && listText(existing.args) === listText(args) && !confirms(existing.origin, origin)) return { current: existing };
   if (existing !== undefined) change.close("macro_uses", "space = ? AND start_address = ?", space, request.start);
   change.insertMacroUse({ space, start: request.start, end: request.end, macro: request.macro, args, origin });
   const current = macroUsesOverlapping(db, request.start, request.start, space).find((row) => row.start === request.start)!;
@@ -938,7 +976,7 @@ export function unclassifyRegion(db: DatabaseSync, context: WriteContext, reques
   return result(write(db, context, "unclassify-region", (change) => unclassifyStep(db, change, context.origin, request)));
 }
 
-export function setComment(db: DatabaseSync, context: WriteContext, request: CommentRequest): WriteResult<CommentRow> {
+export function setComment(db: DatabaseSync, context: WriteContext, request: CommentRequest): WriteResult<CommentRow, CommentRow> {
   checkComment(request);
   return result(write(db, context, "set-comment", (change) => commentStep(db, change, context.origin, request)));
 }
@@ -948,7 +986,7 @@ export function removeComment(db: DatabaseSync, context: WriteContext, request:
   return result(write(db, context, "remove-comment", (change) => uncommentStep(db, change, context.origin, request)));
 }
 
-export function addReference(db: DatabaseSync, context: WriteContext, request: ReferenceRequest): WriteResult<ReferenceRow> {
+export function addReference(db: DatabaseSync, context: WriteContext, request: ReferenceRequest): WriteResult<ReferenceRow, ReferenceRow> {
   checkReference(request);
   return result(write(db, context, "add-reference", (change) => referenceStep(db, change, context.origin, request)));
 }
@@ -959,7 +997,7 @@ export function removeReference(db: DatabaseSync, context: WriteContext, request
 }
 
 /** Starts a file of the generated source at an address; one module per address and per file. */
-export function setModule(db: DatabaseSync, context: WriteContext, request: ModuleRequest): WriteResult<ModuleRow> {
+export function setModule(db: DatabaseSync, context: WriteContext, request: ModuleRequest): WriteResult<ModuleRow, ModuleRow> {
   checkModule(request);
   return result(write(db, context, "set-module", (change) => moduleStep(db, change, context.origin, request)));
 }
@@ -1051,7 +1089,7 @@ export const MAX_BATCH = 10_000;
 /** The result of each write of a batch, in order. */
 export type BatchStep = Step<
   SymbolRow | RegionRow[] | CommentRow | ReferenceRow | ModuleRow | OperandRow | PatchRow | MacroRow | MacroUseRow | null,
-  SymbolRow | RegionRow[] | OperandRow | PatchRow | MacroRow | MacroUseRow
+  SymbolRow | RegionRow[] | CommentRow | ReferenceRow | ModuleRow | OperandRow | PatchRow | MacroRow | MacroUseRow
 >;
 
 /**
@@ -1199,19 +1237,25 @@ const KEYS = {
 
 /**
  * Makes the current knowledge equal to what it was at `revision`, as a new
- * revision. History is never erased; restored rows keep their origin.
+ * revision. With `space`, only the rows of that space change; without it,
+ * every space changes. History is never erased; restored rows keep their origin.
  */
-export function revert(db: DatabaseSync, context: WriteContext, request: { revision: string }): WriteResult<{ restoredRevision: string }> {
+export function revert(db: DatabaseSync, context: WriteContext, request: { revision: string; space?: Space }): WriteResult<{ restoredRevision: string }> {
+  checkSpace(request);
   const restored = resolveRevision(db, request.revision);
-  return write(db, { ...context, restores: restored }, "revert", (change) => {
+  const only = request.space;
+  return write(db, { ...context, restores: restored, ...(only === undefined ? {} : { restoresSpace: only }) }, "revert", (change) => {
     // The coverage maps that the knowledge has follow the revert, also when no coverage range changes.
-    const maps = (runs: CoverageRun[]) => JSON.stringify(runs.map((run) => [run.name, run.sha256, run.space, run.revision]));
+    const maps = (runs: CoverageRun[]) => JSON.stringify(runs.filter((run) => only === undefined || run.space === only).map((run) => [run.name, run.sha256, run.space, run.revision]));
     if (maps(coverageRuns(db, restored)) !== maps(coverageRuns(db))) change.id();
-    const at = "valid_from_revision <= ? AND (valid_to_revision IS NULL OR valid_to_revision > ?)";
+    const inSpace = only === undefined ? "" : " AND space = ?";
+    const spaceArgs = only === undefined ? [] : [only];
+    const at = `valid_from_revision <= ? AND (valid_to_revision IS NULL OR valid_to_revision > ?)${inSpace}`;
+    const current = `valid_to_revision IS NULL${inSpace}`;
     for (const [table, spec] of Object.entries(KEYS)) {
       const name = table === "references" ? '"references"' : table;
-      const then = db.prepare(`SELECT ${spec.columns}, id FROM ${name} WHERE ${at}`).all(restored, restored) as Array<Record<string, unknown>>;
-      const now = db.prepare(`SELECT ${spec.columns}, id FROM ${name} WHERE valid_to_revision IS NULL`).all() as Array<Record<string, unknown>>;
+      const then = db.prepare(`SELECT ${spec.columns}, id FROM ${name} WHERE ${at}`).all(restored, restored, ...spaceArgs) as Array<Record<string, unknown>>;
+      const now = db.prepare(`SELECT ${spec.columns}, id FROM ${name} WHERE ${current}`).all(...spaceArgs) as Array<Record<string, unknown>>;
       const key = (row: Record<string, unknown>) => (spec.key as (row: unknown) => string)(spec.map(row as never));
       const thenKeys = new Set(then.map(key));
       const nowKeys = new Set(now.map(key));
@@ -1253,8 +1297,8 @@ export function revert(db: DatabaseSync, context: WriteContext, request: { revis
     }
     // The program: a row is the same when all its values are the same.
     for (const [table, columns] of PROGRAM_TABLES) {
-      const then = db.prepare(`SELECT ${columns}, id FROM ${table} WHERE ${at}`).all(restored, restored) as Array<Record<string, unknown>>;
-      const now = db.prepare(`SELECT ${columns}, id FROM ${table} WHERE valid_to_revision IS NULL`).all() as Array<Record<string, unknown>>;
+      const then = db.prepare(`SELECT ${columns}, id FROM ${table} WHERE ${at}`).all(restored, restored, ...spaceArgs) as Array<Record<string, unknown>>;
+      const now = db.prepare(`SELECT ${columns}, id FROM ${table} WHERE ${current}`).all(...spaceArgs) as Array<Record<string, unknown>>;
       const key = (row: Record<string, unknown>) => JSON.stringify(columns.split(", ").map((column) => row[column]));
       const thenKeys = new Set(then.map(key));
       const nowKeys = new Set(now.map(key));

package/src/mcp/inputs.ts

@@ -33,12 +33,15 @@ export const AddressInput = z
   .transform((value) => c64AddressOf(value)!)
   .describe("C64 address: $ and 1 to 4 hex digits, $0000 to $ffff");
 
+/** The space of a memory target or condition: the emulator tests only C64 memory. */
+const MemorySpaceInput = SpaceInput.describe("c64 only: the emulator tests only C64 memory. For the drive, use a watchpoint or an address target in space drive8");
+
 const rasterLine = z.number().int().min(0).max(MAX_RASTER_LINE).describe("raster line: PAL 0-311, NTSC 0-262");
 
 const condition = z
   .discriminatedUnion("kind", [
     z.object({ kind: z.literal("register"), register: z.enum(CONDITION_REGISTERS), operator: z.enum(COMPARISONS), value: Byte }).strict(),
-    z.object({ kind: z.literal("memory"), address: AddressInput, operator: z.enum(COMPARISONS), value: Byte, space: SpaceInput, view: MemoryViewInput }).strict(),
+    z.object({ kind: z.literal("memory"), address: AddressInput, operator: z.enum(COMPARISONS), value: Byte, space: MemorySpaceInput, view: MemoryViewInput }).strict(),
     z.object({ kind: z.literal("raster"), line: rasterLine, cycle: z.number().int().min(0).max(64).optional().describe("cycle in the line: PAL 0-62, NTSC 0-64. True from this cycle on") }).strict(),
   ])
   .describe("register: a CPU register compared to a byte. memory: a byte in memory compared to a byte. raster: the raster position");
@@ -50,7 +53,7 @@ export const TOOL_INPUTS = {
 
   runTarget: z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("address"), address: AddressInput, space: SpaceInput, condition: condition.optional().describe("stop at the address only when this is true") }).strict(),
-    z.object({ kind: z.literal("memory"), address: AddressInput, operator: z.enum(COMPARISONS), value: Byte, space: SpaceInput, view: MemoryViewInput }).strict(),
+    z.object({ kind: z.literal("memory"), address: AddressInput, operator: z.enum(COMPARISONS), value: Byte, space: MemorySpaceInput, view: MemoryViewInput }).strict(),
     z.object({ kind: z.literal("raster"), line: rasterLine, cycle: z.number().int().min(0).max(64).optional().describe("cycle in the line: PAL 0-62, NTSC 0-64. Default 0") }).strict(),
   ]),
 
@@ -82,7 +85,7 @@ export const TOOL_INPUTS = {
 
   joystick: z
     .object({
-      port: z.union([z.literal(1), z.literal(2)]).describe("control port 1 or 2"),
+      port: z.union([z.literal(1), z.literal(2)], { error: "port must be the number 1 or 2" }).describe("control port 1 or 2"),
       direction: z.enum(JOYSTICK_DIRECTIONS),
       fire: z.boolean().default(false),
     })

package/src/mcp/output.ts

@@ -7,7 +7,7 @@ import { z } from "zod";
 
 import { projectFolder, writeReported, type Written } from "../host-client/transfer.ts";
 
-export const OutInput = z.string().min(1).describe("write the result to this file, relative to the project folder, in place of returning it. An existing file is overwritten");
+export const OutInput = z.string().min(1).describe("write the data to this file, relative to the project folder. An existing file is overwritten. The tool description tells what the result then gives");
 
 /** The project of a tool with a path. */
 export const ProjectInput = z

package/src/mcp/server.ts

@@ -10,6 +10,7 @@ import { z } from "zod";
 import { formatC64Address } from "../c64.ts";
 import { Byte, TOOL_INPUTS } from "./inputs.ts";
 import { LostBeforeAnswer, type ViceSessionClient } from "../host-client/vice-session.ts";
+import { checkOut } from "../host-client/transfer.ts";
 import { isRefusal } from "../errors.ts";
 import { shownMessage, WireFailure, type WireError } from "../protocol/messages.ts";
 import { COMPARISONS, CONDITION_REGISTERS, MEMORY_VIEWS, SPACES, type Condition } from "../protocol/vice.ts";
@@ -179,10 +180,14 @@ function errorResult(error: WireError): CallToolResult {
  * An unknown field of the tool input also gets the fields that the tool takes.
  */
 function describeIssues(error: z.ZodError, input?: z.ZodObject): string {
+  // An unknown field also breaks the rules that look at the whole object: name only the field.
+  const unknown = error.issues.some((issue) => issue.code === "unrecognized_keys");
   return error.issues
+    .filter((issue) => !unknown || issue.code !== "custom")
     .map((issue) => {
       const where = issue.path.length === 0 ? "input" : issue.path.join(".");
-      const fields = issue.code === "unrecognized_keys" && issue.path.length === 0 && input !== undefined ? `. The fields are ${Object.keys(input.shape).join(", ")}` : "";
+      const names = input === undefined ? [] : Object.keys(input.shape);
+      const fields = issue.code !== "unrecognized_keys" || issue.path.length !== 0 || input === undefined ? "" : names.length === 0 ? ". The tool takes no fields" : `. The fields are ${names.join(", ")}`;
       return `${where}: ${issue.message}${fields}`;
     })
     .join(". ");
@@ -228,6 +233,9 @@ async function runCall(
   const parsed = tool.inputSchema.safeParse(args ?? {});
   if (!parsed.success) return errorResult({ code: "invalid-input", message: describeIssues(parsed.error, tool.inputSchema) });
   try {
+    // An out path is checked before the tool runs: a refused path must not lose the work or leave its side effects.
+    const fields = parsed.data as { out?: unknown; project?: unknown };
+    if (typeof fields.out === "string") checkOut(fields.out, typeof fields.project === "string" ? fields.project : undefined);
     let output: unknown;
     try {
       output = await tool.run(parsed.data, await session());

package/src/mcp/tools/debug.ts

@@ -186,7 +186,8 @@ export const c64Trace = defineTool({
     "Each hit gives the instruction (pc, bytes, text) and the registers a, x, y and sp before it. " +
     "point in a hit is the number of its point in points, 0 for the first. " +
     "It also gives the frame from 0, and the raster line and cycle where the instruction started. " +
-    "A read or write hit also gives the address that the instruction used, and the byte there after the access. " +
+    "A read or write hit also gives the address that the instruction used, and value, the byte that it read or wrote. " +
+    "At $D000-$DFFF only a load or a store gives value: a read after the access can give another byte. " +
     `The trace ends after frames frames (1 to ${MAX_TRACE_FRAMES}), at maxHits hits (at most ${MAX_TRACE_HITS}), or at a breakpoint, a watchpoint or a JAM. ` +
     `The result lists the first ${TRACE_LISTED} hits. With out, it writes all hits as JSON lines to that project file. ` +
     "Each hit stops the machine for a short time. Thus a point with many hits in each frame makes the trace slow. Use a small range and a maxHits. " +
@@ -339,7 +340,9 @@ export const c64Memmap = defineTool({
     "A read on a byte right after executed code, or at a return address, can be a dummy read that the CPU does not use. " +
     "Action summary gives the counts for RAM, ROM and I/O. It also gives the executed code in RAM with its operand bytes, and the RAM that was written and executed. " +
     `Each list has at most ${MAX_SUMMARY_RANGES} ranges. ` +
-    "Action clear sets all access records to zero.",
+    "Action clear sets all access records to zero. " +
+    "The emulator decides RAM, ROM or I/O from one bit of $01. At $A000-$BFFF it gives ROM when bit 0 is set, also when bit 1 is clear and the CPU used RAM. " +
+    "Every access at $D000-$DFFF is I/O, also when $01 shows RAM or the character ROM there. emulatorFlaw in the result tells when ROM at $A000-$BFFF can be RAM.",
   inputSchema: z
     .object({
       action: z.enum(["read", "summary", "clear"]),
@@ -362,6 +365,7 @@ export const c64Memmap = defineTool({
     writtenAndExecuted: z.array(RangeOutput).optional(),
     writtenAndExecutedTruncated: z.boolean().optional(),
     cleared: z.boolean().optional(),
+    emulatorFlaw: z.string().optional().describe("a known flaw of VICE that can make the ROM and I/O classes wrong in this result"),
     ...WrittenOutput,
   }),
   readOnly: false,
@@ -391,12 +395,14 @@ export const c64Memmap = defineTool({
         ...(code.length > MAX_SUMMARY_RANGES ? { codeTruncated: true } : {}),
         writtenAndExecuted: showRanges(written),
         ...(written.length > MAX_SUMMARY_RANGES ? { writtenAndExecutedTruncated: true } : {}),
+        ...basicRomFlaw(romInBasicArea(map, start)),
       };
     }
     requireOut(fields, ["maxRanges"]);
     requireFields("read", fields, ["start", "end", "maxRanges", "out", "project"]);
     if (fields.out !== undefined) {
-      return writeOut(fields.out, await readCoverage(session, start, end), fields.project);
+      const map = await readCoverage(session, start, end);
+      return { ...writeOut(fields.out, map, fields.project), ...basicRomFlaw(romInBasicArea(map, start)) };
     }
     const result = await session.memmap({ action: "read", start, end, maxRanges: fields.maxRanges ?? 256 });
     const ranges = result.ranges.map((range) => ({
@@ -407,8 +413,29 @@ export const c64Memmap = defineTool({
       write: (range.flags & WRITE) !== 0,
       in: sources(range.flags),
     }));
-    return result.next === undefined ? { ranges } : { ranges, truncated: true, next: formatC64Address(result.next) };
+    const flaw = basicRomFlaw(result.ranges.some((range) => range.start <= 0xbfff && range.end >= 0xa000 && (range.flags & ROM_ACCESS) !== 0));
+    return result.next === undefined ? { ranges, ...flaw } : { ranges, truncated: true, next: formatC64Address(result.next), ...flaw };
   },
 });
 
+const ROM_ACCESS = COVERAGE.romRead | COVERAGE.romExecute;
+
+/** True when the map from `start` has a ROM access at $A000-$BFFF. */
+function romInBasicArea(map: Uint8Array, start: number): boolean {
+  for (let address = Math.max(start, 0xa000); address <= Math.min(start + map.length - 1, 0xbfff); address++) {
+    if ((map[address - start]! & ROM_ACCESS) !== 0) return true;
+  }
+  return false;
+}
+
+/** VICE tests only bit 0 of $01 for $A000-$BFFF; the C64 shows BASIC ROM there only when bits 0 and 1 are set. */
+function basicRomFlaw(present: boolean): { emulatorFlaw?: string } {
+  if (!present) return {};
+  return {
+    emulatorFlaw:
+      "The emulator gives ROM for an access at $A000-$BFFF when bit 0 of $01 is set, also when bit 1 is clear and the CPU used the RAM there. " +
+      "Read $01 of the program at that time before you take rom at $A000-$BFFF as the BASIC ROM.",
+  };
+}
+
 export const debugTools = [c64Breakpoint, c64Watchpoint, c64CpuHistory, c64Trace, c64Backtrace, c64Profile, c64Memmap, c64Timing];

package/src/mcp/tools/machine.ts

@@ -5,7 +5,7 @@ import { z } from "zod";
 import { formatC64Address } from "../../c64.ts";
 import { PACKAGE } from "../../package.ts";
 import { VIDEO_STANDARDS } from "../../protocol/messages.ts";
-import { POINT_STOP_REASONS, RESET_MODES, RUN_STATES, WINDOW_ACTIONS } from "../../protocol/vice.ts";
+import { POINT_STOP_REASONS, RESET_MODES, RUN_STATES, SPACES, WINDOW_ACTIONS } from "../../protocol/vice.ts";
 import { AddressOutput, defineTool } from "../server.ts";
 
 export const c64Status = defineTool({
@@ -27,6 +27,7 @@ export const c64Status = defineTool({
     pc: AddressOutput.optional().describe("program counter. Only when the CPU is stopped"),
     stopReason: z.enum(POINT_STOP_REASONS).optional().describe("what stopped the CPU. Only when a breakpoint, a watchpoint or a JAM opcode stopped it"),
     pointId: z.number().int().min(1).optional().describe("the id of the breakpoint or watchpoint that stopped the CPU"),
+    space: z.enum(SPACES).optional().describe("with pc: c64, or drive8 when a breakpoint or watchpoint in the disk drive stopped the CPU. pc is the address in that space"),
     cartridge: z.boolean().describe("true while a cartridge from c64_autostart is attached"),
     version: z.string().describe("the c64-re-tools version of this MCP server"),
   }),
@@ -43,6 +44,7 @@ export const c64Status = defineTool({
       ...(status.pc === undefined ? {} : { pc: formatC64Address(status.pc) }),
       ...(status.stopReason === undefined ? {} : { stopReason: status.stopReason }),
       ...(status.pointId === undefined ? {} : { pointId: status.pointId }),
+      ...(status.space === undefined ? {} : { space: status.space }),
     };
   },
 });

package/src/mcp/tools/media.ts

@@ -44,6 +44,10 @@ export const c64Autostart = defineTool({
   }),
   readOnly: false,
   async run(input, session) {
+    const type = extname(input.path).slice(1).toLowerCase();
+    if (input.index !== undefined && !(DISK_TYPES as readonly string[]).includes(type)) {
+      throw new WireFailure("invalid-input", `index selects an entry of a disk image (${list(DISK_TYPES)}). A .${type} file has no directory: leave out index.`);
+    }
     // VICE numbers the directory entries from 1, and its 0 loads "*".
     return session.autostart({ path: input.path, index: input.index === undefined ? 0 : input.index + 1, run: input.run, root: projectFolder(input.project) });
   },
@@ -131,7 +135,7 @@ export const c64Snapshot = defineTool({
     }
     if (action === "restore" && fields.file !== undefined) {
       requireFields(action, fields, ["file", "project"], ["file"]);
-      return session.snapshotRestore(readProjectFile(fields.file, { root: projectFolder(fields.project) }).bytes);
+      return session.snapshotRestore(readProjectFile(fields.file, { root: projectFolder(fields.project), what: "file" }).bytes);
     }
     if (action === "save") {
       requireOut(fields);

package/src/mcp/tools/memory.ts

@@ -123,7 +123,7 @@ export const c64MemorySearch = defineTool({
   title: "Search C64 memory",
   description:
     `Find a byte pattern of 1 to ${MAX_SEARCH_PATTERN} bytes in memory from start to end. ?? matches any byte. ` +
-    `The result gives the start address of each match, at most maxResults (1 to ${MAX_SEARCH_RESULTS}, default 100). ` +
+    `The result gives the start address of each match, at most maxResults (1 to ${MAX_SEARCH_RESULTS}, default 100). truncated: true tells that more matches can follow. ` +
     "This does not change the run state of the machine.",
   inputSchema: z
     .object({
@@ -135,7 +135,7 @@ export const c64MemorySearch = defineTool({
       maxResults: z.number().int().min(1).max(MAX_SEARCH_RESULTS).default(100),
     })
     .strict(),
-  outputSchema: z.object({ matches: z.array(AddressOutput) }),
+  outputSchema: z.object({ matches: z.array(AddressOutput), truncated: z.boolean().optional().describe("true when the result has maxResults matches: more can follow. Search again from the address after the last match") }),
   readOnly: true,
   async run(input, session) {
     if (input.pattern.length > MAX_SEARCH_PATTERN) {
@@ -147,7 +147,8 @@ export const c64MemorySearch = defineTool({
     // VICE refuses a range shorter than the pattern. Such a range has no match.
     if (end - input.start + 1 < input.pattern.length) return { matches: [] };
     const result = await session.memorySearch({ ...input, end });
-    return { matches: result.matches.map(formatC64Address) };
+    const matches = result.matches.map(formatC64Address);
+    return matches.length >= input.maxResults ? { matches, truncated: true } : { matches };
   },
 });