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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henols/c64-re-tools",
-  "version": "2.0.0-rc.20",
+  "version": "2.0.0-rc.22",
   "description": "Agent-friendly Commodore 64 engineering toolkit for reverse engineering, debugging, development and testing.",
   "license": "MIT",
   "author": "Henrik Olsson",

package/skills/c64-docs/SKILL.md

@@ -7,7 +7,7 @@ description: Use this skill to write the documentation of a C64 program. The doc
 
 ## Purpose
 
-Write documentation that tells how a program works, and that points to the code. The documentation is Markdown in the project, for example in `docs/`. It has two parts:
+Write documentation that tells how a program works, and that points to the code. The documentation is Markdown in the project. The entry page is `README.md` in the project folder. The other pages and the reference are in `docs/`. The documentation has two parts:
 
 - **The reference.** `generate.ts` generates it from the knowledge, the source map of c64-source and the image. It has a page for each module. The page gives the routines, their callers and callees, the data and a call graph. It also has pages for the names, the variables, the tables, the memory map and the graphics. Do not edit these pages. The next run writes over them.
 - **The pages that you write.** They tell how the program works. They give the flows, the state machines, the data formats and the task of each part. Use the page types in `references/page-types.md` and the rules in `references/style.md`.
@@ -20,7 +20,7 @@ This skill does not change the knowledge.
 
 - The source directory of c64-source, with its `source-map.json`, for example `src`. The source must be from the current knowledge revision.
 - The program in the knowledge. Put it in with `image` of the c64-knowledge skill. The reference decodes the tables and shows the graphics from it.
-- The directory of the documentation, for example `docs`. The reference goes into a directory of its own, for example `docs/reference`.
+- The entry page `README.md` and the directory of the other pages, for example `docs`. The reference goes into a directory of its own, for example `docs/reference`.
 
 ## Tools / execution path
 
@@ -28,16 +28,16 @@ The scripts run on this machine. They do not use the emulator or the host runtim
 
 ```
 node <skill>/scripts/generate.ts --source src --out docs/reference
-node <skill>/scripts/link.ts docs --source src
-node <skill>/scripts/link.ts docs --source src --check
+node <skill>/scripts/link.ts README.md docs --source src
+node <skill>/scripts/link.ts README.md docs --source src --check
 ```
 
 | Option | Meaning |
 |---|---|
 | `--source src` | The source directory of c64-source. Both scripts read `src/source-map.json`. |
 | `--out docs/reference` | The directory of the reference. `generate.ts` writes only there. It refuses to start when the directory holds a page that it did not write. |
-| `docs` | The directory of the documentation. `link.ts` reads every `.md` file below it. It changes only the pages that you wrote. It checks the pages of the reference. |
-| `--reference <dir>` | The directory of the reference for `link.ts`. The default is `docs/reference` when it exists. |
+| `README.md docs` | The pages of the documentation: `.md` files and directories. `link.ts` reads each file and every `.md` file below each directory. It changes only the pages that you wrote. It checks the pages of the reference. |
+| `--reference <dir>` | The directory of the reference for `link.ts`. The default is the `reference` directory of the first directory that has one, for example `docs/reference`. |
 | `--check` | `link.ts` writes nothing. It fails when a link is not up to date or a page has a problem. |
 
 ### Project folder
@@ -50,15 +50,16 @@ node <skill>/scripts/link.ts docs --source src --check
 1. Read the knowledge with the c64-knowledge skill. The documentation can only be as good as the knowledge. Each routine needs a name and a comment. Each table needs a region and a name. Each file of the source needs a module with a title. Record what is missing with c64-knowledge.
 2. Generate the source with c64-source. Make sure that `check.identical` is `true`. The script also writes `source-map.json`.
 3. Run `generate.ts`. Read `index.md` of the reference. A module with no routines, or a routine with no comment, shows what the knowledge does not have yet.
-4. Make the plan of the pages. Start from the modules and the call graphs. Find the main loop, the interrupt chain, the dispatch tables, the state machines and the data formats. Each subsystem gets one page. The entry page lists the pages. Use the page types in `references/page-types.md`.
+4. Make the plan of the pages. Start from the modules and the call graphs. Find the main loop, the interrupt chain, the dispatch tables, the state machines and the data formats. Each subsystem gets one page in `docs/`. The entry page `README.md` in the project folder lists the pages. Use the page types in `references/page-types.md`.
 5. Write each page. Read the code and the knowledge for each fact. Run the program with c64-testing or c64-emulator when a fact needs a run. Write each name with its address, for example `` `draw_room` `$09BC` ``. Mark each fact with its evidence. Several subagents can write the pages at the same time, one page each. Give each subagent `references/page-types.md` and `references/style.md`.
 6. Record each new fact in the knowledge first: a name, a comment, a region or a module. Then the source and the reference show it too. A fact only in a page is lost at the next change of the knowledge.
 7. Run `link.ts`. Read `problems` and correct each one. Then run `link.ts --check`. Make sure that `problems.count` is 0 and that `notUpToDate.links` is 0.
-8. After each change to the knowledge, do steps 2, 3 and 7 again. The links then go to the new lines.
+8. When the project folder is in a workspace with other projects, find `README.md` at the root of the workspace. This page lists each program of the workspace. Add one row for the program, with a link to `<project>/README.md` and one sentence. If the page does not exist, make it. Use the workspace index in `references/page-types.md`. `link.ts` does not read this page, because the page is not in the project folder.
+9. After each change to the knowledge, do steps 2, 3 and 7 again. The links then go to the new lines.
 
 ## The links
 
-`link.ts` changes these forms in the pages that you write. It does not change a code block, a mermaid diagram or an HTML comment.
+`link.ts` changes these forms in the pages that you write. It does not change a code block, a mermaid diagram or an HTML comment. The examples are for a page in `docs/`. In `README.md`, the links start with `src/` and `docs/reference/`.
 
 | You write | `link.ts` writes |
 |---|---|

package/skills/c64-docs/references/page-types.md

@@ -4,15 +4,16 @@ Each page that you write is one of these types. The types come from the document
 
 ## 1. The entry page
 
-One entry page for the program, for example `docs/README.md` or `docs/rooms.md` for one large subsystem. It has these parts, in this order:
+One entry page for the program: `README.md` in the project folder. A large subsystem can have an entry page of its own in `docs/`, for example `docs/rooms.md`. The entry page of the program has these parts, in this order:
 
 1. **One paragraph.** What the program is, and which release the documentation is for.
 2. **The table of pages.** One row for each page, with the link and one sentence about its content.
 3. **The layers.** A mermaid diagram of the layers of the program. The layers are the data, the code that runs one time, the main loop and the interrupts. Under the diagram, a numbered list tells how the layers work together.
 4. **The flow of a user.** A mermaid diagram of the steps of the player or user from start to end. An example is the order of the levels.
 5. **Findings.** A table of the facts that a reader does not expect, each with its evidence. Put a bug of the original program here.
-6. **The reference.** A link to `reference/index.md`.
+6. **The reference.** A link to `docs/reference/index.md`.
 7. **Still open.** What is not known yet, and which run can find it.
