@henols/c64-re-tools 2.1.1 → 2.1.2

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. */

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,
@@ -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);
@@ -369,9 +372,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");
 }
 
@@ -1199,19 +1201,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 +1261,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/server.ts

@@ -182,7 +182,8 @@ function describeIssues(error: z.ZodError, input?: z.ZodObject): string {
   return error.issues
     .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(". ");

package/src/mcp/tools/debug.ts

@@ -339,7 +339,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 +364,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 +394,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 +412,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/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 };
   },
 });
 

package/src/media.ts

@@ -0,0 +1,42 @@
+// Media file signatures and sizes. The host checks a file with them before
+// VICE gets it: VICE takes a file that is not of its type in another way, and
+// a CRT or T64 that it cannot read loads as a PRG with a successful autostart.
+
+import { Refusal } from "./errors.ts";
+
+/** The signature at the start of each media type that has one. */
+const SIGNATURES: Readonly<Record<string, readonly string[]>> = {
+  crt: ["C64 CARTRIDGE   "],
+  t64: ["C64"],
+  tap: ["C64-TAPE-RAW"],
+  g64: ["GCR-1541"],
+  p00: ["C64File"],
+};
+
+/** True when `bytes` start with a signature of `type`, or `type` has none. */
+export function hasSignature(type: string, bytes: Uint8Array): boolean {
+  const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const signatures = SIGNATURES[type];
+  return signatures === undefined || signatures.some((signature) => buffer.toString("latin1", 0, signature.length) === signature);
+}
+
+/** The file sizes that VICE reads for each disk image type without a signature. */
+const SIZES: Readonly<Record<string, readonly number[]>> = {
+  d64: [174848, 175531, 196608, 197376, 205312, 206114],
+  d71: [349696, 351062],
+  d81: [819200, 822400],
+};
+
+/** The x64 header: 64 bytes that start with these four, then a d64 image. */
+const X64_MAGIC = Buffer.from([0x43, 0x15, 0x41, 0x64]);
+
+/** Refuses a file whose bytes are not of `type` (its extension), with media-error. */
+export function checkMedia(type: string, bytes: Buffer): void {
+  const refuse = (why: string) => {
+    throw new Refusal("media-error", `The file is not a valid .${type} file: ${why}. Give a file of that type.`);
+  };
+  if (!hasSignature(type, bytes)) refuse(`it does not start with ${SIGNATURES[type]!.map((signature) => `"${signature.trimEnd()}"`).join(" or ")}`);
+  const sizes = SIZES[type];
+  if (sizes !== undefined && !sizes.includes(bytes.length)) refuse(`it has ${bytes.length} bytes, and a .${type} image has ${sizes.join(", ")}`);
+  if (type === "x64" && (!bytes.subarray(0, 4).equals(X64_MAGIC) || !SIZES.d64!.includes(bytes.length - 64))) refuse("it has no x64 header before a d64 image");
+}

package/src/opcodes.ts

@@ -4,7 +4,7 @@
 // spelling, ACME writes only one of them: the generator finds those with a
 // probe and writes the others as bytes.
 
-import { formatC64Byte, formatC64Address } from "./c64.ts";
+import { formatC64Byte, formatC64Address, SYMBOL_NAME } from "./c64.ts";
 
 export type Mode = "imp" | "imm" | "zp" | "zpx" | "zpy" | "abs" | "abx" | "aby" | "ind" | "izx" | "izy" | "rel";
 
