@henols/c64-re-tools 2.1.0-rc.2 → 2.1.1

package/src/host-client/steps.ts

@@ -63,6 +63,8 @@ export type ActionStep =
 
 export const ACTION_STEP_KINDS = ["write", "registers", "joystick", "type", "press", "frames", "runUntil"] as const;
 export type ActionStepKind = (typeof ACTION_STEP_KINDS)[number];
+/** The step kinds that VICE runs: all but press, which only the replay core has. */
+export const VICE_STEP_KINDS = ACTION_STEP_KINDS.filter((kind) => kind !== "press");
 
 /** The fields of each object of the steps: the same as the inputs of the MCP tools. */
 export const STEP_FIELDS = {
@@ -110,6 +112,32 @@ export function keyboardBytes(input: { mode: "text" | "petscii"; text?: string |
   }
 }
 
+/**
+ * One line of JSON with a space after each colon and comma: the form that a
+ * refusal tells the caller to write.
+ */
+export function jsonLine(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(jsonLine).join(", ")}]`;
+  if (isObject(value)) return `{${Object.entries(value).filter(([, item]) => item !== undefined).map(([key, item]) => `${JSON.stringify(key)}: ${jsonLine(item)}`).join(", ")}}`;
+  return JSON.stringify(value) ?? "null";
+}
+
+/** Field names of the 2.0 files and what a 2.1 object has in their place, when it has that field. */
+const RENAMED: Record<string, Array<{ field: string; write: string }>> = {
+  at: [
+    { field: "address", write: "address" },
+    { field: "start", write: "start" },
+  ],
+  bytes: [{ field: "data", write: 'data, the bytes as hex text, for example "data": "a900",' }],
+  equals: [{ field: "operator", write: '"operator": "eq" and "value"' }],
+};
+
+/** What to write in place of a field of the 2.0 files, for an object with these fields; undefined when the field has no 2.1 name there. */
+export function renamedField(key: string, fields: readonly string[]): string | undefined {
+  const renamed = RENAMED[key]?.find((item) => fields.includes(item.field));
+  return renamed === undefined ? undefined : `${key} is a 2.0 field. Write ${renamed.write} in place of ${key}`;
+}
+
 /** The checks of one input: `fail` names the field of the problem. */
 class Fields {
   readonly #value: Record<string, unknown>;
@@ -121,7 +149,11 @@ class Fields {
     this.#fail = fail;
     if (!isObject(value)) fail(`${where} must be an object with ${fields.join(", ")}`);
     this.#value = value as Record<string, unknown>;
-    for (const key of Object.keys(this.#value)) if (!fields.includes(key)) fail(`${where} has the field ${key}, which it does not take. Its fields are ${fields.join(", ")}`);
+    for (const key of Object.keys(this.#value)) {
+      if (fields.includes(key)) continue;
+      const renamed = renamedField(key, fields);
+      fail(`${where} has the field ${key}, which it does not take. ${renamed === undefined ? "" : `${renamed}. `}Its fields are ${fields.join(", ")}`);
+    }
   }
 
   fail(field: string, message: string): never {
@@ -256,22 +288,90 @@ function checkInput(kind: ActionStepKind, value: unknown, at: string, fail: (mes
   }
 }
 
+/** A "$xxxx" text of a number, or the value as it is. */
+const asAddress = (value: unknown) => (isInteger(value, 0, 0xffff) ? `$${value.toString(16).padStart(4, "0")}` : value);
+
+/** The hex text of a list of bytes, or the value as it is. */
+const asHex = (value: unknown) => (Array.isArray(value) && value.every((byte) => isInteger(byte, 0, 0xff)) ? Buffer.from(value as number[]).toString("hex") : value);
+
+/** A runUntil target from the 2.0 input: at (with raster), raster, or memory with at and equals. */
+function targetOf(input: Record<string, unknown>): unknown {
+  if ("target" in input) return input.target;
+  if (isObject(input.memory)) return { kind: "memory", address: input.memory.at ?? input.memory.address, operator: "eq", value: input.memory.equals };
+  if ("at" in input) return { kind: "address", address: input.at, ...(input.raster === undefined ? {} : { condition: { kind: "raster", line: input.raster } }) };
+  return { kind: "raster", line: input.raster };
+}
+
+/**
+ * The 2.1 form of a step that has a form of the 2.0 files: the 2.0 fields
+ * that it has and the step to write. Undefined when the step has no 2.0 form.
+ * Keys of the step other than its kind (for example side) stay.
+ */
+export function newStepForm(kind: string, step: Record<string, unknown>): { fields: string[]; step: Record<string, unknown> } | undefined {
+  const input = step[kind];
+  const { [kind]: _input, ...rest } = step;
+  const form = (fields: string[], value: unknown, others = rest) => ({ fields, step: { [kind]: value, ...others } });
+  switch (kind) {
+    case "runUntil": {
+      const { timeoutFrames: beside, ...others } = rest;
+      const old = isObject(input) && !("target" in input) && ("at" in input || "raster" in input || "memory" in input);
+      if (!isObject(input) || (!old && beside === undefined)) return undefined;
+      const fields = [...(old ? ["at", "raster", "memory"].filter((key) => key in input).map((key) => `runUntil.${key}`) : []), ...(beside === undefined ? [] : ["timeoutFrames beside runUntil"])];
+      const timeoutFrames = beside ?? input.timeoutFrames;
+      return form(fields, { target: targetOf(input), ...(timeoutFrames === undefined ? {} : { timeoutFrames }) }, others);
+    }
+    case "type":
+      return typeof input === "string" ? form(["type as text"], { mode: "text", text: input }) : undefined;
+    case "write": {
+      if (!isObject(input) || !("at" in input || "bytes" in input || Array.isArray(input.data))) return undefined;
+      const { at: old, bytes, address, data, ...others } = input;
+      return form(
+        ["at", "bytes"].filter((key) => key in input).map((key) => `write.${key}`).concat(Array.isArray(data) ? ["write.data as a list"] : []),
+        { address: address ?? old, data: asHex(data ?? bytes), ...others },
+      );
+    }
+    case "registers": {
+      if (!isObject(input)) return undefined;
+      const fields = Object.entries(input).flatMap(([name, value]) => ((name === "pc" && typeof value === "number") || (name !== "pc" && name !== "flags" && typeof value === "string" && c64AddressOf(value) !== undefined) ? [`registers.${name} as ${typeof value === "number" ? "a number" : "text"}`] : []));
+      if (fields.length === 0) return undefined;
+      const values = Object.fromEntries(Object.entries(input).map(([name, value]) => [name, name === "pc" ? asAddress(value) : typeof value === "string" ? (c64AddressOf(value) ?? value) : value]));
+      return form(fields, values);
+    }
+    default:
+      return undefined;
+  }
+}
+
+/** Refuses a step in a form of the 2.0 files: the message names its 2.0 fields and gives the step to write. */
+export function refuseOldStep(kind: string, step: Record<string, unknown>, at: string, fail: (message: string) => never): void {
+  const found = newStepForm(kind, step);
+  if (found === undefined) return;
+  const petscii = kind === "type" ? ', or {"type": {"mode": "petscii", "bytes": [...]}} for PETSCII codes' : "";
+  fail(`${at} has the 2.0 form (${found.fields.join(", ")}). Write ${jsonLine(found.step)}${petscii}`);
+}
+
 /**
  * Checks one action step of the given kind and returns it with the defaults
  * filled in. The step has no other key. `press` is refused unless the caller
- * runs the steps on the replay core.
+ * runs the steps on the replay core. A step in a form of the 2.0 files is
+ * refused with the step to write.
  */
 export function checkActionStep(kind: ActionStepKind, step: Record<string, unknown>, at: string, fail: (message: string) => never, options: { press?: boolean } = {}): ActionStep {
+  refuseOldStep(kind, step, at, fail);
   for (const key of Object.keys(step)) if (key !== kind) fail(`${at} has the key ${key}, which a ${kind} step does not have`);
   if (kind === "press" && options.press !== true) fail(`${at}: ${PRESS_REMEDY}`);
   return checkInput(kind, step[kind], at, fail);
 }
 
-/** The kind of a step: its one key from `kinds`. */
-export function stepKind<K extends string>(step: unknown, kinds: readonly K[], at: string, fail: (message: string) => never): K {
+/**
+ * The kind of a step: its one key from `kinds`. A refusal lists `shown`: the
+ * kinds that the caller runs.
+ */
+export function stepKind<K extends string>(step: unknown, kinds: readonly K[], at: string, fail: (message: string) => never, shown: readonly string[] = kinds): K {
   if (!isObject(step)) return fail(`${at} must be an object`);
   const found = Object.keys(step).filter((key) => (kinds as readonly string[]).includes(key));
-  if (found.length !== 1) return fail(`${at} must have exactly one of ${kinds.join(", ")}`);
+  if (found.length > 1) return fail(`${at} has ${found.length} step kinds: ${found.join(", ")}. Give each one its own step`);
+  if (found.length !== 1) return fail(`${at} must have exactly one of ${shown.join(", ")}`);
   return found[0] as K;
 }
 
@@ -280,7 +380,7 @@ export function checkActionSteps(value: unknown, fail: (message: string) => neve
   if (!Array.isArray(value) || value.length === 0) return fail("the steps are a JSON list with at least one step");
   return value.map((step: unknown, index) => {
     const at = `step ${index + 1}`;
-    return checkActionStep(stepKind(step, ACTION_STEP_KINDS, at, fail), step as Record<string, unknown>, at, fail, options);
+    return checkActionStep(stepKind(step, ACTION_STEP_KINDS, at, fail, options.press === true ? ACTION_STEP_KINDS : VICE_STEP_KINDS), step as Record<string, unknown>, at, fail, options);
   });
 }
 

package/src/host-client/tools.ts

@@ -85,6 +85,6 @@ export async function hostTools(options: ToolCallOptions = {}): Promise<{ host:
 
 /** Skill scripts see failures and wire limits through the host-client, never the private protocol module. */
 export { WireFailure } from "../protocol/messages.ts";
-export { DISK_ACTIONS } from "../protocol/tools.ts";
+export { DISK_ACTIONS, DISK_IMAGE_TYPES } from "../protocol/tools.ts";
 export { JOYSTICK_DIRECTIONS, MAX_BASELINES, MAX_EXECUTION_COUNT, MAX_KEYBOARD_BYTES, MAX_MASK_RECTANGLES, MAX_MEMORY_READ, MAX_MEMORY_WRITE, MAX_TIMEOUT_FRAMES, maskCoversFrame } from "../protocol/vice.ts";
 export { MAX_TRACE_FRAMES, MAX_TRACE_HITS, MAX_TRACE_POINTS, TRACE_KINDS, type TraceHit, type TraceKind } from "../protocol/vice.ts";

package/src/host-client/transfer.ts

@@ -58,10 +58,33 @@ 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}.`);
+}
+
 /**
  * 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.
+ * 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.
  */
 export function writeProjectFile(path: string, bytes: Uint8Array, options: { root?: string; what?: string } = {}): void {
   const root = options.root ?? currentProject();
@@ -76,16 +99,20 @@ export function writeProjectFile(path: string, bytes: Uint8Array, options: { roo
   let existing = dirname(file);
   while (!existsSync(existing)) existing = dirname(existing);
   if (!isInside(realpathSync(root), realpathSync(existing))) throw refuse();
-  mkdirSync(dirname(file), { recursive: true });
-  if (!isInside(realpathSync(root), realpathSync(dirname(file)))) throw refuse();
-  let link = false;
   try {
-    link = lstatSync(file).isSymbolicLink();
+    mkdirSync(dirname(file), { recursive: true });
+    if (!isInside(realpathSync(root), realpathSync(dirname(file)))) throw refuse();
+    let link = false;
+    try {
+      link = lstatSync(file).isSymbolicLink();
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+    if (link) throw refuse();
+    writeFileSync(file, bytes);
   } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    throw writeRefusal(error, path, options.what) ?? error;
   }
-  if (link) throw refuse();
-  writeFileSync(file, bytes);
 }
 
 /** Directories never staged: version control and the toolkit's own project state. */

package/src/knowledge/expression.ts

@@ -119,7 +119,7 @@ function value(node: Node, resolve: (name: string) => number | undefined): numbe
       return node.value;
     case "name": {
       const found = resolve(node.name);
-      if (found === undefined) throw new Refusal("invalid-input", `"${node.name}" is no symbol of the knowledge and no platform name.`);
+      if (found === undefined) throw new Refusal("invalid-input", `${node.name} is not a symbol of the knowledge or a platform name. Give a number, a symbol that knowledge.ts symbols lists, or a platform name that memory-map.ts at gives.`);
       return found;
     }
     case "unary": {

package/src/knowledge/history.ts

@@ -38,7 +38,7 @@ import {
   type SymbolRow,
 } from "./read.ts";
 import { DEFAULT_SPACE, type EvidenceKind, type Origin, type Space } from "./schema.ts";
-import { compareText } from "./text.ts";
+import { compareText, NO_REVISION } from "./text.ts";
 import type { Evidence } from "./write.ts";
 
 export interface Revision {
@@ -49,6 +49,8 @@ export interface Revision {
   description?: string;
   inputHash?: string;
   toolVersion?: string;
+  /** A revert: the revision whose knowledge it restored. */
+  restores?: string;
   /** What the change rests on. */
   evidence?: Evidence[];
 }
@@ -79,6 +81,7 @@ function toRevision(row: Raw): Revision {
   if (row.description !== null) revision.description = row.description as string;
   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;
   return revision;
 }
 
@@ -170,8 +173,21 @@ export function revisions(db: DatabaseSync | undefined, options: { limit?: numbe
   return (rows as Raw[]).map((row) => withEvidence(db, toRevision(row)));
 }
 
+/** Revision 0: the knowledge before every revision. It is empty, and no write made it, so it has no time, origin or evidence. */
+export interface InitialRevision {
+  id: typeof NO_REVISION;
+  operation: "none";
+  description: string;
+  createdAt?: undefined;
+  origin?: undefined;
+  inputHash?: undefined;
+  toolVersion?: undefined;
+  restores?: undefined;
+  evidence?: undefined;
+}
+
 export interface RevisionChanges {
-  revision: Revision;
+  revision: Revision | InitialRevision;
   /** Rows this revision made current. */
   added: HistoryEntry[];
   /** Rows this revision closed. */
@@ -181,6 +197,7 @@ export interface RevisionChanges {
 /** One revision and exactly what it changed. */
 export function revision(db: DatabaseSync | undefined, text: string): RevisionChanges {
   const id = resolveRevision(db, text);
+  if (id === NO_REVISION) return { revision: { id: NO_REVISION, operation: "none", description: "The knowledge before every revision. It is empty." }, added: [], closed: [] };
   const raw = db?.prepare("SELECT * FROM revisions WHERE id = ?").get(id) as Raw | undefined;
   if (db === undefined || raw === undefined) throw new Refusal("not-found", `There is no revision ${id}.`);
   const tables = [

package/src/knowledge/names.ts

@@ -20,7 +20,8 @@ export function addressOfName(db: DatabaseSync | undefined, name: string, space:
   if (addresses.length === 1) return addresses[0]!;
   const where = space === DEFAULT_SPACE ? "" : ` in ${space}`;
   if (addresses.length > 1) throw new Refusal("invalid-input", `the analyzers give ${name} to ${rows.map((row) => `${formatC64Address(row.address)} (${row.origin})`).join(" and ")}${where}. Give the address`);
-  throw new Refusal("not-found", `no symbol or analyzer name${where} is ${name}`);
+  const option = space === DEFAULT_SPACE ? "" : ` --space ${space}`;
+  throw new Refusal("not-found", `${name} is not a name in the knowledge${where}. Give a $ address, or a name that knowledge.ts symbols${option} lists, with or without --analyzer.`);
 }
 
 /** Every name of a space with its address: the symbols, and each analyzer name that addressOfName accepts. With kinds, only names of those kinds. */

package/src/knowledge/program.ts

@@ -10,6 +10,7 @@ import { Refusal } from "../errors.ts";
 import { type AddressRange, COVERAGE, formatC64Address } from "../c64.ts";
 
 import { COVERAGE_KINDS, DEFAULT_SPACE, MEMORY_ROW, type CoverageKind, type Space } from "./schema.ts";
+import { coverageRuns } from "./read.ts";
 import { checkSpace, write, type Evidence, type WriteContext } from "./write.ts";
 
 /** The 64 KiB of one space: offset n is address n. */
@@ -147,22 +148,6 @@ function currentCoverage(db: DatabaseSync, space: Space): Map<CoverageKind, Uint
   return maps;
 }
 
-/** One import of a coverage map: its project path, its SHA-256, the space it went into and the revision. */
-export interface CoverageRun {
-  name: string;
-  sha256: string;
-  space: Space;
-  revision: string;
-}
-
-/** The imports of coverage maps, by name and then oldest first: the last import of a name is the latest. */
-export function coverageRuns(db: DatabaseSync | undefined): CoverageRun[] {
-  if (db === undefined) return [];
-  return db
-    .prepare(`SELECT DISTINCT e.ref AS name, e.sha256 AS sha256, coalesce(e.space, '${DEFAULT_SPACE}') AS space, e.revision AS revision FROM evidence e JOIN revisions r ON r.id = e.revision WHERE r.operation = 'coverage' AND e.kind = 'coverage' ORDER BY e.ref, e.revision`)
-    .all() as unknown as CoverageRun[];
-}
-
 /**
  * Joins coverage maps into the coverage of a space: adds the ranges of
  * the flags that no imported run set before, and as wx the addresses that one

package/src/knowledge/read.ts

@@ -243,6 +243,49 @@ export function currentRevision(db: DatabaseSync | undefined): string {
   return (db.prepare("SELECT max(id) AS id FROM revisions").get() as { id: string | null }).id ?? "0";
 }
 
+/** One import of a coverage map: its project path, its SHA-256, the space it went into and the revision. */
+export interface CoverageRun {
+  name: string;
+  sha256: string;
+  space: Space;
+  revision: string;
+}
+
+/**
+ * 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.
+ * 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
+       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 }>;
+  // The maps after each revision that changed them, oldest first.
+  const after: Array<{ id: string; runs: CoverageRun[] }> = [];
+  let runs: CoverageRun[] = [];
+  for (const row of rows) {
+    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;
+    } 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];
+    }
+    if (after.at(-1)?.id === row.id) after[after.length - 1]!.runs = runs;
+    else after.push({ id: row.id, runs });
+  }
+  return [...runs].sort((a, b) => (a.name === b.name ? (a.revision < b.revision ? -1 : a.revision > b.revision ? 1 : 0) : a.name < b.name ? -1 : 1));
+}
+
 /** At most this many ids are named when a start of an id fits several revisions. */
 const NAMED_REVISIONS = 5;
 

package/src/knowledge/schema.ts

@@ -113,7 +113,8 @@ function createSchema(db: DatabaseSync): void {
         operation    TEXT NOT NULL,
         input_hash   TEXT,
         tool_version TEXT,
-        description  TEXT
+        description  TEXT,
+        restored_revision TEXT
       );
       CREATE TABLE symbols (
         id                  TEXT PRIMARY KEY,
@@ -316,7 +317,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 = 6;
+export const INDEX_VERSION = 7;
 
 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

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

package/src/knowledge/write.ts

@@ -32,6 +32,7 @@ import {
   referencesFrom,
   REGION_COLUMNS,
   regionsOverlapping,
+  coverageRuns,
   resolveRevision,
   SUPPRESSION_COLUMNS,
   suppressionsOverlapping,
@@ -49,6 +50,7 @@ import {
   toSuppression,
   toSymbol,
   type CommentRow,
+  type CoverageRun,
   type MacroRow,
   type MacroUseRow,
   type ModuleRow,
@@ -59,7 +61,7 @@ import {
   type SuppressionRow,
   type SymbolRow,
 } from "./read.ts";
-import { 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, 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. */
@@ -136,6 +138,8 @@ export interface ChangeContext {
   inputHash?: string;
   toolVersion?: string;
   evidence?: Evidence[];
+  /** A revert: the revision whose knowledge it restores. */
+  restores?: string;
 }
 
 /**
@@ -177,8 +181,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) VALUES (?, ?, ?, ?, ?, ?, ?)")
-      .run(id, isoCet(now), this.#context.origin, this.#operation, this.#context.inputHash ?? null, this.#context.toolVersion ?? null, this.#context.description ?? null);
+      .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);
     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);
@@ -321,7 +325,7 @@ function checkEvidence(evidence: Evidence[] | undefined): void {
 }
 
 /** Runs semantic writes in one transaction, as one revision. */
-export function write<T>(db: DatabaseSync, context: WriteContext, operation: string, work: (change: Change) => T): { revision: string | null; current: T } {
+export function write<T>(db: DatabaseSync, context: WriteContext & Pick<ChangeContext, "restores">, operation: string, work: (change: Change) => T): { revision: string | null; current: T } {
   if (context.origin !== "user" && context.origin !== "llm") {
     throw new Refusal("invalid-input", "A semantic write comes from the user or the LLM.");
   }
@@ -572,6 +576,32 @@ function checkOperand(request: OperandRequest): void {
 
 const shown = (value: number, size: number) => (value < 0 ? String(value) : `$${value.toString(16).padStart(size === 0x100 ? 2 : 4, "0")}`);
 
+/**
+ * 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.
+ */
+function checkInstructionStart(db: DatabaseSync, space: Space, image: OperandImage, address: number): void {
+  const where = formatC64Address(address);
+  const code = regionsOverlapping(db, address, address, space).find((region) => CODE_REGION_TYPES.includes(region.type));
+  if (code === undefined) {
+    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);
+    if (opcode === undefined) {
+      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)}.`);
+  }
+}
+
 /**
  * Refuses an expression whose value is not the operand in the image, and
  * returns the addresses of its names. Symbols of the knowledge come first, then
@@ -581,6 +611,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);
   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.`);
@@ -1171,8 +1202,11 @@ const KEYS = {
  * revision. History is never erased; restored rows keep their origin.
  */
 export function revert(db: DatabaseSync, context: WriteContext, request: { revision: string }): WriteResult<{ restoredRevision: string }> {
-  return write(db, context, "revert", (change) => {
-    const restored = resolveRevision(db, request.revision);
+  const restored = resolveRevision(db, request.revision);
+  return write(db, { ...context, restores: restored }, "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]));
+    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 > ?)";
     for (const [table, spec] of Object.entries(KEYS)) {
       const name = table === "references" ? '"references"' : table;

package/src/mcp/output.ts

@@ -22,6 +22,11 @@ export const WrittenOutput = {
   sha256: z.string().regex(/^[0-9a-f]{64}$/).optional(),
 };
 
+/** Lines as file text: each line ends with a newline, and no lines give an empty file. */
+export function linesText(lines: readonly string[]): string {
+  return lines.map((line) => `${line}\n`).join("");
+}
+
 /** Writes `data` to the file `path` of the project that `project` names (or the project lookup finds), and gives what the result shows in its place. */
 export function writeOut(path: string, data: Uint8Array | string, project: string | undefined): Written {
   return writeReported(path, data, { what: "out", root: projectFolder(project) });

package/src/mcp/server.ts

@@ -91,6 +91,17 @@ export function requireFields(action: string, given: Record<string, unknown>, al
   }
 }
 
+/**
+ * Checks the fields that go with out: project only with out, and the
+ * fields of `notWithOut` only without it.
+ */
+export function requireOut(given: { out?: unknown; project?: unknown } & Record<string, unknown>, notWithOut: readonly string[] = []): void {
+  if (given.out === undefined && given.project !== undefined) throw new WireFailure("invalid-input", "project is used only with out.");
+  for (const field of notWithOut) {
+    if (given.out !== undefined && given[field] !== undefined) throw new WireFailure("invalid-input", `${field} is not used with out.`);
+  }
+}
+
 /** A tool result that carries content blocks (for example an image) beside its structured result. */
 export class ToolOutput<T> {
   readonly structured: T;
@@ -163,12 +174,16 @@ function errorResult(error: WireError): CallToolResult {
   return { isError: true, content: [{ type: "text", text: JSON.stringify({ error: { code: error.code, message: shownMessage(error) } }) }] };
 }
 
-/** "address: Invalid string: must match ..." style messages, one sentence per problem. */
-function describeIssues(error: z.ZodError): string {
+/**
+ * "address: Invalid string: must match ..." style messages, one sentence per problem.
+ * An unknown field of the tool input also gets the fields that the tool takes.
+ */
+function describeIssues(error: z.ZodError, input?: z.ZodObject): string {
   return error.issues
     .map((issue) => {
       const where = issue.path.length === 0 ? "input" : issue.path.join(".");
-      return `${where}: ${issue.message}`;
+      const fields = issue.code === "unrecognized_keys" && issue.path.length === 0 && input !== undefined ? `. The fields are ${Object.keys(input.shape).join(", ")}` : "";
+      return `${where}: ${issue.message}${fields}`;
     })
     .join(". ");
 }
@@ -211,7 +226,7 @@ async function runCall(
   const tool = tools.get(name);
   if (tool === undefined) return errorResult({ code: "invalid-input", message: `There is no tool named ${name}.` });
   const parsed = tool.inputSchema.safeParse(args ?? {});
-  if (!parsed.success) return errorResult({ code: "invalid-input", message: describeIssues(parsed.error) });
+  if (!parsed.success) return errorResult({ code: "invalid-input", message: describeIssues(parsed.error, tool.inputSchema) });
   try {
     let output: unknown;
     try {

package/src/mcp/tools/debug.ts

@@ -7,9 +7,9 @@ import { COVERAGE, executedRamCode, EXECUTE, formatC64Address, READ, WRITE, type
 import { WireFailure } from "../../protocol/messages.ts";
 import { CHECKPOINT_ACTIONS, MAX_BACKTRACE, MAX_HISTORY, MAX_TRACE_FRAMES, MAX_TRACE_HITS, MAX_TRACE_POINTS, TRACE_KINDS, TRACE_ENDS, MAX_MEMMAP_RANGES, MAX_MEMORY_READ, MAX_PROFILE, MAX_WATCH_SIZE, SPACES, TIMING_ACTIONS, WATCH_ACCESS, type Breakpoint, type Watchpoint } from "../../protocol/vice.ts";
 import { readCoverage } from "../../host-client/coverage.ts";
-import { OutInput, ProjectInput, writeOut, WrittenOutput } from "../output.ts";
+import { linesText, OutInput, ProjectInput, writeOut, WrittenOutput } from "../output.ts";
 import { AddressInput, Byte, SpaceInput, TOOL_INPUTS } from "../inputs.ts";
-import { AddressOutput, ConditionOutput, defineTool, HexData, requireFields, showCondition, toCondition } from "../server.ts";
+import { AddressOutput, ConditionOutput, defineTool, HexData, requireFields, requireOut, showCondition, toCondition } from "../server.ts";
 import { spaced } from "./memory.ts";
 
 /** No default here: a filled-in default would count as a field the other actions refuse. */
@@ -169,7 +169,7 @@ export const c64CpuHistory = defineTool({
       const raster = entry.rasterLine === undefined ? "" : `  line ${entry.rasterLine} cycle ${entry.rasterCycle ?? 0}`;
       return `${formatC64Address(entry.address)}  ${spaced(entry.bytes).padEnd(9)} ${entry.text.padEnd(16)} a=${byte(entry.a)} x=${byte(entry.x)} y=${byte(entry.y)} sp=${byte(entry.sp)}${raster}`;
     });
-    return { count: entries.length, ...writeOut(out, `${lines.join("\n")}\n`, project) };
+    return { count: entries.length, ...writeOut(out, linesText(lines), project) };
   },
 });
 
@@ -184,6 +184,7 @@ export const c64Trace = defineTool({
     "A point is exec (an instruction at an address from start to end), read or write (an access from start to end). " +
     `Give 1 to ${MAX_TRACE_POINTS} points. ` +
     "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. " +
     `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. ` +
@@ -233,7 +234,7 @@ export const c64Trace = defineTool({
     const shown = traced.hits.map(({ address, ...hit }) => ({ ...hit, pc: formatC64Address(hit.pc), ...(address === undefined ? {} : { address: formatC64Address(address) }) }));
     const summary = { end: traced.end, frames: traced.frames, pc: formatC64Address(traced.pc), count: traced.hits.length, hits: shown.slice(0, TRACE_LISTED) };
     if (out === undefined) return summary;
-    return { ...summary, ...writeOut(out, `${shown.map((hit) => JSON.stringify(hit)).join("\n")}\n`, project) };
+    return { ...summary, ...writeOut(out, linesText(shown.map((hit) => JSON.stringify(hit))), project) };
   },
 });
 
@@ -392,11 +393,11 @@ export const c64Memmap = defineTool({
         ...(written.length > MAX_SUMMARY_RANGES ? { writtenAndExecutedTruncated: true } : {}),
       };
     }
+    requireOut(fields, ["maxRanges"]);
+    requireFields("read", fields, ["start", "end", "maxRanges", "out", "project"]);
     if (fields.out !== undefined) {
-      requireFields("read", fields, ["start", "end", "out", "project"]);
       return writeOut(fields.out, await readCoverage(session, start, end), fields.project);
     }
-    requireFields("read", fields, ["start", "end", "maxRanges"]);
     const result = await session.memmap({ action: "read", start, end, maxRanges: fields.maxRanges ?? 256 });
     const ranges = result.ranges.map((range) => ({
       start: formatC64Address(range.start),