+8. **The release and the rebuild.** What the release holds, for example a crack with a cracktro and a mover. Which part is the clean program of the knowledge. Which changes of the release to the machine state stay, and how the loader sets them. How the source assembles to the clean program, and which scenarios compare the original with the rebuild.
 
 ```markdown
 # <Program>: <subject>
@@ -21,7 +22,7 @@ One entry page for the program, for example `docs/README.md` or `docs/rooms.md`
 
 | Page | Content |
 |---|---|
-| [parts/main_loop.md](parts/main_loop.md) | **The main loop.** <one sentence> |
+| [parts/main_loop.md](docs/parts/main_loop.md) | **The main loop.** <one sentence> |
 
 ## 1. The layers
 
@@ -31,23 +32,50 @@ flowchart TB
   ...
 ~~~
 
-## 2. Findings
+## 2. The flow of a player
+
+...
+
+## 3. Findings
 
 | Finding | Evidence |
 |---|---|
 | <fact> | Observed: <what run showed it> |
 
-## 3. Still open
+## 4. The reference
+
+[docs/reference/index.md](docs/reference/index.md)
+
+## 5. Still open
 
 - <question> — <the run that can answer it>
+
+## 6. The release and the rebuild
+
+- **The release.** <the file on the disk, and what the release adds to the program>
+- **The rebuild.** <the source, the loader and the scenarios>
+```
+
+## 2. The workspace index
+
+A workspace with several projects has one `README.md` at its root. It lists each program of the workspace. It has a title, one sentence and a table with one row for each program. Each row has a link to the entry page of the program and one sentence about the program.
+
+```markdown
+# C64 games
+
+Reverse-engineered C64 games. Each game has its own folder with the original disk, the rebuilt source and the documentation.
+
+| Game | |
+|---|---|
+| [Bruce Lee](bruce_lee/README.md) | Datasoft 1984. How the program works, from the cold start to the last room. |
 ```
 
-## 2. The subsystem page
+## 3. The subsystem page
 
 One page for each subsystem, for example the main loop, the interrupt chain, the room generation or the sound player. It has these parts:
 
 1. **The scope.** A list of what the page covers, and the sources (the source files, the assets).
-2. **The conventions.** The terms of the page, for example "a pass is one run of `main_loop` `$1BC2`". Also the evidence labels. Use the conventions block of section 5.
+2. **The conventions.** The terms of the page, for example "a pass is one run of `main_loop` `$1BC2`". Also the evidence labels. Use the conventions block of section 6.
 3. **The overview.** A short text diagram or a mermaid flowchart of the calls, from the entry of the subsystem to its end.
 4. **The catalogue.** A table of the data of the subsystem. Each row has the name, the address, the layout (bytes, entries, the meaning of each byte), the readers and the writers.
 5. **The step-by-step walk.** For each main routine: a numbered list of what it does, in the order of the code. Each step gives the names and addresses. Add pseudo-code when a loop or a condition is not clear from the list.
@@ -71,7 +99,7 @@ stateDiagram-v2
 | Waiting `$00` | `move_timer` = 0 | Moving `$01` | `update_slider` `$3F8C` |
 ```
 
-## 3. The entity sections
+## 4. The entity sections
 
 A program often has many items of one kind: levels, rooms, enemies, tunes. Give each item one section of the same form, in a page for a group of items. Each section has these parts:
 
@@ -83,7 +111,7 @@ A program often has many items of one kind: levels, rooms, enemies, tunes. Give
 
 End the group page with a table of the dependencies between the items.
 
-## 4. The data-format page
+## 5. The data-format page
 
 One page for each format of data, for example a packed map, a music stream or a sprite format. It has these parts:
 
@@ -101,7 +129,7 @@ One page for each format of data, for example a packed map, a music stream or a
 | `$01-$7F` | The next byte, `b` times. |
 ```
 
-## 5. The conventions block
+## 6. The conventions block
 
 Put this block near the top of each subsystem page. Change the terms for the program.
 

package/skills/c64-docs/scripts/generate.ts

@@ -11,7 +11,7 @@ import { writeProjectFile } from "#src/host-client/transfer.ts";
 import { conflicts } from "#src/knowledge/conflicts.ts";
 import { KnowledgeError, openForRead } from "#src/knowledge/database.ts";
 import { currentRevision, listComments, listModules, listReferences, listRegions, listSymbols } from "#src/knowledge/read.ts";
-import { resolveProjectPath } from "#src/project.ts";
+import { resolveProjectFile, resolveProjectPath } from "#src/project.ts";
 import { runScript, UsageError } from "#src/script.ts";
 import { buildReference, GENERATED_MARK } from "./lib/reference.ts";
 import { readSourceMap } from "./lib/source-map.ts";