@@ -45,6 +45,17 @@ export const MODE_LENGTH: Record<Mode, 1 | 2 | 3> = { imp: 1, imm: 2, zp: 2, zpx
 /** Every mnemonic in the table: a symbol with one of these names would read as an instruction. */
 export const MNEMONICS: ReadonlySet<string> = new Set(OPCODES.map((opcode) => opcode.mnemonic));
 
+/**
+ * Why ACME cannot take a name as a label, or undefined when it can. A label
+ * has label syntax (SYMBOL_NAME) and is no mnemonic in upper or lower case.
+ * The one rule for a symbol of the knowledge and a label of c64-source.
+ */
+export function labelProblem(name: string): string | undefined {
+  if (!SYMBOL_NAME.test(name)) return "A symbol name is a letter or underscore, then letters, digits or underscores (at most 64), with an optional leading dot.";
+  if (MNEMONICS.has(name.toLowerCase())) return `${name} is the name of a 6502 instruction, which ACME cannot read as a label. Give another name.`;
+  return undefined;
+}
+
 const ZERO_PAGE_OF: Partial<Record<Mode, Mode>> = { abs: "zp", abx: "zpx", aby: "zpy" };
 
 /** True when the mnemonic also has the zero-page form of an absolute mode: ACME would pick it for a small operand. */
@@ -78,26 +89,48 @@ export function useKind(opcode: number): UseKind {
 }
 
 
-/** The text of the instruction in `bytes` at `pc`, for example "sta $d011" or "bne $c002". */
-export function instructionText(bytes: readonly number[], pc: number): string {
-  const { mnemonic, mode } = OPCODES[bytes[0]!]!;
-  const low = bytes[1] ?? 0;
-  const word = low | ((bytes[2] ?? 0) << 8);
+/**
+ * The ACME text of an instruction with its operand as an expression: the
+ * mnemonic, the size suffix (+1 or +2, or none) and the operand in the syntax
+ * of its addressing mode, for example "lda #<table", "sta screen,x" or
+ * "lda (pointer),y". ACME reads an operand in brackets as indirect, so a
+ * non-immediate expression that starts with a bracket gets 0+ in front.
+ * The one place that writes an instruction: the generated source, the
+ * listing of the knowledge and the disassembly of the emulator use it.
+ */
+export function instructionWith(opcode: number, expression: string, suffix = ""): string {
+  const { mnemonic, mode } = OPCODES[opcode]!;
+  const value = mode !== "imm" && expression.startsWith("(") ? `0+${expression}` : expression;
   const operand: Record<Mode, string> = {
     imp: "",
-    imm: `#${formatC64Byte(low)}`,
-    zp: formatC64Byte(low),
-    zpx: `${formatC64Byte(low)},x`,
-    zpy: `${formatC64Byte(low)},y`,
-    abs: formatC64Address(word),
-    abx: `${formatC64Address(word)},x`,
-    aby: `${formatC64Address(word)},y`,
-    ind: `(${formatC64Address(word)})`,
-    izx: `(${formatC64Byte(low)},x)`,
-    izy: `(${formatC64Byte(low)}),y`,
-    rel: formatC64Address((pc + 2 + (low < 0x80 ? low : low - 0x100)) & 0xffff),
+    imm: `#${value}`,
+    zp: value,
+    zpx: `${value},x`,
+    zpy: `${value},y`,
+    abs: value,
+    abx: `${value},x`,
+    aby: `${value},y`,
+    ind: `(${value})`,
+    izx: `(${value},x)`,
+    izy: `(${value}),y`,
+    rel: value,
   };
-  return operand[mode] === "" ? mnemonic : `${mnemonic} ${operand[mode]}`;
+  return operand[mode] === "" ? `${mnemonic}${suffix}` : `${mnemonic}${suffix} ${operand[mode]}`;
+}
+
+/** The value of the operand of the instruction in `bytes` at `pc` as a number: a byte, a word, or the target of a branch. Empty for no operand. */
+export function operandNumber(bytes: readonly number[], pc: number): string {
+  const { mode } = OPCODES[bytes[0]!]!;
+  const low = bytes[1] ?? 0;
+  if (mode === "imp") return "";
+  if (mode === "rel") return formatC64Address((pc + 2 + (low < 0x80 ? low : low - 0x100)) & 0xffff);
+  return MODE_LENGTH[mode] === 3 ? formatC64Address(low | ((bytes[2] ?? 0) << 8)) : formatC64Byte(low);
+}
+
+/** The text of the instruction in `bytes` at `pc` as the monitor shows it, for example "STA $d011" or "BNE $c002". */
+export function instructionText(bytes: readonly number[], pc: number): string {
+  const { mnemonic } = OPCODES[bytes[0]!]!;
+  return `${mnemonic.toUpperCase()}${instructionWith(bytes[0]!, operandNumber(bytes, pc)).slice(mnemonic.length)}`;
 }
 
 /**

package/src/project.ts

@@ -5,7 +5,7 @@
 // the agent saves for itself and ignores itself in git.
 
 import { Refusal } from "./errors.ts";
-import { existsSync, mkdirSync, readdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { accessSync, constants, existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 
@@ -117,7 +117,8 @@ export function namedProject(folder: string, cwd: string = process.cwd()): strin
   if (stat === undefined) throw new Refusal("not-found", `There is no folder ${folder}.`);
   if (!stat.isDirectory()) throw new Refusal("invalid-input", `${folder} is not a folder.`);
   if (path === homedir()) throw new Refusal("invalid-input", "The home folder is not a project folder.");
-  const outer = foldersUpFrom(path).slice(1).find(isProject);
+  // A project inside another project is a project of its own, as the lookup from a working directory in it finds.
+  const outer = isProject(path) ? undefined : foldersUpFrom(path).slice(1).find(isProject);
   if (outer !== undefined) {
     throw new Refusal("invalid-input", `${folder} is inside the project ${relative(cwd, outer) || outer}. Give that project folder.`);
   }
@@ -180,6 +181,113 @@ export function resolveProjectPath(path: string, root = projectRoot()): string {
   throw new Refusal("invalid-input", `${path} leads out of the project folder: give a path that stays inside it.`);
 }
 
+/** The folder of the committed knowledge text in PROJECT_DIRECTORY. The knowledge (src/knowledge/database.ts) has the same name. */
+export const KNOWLEDGE_TEXT_DIRECTORY = "knowledge";
+
+/** The index of the knowledge in LOCAL_DIRECTORY, and the files that SQLite keeps beside it. The knowledge has the same name. */
+const KNOWLEDGE_INDEX = /^knowledge\.db(?:-wal|-shm|-journal)?$/;
+
+/**
+ * The part of the knowledge that a path relative to the project folder is in:
+ * the text in .c64-re-tools/knowledge/ or the index in .c64-re-tools/local/.
+ * Undefined for every other path. Letter case does not count: some file
+ * systems do not tell the cases apart.
+ */
+export function knowledgePart(fromRoot: string): string | undefined {
+  const parts = fromRoot.split(/[\\/]+/).filter((part) => part !== "" && part !== ".").map((part) => part.toLowerCase());
+  if (parts[0] !== PROJECT_DIRECTORY) return undefined;
+  if (parts[1] === KNOWLEDGE_TEXT_DIRECTORY) return `${PROJECT_DIRECTORY}/${KNOWLEDGE_TEXT_DIRECTORY}/`;
+  if (parts[1] === LOCAL_DIRECTORY && parts.length === 3 && KNOWLEDGE_INDEX.test(parts[2]!)) return `${PROJECT_DIRECTORY}/${LOCAL_DIRECTORY}/${parts[2]}`;
+  return undefined;
+}
+
+/** What a command writes at an output path: one file, or files in a folder. */
+export type OutputKind = "file" | "folder";
+
+/** 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 message for a write that the file system refused because of the path
+ * (a folder, a file in place of a folder, no permission): the path and what
+ * to do. Undefined for another error, which is no fault of the path.
+ */
+export function writeProblem(error: unknown, path: string, what?: string): string | undefined {
+  const problem = WRITE_PROBLEMS[(error as NodeJS.ErrnoException | undefined)?.code ?? ""];
+  return problem === undefined ? undefined : `${what === undefined ? "" : `${what}: `}${path} ${problem}.`;
+}
+
+/**
+ * Checks a path that a command writes, before the command does any work. The
+ * path must stay inside the project, also through symbolic links, and must
+ * not be in the knowledge (only the c64-knowledge skill writes it). A file
+ * must not be a folder or a symbolic link; a folder must be a folder. The
+ * nearest folder that exists must be a folder that can be written. Returns
+ * the absolute path. Throws a Refusal (invalid-input) whose message starts
+ * with `what` (for example --out). writeProjectFile does the same check for
+ * each file that it writes.
+ */
+export function checkOutputPath(path: string, kind: OutputKind, options: { root?: string; what?: string } = {}): string {
+  const root = options.root ?? projectRoot();
+  const what = options.what;
+  const outside = () => new Refusal("invalid-input", `${what ?? path}: give a path relative to the project folder that stays inside it, not ${path}.`);
+  const problem = (error: unknown) => {
+    const message = writeProblem(error, path, what);
+    return message === undefined ? error : new Refusal("invalid-input", message);
+  };
+  const inKnowledge = (fromRoot: string) => {
+    const part = knowledgePart(fromRoot);
+    if (part !== undefined) {
+      throw new Refusal("invalid-input", `${what === undefined ? "" : `${what}: `}${path} is in ${part}, the knowledge of the project. Only the c64-knowledge skill writes it: a write there destroys the knowledge. Give a path outside ${PROJECT_DIRECTORY}/${KNOWLEDGE_TEXT_DIRECTORY}/, for example ${PROJECT_DIRECTORY}/${LOCAL_DIRECTORY}/<file>.`);
+    }
+  };
+  let target: string;
+  try {
+    target = resolveProjectPath(path, root);
+  } catch {
+    throw outside();
+  }
+  inKnowledge(relative(root, target));
+  // The nearest entry that exists: the path itself, or a folder above it.
+  let existing = target;
+  for (;;) {
+    let found;
+    try {
+      found = lstatSync(existing, { throwIfNoEntry: false });
+    } catch (error) {
+      throw problem(error);
+    }
+    if (found !== undefined) break;
+    existing = dirname(existing);
+  }
+  const realRoot = realpathSync(root);
+  if (existing === target && kind === "file" && lstatSync(target).isSymbolicLink()) throw outside();
+  const real = realpathSync(existing);
+  if (!isInside(realRoot, real)) throw outside();
+  inKnowledge(relative(realRoot, join(real, relative(existing, target))));
+  const stat = statSync(real);
+  if (existing === target && kind === "file") {
+    if (stat.isDirectory()) throw problem({ code: "EISDIR" });
+  } else if (!stat.isDirectory()) {
+    throw problem({ code: "ENOTDIR" });
+  }
+  try {
+    accessSync(real, constants.W_OK);
+  } catch (error) {
+    throw problem(error);
+  }
+  return target;
+}
+
 /** A project path in one spelling: relative to the project folder, with / and without ./, .. or a double /. Refuses a path as resolveProjectPath does. */
 export function projectRelative(path: string, root = projectRoot()): string {
   return relative(root, resolveProjectPath(path, root)).split(sep).join("/");