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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henols/c64-re-tools",
-  "version": "2.0.0-rc.21",
+  "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/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

@@ -41,8 +41,13 @@ const isDirectory = (path: string) => {
 };
 
 function markdownFiles(directory: string): string[] {
-  const root = resolveProjectPath(directory);
   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))) {
@@ -55,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 {
@@ -73,15 +81,22 @@ 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("");
@@ -118,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]));
@@ -144,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.` });
@@ -176,7 +202,11 @@ function run(argv: string[]): { output: Record<string, unknown>; failed: boolean
   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 });
@@ -184,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/src/host-client/image.ts

@@ -37,16 +37,19 @@ export function readImage(path: string): Image {
   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) => {
@@ -58,6 +61,6 @@ export function readImage(path: string): Image {
   if (memory.length !== 0x10000) fail(`its image has ${memory.length} bytes, not 65536`);
   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/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);