@@ -28,9 +28,8 @@ When the knowledge has the program of the source (knowledge.ts image of the
 c64-knowledge skill, D83), the reference decodes the tables and shows the
 graphics. The result is one JSON object.`;
 
-/** The files of an earlier run, or a refusal that names a file of a person. */
-function oldFiles(out: string): string[] {
-  const directory = resolveProjectPath(out);
+/** The files of an earlier run in `directory`, the real folder of --out, or a refusal that names a file of a person. */
+function oldFiles(out: string, directory: string): string[] {
   if (!existsSync(directory)) return [];
   const found: string[] = [];
   const walk = (relative: string) => {
@@ -62,6 +61,15 @@ function run(argv: string[]): Record<string, unknown> {
       throw new UsageError(`${option} must be a path relative to the project folder that stays inside it, not ${path}`);
     }
   }
+  // The files of an earlier run are deleted: only in a folder that is inside the project, also after its symbolic links.
+  let directory = resolveProjectPath(values.out);
+  if (existsSync(directory)) {
+    try {
+      directory = resolveProjectFile(values.out);
+    } catch {
+      throw new UsageError(`--out must be a path relative to the project folder that stays inside it, also through symbolic links, not ${values.out}`);
+    }
+  }
   const map = readSourceMap(values.source);
   const db = openForRead();
   let knowledge;
@@ -86,14 +94,13 @@ function run(argv: string[]): Record<string, unknown> {
   } finally {
     db?.close();
   }
-  const old = oldFiles(values.out);
+  const old = oldFiles(values.out, directory);
   const built = buildReference({
     out: posix.normalize(values.out),
     map,
     ...knowledge,
     ...(image === undefined ? {} : { image: { byteAt: image.byteAt, inImage: (address: number) => image.segments.some((segment) => address >= segment.start && address <= segment.end) } }),
   });
-  const directory = resolveProjectPath(values.out);
   for (const path of old) rmSync(join(directory, path), { force: true });
   for (const file of built.files) writeProjectFile(file.path, file.bytes, { what: "--out" });
   return { out: values.out, revision: knowledge.revision, index: posix.join(posix.normalize(values.out), "index.md"), ...built.counts, program: image === undefined ? "none: put the program into the knowledge with knowledge.ts image to decode the tables and show the graphics" : "the knowledge" };

package/skills/c64-docs/scripts/lib/links.ts

@@ -60,7 +60,14 @@ const relative = (page: string, target: string) => {
 /** The project path of a link target, without its fragment; undefined for a link out of the project (a URL, or a page anchor only). */
 export function targetPath(page: string, target: string): string | undefined {
   if (/^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith("#")) return undefined;
-  return posix.normalize(posix.join(posix.dirname(page), decodeURIComponent(target.split("#")[0]!)));
+  const raw = target.split("#")[0]!;
+  let path = raw;
+  try {
+    path = decodeURIComponent(raw);
+  } catch {
+    // A % that starts no escape ("100%.md") is part of the name.
+  }
+  return posix.normalize(posix.join(posix.dirname(page), path));
 }
 
 /** Writes the links of the name mentions of a page; returns the new text, the number of links changed and the problems. */
@@ -129,6 +136,11 @@ export function checkLinks(page: string, text: string, files: Files): Problem[]
     if (!anchors.has(path)) anchors.set(path, anchorsOf(path === page ? text : (files.text(path) ?? "")));
     return anchors.get(path)!;
   };
+  const lineCounts = new Map<string, number>();
+  const lineCount = (path: string) => {
+    if (!lineCounts.has(path)) lineCounts.set(path, (files.text(path) ?? "").split("\n").length);
+    return lineCounts.get(path)!;
+  };
   for (const link of linksOf(text)) {
     const report = (kind: ProblemKind, message: string) => problems.push({ page, line: link.line, kind, message });
     const fragment = link.target.includes("#") ? link.target.slice(link.target.indexOf("#") + 1) : undefined;
@@ -147,7 +159,7 @@ export function checkLinks(page: string, text: string, files: Files): Problem[]
     if (path.endsWith(".md")) {
       if (!anchorsAt(path).has(fragment)) report("missing-anchor", `${link.target}: ${path} has no anchor ${fragment}.`);
     } else if (line !== null) {
-      const count = (files.text(path) ?? "").split("\n").length;
+      const count = lineCount(path);
       if (Number(line[1]) > count) report("missing-line", `${link.target}: ${path} has ${count} lines.`);
     }
   }

package/skills/c64-docs/scripts/link.ts

@@ -16,13 +16,14 @@ import { checkLinks, linkPage, type Files, type Problem } from "./lib/links.ts";
 import { GENERATED_MARK } from "./lib/reference.ts";
 import { readSourceMap } from "./lib/source-map.ts";
 
-const USAGE = `link.ts <docs> --source <dir> [--reference <dir>] [--check]
+const USAGE = `link.ts <pages>... --source <dir> [--reference <dir>] [--check]
 
-  <docs>             the documentation directory, relative to the project folder;
-                     link.ts reads every .md file below it
+  <pages>...         .md files and directories of the documentation, relative to
+                     the project folder, for example README.md docs; link.ts reads
+                     each file and every .md file below each directory
   --source <dir>     the source directory of c64-source, with its source-map.json
-  --reference <dir>  the reference pages of generate.ts; the default is
-                     <docs>/reference when it exists
+  --reference <dir>  the reference pages of generate.ts; the default is the
+                     reference/ folder of the first directory that has one
   --check            write nothing; fail when a link is not up to date or a page
                      has a problem
 
@@ -34,9 +35,19 @@ const MAX_LISTED = 50;
 /** A name outside the image covers the addresses up to the next name, at most this many. */
 const MAX_BODY = 256;
 
+const isDirectory = (path: string) => {
+  const real = resolveProjectPath(path);
+  return existsSync(real) && statSync(real).isDirectory();
+};
+
 function markdownFiles(directory: string): string[] {
-  const root = resolveProjectPath(directory);
-  if (!existsSync(root) || !statSync(root).isDirectory()) throw new WireFailure("not-found", `There is no directory ${directory} in the project folder.`);
+  if (!isDirectory(directory)) throw new WireFailure("not-found", `There is no directory ${directory} in the project folder.`);
+  let root: string;
+  try {
+    root = resolveProjectFile(directory);
+  } catch {
+    throw new WireFailure("invalid-input", `${directory} leads out of the project folder through a symbolic link.`);
+  }
   const found: string[] = [];
   const walk = (relative: string) => {
     for (const entry of readdirSync(join(root, relative), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
@@ -49,6 +60,9 @@ function markdownFiles(directory: string): string[] {
   return found;
 }
 
+/** The text of each file that the run read: a page, a source file or a reference page is read once. */
+const texts = new Map<string, string | undefined>();
+
 const files: Files = {
   inside: (path) => {
     try {
@@ -67,27 +81,38 @@ const files: Files = {
     }
   },
   text: (path) => {
+    if (texts.has(path)) return texts.get(path);
+    let text: string | undefined;
     try {
       const real = resolveProjectFile(path);
-      return statSync(real).isFile() ? readFileSync(real, "utf8") : undefined;
+      text = statSync(real).isFile() ? readFileSync(real, "utf8") : undefined;
     } catch {
-      return undefined;
+      text = undefined;
     }
+    texts.set(path, text);
+    return text;
   },
 };
 
+/** A .md entry of a directory that is a symbolic link to no file, or to a file outside the project. */
+const unreadable = (page: string): Problem => ({ page, line: 1, kind: "missing-file", message: `${page} is a symbolic link to no file or to a file outside the project folder.` });
+
 function run(argv: string[]): { output: Record<string, unknown>; failed: boolean } {
   const { values, positionals } = parseArgs({ args: argv, strict: true, allowPositionals: true, options: { source: { type: "string" }, reference: { type: "string" }, check: { type: "boolean" }, help: { type: "boolean" } } });
   if (values.help) throw new UsageError("");
-  if (positionals.length !== 1) throw new UsageError("give one documentation directory");
+  if (positionals.length === 0) throw new UsageError("give the pages: .md files and directories of the documentation, for example README.md docs");
   if (values.source === undefined) throw new UsageError("give --source <dir>: the source directory of c64-source");
-  const docs = posix.normalize(positionals[0]!);
-  for (const [option, path] of [["<docs>", docs], ["--source", values.source], ["--reference", values.reference]] as const) {
+  const given = [...new Set(positionals.map((path) => posix.normalize(path)))];
+  for (const [option, path] of [...given.map((path) => ["<pages>", path] as const), ["--source", values.source], ["--reference", values.reference]] as const) {
     if (path === undefined) continue;
     if (!files.inside(path)) throw new UsageError(`${option} must be a path relative to the project folder that stays inside it, not ${path}`);
   }
+  for (const path of given) {
+    if (!path.endsWith(".md") && files.exists(path) && !isDirectory(path)) throw new UsageError(`<pages> takes .md files and directories, not ${path}`);
+  }
+  const directories = given.filter((path) => !path.endsWith(".md") || isDirectory(path));
   const map = readSourceMap(values.source);
-  const reference = values.reference === undefined ? (existsSync(resolveProjectPath(posix.join(docs, "reference"))) ? posix.join(docs, "reference") : undefined) : posix.normalize(values.reference);
+  const reference = values.reference === undefined ? directories.map((path) => posix.join(path, "reference")).find((path) => isDirectory(path)) : posix.normalize(values.reference);
   const problems: Problem[] = [];
   const db = openForRead();
   let symbols;
@@ -108,14 +133,21 @@ function run(argv: string[]): { output: Record<string, unknown>; failed: boolean
   const routines = symbols.filter((symbol) => symbol.kind === "routine").map((symbol) => symbol.address).sort((a, b) => a - b);
   const named = [...new Set(symbols.map((symbol) => symbol.address))].sort((a, b) => a - b);
   const kinds = new Map(symbols.map((symbol) => [symbol.name, symbol.kind]));
+  const bodyEnds = new Map<string, number | undefined>();
   const bodyEnd = (name: string) => {
+    if (bodyEnds.has(name)) return bodyEnds.get(name);
     const address = addresses.get(name);
-    if (address === undefined) return undefined;
-    const next = ((kinds.get(name) === "routine" ? routines : named).find((other) => other > address) ?? 0x10000) - 1;
-    const file = map.lineOf(address)?.file;
-    if (file === undefined) return Math.min(next, address + MAX_BODY - 1);
-    let end = address;
-    while (end < next && map.lineOf(end + 1)?.file === file) end++;
+    let end: number | undefined;
+    if (address !== undefined) {
+      const next = ((kinds.get(name) === "routine" ? routines : named).find((other) => other > address) ?? 0x10000) - 1;
+      const file = map.lineOf(address)?.file;
+      if (file === undefined) end = Math.min(next, address + MAX_BODY - 1);
+      else {
+        end = address;
+        while (end < next && map.lineOf(end + 1)?.file === file) end++;
+      }
+    }
+    bodyEnds.set(name, end);
     return end;
   };
   const nameAt = new Map(symbols.map((symbol) => [symbol.address, symbol.name]));
@@ -134,7 +166,11 @@ function run(argv: string[]): { output: Record<string, unknown>; failed: boolean
   const entries = new Map<string, string>();
   const referencePages = reference === undefined ? [] : markdownFiles(reference);
   for (const page of referencePages) {
-    const text = files.text(page)!;
+    const text = files.text(page);
+    if (text === undefined) {
+      problems.push(unreadable(page));
+      continue;
+    }
     const stamp = /^<!-- Generated by c64-docs from knowledge revision (\S+) /.exec(text);
     if (text.startsWith(GENERATED_MARK) && stamp !== null && stamp[1] !== map.revision) {
       problems.push({ page, line: 1, kind: "stale-reference", message: `${page} is from knowledge revision ${stamp[1]}, and the source from ${map.revision}. Run generate.ts again.` });
@@ -158,11 +194,19 @@ function run(argv: string[]): { output: Record<string, unknown>; failed: boolean
     managed: (path: string) => inside(path, posix.normalize(map.directory)) || inside(path, reference),
   };
 
-  const pages = markdownFiles(docs);
+  const pages = [...new Set(given.flatMap((path) => {
+    if (directories.includes(path)) return markdownFiles(path);
+    if (files.text(path) === undefined) throw new WireFailure("not-found", `There is no file ${path} in the project folder.`);
+    return [path];
+  }))];
   const changedPages: string[] = [];
   let links = 0;
   for (const page of pages) {
-    const text = files.text(page)!;
+    const text = files.text(page);
+    if (text === undefined) {
+      problems.push(unreadable(page));
+      continue;
+    }
     // A generated page is right by its making: it is only checked.
     const generated = text.startsWith(GENERATED_MARK);
     const linked = generated ? { text, changed: 0, problems: [] } : linkPage(text, { page, ...context });
@@ -170,7 +214,9 @@ function run(argv: string[]): { output: Record<string, unknown>; failed: boolean
     if (linked.changed === 0) continue;
     links += linked.changed;
     changedPages.push(page);
-    if (!values.check) writeProjectFile(page, Buffer.from(linked.text, "utf8"));
+    if (values.check) continue;
+    writeProjectFile(page, Buffer.from(linked.text, "utf8"));
+    texts.set(page, linked.text);
   }
   const byKind: Record<string, number> = {};
   for (const problem of problems) byKind[problem.kind] = (byKind[problem.kind] ?? 0) + 1;

package/skills/c64-knowledge/SKILL.md

@@ -109,7 +109,7 @@ Write:
 
 1. Read the current value with `at`. Note the `revision` in the result.
 2. Decide the change. Keep observed facts apart from your conclusions.
-3. Write it with `--reason` and `--expect-revision` set to the revision you read. Add `--evidence` for each thing that the change rests on: `coverage:<map>`, `test:<file>`, `file:<file>` or `note:<text>`. `<map>` is a coverage map that `coverage` put into the knowledge, by its path at that time. The script keeps the SHA-256 of each file and map.
+3. Write it with `--reason` and `--expect-revision` set to the revision you read. Add `--evidence` for each thing that the change rests on: `coverage:<map>`, `test:<file>`, `file:<file>` or `note:<text>`. `<map>` is a coverage map that `coverage` put into the knowledge, by its path at that time. The script uses the last import of the map into the space of the write. The script keeps the SHA-256 of each file and map.
 4. Read the result. A `revision` of `null` means that nothing changed.
 
 Each write is one revision. A classification inside a region splits that region, so regions never overlap.
@@ -124,7 +124,7 @@ The knowledge holds the program, so a project needs no image or coverage files.
 4. Read what the knowledge holds with `program`: the segments, the entry, and the coverage maps that it has.
 
 - `image` writes only the bytes that changed. The same image again writes nothing. A new image replaces the program of the space. The history keeps the old bytes.
-- `coverage` joins the maps. It keeps each address that a run executed, read or wrote. It also keeps each address that one run wrote and executed: self-modified code. A map that the knowledge has is not added again.
+- `coverage` joins the maps. It keeps each address that a run executed, read or wrote. It also keeps each address that one run wrote and executed: self-modified code. `coverage` puts each map into the space of `--space`. You can add the same map to each space. A map that the space has is not added again.
 - The capture and the maps are not necessary after the import. Keep them in `.c64-re-tools/local/`.
 
 For more than a few writes, use `apply -` and give the writes on standard input as one JSON list. Each write has `op` and the arguments of the command with the same name, for example:

package/skills/c64-knowledge/scripts/knowledge.ts

@@ -100,7 +100,7 @@ import {
 import { platformNames } from "#src/platform.ts";
 import { addCoverage, coverageRuns, programCoverage, programImage, requireProgram, setImage, type ImageRequest } from "#src/knowledge/program.ts";
 import { WireFailure } from "#src/host-client/tools.ts";
-import { isInside, LOCAL_DIRECTORY, PROJECT_DIRECTORY, projectRoot, resolveProjectPath } from "#src/project.ts";
+import { isInside, LOCAL_DIRECTORY, PROJECT_DIRECTORY, projectRelative, projectRoot, resolveProjectPath } from "#src/project.ts";
 import { listing, listingText, type ListingSource } from "./lib/listing.ts";
 import { runScript, UsageError } from "#src/script.ts";
 
@@ -424,7 +424,7 @@ function run(argv: string[]): unknown {
   const context: WriteContext = { origin: values.origin === undefined ? "llm" : oneOf(["user", "llm"] as const, values.origin, "--origin") };
   if (values.reason !== undefined) context.description = values.reason;
   if (values["expect-revision"] !== undefined) context.expectedRevision = values["expect-revision"];
-  if (values.evidence !== undefined) context.evidence = values.evidence.map(evidenceOf);
+  if (values.evidence !== undefined) context.evidence = values.evidence.map((value) => evidenceOf(value, space));
   // Every argument is checked before the database opens: a refused write creates no database.
   if (values.title !== undefined && command !== "module") throw new UsageError("--title works only with module");
   for (const option of ["lo", "hi", "value", "expr", "offset"] as const) {
@@ -562,7 +562,7 @@ function readAnswer(db: DatabaseSync | undefined, command: string, args: string[
                 state: image.state !== undefined,
                 stages: image.stages?.length ?? 0,
               },
-        coverage: { maps: coverageRuns(db).map((run) => run.name), ranges: Object.fromEntries(ranges.map((row) => [row.kind, row.count])) },
+        coverage: { maps: [...new Set(coverageRuns(db).filter((run) => run.space === space).map((run) => run.name))], ranges: Object.fromEntries(ranges.map((row) => [row.kind, row.count])) },
       };
     }
     case "export": {
@@ -644,23 +644,34 @@ function originFilter(value: string): Origin[] {
   return [...origins];
 }
 
+/** A project path as the knowledge names it: one spelling for each file, so ./runs/a.bin and runs/a.bin are the same file. */
+function knowledgePath(path: string, what: string): string {
+  try {
+    return projectRelative(path);
+  } catch {
+    throw new UsageError(`${what} must be a path relative to the project folder that stays inside it, not ${path}`);
+  }
+}
+
 /**
  * --evidence kind:ref. A file kind names a project file and keeps its SHA-256, so a later change of the file shows.
  * A file in .c64-re-tools/local/ is refused (D82): git ignores it, and the move that keeps it changes the path.
  */
-function evidenceOf(value: string): Evidence {
+function evidenceOf(value: string, space: string): Evidence {
   const colon = value.indexOf(":");
   const kind = oneOf(EVIDENCE_KINDS, colon < 0 ? value : value.slice(0, colon), "--evidence kind");
-  const ref = colon < 0 ? "" : value.slice(colon + 1);
-  if (ref === "") throw new UsageError(`--evidence needs ${kind}:<${kind === "note" ? "text" : "file"}>`);
-  if (kind === "note") return { kind, ref };
-  // A coverage map is evidence by the name that coverage imported it with (D83).
+  const given = colon < 0 ? "" : value.slice(colon + 1);
+  if (given === "") throw new UsageError(`--evidence needs ${kind}:<${kind === "note" ? "text" : "file"}>`);
+  if (kind === "note") return { kind, ref: given };
+  const ref = knowledgePath(given, `--evidence ${kind}:<file>`);
+  // A coverage map is evidence by the name that coverage imported it with (D83): the latest import into the space of the write (D86).
   if (kind === "coverage") {
     const db = openForRead();
     try {
-      const run = coverageRuns(db).find((item) => item.name === ref);
-      if (run === undefined) throw new UsageError(`--evidence coverage:${ref} names no coverage map of the knowledge: import the map with coverage first`);
-      return { kind, ref, sha256: run.sha256 };
+      const run = coverageRuns(db).filter((item) => item.name === ref && item.space === space).at(-1);
+      const where = space === DEFAULT_SPACE ? "" : ` in ${space}`;
+      if (run === undefined) throw new UsageError(`--evidence coverage:${given} names no coverage map of the knowledge${where}: import the map with coverage${space === DEFAULT_SPACE ? "" : ` --space ${space}`} first`);
+      return { kind, ref, sha256: run.sha256, ...(run.space === DEFAULT_SPACE ? {} : { space: run.space }) };
     } finally {
       db?.close();
     }
@@ -719,7 +730,7 @@ function programOperation(command: "image" | "coverage", args: string[], context
     };
   }
   if (args.length === 0) throw new UsageError("coverage needs one or more coverage maps");
-  const maps = args.map((path) => ({ name: path, bytes: readProjectFile(path).bytes }));
+  const maps = args.map((path) => ({ bytes: readProjectFile(path).bytes, name: knowledgePath(path, "coverage <map>") }));
   return (db) => {
     const { revision, current } = addCoverage(db, context, { space, maps });
     return { revision, ...spaceOf(current), imported: current.imported, known: current.known, ranges: current.ranges };

package/skills/c64-reverse-engineering/SKILL.md

@@ -87,7 +87,7 @@ Do the stages in this sequence. Go to the next stage only when its exit check is
 | 7. Name | c64-provenance: if the workspace has a library, find its routines with `match` and apply the batch. Then c64-knowledge and c64-memory-map: name each routine in the scope and give it a comment. Record the modules. When the scope has hundreds of routines, ask the user which routines to name. The source gives the other routines an `l_xxxx` label. | Each routine that the user selected has a name and a comment. |
 | 8. Generate | c64-source into `src/`. For an unpacked program, add `--loader`. | `check.identical` is true. For an unpacked program, `loader.verified` is true. |
 | 9. Build and test | c64-assembler with `--compare` into `build/`. c64-testing scenarios in `tests/`. | The criteria of stage 1 are true. |
-| 10. Document | When the criteria ask for documentation: c64-docs into `docs/`. | `link.ts --check` of c64-docs gives no problem. |
+| 10. Document | When the criteria ask for documentation: c64-docs into `README.md` and `docs/`. | `link.ts --check` of c64-docs gives no problem. |
 | 11. Hand over | Find each file that you made outside `.c64-re-tools/local/` and that is not a deliverable. Move it into `.c64-re-tools/local/`. Then give the answer (below). | Each file that you made outside `.c64-re-tools/local/` is a deliverable. |
 
 In stage 5, if you cannot get to a part of the program, ask the user how to get to it. Do stages 7 and 8 again until the source is clear. Each run of c64-source writes the source again.
@@ -100,7 +100,7 @@ After stage 7, save each routine that other programs can have to the library wit
 - the generated source
 - the built program and the loader
 - the c64-testing scenarios
-- the documentation in `docs/`, when the criteria ask for it
+- the documentation in `README.md` and `docs/`, when the criteria ask for it
 - the runs in `runs/` that the knowledge gives as evidence
 - the scripts in `tools/` for the formats of this program, when you wrote them.
 
@@ -128,6 +128,7 @@ tests/         c64-testing scenarios
 runs/          the runs that the knowledge gives as evidence
 docs/          the documentation from c64-docs, with the reference in docs/reference/
 tools/         scripts for the formats of this program only
+README.md      the entry page of the documentation from c64-docs
 ```
 
 Commit each folder of the layout and `.c64-re-tools/knowledge/`. The knowledge holds the program, the entry state and the coverage, so the project needs no other folder for them. Put all other files that you make in `.c64-re-tools/local/`, also the captures and the coverage maps after you put them into the knowledge. Do not let git ignore a folder of the layout. Do not change the `.gitignore` files of the project.

