@henols/c64-re-tools 2.1.2 → 2.1.3

package/package.json

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

package/skills/c64-disk/scripts/lib/containers.ts

@@ -33,7 +33,8 @@ export interface Crt {
 
 export function parseCrt(bytes: Uint8Array): Crt {
   const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-  if (buffer.length < 0x40 || !hasSignature("crt", buffer)) throw new Refusal("media-error", "the file is not a CRT: it does not start with C64 CARTRIDGE");
+  if (!hasSignature("crt", buffer)) throw new Refusal("media-error", "the file is not a CRT: it does not start with C64 CARTRIDGE");
+  if (buffer.length < 0x40) throw new Refusal("media-error", `the CRT header is shorter than 64 bytes: the file has only ${buffer.length} bytes`);
   const headerLength = buffer.readUInt32BE(0x10);
   const type = buffer.readUInt16BE(0x16);
   const exrom = buffer[0x18]!;

package/skills/c64-emulator/SKILL.md

@@ -135,6 +135,8 @@ An error is `{"error": {"code": "...", "message": "..."}}`. The message tells wh
 - `machine-unavailable` and the message says that the VICE window closed: the session starts the emulator again. Wait a few seconds. Then do the operation again.
 - `machine-state-lost` with a different message: the connection to the host runtime was lost, and the machine state is gone. Do not continue with results from before. The next call starts a new machine when the host runtime runs. Load the program again, and set the breakpoints and the watchpoints again. If the next call gives `machine-unavailable` with a message that the host runtime does not run, obey the rule for that message.
 - `machine-unavailable` and the message names a pause or a dialog in the emulator window: this occurs only while the window is open. Do not send more operations. Tell the user to resume the emulator (Pause, Alt+P) or to close the dialog in the VICE window. Then do the operation again. The machine state does not change.
+- `machine-unavailable` and the message says that the emulator does not take commands now, with no window open: wait a few seconds. Then do the operation again one time. If you get the same error again, stop the task. Tell the user to restart the c64-re-tools MCP server, and wait for the user.
+- `media-error`: the file is not of the type that its extension names. Give a file of that type.
 - `machine-running`: stop the CPU first, then try again.
 - `installation-incomplete`, or `machine-unavailable` with a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script. Do not try to repair the installation.
 - `c64_run_until` with `stopReason` `timeout`: the target did not occur in the frame limit. This is evidence too. Report it.

package/skills/c64-knowledge/SKILL.md

@@ -129,12 +129,16 @@ Write:
 
 Each write is one revision. A classification inside a region splits that region, so regions never overlap.
 
+A write can give the same fact that an analyzer gave. Then the fact gets the origin of the write, and `previous` in the result shows the row of the analyzer. The next analysis does not remove the fact. This is true for a symbol, a region, a comment and a reference. A `--by user` write over the same fact of `llm` also changes the origin to `user`. A `--by llm` write over the same fact of `user` changes nothing.
+
+A comment and a module are at the start of an instruction. In a code region, the script refuses an address that is an operand byte of an instruction. The error gives the start of that instruction. In data, each address is correct.
+
 ## The program and the coverage
 
 The knowledge holds the program, so a project needs no image or coverage files. The other skills read them from the knowledge and take no path to them.
 
 1. Capture a packed program with the c64-unpacker skill into `.c64-re-tools/local/`. Then put it in with `image .c64-re-tools/local/capture/image.json`. The script reads `image.bin`, `entry_state.json` and the stages next to it.
-2. For a program without a packer, drive code or a cartridge bank, put the PRG in with `image <file.prg>`. Give `--space drive8` or `--space bank0` for drive code or a bank.
+2. For a program without a packer, drive code or a cartridge bank, put the PRG in with `image <file.prg>`. Give `--space drive8` or `--space bank0` for drive code or a bank. A PRG has the extension `.prg` or no extension. The script refuses a file with another extension.
 3. Write each coverage map of a run into `.c64-re-tools/local/`. Then add it with `coverage <map.bin> ...`.
 4. Read what the knowledge holds with `program`: the segments, the entry, and the coverage maps that it has.
 
@@ -235,7 +239,7 @@ A patch is ACME code that replaces a range of the program when the build defines
 - The code must fit in the range. NOP ($EA) fills the bytes after the code. `--nop` gives a range of NOP only.
 - `--code` gives the code as text. `--code-file` reads the code from a project file. The code can use the labels and the macros of the source, and local labels with a dot, for example `.skip`.
 - The braces in the code must be pairs, because the source puts the code inside `{ }`.
-- A patch cannot overlap another patch or a macro use.
+- A patch cannot overlap another patch or a macro use. A patch with the same start and the same switch replaces the patch. A patch of another switch at the same start gives the error `conflict`.
 - Each byte of the range must be in the program of the knowledge.
 - A `patch` write without `--comment` keeps the comment that the patch has.
 

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

@@ -328,6 +328,9 @@ function shownPrevious(row: NonNullable<BatchStep["previous"]>) {
   if ("switch" in row) return patch(row);
   if ("body" in row) return macro(row);
   if ("macro" in row) return macroUse(row);
+  if ("placement" in row) return comment(row);
+  if ("from" in row) return reference(row);
+  if ("file" in row) return module(row);
   return symbol(row);
 }
 
@@ -659,10 +662,7 @@ const WRITE_COMMANDS: CommandSpec[] = [
     (call) => {
       const context = contextOf(call);
       const request = { space: call.space, address: call.parseAddress(call.subject(0), "<address>"), placement: oneOf(COMMENT_PLACEMENTS, call.subject(1), "<placement>"), text: call.rest(2).join(" ") };
-      return (db) => {
-        const result = setComment(db, context, request);
-        return { revision: result.revision, comment: comment(result.current) };
-      };
+      return (db) => shown(setComment(db, context, request), "comment", comment);
     },
   ),
   writeCommand({ name: "uncomment", summary: "Removes a comment.", subjects: [ADDRESS, { name: "<placement>", help: `one of ${COMMENT_PLACEMENTS.join(", ")}` }] }, (call) => {
@@ -681,10 +681,7 @@ const WRITE_COMMANDS: CommandSpec[] = [
         const context = contextOf(call);
         const request = { space: call.space, from: call.parseAddress(call.subject(0), "<from>"), to: call.parseAddress(call.subject(1), "<to>"), kind: oneOf(REFERENCE_KINDS, call.subject(2), "<kind>") };
         return name === "reference"
-          ? (db) => {
-              const result = addReference(db, context, request);
-              return { revision: result.revision, reference: reference(result.current) };
-            }
+          ? (db) => shown(addReference(db, context, request), "reference", reference)
           : (db) => ({ revision: removeReference(db, context, request).revision });
       },
     ),
@@ -695,10 +692,7 @@ const WRITE_COMMANDS: CommandSpec[] = [
       const context = contextOf(call);
       const title = call.string("title");
       const request = { space: call.space, start: call.parseAddress(call.subject(0), "<start>"), file: call.subject(1), ...(title === undefined ? {} : { title }) };
-      return (db) => {
-        const result = setModule(db, context, request);
-        return { revision: result.revision, module: module(result.current) };
-      };
+      return (db) => shown(setModule(db, context, request), "module", module);
     },
   ),
   writeCommand({ name: "unmodule", summary: "Removes the module that starts at an address.", subjects: [START] }, (call) => {

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

@@ -68,7 +68,14 @@ export function listing(source: ListingSource, start: number, end: number): List
     const bytes = Array.from({ length }, (_, offset) => source.byteAt(address + offset)!.toString(16).padStart(2, "0")).join(" ");
     const label = source.nameOf(address);
     const second = source.secondNames(address).filter((name) => name !== label);
-    const { line: lineComments, side } = source.comments(address);
+    const { line: lineComments, side: own } = source.comments(address);
+    // A comment inside the line (knowledge of an older version) shows with its address, as in the source of c64-source.
+    const inner: string[] = [];
+    for (let offset = 1; offset < length; offset++) {
+      const found = source.comments(address + offset);
+      for (const text of [...found.line, ...(found.side === undefined ? [] : [found.side])]) inner.push(`${formatC64Address(address + offset)}: ${text}`);
+    }
+    const side = own === undefined && inner.length === 0 ? undefined : [...(own === undefined ? [] : [own]), ...inner].join(" ");
     const references = source.references(address);
     const access = accessOf(source.coverage, address, length);
     return {

package/skills/c64-memory-map/SKILL.md

@@ -36,6 +36,8 @@ node <skill>/scripts/memory-map.ts export --out src/hw.asm
 
 Write a value for `decode` and `--bank` as `$` and hex digits, as a decimal number, or as `%` and binary digits. Put a `$` value in single quotes in a shell.
 
+`at` and `decode` also take a platform name, for example `SCROLY` or `CHROUT`, in upper or lower case. A platform name comes before a name of the knowledge. `list` and `export` show the platform names.
+
 ### Calling the script
 
 - Call a script as `node <skill>/scripts/<script>.ts <command> [subjects] [options]`. The command comes first.

package/skills/c64-memory-map/scripts/memory-map.ts

@@ -3,6 +3,7 @@
 // writes the platform names to a project file as an ACME include.
 
 import { formatC64Address, formatC64Byte } from "#src/c64.ts";
+import { isRefusal, Refusal } from "#src/errors.ts";
 import { writeReported } from "#src/host-client/transfer.ts";
 import { knowledgeNames } from "#src/knowledge/names.ts";
 import { decode, IO, lookup, platformNames, ROM, SYSTEM, type Entry } from "#src/platform.ts";
@@ -10,6 +11,24 @@ import { listed, OPTIONS, runScript, UsageError } from "#src/script.ts";
 
 const show = (entry: Entry) => ({ start: formatC64Address(entry.start), ...(entry.end !== entry.start ? { end: formatC64Address(entry.end) } : {}), name: entry.name, meaning: entry.meaning });
 
+/** The platform names by name in upper case: memory-map knows them also outside a project. */
+const PLATFORM = new Map(platformNames().map((entry) => [entry.name.toUpperCase(), entry.address]));
+
+/**
+ * The address of a name: a platform name (a register, a KERNAL or BASIC entry,
+ * a system variable) in any letter case first, else a name of the knowledge.
+ */
+function names(name: string, space: string): number {
+  const platform = PLATFORM.get(name.toUpperCase());
+  if (platform !== undefined) return platform;
+  try {
+    return knowledgeNames(name, space);
+  } catch (error) {
+    if (!isRefusal(error) || error.code !== "not-found") throw error;
+    throw new Refusal("not-found", `${name} is not a C64 platform name and not a name in the knowledge. Give a $ address, a platform name that memory-map.ts list or export shows (for example SCROLY or CHROUT), or a name that knowledge.ts symbols lists.`);
+  }
+}
+
 const LISTS: Record<string, () => Entry[]> = {
   vic: () => IO[0]!.registers,
   sid: () => IO[1]!.registers,
@@ -22,12 +41,12 @@ const LISTS: Record<string, () => Entry[]> = {
 await runScript({
   name: "memory-map",
   summary: "The platform meaning of C64 addresses and of values in platform registers.",
-  names: knowledgeNames,
+  names,
   commands: [
     {
       name: "at",
       summary: "The platform meaning of each address: its name, area and meaning.",
-      subjects: [{ name: "<address>", help: "an address or a name of the knowledge", list: true }],
+      subjects: [{ name: "<address>", help: "an address, a platform name such as SCROLY, or a name of the knowledge", list: true }],
       run: (call) => ({
         addresses: call.subjects.map((text) => {
           const found = lookup(call.parseAddress(text, "<address>"));
@@ -47,7 +66,7 @@ await runScript({
       name: "decode",
       summary: "The meaning of a value in a platform register.",
       subjects: [
-        { name: "<register>", help: "the register: $0001, $d011, $d016, $d018, $d010, $d015-$d01f, $dc0d, $dd00 or $dd0d" },
+        { name: "<register>", help: "the register, as an address or a platform name: $0001, $d011 (SCROLY), $d016, $d018, $d010, $d015-$d01f, $dc0d, $dd00 or $dd0d" },
         { name: "<value>", help: "the value of the register: $ and hex, decimal, or % and binary, 0 to 255" },
       ],
       options: { bank: { kind: "number", value: "<value>", help: "the value of $dd00, for the VIC-II bank of a $d018 value", max: 0xff } },

package/skills/c64-provenance/SKILL.md

@@ -97,7 +97,8 @@ Use `separate` when you have only one release. It reads the program, its stages
 - `ranges`: the program in ranges with the same stage and access. `stage` is the last unpack stage that wrote the range. The last stage is the program. An earlier stage is a depacker, an intro or a loader. Only a capture of c64-unpacker `capture` has stages. For a program from `loads` or a PRG, `noStages` tells this.
 - `access`: from the coverage of the knowledge: `executed`, `read`, `written`, `read-written` or `untouched`. `untouched` bytes did not take part in the runs. A `read` byte right after executed code, or at a return address, can be a dummy read of the 6502 that the program does not use.
 - `codeRegions.total`: the number of code regions in the knowledge.
-- `codeRegions.unreachable`: code regions of the knowledge that no chain of call and jump references reaches from the entry. A region also reaches the code after it when its last instruction is not RTS, RTI, JMP, BRK or JAM: the CPU continues there. Run c64-static-analysis first, so that the knowledge has the code regions and the references.
+- `roots`: the addresses where the reachability starts. They are the entry, and the NMI, RESET and IRQ vectors at `$FFFA`-`$FFFF` when the image holds them. An interrupt handler starts from its vector, because no call or jump goes to it. `from` tells the source of each root.
+- `codeRegions.unreachable`: code regions of the knowledge that no chain of call and jump references reaches from a root. A region also reaches the code after it when its last instruction is not RTS, RTI, JMP, BRK or JAM: the CPU continues there. Run c64-static-analysis first, so that the knowledge has the code regions and the references.
 - `outside`: RAM outside the program that the program `read` or `executed` but did not write, and code it `generated`. A loader or an earlier stage put the bytes that the program did not write. A `generated` range can have gaps of two bytes or less: these are operand bytes.
 
 Each list has `count` and `listed`. `listed` has the first ranges, at most `--max-listed` (default 50). `--out` writes all of them and the result shows the file as `{out, bytes, sha256}`. Run more coverage runs for parts that are `untouched`, and add them with `coverage` of the c64-knowledge skill, before you decide.
@@ -113,7 +114,7 @@ Use `leftovers` to find what the program holds in addition to its working code.
 | `fill` | One byte that repeats, at least 16 times, or a pattern of two to four bytes that repeats, at least 32 bytes in total. `pattern` is the repeated bytes. |
 | `residue` | Bytes that no run touched and that are no text, BASIC, fill or code region. `bytes` shows the first 16 bytes. |
 | `copies` | Bytes that are the same as earlier bytes of the program, at least 32 bytes. `copyOf` is the address of the earlier bytes. |
-| `deadCode` | Code regions of the knowledge that the entry does not reach, as in `codeRegions.unreachable` of `separate`, and that no run executed. |
+| `deadCode` | Code regions of the knowledge that no root reaches, as in `codeRegions.unreachable` of `separate`, and that no run executed. |
 
 Text from another computer can show the tools of the developer:
 
@@ -194,7 +195,7 @@ Record a confirmed conclusion as a normal comment, region or symbol with the c64
 
 The differing ranges with the bytes of each release and the groups that agree, and the share of identical bytes. `common` gives the ranges where all releases have bytes. `releases` gives the segments and the `shift` of each release. With `--frames`, each difference also has `runtime`, and `run` tells if each release started, or why not.
 
-For `leftovers`: the lists of findings, with `entry` and the number of `stages`. `noEntry`, `noStages` and `noCoverage` tell which knowledge is missing.
+For `leftovers`: the lists of findings, with `entry`, `roots` and the number of `stages`. `noStages` and `noCoverage` tell which knowledge is missing. Without a root, `roots` tells why `deadCode` is empty.
 
 The runtime evidence and the leftovers are evidence only. The script does not decide which bytes are original.
 

package/skills/c64-provenance/scripts/lib/library.ts

@@ -5,8 +5,8 @@
 // suggests its names there as an apply batch. Nothing here writes knowledge.
 
 import { createHash } from "node:crypto";
-import { mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
-import { join, relative, resolve, sep } from "node:path";
+import { mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
 
 import { Refusal } from "#src/errors.ts";
 import { writeRefusal, type Written } from "#src/host-client/transfer.ts";
@@ -14,7 +14,7 @@ import { formatC64Address, instructionLength } from "#src/c64.ts";
 import { evaluate, identifiers, operandText } from "#src/knowledge/expression.ts";
 import type { CommentRow, OperandRow, ReferenceRow, RegionRow, SymbolRow } from "#src/knowledge/read.ts";
 import { COMMENT_PLACEMENTS, type CommentPlacement, isSemantic, OPERAND_SELECTS, type OperandSelect, REFERENCE_KINDS, type ReferenceKind, REGION_TYPES, type RegionType, SYMBOL_KINDS, type SymbolKind } from "#src/knowledge/schema.ts";
-import { PROJECT_DIRECTORY } from "#src/project.ts";
+import { checkOutputPath, isInside, PROJECT_DIRECTORY } from "#src/project.ts";
 
 /** A routine shorter than this is not saved and not searched: its bytes occur by chance. */
 export const MIN_ROUTINE = 16;
@@ -291,14 +291,37 @@ export function parseRoutine(text: string, file: string): Routine {
   };
 }
 
+/**
+ * Refuses a library folder to write that is inside the project `root`, also
+ * through a symbolic link, when the output check of every script refuses it
+ * (checkOutputPath): for example a folder in the knowledge. A folder outside
+ * the project gets no check.
+ */
+function checkLibraryOutput(path: string, root: string): void {
+  let existing = path;
+  while (statSync(existing, { throwIfNoEntry: false }) === undefined && dirname(existing) !== existing) existing = dirname(existing);
+  const real = join(realpathSync(existing), relative(existing, path));
+  const realRoot = realpathSync(root);
+  for (const [base, target] of [[root, path], [realRoot, real]] as const) {
+    if (isInside(base, target)) {
+      // A project path shows with "/" on every system, as the messages give it.
+      checkOutputPath(relative(base, target).split(sep).join("/") || ".", "folder", { root: base, what: "--library" });
+      return;
+    }
+  }
+}
+
 /**
  * The library folder that --library names, relative to the working directory
  * like --project (D71). A library is a plain folder, never a project. With
- * `create`, a missing folder is made.
+ * `create`, a missing folder is made; a folder inside the project must pass
+ * the output check of every script, which refuses the knowledge.
  */
 export function libraryFolder(folder: string, options: { create: boolean; cwd?: string }): string {
   if (folder.length === 0) throw new Refusal("invalid-input", "The library folder must not be empty.");
-  const path = resolve(options.cwd ?? process.cwd(), folder);
+  const root = options.cwd ?? process.cwd();
+  const path = resolve(root, folder);
+  if (options.create) checkLibraryOutput(path, root);
   const stat = statSync(path, { throwIfNoEntry: false });
   if (stat === undefined) {
     if (!options.create) throw new Refusal("not-found", `There is no library folder ${folder}. Save a routine to it first with routine.`);

package/skills/c64-provenance/scripts/lib/separate.ts

@@ -1,7 +1,8 @@
 // Evidence from one release: for each range of the image, the unpack
 // stage that wrote it and the access class from coverage; for each code
 // region of knowledge, whether call and jump references or the run on from
-// its last instruction reach it from the entry; and what the program reads
+// its last instruction reach it from a root (the entry, and the NMI, RESET
+// and IRQ vectors at $fffa-$ffff when the image holds them); and what the program reads
 // or executes outside the image. Evidence only: nothing here decides what is
 // original.
 
@@ -30,13 +31,21 @@ export interface EvidenceRange extends AddressRange {
 
 export interface CodeRegionEvidence extends AddressRange {
   type: string;
-  /** Absent when the image has no entry. */
+  /** Absent when the image has no root: no entry and no hardware vector. */
   reachable?: boolean;
   /** Absent without coverage. */
   executed?: boolean;
 }
 
+/** An address where the reachability starts, and why: the entry, or a hardware vector in the image. */
+export interface Root {
+  address: number;
+  from: "entry" | "NMI vector $fffa" | "RESET vector $fffc" | "IRQ vector $fffe";
+}
+
 export interface Separation {
+  /** The roots of the reachability, in the order entry, NMI, RESET, IRQ. */
+  roots: Root[];
   ranges: EvidenceRange[];
   codeRegions: CodeRegionEvidence[];
   /**
@@ -50,6 +59,24 @@ export interface Separation {
 
 const SYSTEM_PAGES_END = 0x03ff;
 
+/** The hardware vectors of the 6510: the CPU reads them from $fffa-$ffff, the RAM when the KERNAL is banked out. */
+const HARDWARE_VECTORS = [
+  { at: 0xfffa, from: "NMI vector $fffa" },
+  { at: 0xfffc, from: "RESET vector $fffc" },
+  { at: 0xfffe, from: "IRQ vector $fffe" },
+] as const;
+
+/**
+ * The roots of the reachability: the entry, and each hardware vector whose
+ * two bytes are in the image. An interrupt handler runs by its vector, and
+ * no call or jump reference reaches it.
+ */
+export function reachabilityRoots(segments: readonly AddressRange[], memory: Uint8Array, entry?: number): Root[] {
+  const inImage = (address: number) => segments.some((segment) => address >= segment.start && address <= segment.end);
+  const vectors = HARDWARE_VECTORS.filter((vector) => inImage(vector.at) && inImage(vector.at + 1)).map((vector): Root => ({ address: memory[vector.at]! | (memory[vector.at + 1]! << 8), from: vector.from }));
+  return [...(entry === undefined ? [] : [{ address: entry, from: "entry" as const }]), ...vectors];
+}
+
 /** BRK, JMP, RTI, RTS, JMP (indirect) and the JAM opcodes: the CPU does not run on to the next instruction after them. */
 const NO_FALL_THROUGH = new Set([0x00, 0x4c, 0x40, 0x60, 0x6c, 0x02, 0x12, 0x22, 0x32, 0x42, 0x52, 0x62, 0x72, 0x92, 0xb2, 0xd2, 0xf2]);
 
@@ -114,12 +141,13 @@ export function separate(input: SeparationInput): Separation {
     }
   }
 
-  // Reachability: from the region that holds the entry, through call and jump references and the run on
+  // Reachability: from the regions that hold a root, through call and jump references and the run on
   // from the last instruction of a region into the next address, to a fixed point.
   const regions = input.codeRegions.filter((region) => input.segments.some((segment) => region.start <= segment.end && segment.start <= region.end));
   const holding = (address: number) => regions.findIndex((region) => address >= region.start && address <= region.end);
+  const roots = reachabilityRoots(input.segments, input.memory, input.entry);
   const reached = new Set<number>();
-  if (input.entry !== undefined && holding(input.entry) >= 0) reached.add(holding(input.entry));
+  for (const root of roots) if (holding(root.address) >= 0) reached.add(holding(root.address));
   // The CPU runs the bytes after the region as instructions: through bytes of no code region (a dual-use
   // instruction, for example) into the next code region, unless one of them does not run on.
   const runOn = (from: number): number | undefined => {
@@ -154,7 +182,7 @@ export function separate(input: SeparationInput): Separation {
       ran = false;
       for (let address = region.start; address <= region.end && !ran; address++) ran = executed[address] === 1;
     }
-    return { start: region.start, end: region.end, type: region.type, ...(input.entry === undefined ? {} : { reachable: reached.has(index) }), ...(ran === undefined ? {} : { executed: ran }) };
+    return { start: region.start, end: region.end, type: region.type, ...(roots.length === 0 ? {} : { reachable: reached.has(index) }), ...(ran === undefined ? {} : { executed: ran }) };
   });
 
   const read: number[] = [];
@@ -174,5 +202,5 @@ export function separate(input: SeparationInput): Separation {
     for (let address = from + 1; address < to; address++) if (inImage(address)) return false;
     return true;
   };
-  return { ranges, codeRegions, outside: { read: merge(read), executed: merge(ranOutside), generated: merge(generated, 2, outsideImage) } };
+  return { roots, ranges, codeRegions, outside: { read: merge(read), executed: merge(ranOutside), generated: merge(generated, 2, outsideImage) } };
 }

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

@@ -47,7 +47,7 @@ import { compareReleases, shiftSuggestion, suggestShifts, type Release } from ".
 import { findRoutine, libraryFolder, readLibrary, routineFrom, saveRoutine, suggest } from "./lib/library.ts";
 import { watchRelease, type Start } from "./lib/runtime.ts";
 import { findLeftovers } from "./lib/leftovers.ts";
-import { separate } from "./lib/separate.ts";
+import { separate, type Root } from "./lib/separate.ts";
 
 const hexBytes = (bytes: number[]) => Buffer.from(bytes).toString("hex").replace(/(..)(?!$)/g, "$1 ");
 
@@ -239,6 +239,11 @@ function programEvidence() {
   return { program, stages, coverage, found };
 }
 
+/** The roots of the reachability as a person reads them. */
+const showRoots = (roots: readonly Root[]) => roots.map((root) => ({ address: formatC64Address(root.address), from: root.from }));
+
+const NO_ROOTS = "none: the program in the knowledge has no entry, and the image does not hold the hardware vectors at $fffa-$ffff, so no code region is reachable or unreachable.";
+
 const NO_STAGES = "The program in the knowledge has no stage log. Only a capture of c64-unpacker gives one. A capture of loads holds one part of a program and has none.";
 
 /** separate: evidence from the program in the knowledge, with all ranges in --out and the first ones in the result. */
@@ -251,7 +256,8 @@ function separateCommand(call: Call): unknown {
   const ranges = found.ranges.map((range) => ({ ...show(range), ...(range.stage === undefined ? {} : { stage: range.stage }), ...(range.access === undefined ? {} : { access: range.access }) }));
   const codeRegions = found.codeRegions.map((region) => ({ ...show(region), type: region.type, ...(region.reachable === undefined ? {} : { reachable: region.reachable }), ...(region.executed === undefined ? {} : { executed: region.executed }) }));
   const outside = { read: found.outside.read.map(show), executed: found.outside.executed.map(show), generated: found.outside.generated.map(show) };
-  const written = out === undefined ? undefined : writeReported(out, `${JSON.stringify({ ranges, codeRegions, outside }, null, 1)}\n`, { what: "--out" });
+  const roots = showRoots(found.roots);
+  const written = out === undefined ? undefined : writeReported(out, `${JSON.stringify({ roots, ranges, codeRegions, outside }, null, 1)}\n`, { what: "--out" });
   const rest = out === undefined ? undefined : out;
   const list = <T>(items: T[]) => listed(items, max, undefined, rest);
   const bytes = (filter: (range: (typeof found.ranges)[number]) => boolean) => found.ranges.filter(filter).reduce((sum, range) => sum + range.end - range.start + 1, 0);
@@ -266,10 +272,12 @@ function separateCommand(call: Call): unknown {
         }),
     ...(coverage === undefined ? {} : { bytesByAccess: Object.fromEntries((["executed", "read", "written", "read-written", "untouched"] as const).map((access) => [access, bytes((range) => range.access === access)])) }),
     ranges: list(ranges),
+    // The roots of the reachability: the entry and the hardware vectors in the image.
+    roots: roots.length === 0 ? NO_ROOTS : roots,
     // total counts every code region; unreachable is a list like the others.
     codeRegions: {
       total: codeRegions.length,
-      ...(loaded.entry === undefined ? {} : { unreachable: list(codeRegions.filter((region) => region.reachable === false)) }),
+      ...(roots.length === 0 ? {} : { unreachable: list(codeRegions.filter((region) => region.reachable === false)) }),
     },
     ...(coverage === undefined ? {} : { outside: { read: list(outside.read), executed: list(outside.executed), generated: list(outside.generated) } }),
     ...(written === undefined ? {} : written),
@@ -310,7 +318,8 @@ function leftoversCommand(call: Call): unknown {
   const written = out === undefined ? undefined : writeReported(out, `${JSON.stringify(all, null, 1)}\n`, { what: "--out" });
   const list = <T>(items: T[]) => listed(items, max, undefined, out ?? "a larger --max-listed, or --out <file>");
   return {
-    ...(program.entry === undefined ? { noEntry: "The program in the knowledge has no entry, so deadCode is empty." } : { entry: formatC64Address(program.entry) }),
+    ...(program.entry === undefined ? {} : { entry: formatC64Address(program.entry) }),
+    roots: found.roots.length === 0 ? NO_ROOTS : showRoots(found.roots),
     ...(stages === undefined ? { noStages: NO_STAGES } : { stages: stages.length }),
     ...(coverage === undefined ? { noCoverage: "The knowledge has no coverage, so residue is empty and no finding has access. Add coverage with coverage of the c64-knowledge skill." } : {}),
     text: list(all.text.map((item) => (item.text.length > SHOWN_TEXT ? { ...item, text: `${item.text.slice(0, SHOWN_TEXT)} ...`, length: item.text.length } : item))),

package/skills/c64-source/SKILL.md

@@ -80,7 +80,7 @@ When the knowledge has coverage, code that no run executed gets the line `; not
 - `constants.asm` holds the names of addresses outside the program, for example `EXTCOL = $d020`. The file puts the names in groups by memory area, for example zero page, VIC-II registers or CIA 1 registers. Each group is in address order. Drive code and banks have one group only. The side comment of a name tells what the address is. This text is the knowledge comment of the address. Without a comment, the text is the platform meaning. When the knowledge name is not the platform name, the platform name comes first. For an I/O mirror without a meaning, the text gives the register that the mirror repeats. Then `Used:` counts how the source uses the name. The kinds are `read`, `written`, `modified`, `called`, `jumped to`, `jumped through`, `branched to`, `pointer`, `address`, `table` and `macro argument`. `address` is an immediate operand expression. `table` is an entry in a table of addresses.
 - The top of `constants.asm` sets each switch to 0, for example `!ifndef CRACK { CRACK = 0 }`. A build that defines the switch as 1 uses the patches of that switch.
 - A label or a constant gets the name of the address in the knowledge. Without a knowledge name, it gets the platform name of the c64-memory-map skill, for example `EXTCOL` or `CHROUT`. A platform name wins over a name from an analyzer (`dxa`, `ghidra` or `heuristic`), for example `EXTCOL` over `ld020`. A `user` or `llm` name wins over a platform name. An address in the program without a name gets `l_xxxx`.
-- The source uses the names of a ROM only when the program uses that ROM. When the knowledge has coverage, a ROM is in use when a run executed code of it. A read of ROM bytes as data does not count. Without coverage, `$01` of the entry state tells which ROMs are in. When the program uses neither ROM, the zero page and pages 2 and 3 get no system names. `romNamesLeftOut` gives the ROMs that the source did not name, and the evidence.
+- The source uses the names of a ROM only when the program uses that ROM. When the knowledge has coverage, a ROM is in use when a run executed code of it. A read of ROM bytes as data does not count. Without coverage, `$01` of the entry state tells which ROMs are in. When the program uses neither ROM, the zero page and pages 2 and 3 get no system names. `romNamesLeftOut` gives the ROMs that the source did not name, and the evidence. An operand expression or a macro use with such a name gets that reason.
 - `sta $d011  ; $d011: yScroll 3, rows 25, displayEnabled` is a store of an immediate to a register that the c64-memory-map skill decodes. The side comment gives the decoded value. A side comment in the knowledge replaces it.
 - Code regions, and the instructions that Ghidra decodes outside of data regions, become instructions.
 - Data regions become data by their type: `!byte`, `!word`, `!pet`, `!scr`, `!fill`, tables of labels, and sprite bytes in binary.

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

@@ -34,6 +34,8 @@ export interface SourceInput {
   coverage?: Uint8Array;
   /** Platform names: the name of an address that knowledge does not name, the last address of its entry, and what it is. */
   platform?: ReadonlyArray<{ address: number; end: number; name: string; meaning?: string }>;
+  /** The platform names that `platform` leaves out, because the program does not use their ROM: the reason of an expression that names one tells it. */
+  platformLeftOut?: ReadonlySet<string>;
   /** The platform area of an address, and the register that an I/O mirror repeats: constants.asm groups and describes its names with them. */
   describe?: (address: number) => { area: Area; mirrorOf?: number };
   /** What a value in a platform register means (c64-memory-map): an immediate stored to such a register gets it as a side comment. Throws for a register without a decoder. */
@@ -355,6 +357,17 @@ export function layout(input: SourceInput): Layout {
   for (const row of input.platform ?? []) if (!byName.has(row.name)) byName.set(row.name, row.address);
   for (const symbol of input.symbols) byName.set(symbol.name, symbol.address);
   const instructionAt = new Map(pieces.flatMap((piece) => piece.items.flatMap((item) => (item.kind === "instruction" ? [[item.address, item] as const] : []))));
+  /** Why names of an expression are not names of the source: not known, or platform names of a ROM that the program does not use. */
+  const unknownNames = (missing: readonly string[], remedy: string) => {
+    const leftOut = missing.filter((name) => input.platformLeftOut?.has(name) === true);
+    const unknown = missing.filter((name) => !leftOut.includes(name));
+    const are = (names: readonly string[]) => `${names.join(", ")} ${names.length === 1 ? "is" : "are"}`;
+    return [
+      ...(unknown.length === 0 ? [] : [`${are(unknown)} not a symbol of the knowledge or a platform name.`]),
+      ...(leftOut.length === 0 ? [] : [`${are(leftOut)} a platform name of a ROM that the program does not use, so the source leaves ${leftOut.length === 1 ? "it" : "them"} out (romNamesLeftOut).`]),
+      remedy,
+    ].join(" ");
+  };
   // A macro use is a run of whole instructions of one file, of a macro with one param for each arg, whose args name known names.
   const macrosByName = new Map((input.macros ?? []).map((macro) => [macro.name, macro]));
   const macrosAsInstructions: MacroAsInstructions[] = [];
@@ -384,7 +397,7 @@ export function layout(input: SourceInput): Layout {
     }
     const missing = [...new Set(use.args.flatMap((arg) => identifiers(arg)))].filter((name) => !byName.has(name));
     if (missing.length > 0) {
-      fallBack(`${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} not a symbol of the knowledge or a platform name. Name the address with knowledge.ts rename, or give other args with knowledge.ts use.`);
+      fallBack(unknownNames(missing, "Name the address with knowledge.ts rename, or give other args with knowledge.ts use."));
       continue;
     }
     candidates.push({ use, items: run as InstructionItem[] });
@@ -403,7 +416,7 @@ export function layout(input: SourceInput): Layout {
     }
     const missing = identifiers(expression).filter((name) => !byName.has(name));
     if (missing.length > 0) {
-      operandsAsNumbers.push({ address: operand.address, expression, reason: `${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} not a symbol of the knowledge or a platform name. Name the address with knowledge.ts rename, or write the operand again with knowledge.ts operand.` });
+      operandsAsNumbers.push({ address: operand.address, expression, reason: unknownNames(missing, "Name the address with knowledge.ts rename, or write the operand again with knowledge.ts operand.") });
       continue;
     }
     // An immediate operand builds the address of a name; any other operand uses the address as the instruction does.
@@ -1020,8 +1033,9 @@ export function render(layout: Layout, asBytes: ReadonlySet<string>, header: str
             out.push(`${label} = * + ${offset}`);
             result.labels.push({ address: inside, name: label, file: piece.file, line: out.length });
           }
-          for (const text of lineComments.get(inside) ?? []) sides.push(text);
-          if (sideComments.has(inside)) sides.push(sideComments.get(inside)!);
+          // A comment at an operand byte (knowledge of an older version) shows with its address, as in the listing of c64-knowledge.
+          for (const text of lineComments.get(inside) ?? []) sides.push(`${formatC64Address(inside)}: ${text}`);
+          if (sideComments.has(inside)) sides.push(`${formatC64Address(inside)}: ${sideComments.get(inside)!}`);
         }
         const form = formOf(layout, item);
         const { mode } = OPCODES[item.opcode]!;

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

@@ -11,7 +11,7 @@ import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 
 import { Refusal } from "#src/errors.ts";
-import { type AddressRange, COVERAGE, coverageSeedKinds, formatC64Address, textToPetscii } from "#src/c64.ts";
+import { type AddressRange, coverageSeedKinds, formatC64Address, 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 { writeReported, type Written } from "#src/host-client/transfer.ts";
@@ -26,7 +26,7 @@ import { assemble } from "#src/native/acme.ts";
 import { analyze } from "#src/native/ghidra/analyze.ts";
 import { localToolContext } from "#src/native/local.ts";
 import { GHIDRA_LIMITS, type AssembledSymbol, type Diagnostic } from "#src/native/types.ts";
-import { decode as decodeRegister, describeAddress, platformNamesFor, romUseOf, romUseOfPort, type RomUse } from "#src/platform.ts";
+import { decode as decodeRegister, describeAddress, platformNames, platformNamesFor, romUseOfProgram } from "#src/platform.ts";
 import { resolveProjectPath } from "#src/project.ts";
 import { listed, OPTIONS, runScript, UsageError, type Call } from "#src/script.ts";
 import { knowledgeNames } from "#src/knowledge/names.ts";
@@ -491,15 +491,10 @@ async function runLoader(path: string, program: Buffer, plan: LoaderPlan, image:
   }
 }
 
-/**
- * The ROMs the program uses: from the coverage when the knowledge has
- * it, else from $01 of the entry state, else both.
- */
-function romsInUse(image: ProgramImage, coverage: Uint8Array | undefined): RomUse & { from: "coverage" | "entry state" | "none" } {
-  if (coverage !== undefined) return { ...romUseOf(coverage, COVERAGE.romExecute), from: "coverage" };
-  const port = (image.state?.cpuPort as Record<string, unknown> | undefined)?.$01;
-  if (typeof port === "number") return { ...romUseOfPort(port), from: "entry state" };
-  return { basic: true, kernal: true, from: "none" };
+/** The platform names that `used` leaves out: the names of the ROMs that the program does not use. */
+function leftOutNames(used: ReadonlyArray<{ name: string }>): Set<string> {
+  const kept = new Set(used.map((entry) => entry.name));
+  return new Set(platformNames().flatMap((entry) => (kept.has(entry.name) ? [] : [entry.name])));
 }
 
 /** The first words of every file that the script writes. */
@@ -549,7 +544,8 @@ async function generate(call: Call): Promise<{ output: Record<string, unknown>;
   }
   // Read the entry state before the long steps, so a bad state stops the run at once.
   const state = loaderWanted ? loaderState(image.state, "the entry state of the knowledge") : undefined;
-  const romUse = romsInUse(image, coverage);
+  const romUse = romUseOfProgram(coverage, image.state);
+  const platform = platformNamesFor(romUse);
   const { instructions, dataOnly } = await decode(image, knowledge, entries, coverage);
   const laid = layout({
     segments: image.segments,
@@ -567,7 +563,7 @@ async function generate(call: Call): Promise<{ output: Record<string, unknown>;
     macroUses: knowledge.macroUses,
     ...(coverage === undefined ? {} : { coverage }),
     // The platform names are C64 names: drive code and banks get none. A ROM that the program does not use gives none.
-    ...(space === DEFAULT_SPACE ? { platform: platformNamesFor(romUse), describe: describeAddress, decode: decodeRegister } : {}),
+    ...(space === DEFAULT_SPACE ? { platform, platformLeftOut: leftOutNames(platform), describe: describeAddress, decode: decodeRegister } : {}),
   });
   const asBytes = await probe(laid);
   const header = [`Generated by c64-source from knowledge revision ${knowledge.revision}${space === DEFAULT_SPACE ? "" : ` in space ${space}`}.`, "Change names, comments, regions and modules in knowledge, then generate again."];

package/skills/c64-static-analysis/SKILL.md

@@ -40,9 +40,10 @@ Both analyzers use the knowledge from the user and the LLM as seeds:
 
 - Each routine is an entry point.
 - Each region that is not code stays data.
+- Each symbol of the kind `data` or `variable` stays data. The region that is not code and that holds the symbol stays data, also a region of an analyzer. Without such a region, the byte of the symbol stays data. A symbol in a code region or at an executed address is not data. When the region holds an entry point or an executed address, only the byte of the symbol stays data.
 - Each name is a label. The listing, Ghidra and the decompiler show that name.
 
-Facts that an analyzer found are not seeds. A new analysis can then correct or remove them.
+Facts that an analyzer found are not seeds alone. A new analysis can then correct or remove them.
 
 More seeds come from evidence:
 
@@ -90,9 +91,9 @@ The analyzers take at most 1024 entry points. Knowledge routines and `--entry` c
    - `conflicts` lists the places where the analyzer and the current knowledge disagree.
    - DXA or Ghidra can find data where a run executed an instruction start (`executed`), or where a `user` or `llm` symbol of kind `label` or `routine` is (`knowledge`). Then the script does not write that data region, and the earlier region of the analyzer stays. `conflicts` lists each such place. Executed code and your names have priority over the guess of an analyzer.
    - `idioms` tells what the script found by pattern: RTS dispatch tables (`rtsTables`), JMP tables (`jumpTables`) and BIT skips (`bitSkips`). It also finds the `CBM80` header of a cartridge bank at `$8000` (`cartridgeHeaders`). The two start vectors of the header become entry points. The script writes them as knowledge with the origin `heuristic`, and seeds their targets into the same analysis. `candidates` gives DOP padding (`dop`) and opcodes that the program wrote and executed (`selfModified`). For `selfModified`, the write and the execution must be in one coverage file. A coverage file does not record the order. Thus a candidate can also be code that ran first, and that the program then wrote over. To prevent this, save one coverage file for each part of the program, for example the intro and the game. A loader that copies relocated code is also such a part. Clear the memory map between the parts. Each list has a `count`. The script does not write the candidates. Look at them and decide.
-   - `candidates.pointers` gives code that makes an address from immediates. A `vector` or a `zero-page pointer` candidate stores a low byte (`low`) and a high byte (`high`) to a vector or to a zero-page pair that `(zp),y` uses. Its `target` is in the program or has a platform name. A `sprite pointer` candidate stores an immediate (`at`) to a sprite pointer of the screen at $0400 in VIC bank 0. Its `target` (the value × 64) is in a `sprite` region. For each candidate that you confirm, write operand expressions with `operand` of the c64-knowledge skill, for example `operand '<low>' --lo <target name>` and `operand '<high>' --hi <target name>`. Then a rebuild can move the target.
+   - `candidates.pointers` gives code that makes an address from immediates. The script reads only the instructions of the code regions, from the start of each region. A `vector` or a `zero-page pointer` candidate stores a low byte (`low`) and a high byte (`high`) to a vector or to a zero-page pair. A `(zp),y` instruction of the code uses the zero-page pair. Its `target` is in the program or has a platform name. A `sprite pointer` candidate stores an immediate (`at`) to a sprite pointer of the screen at $0400 in VIC bank 0. Its `target` (the value × 64) is in a `sprite` region. For each candidate that you confirm, write operand expressions with `operand` of the c64-knowledge skill, for example `operand '<low>' --lo <target name>` and `operand '<high>' --hi <target name>`. Then a rebuild can move the target.
    - `candidates.pitfalls` gives code that a C64 runs in a different way than it reads. `raster-bit-8`: the instruction at `at` reads $D011, and the instruction at `store` writes the value back. A read of $D011 gives bit 8 of the raster line in bit 7. Thus the write can move the raster interrupt to line 256 or later, and on PAL past line 311 the interrupt never comes. Examine each candidate. Where the code must not keep bit 7, add a comment and test the program.
-   - `candidates.macros` gives runs of instructions that a macro writes as one line, for example `+inc16 ptr`. The script knows these 6502 idioms: `inc16`, `dec16`, `add16_8`, `add16`, `sub16`, `set16`, `mov16` and `wait_line`. It reads the code regions after the analysis. An arg has the name of a `user` or `llm` symbol or a platform name. Each candidate has `macro`, `start`, `end`, `args` and `text`. `known` counts the uses that the knowledge has. `leftOut` counts the candidates with a label inside, or with a patch or a use over them. The c64-source skill writes such a candidate as instructions. With `--out-macro-batch`, `batch` gives the file, the count of writes (`writes`) and the `apply` command. The batch holds the macros that the knowledge does not have, and the uses. When the knowledge has a macro with the same name and another body, `otherMacros` tells that the batch does not have its uses. The script does not write the candidates. Apply the batch, then generate the source again.
+   - `candidates.macros` gives runs of instructions that a macro writes as one line, for example `+inc16 ptr`. The script knows these 6502 idioms: `inc16`, `dec16`, `add16_8`, `add16`, `sub16`, `set16`, `mov16` and `wait_line`. It reads the code regions after the analysis. An arg has the name of a `user` or `llm` symbol or a platform name. A platform name of a ROM that the program does not use is not an arg, because the c64-source skill does not use it. Each candidate has `macro`, `start`, `end`, `args` and `text`. `known` counts the uses that the knowledge has. `leftOut` counts the candidates with a label inside, or with a patch or a use over them. The c64-source skill writes such a candidate as instructions. With `--out-macro-batch`, `batch` gives the file, the count of writes (`writes`) and the `apply` command. The batch holds the macros that the knowledge does not have, and the uses. When the knowledge has a macro with the same name and another body, `otherMacros` tells that the batch does not have its uses. The script does not write the candidates. Apply the batch, then generate the source again.
    - When the knowledge has coverage, a code finding replaces the DXA or Ghidra data where a run executed an instruction start. `coverageConflicts` lists the analyzer data regions where the coverage still shows executed code. Classify them as code with the c64-knowledge skill, or as `dual-use` when the bytes are also data. For many conflicts, write all classifications in one `apply` batch of the c64-knowledge skill.
 6. Give each important routine a name with the c64-knowledge skill. Then run the analysis again. The analyzers use the new names.