package/skills/c64-source/scripts/generate.ts

@@ -8,10 +8,10 @@
 // passes, 1 when one fails, 2 for a bad call.
 
 import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
-import { join, posix } from "node:path";
+import { join } from "node:path";
 import { parseArgs } from "node:util";
 
-import { COVERAGE, coverageSeedKinds, formatC64Address, parseC64Address, prgRange, textToPetscii } from "#src/c64.ts";
+import { COVERAGE, coverageSeedKinds, formatC64Address, parseC64Address, textToPetscii } from "#src/c64.ts";
 import { autostartLoaded, RUN_LIMIT_FRAMES } from "#src/host-client/autostart.ts";
 import { MAX_MEMORY_READ, WireFailure } from "#src/host-client/tools.ts";
 import { writeProjectFile } from "#src/host-client/transfer.ts";

package/skills/c64-unpacker/scripts/unpack.ts

@@ -104,7 +104,6 @@ async function runSteps(client: ViceSessionClient, steps: ActionStep[]): Promise
 async function trace(program: string, options: { frames: number; entry?: number; steps: ActionStep[] }): Promise<{ output: Record<string, unknown>; failed: boolean }> {
   const { bytes } = readProjectFile(program);
   if (bytes.length < 3) throw new UsageError("the file is too short for a PRG");
-  const load = bytes[0]! | (bytes[1]! << 8);
   if (options.entry === undefined && basicStart(bytes) === undefined) throw new UsageError(NO_BASIC);
   const client = await ViceSessionClient.open({ videoStandard: "pal" });
   try {

package/src/host-client/coverage.ts

@@ -3,38 +3,11 @@
 
 import { COVERAGE, type CodeRange } from "../c64.ts";
 import { MAX_MEMMAP_RANGES, type MemmapRange } from "../protocol/vice.ts";
-import { readProjectFile } from "./transfer.ts";
 import type { ViceSessionClient } from "./vice-session.ts";
 
 /** A full coverage file: offset n is address n (D40). */
 export const FULL_COVERAGE = 0x10000;
 
-/** Reads full coverage files from the project, one map per file. `fail` refuses a file of another size. */
-export function readCoverageMaps(paths: string[], fail: (message: string) => never): Uint8Array[] {
-  return paths.map((path) => {
-    const { bytes } = readProjectFile(path);
-    if (bytes.length !== FULL_COVERAGE) {
-      fail(`--coverage ${path} has ${bytes.length} bytes; a full coverage file has 65536, one for each address. Write it with c64_memmap action read and out, without start and end.`);
-    }
-    return bytes;
-  });
-}
-
-/** Joins coverage maps: an address has every flag that any run gave it. */
-export function joinCoverage(maps: readonly Uint8Array[]): Uint8Array {
-  const joined = new Uint8Array(FULL_COVERAGE);
-  for (const map of maps) for (let address = 0; address < FULL_COVERAGE; address++) joined[address]! |= map[address]!;
-  return joined;
-}
-
-/**
- * Reads full coverage files from the project and joins them: an address has
- * every flag that any run gave it. `fail` refuses a file of another size.
- */
-export function readCoverageFiles(paths: string[], fail: (message: string) => never): Uint8Array | undefined {
-  return paths.length === 0 ? undefined : joinCoverage(readCoverageMaps(paths, fail));
-}
-
 /** The coverage bytes of start..end, read from the session in parts. */
 export async function readCoverage(session: Pick<ViceSessionClient, "memmap">, start = 0x0000, end = 0xffff): Promise<Uint8Array> {
   const map = new Uint8Array(end - start + 1);

package/src/host-client/image.ts

@@ -1,5 +1,5 @@
-// The image that a skill script works on: an image.json of the c64-unpacker
-// skill (a 64 KiB memory and its segments) or a PRG, read from the project.
+// An image.json of the c64-unpacker skill (a 64 KiB memory and its segments)
+// or a PRG, read from the project to put it into the knowledge (D83).
 
 import { posix } from "node:path";
 
@@ -12,12 +12,9 @@ export class ImageError extends Error {
 }
 
 export interface Image {
-  path: string;
   segments: Array<{ start: number; end: number }>;
   /** The byte at an address inside a segment. */
   byteAt: (address: number) => number;
-  /** The bytes that Ghidra analyzes, and how. */
-  analyzed: { bytes: Buffer; kind: "prg" | "flat64k" };
   entry?: number;
   /** entry_state.json next to image.json. */
   statePath?: string;
@@ -35,21 +32,24 @@ export function readImage(path: string): Image {
     } catch (error) {
       throw new ImageError(`${path}: ${(error as Error).message}`);
     }
-    return { path, segments: [{ start: range.start, end: range.end }], byteAt: (address) => range.body[address - range.start]!, analyzed: { bytes, kind: "prg" } };
+    return { segments: [{ start: range.start, end: range.end }], byteAt: (address) => range.body[address - range.start]! };
   }
   const fail = (what: string): never => {
     throw new ImageError(`${path} is not an image.json of the c64-unpacker skill: ${what}`);
   };
-  let manifest: Record<string, unknown>;
+  const isObject = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+  let parsed: unknown;
   try {
-    manifest = JSON.parse(bytes.toString("utf8")) as Record<string, unknown>;
+    parsed = JSON.parse(bytes.toString("utf8"));
   } catch (error) {
     return fail((error as Error).message);
   }
+  const manifest = isObject(parsed) ? parsed : fail("it is not a JSON object");
   const address = (value: unknown, what: string) => (typeof value === "string" && /^\$[0-9a-f]{4}$/i.test(value) ? Number.parseInt(value.slice(1), 16) : fail(`${what} is not a $ address`));
   if (typeof manifest.image !== "string") fail("it has no image");
   if (!Array.isArray(manifest.segments) || manifest.segments.length === 0) fail("it has no segments");
-  const segments = (manifest.segments as Array<Record<string, unknown>>)
+  const segments = (manifest.segments as unknown[])
+    .map((segment, index) => (isObject(segment) ? segment : fail(`segment ${index + 1} is not an object`)))
     .map((segment, index) => ({ start: address(segment.start, `segment ${index + 1} start`), end: address(segment.end, `segment ${index + 1} end`) }))
     .sort((a, b) => a.start - b.start);
   segments.forEach((segment, index) => {
@@ -59,8 +59,8 @@ export function readImage(path: string): Image {
   const directory = posix.dirname(path);
   const memory = readProjectFile(posix.join(directory, manifest.image as string)).bytes;
   if (memory.length !== 0x10000) fail(`its image has ${memory.length} bytes, not 65536`);
-  const image: Image = { path, segments, byteAt: (at) => memory[at]!, analyzed: { bytes: memory, kind: "flat64k" }, statePath: posix.join(directory, "entry_state.json") };
+  const image: Image = { segments, byteAt: (at) => memory[at]!, statePath: posix.join(directory, "entry_state.json") };
   if (manifest.entry !== undefined) image.entry = address(manifest.entry, "entry");
-  if (Array.isArray(manifest.stages)) image.stages = manifest.stages as Array<Record<string, unknown>>;
+  if (Array.isArray(manifest.stages)) image.stages = manifest.stages.map((stage, index) => (isObject(stage) ? stage : fail(`stage ${index + 1} is not an object`)));
   return image;
 }

package/src/host-client/transfer.ts

@@ -1,7 +1,7 @@
 // Reads project files on the client side for transfer to the Host Runtime.
 // The host never sees a client path: only bytes and the file's type.
 
-import { lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import { dirname, extname, join, relative, sep } from "node:path";
 
 import { isInside, ProjectError, projectRoot, resolveProject, resolveProjectFile, resolveProjectPath } from "../project.ts";
@@ -80,6 +80,10 @@ export function writeProjectFile(path: string, bytes: Uint8Array, options: { roo
   } catch {
     throw refuse();
   }
+  // The nearest folder that exists must be inside the project before a folder is made below it.
+  let existing = dirname(file);
+  while (!existsSync(existing)) existing = dirname(existing);
+  if (!isInside(realpathSync(root), realpathSync(existing))) throw refuse();
   mkdirSync(dirname(file), { recursive: true });
   if (!isInside(realpathSync(root), realpathSync(dirname(file)))) throw refuse();
   let link = false;

package/src/knowledge/history.ts

@@ -149,9 +149,14 @@ export function revisionNote(db: DatabaseSync | undefined, id: string): { reason
 
 /** The revision with its evidence, when it has any. */
 function withEvidence(db: DatabaseSync, revision: Revision): Revision {
-  const rows = db.prepare("SELECT kind, ref, sha256 FROM evidence WHERE revision = ? ORDER BY id").all(revision.id) as Raw[];
+  const rows = db.prepare("SELECT kind, ref, sha256, space FROM evidence WHERE revision = ? ORDER BY id").all(revision.id) as Raw[];
   if (rows.length === 0) return revision;
-  const evidence = rows.map((row): Evidence => ({ kind: row.kind as EvidenceKind, ref: row.ref as string, ...(row.sha256 === null ? {} : { sha256: row.sha256 as string }) }));
+  const evidence = rows.map((row): Evidence => ({
+    kind: row.kind as EvidenceKind,
+    ref: row.ref as string,
+    ...(row.sha256 === null ? {} : { sha256: row.sha256 as string }),
+    ...(row.space === null ? {} : { space: row.space as Space }),
+  }));
   return { ...revision, evidence };
 }
 

package/src/knowledge/program.ts

@@ -146,20 +146,28 @@ function currentCoverage(db: DatabaseSync, space: Space): Map<CoverageKind, Uint
   return maps;
 }
 
-/** The project paths of the coverage maps that the knowledge imported, with their SHA-256. */
-export function coverageRuns(db: DatabaseSync | undefined): Array<{ name: string; sha256: string }> {
+/** One import of a coverage map: its project path, its SHA-256, the space it went into (D86) 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 FROM evidence e JOIN revisions r ON r.id = e.revision WHERE r.operation = 'coverage' AND e.kind = 'coverage' ORDER BY e.ref").all() as Array<{
-    name: string;
-    sha256: string;
-  }>;
+  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 (D83): adds the ranges of
  * the flags that no imported run set before, and as wx the addresses that one
- * run both wrote and executed. Each new map is evidence of the revision. A map
- * that the knowledge has with the same name and bytes is not imported again.
+ * run both wrote and executed. Each new map is evidence of the revision, with
+ * its space. A map that the space has with the same name and bytes is not
+ * imported again.
  */
 export function addCoverage(
   db: DatabaseSync,
@@ -172,9 +180,9 @@ export function addCoverage(
     if (map.bytes.length !== SIZE) throw new KnowledgeError("invalid-input", `${map.name} has ${map.bytes.length} bytes; a coverage map has 65536, one for each address.`);
   }
   const hashed = request.maps.map((map) => ({ ...map, sha256: createHash("sha256").update(map.bytes).digest("hex") }));
-  const known = new Set(coverageRuns(db).map((run) => `${run.name}\n${run.sha256}`));
+  const known = new Set(coverageRuns(db).filter((run) => run.space === space).map((run) => `${run.name}\n${run.sha256}`));
   const fresh = hashed.filter((map) => !known.has(`${map.name}\n${map.sha256}`));
-  const evidence: Evidence[] = [...(context.evidence ?? []), ...fresh.map((map): Evidence => ({ kind: "coverage", ref: map.name, sha256: map.sha256 }))];
+  const evidence: Evidence[] = [...(context.evidence ?? []), ...fresh.map((map): Evidence => ({ kind: "coverage", ref: map.name, sha256: map.sha256, ...(space === DEFAULT_SPACE ? {} : { space }) }))];
   return write(db, { ...context, evidence }, "coverage", (change) => {
     const result = { space, imported: fresh.map((map) => map.name), known: hashed.filter((map) => !fresh.includes(map)).map((map) => map.name), ranges: 0 };
     if (fresh.length === 0) return result;

package/src/knowledge/schema.ts

@@ -151,7 +151,8 @@ function createSchema(db: DatabaseSync): void {
         revision TEXT NOT NULL REFERENCES revisions (id),
         kind     TEXT NOT NULL CHECK (kind IN (${list(EVIDENCE_KINDS)})),
         ref      TEXT NOT NULL CHECK (length(ref) > 0),
-        sha256   TEXT CHECK (sha256 IS NULL OR length(sha256) = 64)
+        sha256   TEXT CHECK (sha256 IS NULL OR length(sha256) = 64),
+        space    TEXT CHECK (space IS NULL OR ${SPACE_CHECK})
       );
       CREATE INDEX evidence_revision ON evidence (revision);
       CREATE TABLE comments (
@@ -309,7 +310,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 = 5;
+export const INDEX_VERSION = 6;
 
 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

@@ -231,10 +231,10 @@ export function tableText(db: DatabaseSync, spec: TableSpec): string {
 
 /** The text of the revision log: every revision with its evidence, oldest first. */
 export function revisionsText(db: DatabaseSync): string {
-  const evidence = db.prepare("SELECT kind, ref, sha256 FROM evidence WHERE revision = ? ORDER BY id");
+  const evidence = db.prepare("SELECT kind, ref, sha256, space FROM evidence WHERE revision = ? ORDER BY id");
   return (db.prepare("SELECT * FROM revisions ORDER BY id").all() as Raw[])
     .map((raw) => {
-      const items = (evidence.all(raw.id as string) as Raw[]).map((item) => ({ kind: item.kind, ref: item.ref, ...(item.sha256 === null ? {} : { sha256: item.sha256 }) }));
+      const items = (evidence.all(raw.id as string) as Raw[]).map((item) => ({ kind: item.kind, ref: item.ref, ...(item.sha256 === null ? {} : { sha256: item.sha256 }), ...(item.space === null ? {} : { space: item.space }) }));
       return `${lineOf(raw, REVISION_FIELDS, items.length === 0 ? {} : { evidence: items })}\n`;
     })
     .join("");
@@ -337,7 +337,7 @@ function joinById<T extends { id: string }>(file: string, entries: Array<{ line:
 interface RevisionLine {
   id: string;
   columns: Raw;
-  evidence: Array<{ kind: unknown; ref: unknown; sha256: unknown }>;
+  evidence: Array<{ kind: unknown; ref: unknown; sha256: unknown; space: unknown }>;
 }
 
 const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b);
@@ -349,8 +349,8 @@ function parseRevisions(text: string): RevisionLine[] {
     const evidence = value.evidence ?? [];
     if (!Array.isArray(evidence) || evidence.some((item) => typeof item !== "object" || item === null)) bad(REVISIONS_FILE, line, "evidence must be a list of objects.");
     const items = (evidence as Raw[]).map((item) => {
-      for (const key of Object.keys(item)) if (!["kind", "ref", "sha256"].includes(key)) bad(REVISIONS_FILE, line, `the evidence key ${JSON.stringify(key)} is not known.`);
-      return { kind: item.kind, ref: item.ref, sha256: item.sha256 ?? null };
+      for (const key of Object.keys(item)) if (!["kind", "ref", "sha256", "space"].includes(key)) bad(REVISIONS_FILE, line, `the evidence key ${JSON.stringify(key)} is not known.`);
+      return { kind: item.kind, ref: item.ref, sha256: item.sha256 ?? null, space: item.space ?? null };
     });
     return { line, row: { id: columns.id as string, columns, evidence: items } };
   });
@@ -389,12 +389,12 @@ function parseRows(spec: TableSpec, text: string): RowLine[] {
  */
 export function loadText(db: DatabaseSync, files: ReadonlyMap<string, { text: string }>): void {
   const insertRevision = db.prepare(`INSERT INTO revisions (${REVISION_FIELDS.map((item) => item.column).join(", ")}) VALUES (${REVISION_FIELDS.map(() => "?").join(", ")})`);
-  const insertEvidence = db.prepare("INSERT INTO evidence (revision, kind, ref, sha256) VALUES (?, ?, ?, ?)");
+  const insertEvidence = db.prepare("INSERT INTO evidence (revision, kind, ref, sha256, space) VALUES (?, ?, ?, ?, ?)");
   const revisions = parseRevisions(files.get(REVISIONS_FILE)?.text ?? "").sort((a, b) => compareText(a.id, b.id));
   for (const revision of revisions) {
     try {
       insertRevision.run(...(REVISION_FIELDS.map((item) => revision.columns[item.column]) as Array<string | null>));
-      for (const item of revision.evidence) insertEvidence.run(revision.id, item.kind as string, item.ref as string, item.sha256 as string | null);
+      for (const item of revision.evidence) insertEvidence.run(revision.id, item.kind as string, item.ref as string, item.sha256 as string | null, item.space as string | null);
     } catch (error) {
       throw new KnowledgeError("invalid-database", `.c64-re-tools/knowledge/${REVISIONS_FILE}: the revision ${revision.id} is not valid: ${(error as Error).message}`);
     }

package/src/knowledge/write.ts

@@ -92,6 +92,8 @@ export interface Evidence {
   kind: EvidenceKind;
   ref: string;
   sha256?: string;
+  /** The space that a coverage map was imported into (D86); none is the C64, as for a row. */
+  space?: Space;
 }
 
 /** Who writes and why. Semantic writes come from the user or the LLM, never as an analyzer. */
@@ -212,8 +214,8 @@ export class Change {
       .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);
     this.revision = id;
-    const evidence = this.#db.prepare("INSERT INTO evidence (revision, kind, ref, sha256) VALUES (?, ?, ?, ?)");
-    for (const item of this.#context.evidence ?? []) evidence.run(id, item.kind, item.ref, item.sha256 ?? null);
+    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);
     return id;
   }
 
@@ -348,6 +350,7 @@ function checkEvidence(evidence: Evidence[] | undefined): void {
     checkOneOf(EVIDENCE_KINDS, item.kind, "evidence kind");
     if (item.ref.trim().length === 0 || item.ref.length > MAX_EVIDENCE_REF) throw new KnowledgeError("invalid-input", `evidence has 1 to ${MAX_EVIDENCE_REF} characters after its kind.`);
     if (item.sha256 !== undefined && !/^[0-9a-f]{64}$/.test(item.sha256)) throw new KnowledgeError("invalid-input", "evidence sha256 must be 64 lowercase hex digits.");
+    checkSpace(item);
   }
 }
 

package/src/mcp/tools/debug.ts

@@ -8,7 +8,7 @@ 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 { AddressInput, AddressOutput, Byte, ConditionInput, ConditionOutput, defineTool, HexData, requireFields, showCondition, SpaceInput, toCondition, type ViceSessionApi } from "../server.ts";
+import { AddressInput, AddressOutput, Byte, ConditionInput, ConditionOutput, defineTool, HexData, requireFields, showCondition, SpaceInput, 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. */

package/src/opcodes.ts

@@ -56,10 +56,6 @@ export function takesAddress(mode: Mode): boolean {
   return mode !== "imp" && mode !== "imm";
 }
 
-export function isZeroPageMode(mode: Mode): boolean {
-  return mode === "zp" || mode === "zpx" || mode === "zpy" || mode === "izx" || mode === "izy";
-}
-
 /** How an instruction uses the address of its operand, in the order a summary lists them. */
 export const USE_KINDS = ["read", "written", "modified", "called", "jumped to", "jumped through", "branched to", "pointer", "address", "table", "macro argument"] as const;
 export type UseKind = (typeof USE_KINDS)[number];

package/src/project.ts

@@ -44,6 +44,9 @@ const SCRIPT_REMEDY = "Give --project <folder>";
 /** The folder that --project chose for this process, or undefined. */
 let chosen: string | undefined;
 
+/** The project that the D67 lookup found from a working directory, kept for the next call from the same directory. */
+let found: { cwd: string; root: string } | undefined;
+
 function isProject(folder: string): boolean {
   return statSync(join(folder, PROJECT_DIRECTORY), { throwIfNoEntry: false })?.isDirectory() === true;
 }
@@ -163,7 +166,13 @@ export function useProject(folder: string): void {
 
 /** The project folder of this process: the --project choice, else the D67 lookup from the working directory. */
 export function projectRoot(): string {
-  const root = chosen ?? findProject();
+  let root = chosen;
+  if (root === undefined) {
+    const cwd = process.cwd();
+    if (found?.cwd !== cwd) found = { cwd, root: findProject(cwd) };
+    root = found.root;
+  }
+  // Each call: the first write of a process can make .c64-re-tools/ after the lookup.
   ensureLocal(root);
   return root;
 }
@@ -181,6 +190,11 @@ export function resolveProjectPath(path: string, root = projectRoot()): string {
   throw new TypeError("Project path escapes the project root");
 }
 
+/** A project path in one spelling: relative to the project folder, with / and without ./, .. or a double /. Throws TypeError as resolveProjectPath does. */
+export function projectRelative(path: string, root = projectRoot()): string {
+  return relative(root, resolveProjectPath(path, root)).split(sep).join("/");
+}
+
 /** True when `candidate` is `root` or below it. Both are absolute paths. */
 export function isInside(root: string, candidate: string): boolean {
   const fromRoot = relative(root, candidate);

package/src/protocol/tools.ts

@@ -109,20 +109,6 @@ export function isRelativePath(value: unknown): value is string {
   return typeof value === "string" && value.length <= 1024 && RELATIVE_PATH.test(value) && !value.includes("//") && !value.endsWith("/");
 }
 
-/** Validates a transferred source tree against its attachments. Throws WireFailure(invalid-input). */
-export function validateSourceTree(value: unknown, attachments: readonly Uint8Array[]): SourceTree {
-  if (!Array.isArray(value) || value.length > MAX_TREE_FILES) invalid(`files must list at most ${MAX_TREE_FILES} files`);
-  if (value.length !== attachments.length) invalid("each listed file needs exactly one attachment");
-  const seen = new Set<string>();
-  return value.map((entry, index) => {
-    if (!isObject(entry) || !isRelativePath(entry.path)) invalid("each file needs a relative path inside the source root");
-    if (seen.has(entry.path)) invalid(`the file ${entry.path} is listed twice`);
-    seen.add(entry.path);
-    if (entry.size !== attachments[index]!.length) invalid(`the size of ${entry.path} does not match its bytes`);
-    return { path: entry.path, size: entry.size as number };
-  });
-}
-
 /** Refuses anything but exactly one attachment with at least one byte, named by what it must hold. */
 function oneFile(attachments: readonly Uint8Array[], what: string): void {
   if (attachments.length !== 1 || attachments[0]!.length === 0) invalid(`${what} must be the one attachment, and it must not be empty`);