@henols/c64-re-tools 2.0.0-rc.7 → 2.0.0-rc.9

package/README.md

@@ -27,6 +27,8 @@ Start the Host Runtime and leave it running:
 npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host
 ```
 
+Add `--log-console` to print each request and each c1541 or petcat run, or `--log-dir <directory>` to write them to a file. Both are off by default.
+
 Install into your project and start the agent:
 
 ```
@@ -64,7 +66,7 @@ The Feature installs ACME, dxa, Java 21 and Ghidra, puts the toolkit into the pr
 | `C64RT_GHIDRA` | skills, CLI | The Ghidra installation directory, when `analyzeHeadless` is not on `PATH`. |
 | `C64RT_HOST` | MCP, skills, CLI | `host:port` of the Host Runtime when it is not on 127.0.0.1, `host.docker.internal` or `host.containers.internal` at 6464. |
 | `C64RT_VIDEO` | MCP | `pal` (default) or `ntsc`, fixed for the life of the MCP process. |
-| `C64RT_TRACE` | host, MCP, skills, CLI | A directory for a trace of what the programs do, for a person who debugs a run. See [docs/debug-install.md](docs/debug-install.md). Nothing of the trace reaches the agent. |
+| `C64RT_TRACE` | MCP, skills, CLI | A directory for a trace of what the programs do, for a person who debugs a run. See [docs/debug-install.md](docs/debug-install.md). Nothing of the trace reaches the agent. The host uses `--log-dir` instead. |
 
 Ghidra runs with its own settings directory for each request. The toolkit
 brings its own NMOS 6510 language (all 256 opcodes); your Ghidra installation

package/package.json

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

package/skills/c64-basic/SKILL.md

@@ -54,7 +54,7 @@ The exit status is 0 for a listing. The exit status is 1 for `decoded: false` an
 
 ## Failure and conflicts
 
-- `decoded: false`: the file is not a BASIC program. This is a normal result. Usually the file is machine code. Give it to the c64-static-analysis skill.
+- `decoded: false`: the file is not a BASIC program. This is a normal result. Usually the file is machine code. Give it to the c64-static-analysis skill. A memory dump also gives `decoded: false`: its first two bytes are not a load address, and its bytes go past `$ffff`.
 - An empty `handoffs` list: the BASIC does not start machine code with SYS or USR. Do not make up a handoff. Look for a POKE into a vector or a LOAD of another file in the listing.
 - `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.
 - `not-found` or `invalid-input`: the path or an argument is wrong. Read the message and correct the call.

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

@@ -22,7 +22,7 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
   const result = await decodeBasic({ program });
   if (!result.decoded) return { output: { decoded: false, reason: result.reason }, failed: true };
   const size = statSync(resolveProjectPath(program)).size - 2;
-  const end = Math.min(0xffff, result.loadAddress + size - 1);
+  const end = result.loadAddress + size - 1;
   return {
     output: {
       decoded: true,

package/skills/c64-emulator/SKILL.md

@@ -66,12 +66,13 @@ Write operations need a stopped CPU. Stop the CPU with `c64_execution` action `p
 
 `c64_reset` with `run` false stops the CPU at the first instruction of the reset routine. The result gives that address in `pc`. A reset and `c64_autostart` set `c64_timing` to zero.
 
-A cartridge from `c64_autostart` stays in the C64 through every reset, as on a real C64. `c64_status` gives `cartridge: true` while the C64 has it. `c64_autostart` of a file that is not a cartridge removes the cartridge first.
+A cartridge from `c64_autostart` stays in the C64 through every reset, as on a real C64. `c64_status` gives `cartridge: true` while the C64 has it, and `cartridge: false` when it does not. `c64_autostart` of a file that is not a cartridge removes the cartridge first. `c64_autostart` also sets both joysticks to the center first. `joysticksCentred` gives the ports that it changed.
 
 Step, next and until-return work only in space `c64`. The emulator cannot stop the disk drive CPU after one instruction. To find when the drive executes an address, use `c64_run_until` with an address target in space `drive8`, or a breakpoint in space `drive8`. The drive can execute a few more instructions before it stops. The computer completes its current instruction. The `pc` in the result is the drive address where it stopped.
 
 `c64_keyboard` puts keys in the keyboard queue of the KERNAL. A program that reads the keyboard hardware directly does not see them. Many games do this. The emulator has no command that presses one key of the keyboard matrix. For such a program:
 
+- After `c64_window` or a snapshot restore, the profiler of VICE keeps the routines that ran before the restore. Then `c64_profile` can give the cycles of the program to such a routine, for example `$fd50`. Do not trust the routine addresses of `c64_profile` after a restore.
 - VICE 3.10 and older have a known flaw: bits 5-7 of `$DC00` and `$DC01` are always 0. Then `emulatorFlaw` in the result of `c64_keyboard` and `c64_joystick` gives the flaw. With this flaw, a wait for any key that reads all keyboard columns at one time ends without a key. A wait for one specific key, or a compare of the full byte of a joystick port, never ends. Tell the user about the flaw. The next VICE release and the VICE nightly builds do not have it. Joystick port 1 uses the same lines as the keyboard.
 - For one specific key, for example F1 or RUN/STOP, open the window and ask the user to press the key.
 - Do not change the program to make it accept a key.

package/skills/c64-knowledge/SKILL.md

@@ -146,7 +146,7 @@ The script records the origin `llm`. Use `--origin user` only when the user deci
 
 For a read: the current or historical knowledge in compact JSON.
 
-For a write: the new revision and the current value after the write. If the write replaces a symbol or a region of a different origin, `previous` gives that row as it was before the write. For example, an `llm` write over a `user` name gives `previous`. Read `previous` and tell the user about the change.
+For a write: the new revision and the current value after the write. If the write replaces a symbol or a region of a different origin, `previous` gives that row as it was before the write. For example, an `llm` write over a `user` name gives `previous`. Read `previous` and tell the user about the change. For `apply`, `replaced` lists each write that replaced a row. Each item has the number of the write, its `op` and its `previous`.
 
 The exit status is 0 for a result. The exit status is 1 for an error from the knowledge, for example `conflict`. The exit status is 2 for a wrong argument.
 

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

@@ -346,8 +346,11 @@ function applyOperation(args: string[], context: WriteContext, space: string): W
   const operations = parsed.map((item, index) => batchOperation(item, `write ${index + 1}`, space));
   return (db) => {
     const applied = applyBatch(db, context, operations);
-    // replaced: writes that replaced a row of another origin, as previous does for one write.
-    return { revision: applied.revision, writes: applied.steps.length, replaced: applied.steps.filter((step) => step.previous !== undefined).length };
+    // replaced: each write that replaced a row of another origin, with that row as previous gives it for one write (b2/07).
+    const replaced = applied.steps.flatMap((step, index) =>
+      step.previous === undefined ? [] : [{ write: index + 1, op: operations[index]!.op, previous: Array.isArray(step.previous) ? step.previous.map(region) : symbol(step.previous) }],
+    );
+    return { revision: applied.revision, writes: applied.steps.length, replaced };
   };
 }
 

package/skills/c64-provenance/SKILL.md

@@ -47,7 +47,9 @@ With `--run`, a PRG starts with autostart and RUN. An image starts from its byte
 ## Workflow
 
 1. Run the script on the releases.
-2. Read `identicalShare`. If it is low and `suggestedShifts` is present, the releases are at different addresses. Run the script again with the `--shift` of `suggestedShifts`. `shiftsNotSuggested` tells why a found shift does not fit in `$0000-$ffff`.
+2. Read `identicalShare`. If it is low and `suggestedShifts` is present, the releases are at different addresses. Run the script again with a `--shift` of `suggestedShifts`. `shiftsNotSuggested` tells why a found shift does not fit in `$0000-$ffff`.
+
+   `suggestedShifts` has at most 3 shifts for each release. The shift with the most `matchingSequences` is first. Data that did not move and code that moved give different shifts. Try each shift. `current: true` marks the shift of this run.
 3. Read `differences`. Each one has an address range, the bytes of each release, and `groups`: the releases that have the same bytes there.
 4. To know how the program uses the differences, run the script again with `--run` and the frames that get the program to the part you examine. Read `runtime` of each difference:
    - `first`: the first access in that release: `read`, `write`, `execute` or `none`. An instruction that reads and then writes the same byte, for example INC, counts as `read`. The operand bytes of an executed instruction count as `execute`, for example the value of `LDA #$03`.
@@ -67,6 +69,7 @@ Use `separate` when you have only one release. It gives evidence, not a decision
 
 - `ranges`: the image in ranges with the same stage and access. `stage` is the last unpack stage that wrote the range. In `image.json`, the last stage is the program. An earlier stage is a depacker, an intro or a loader. Only an image from c64-unpacker `capture` has stages. For an image from `loads`, `noStages` tells this.
 - `access`: from the joined `--coverage` files: `executed`, `read`, `written`, `read-written` or `untouched`. `untouched` bytes did not take part in the runs.
+- `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. Run c64-static-analysis first, so that the knowledge has the code regions and the references.
 - `outside`: RAM outside the image 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.
 

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

@@ -93,11 +93,15 @@ function addressesOf(release: Release): number[] {
   return release.segments.flatMap((segment) => Array.from({ length: segment.end - segment.start + 1 }, (_, offset) => segment.start + offset));
 }
 
+/** Most shifts that suggestShifts gives: data that did not move can outvote code that did (b2/04). */
+export const MAX_SUGGESTED_SHIFTS = 3;
+
 /**
- * The shift that puts `other` over `base` best: the most common address
- * difference between equal 8-byte sequences. Undefined when nothing matches.
+ * The shifts that put `other` over `base` best: the most common address
+ * differences between equal 8-byte sequences, most votes first. A shift with
+ * less than a tenth of the best one's votes is chance. Empty when nothing matches.
  */
-export function suggestShift(base: Release, other: Release): { shift: number; matches: number } | undefined {
+export function suggestShifts(base: Release, other: Release): Array<{ shift: number; matches: number }> {
   const WINDOW = 8;
   const key = (release: Release, addresses: number[], at: number) =>
     String.fromCharCode(...addresses.slice(at, at + WINDOW).map((address) => release.byteAt(address)));
@@ -117,9 +121,8 @@ export function suggestShift(base: Release, other: Release): { shift: number; ma
       votes.set(shift, (votes.get(shift) ?? 0) + 1);
     }
   }
-  let best: { shift: number; matches: number } | undefined;
-  for (const [shift, matches] of votes) if (best === undefined || matches > best.matches) best = { shift, matches };
-  return best;
+  const ranked = [...votes].map(([shift, matches]) => ({ shift, matches })).sort((a, b) => b.matches - a.matches || Math.abs(a.shift) - Math.abs(b.shift));
+  return ranked.filter((found) => found.matches * 10 >= ranked[0]!.matches).slice(0, MAX_SUGGESTED_SHIFTS);
 }
 
 export type ShiftSuggestion = { release: number; shift: number; matchingSequences: number } | { release: number; matchingSequences: number; reason: string };

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

@@ -18,7 +18,7 @@ import { KnowledgeError, openForRead } from "#src/knowledge/database.ts";
 import { listReferences, listRegions } from "#src/knowledge/read.ts";
 import { CODE_REGION_TYPES } from "#src/knowledge/schema.ts";
 import { runScript, UsageError } from "#src/script.ts";
-import { compareReleases, shiftSuggestion, suggestShift, type Range, type Release } from "./compare.ts";
+import { compareReleases, shiftSuggestion, suggestShifts, type Range, type Release } from "./compare.ts";
 import { watchRelease, type ImageState, type Start } from "./runtime.ts";
 import { separate } from "./separate.ts";
 
@@ -204,12 +204,17 @@ async function run(argv: string[]): Promise<unknown> {
   const compared = comparison.identicalBytes + comparison.differingBytes;
   const identicalShare = compared === 0 ? 0 : comparison.identicalBytes / compared;
   // A poor match at the load addresses can mean that the releases are placed differently.
+  // Each release gets its best shifts: data that stayed can outvote code that moved, so one is not enough (b2/04).
+  const applied = loaded.map((item) => item.shift);
   const suggestions =
     identicalShare < 0.5
-      ? releases.slice(1).flatMap((release, index) => {
-          const best = suggestShift(releases[0]!, release);
-          return best === undefined || best.shift === 0 ? [] : [shiftSuggestion(releases, loaded.map((item) => item.shift), index + 1, best)];
-        })
+      ? releases.slice(1).flatMap((release, index) =>
+          suggestShifts(releases[0]!, release).map((found) => {
+            const suggestion = shiftSuggestion(releases, applied, index + 1, found);
+            // The shift that the run already has: its votes tell how good the present alignment is.
+            return "shift" in suggestion && suggestion.shift === applied[suggestion.release - 1] ? { ...suggestion, current: true } : suggestion;
+          }),
+        )
       : [];
   const suggested = suggestions.filter((suggestion) => "shift" in suggestion);
   const notSuggested = suggestions.filter((suggestion) => "reason" in suggestion);
@@ -316,9 +321,10 @@ function separateCommand(path: string, coveragePaths: string[], out: string | un
         }),
     ...(coverage === undefined ? {} : { bytesByAccess: Object.fromEntries((["executed", "read", "written", "read-written", "untouched"] as const).map((access) => [access, bytes((range) => range.access === access)])) }),
     ranges: listed(ranges),
+    // total counts every code region; unreachable is a list like the others (b2/08).
     codeRegions: {
-      count: codeRegions.length,
-      ...(loaded.entry === undefined ? {} : { unreachable: codeRegions.filter((region) => region.reachable === false) }),
+      total: codeRegions.length,
+      ...(loaded.entry === undefined ? {} : { unreachable: listed(codeRegions.filter((region) => region.reachable === false)) }),
     },
     ...(coverage === undefined ? {} : { outside: { read: listed(outside.read), executed: listed(outside.executed), generated: listed(outside.generated) } }),
     ...(out === undefined ? {} : { out }),

package/skills/c64-source/SKILL.md

@@ -52,7 +52,7 @@ node <skill>/scripts/generate.ts unpacked/image.json --out src --loader
 - `main.asm` sets the address of each segment and includes the files in address order.
 - Each module in the knowledge is one file. A module starts at its address and stops at the next module or at the end of its segment. Without modules, each segment is one file, `segment_xxxx.asm`.
 - `constants.asm` holds the names of addresses outside the image, for example `EXTCOL = $d020`.
-- 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`. An address in the image without a name gets `l_xxxx`.
+- 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 image without a name gets `l_xxxx`.
 - 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.
 - `lda+2 $0012` is an absolute operand below $0100. `+1` is a zero-page operand with a label.
@@ -72,11 +72,12 @@ Do not edit the generated files. The next run writes over them.
 2. It moves its copier to two free pages. The copier runs with interrupts off and with all RAM visible.
 3. It copies each segment and the pages $0002-$03ff of the entry state into place. The script selects an order in which no copy writes over the packed bytes of a copy that has not run yet.
 4. It sets the display registers of the VIC-II and the VIC bank from `io` in the entry state. Then it waits for the raster line of the entry.
-5. It sets $00/$01, the stack pointer, A, X, Y and the flags, and jumps to the entry.
+5. It sets the CIA timers, their latches and the interrupt masks from `io` and `cia` in the entry state. A running timer gets the value that counts down to the timer value of the entry at the entry.
+6. It sets $00/$01, the stack pointer, A, X, Y and the flags, and jumps to the entry.
 
-The flags go through the free stack byte below the stack pointer (`stackByte`). The loader changes this byte. The loader does not set the SID, the CIA timers or the interrupt registers of the VIC-II. They stay as the KERNAL set them. Thus a scenario can still find a difference in an interrupt or a timer. Then use `runUntil` with `raster` in the c64-testing skill.
+The flags go through the free stack byte below the stack pointer (`stackByte`). The loader changes this byte. The loader does not set the SID, the time of day of the CIAs, the CIA interrupt flags or the interrupt registers of the VIC-II. `loader.limits` names each CIA value that the loader cannot set as it was at the entry. A program that reads the SID voice 3 for random numbers can still differ in a scenario. A raster sync does not change a timer or the SID. Then observe after the program sets up its own random numbers.
 
-The script simulates the copies first. Then it runs `loader.prg` in the emulator to its jump to the entry. It compares the memory, $00/$01, the registers, the display registers of the VIC-II, the VIC bank and the raster line with the entry state there. `loader.verified: true` tells that all of them are equal. An interrupt can run right at the entry, as in the original program.
+The script simulates the copies first. Then it runs `loader.prg` in the emulator to its jump to the entry. It compares the memory, $00/$01, the registers, the display registers of the VIC-II, the VIC bank and the raster line with the entry state there. It also compares the CIA timers, latches and interrupt masks. `loader.verified: true` tells that all of them are equal. An interrupt can run right at the entry, as in the original program.
 
 ## Knowledge
 
@@ -102,7 +103,7 @@ One JSON object:
 - `entryOutside`: the entry of `image.json` is in no segment of the image, with a `reason`. The image does not hold the program.
 - `notExecuted`: with `--coverage`, the count of instructions that no run executed, the count of their ranges, and the first ranges. `all` names the file `not_executed.json` in `--out`. It has all of the ranges. Put all of these ranges in the report.
 - `check`: `identical`, and the result for each segment. A different segment gives its first different address.
-- `loader`: the program, the copies in their order, the copier page, `stackByte`, `verified` and `differences`. When the script cannot make the loader, `loader` has `verified: false` and a `reason`. The loader includes the source. Thus a source that does not assemble to the image also stops the loader.
+- `loader`: the program, the copies in their order, the copier page, `stackByte`, `verified` and `differences`. `limits` lists the CIA values that the loader cannot set. When the script cannot make the loader, `loader` has `verified: false` and a `reason`. The loader includes the source. Thus a source that does not assemble to the image also stops the loader.
 
 The exit status is 0 when the source is identical and the emulator check of the loader passes. The exit status is 1 for a failed check, for an entry in no segment, and for an error. The exit status is 2 for a wrong argument.
 

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

@@ -130,6 +130,8 @@ async function decode(image: Image, knowledge: ReturnType<typeof readKnowledge>,
   }
   const entryPoints = [...seeds].filter(inImage).sort((a, b) => a - b);
   if (entryPoints.length === 0) {
+    // An entry in no segment is a capture fault: the image is data only, and the result says entryOutside (R3-01).
+    if (image.entry !== undefined && !inImage(image.entry)) return new Map();
     throw new UsageError("Ghidra needs an entry point: give --entry, or record a routine or a code region in knowledge with the c64-knowledge skill");
   }
   const dataRanges = knowledge.regions
@@ -286,6 +288,21 @@ async function runLoader(path: string, program: Buffer, plan: LoaderPlan, image:
       const wanted = rasterLine(state.vic.registers);
       if (line !== wanted && line !== wanted + 1) differences.push(`the raster line is ${line}, not ${wanted}`);
     }
+    if (plan.cia !== undefined) {
+      // The CIA timers (D63): at the jump a running timer is 3 cycles, the JMP, before its value at the entry.
+      const chips = (await client.cia("both")).chips;
+      const word = (value: number) => `$${value.toString(16).padStart(4, "0")}`;
+      const differWord = (what: string, got: number, wanted: number) => got !== wanted && differences.push(`${what} is ${word(got)}, not ${word(wanted)}`);
+      for (const timer of plan.cia.timers) {
+        const chip = chips[timer.cia - 1]!;
+        const name = `CIA ${timer.cia} timer ${timer.timer}`;
+        const [counter, latch, control] = timer.timer === "A" ? [chip.timerA, chip.latchA, chip.controlA] : [chip.timerB, chip.latchB, chip.controlB];
+        differ(`${name} control`, control, timer.control);
+        differWord(`${name} latch`, latch, timer.latch);
+        if (timer.counterAtJump !== undefined) differWord(`${name} counter`, counter, timer.counterAtJump);
+      }
+      plan.cia.masks.forEach((mask, index) => differ(`CIA ${index + 1} interrupt mask`, chips[index]!.interruptMask, mask));
+    }
     return { verified: differences.length === 0, differences: differences.slice(0, MAX_LISTED) };
   } finally {
     await client.close();
@@ -457,6 +474,8 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
     copier: formatC64Address(loader.copier),
     stackByte: formatC64Address(loader.stackByte),
     ...ran,
+    // What the loader cannot set as it was at the entry (D63).
+    ...(loader.cia === undefined || loader.cia.limits.length === 0 ? {} : { limits: loader.cia.limits }),
   };
   return { output, failed: !ran.verified };
 }

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

@@ -1,8 +1,8 @@
 // The loader of a generated source (D48): a PRG that copies each segment and
 // the entry state's pages $0002-$03ff into place, sets the display registers
 // of the VIC-II and the VIC bank, waits for the entry's raster line (D60),
-// sets $00/$01, the stack pointer, A, X, Y and the flags, and jumps to the
-// entry. The copies run
+// sets the CIA timers and interrupt masks (D63), sets $00/$01, the stack
+// pointer, A, X, Y and the flags, and jumps to the entry. The copies run
 // from a free page with SEI and all RAM visible, in an order where no copy
 // overwrites the packed bytes of a copy that has not run yet. The plan is
 // simulated here before the emulator runs it.
@@ -24,6 +24,16 @@ export interface EntryState {
   pages: Uint8Array;
   /** The VIC-II at the entry (D60): $d000-$d02e, and the VIC bank (bits 0-1 of $dd00). */
   vic?: { registers: Uint8Array; bank: number };
+  /** CIA 1 and CIA 2 at the entry (D63). */
+  cia?: [EntryCia, EntryCia];
+}
+
+/** A CIA at the entry: $xx00-$xx0f as a read without side effects gives them, and what no read gives. */
+export interface EntryCia {
+  registers: Uint8Array;
+  latchA: number;
+  latchB: number;
+  interruptMask: number;
 }
 
 /**
@@ -85,6 +95,7 @@ export function readEntryState(text: string, path: string): EntryState {
     port: [byte(value.cpuPort?.$00, "cpuPort.$00"), byte(value.cpuPort?.$01, "cpuPort.$01")],
     pages,
     ...readVic(value.io, fail),
+    ...readCia(value, fail),
   };
 }
 
@@ -114,6 +125,8 @@ export interface LoaderPlan {
   stackByte: number;
   end: number;
   text: string;
+  /** The CIA timers and masks that the loader sets, when the entry state has them (D63). */
+  cia?: CiaPlan;
 }
 
 /** The label of the loader's jump to the entry, in ACME's symbol list. */
@@ -190,6 +203,151 @@ function readVic(io: Record<string, any> | undefined, fail: (what: string) => ne
   return { vic: { registers: Buffer.from(vic, "hex"), bank: Number.parseInt(cia2.slice(0, 2), 16) & 0x03 } };
 }
 
+function readCia(value: Record<string, any>, fail: (what: string) => never): { cia: [EntryCia, EntryCia] } | Record<string, never> {
+  if (value.cia === undefined) return {};
+  const chip = (name: "cia1" | "cia2"): EntryCia => {
+    const bytes = value.io?.[name]?.bytes;
+    if (typeof bytes !== "string" || !/^[0-9a-f]{32}$/i.test(bytes)) return fail(`io.${name}.bytes is not 16 bytes of hex`);
+    const hidden = value.cia[name];
+    const number = (item: unknown, what: string, max: number) => (Number.isInteger(item) && (item as number) >= 0 && (item as number) <= max ? (item as number) : fail(`cia.${name}.${what} is not a number from 0 to ${max}`));
+    return { registers: Buffer.from(bytes, "hex"), latchA: number(hidden?.latchA, "latchA", 0xffff), latchB: number(hidden?.latchB, "latchB", 0xffff), interruptMask: number(hidden?.interruptMask, "interruptMask", 0x1f) };
+  };
+  return { cia: [chip("cia1"), chip("cia2")] };
+}
+
+/** One CIA timer that the loader sets, and what the check of the loader expects of it at the jump. */
+export interface CiaTimerPlan {
+  cia: 1 | 2;
+  timer: "A" | "B";
+  /** The control register as a read gives it: without bit 4, the force load. */
+  control: number;
+  latch: number;
+  /** The counter at the jump, 3 cycles before the entry; undefined when the loader cannot set it. */
+  counterAtJump?: number;
+}
+
+export interface CiaPlan {
+  timers: CiaTimerPlan[];
+  masks: [number, number];
+  /** What the loader cannot set as it was at the entry. */
+  limits: string[];
+}
+
+/**
+ * The CIA timers as the KERNAL leaves them when RUN starts the loader, on a
+ * PAL C64: only CIA 1 timer A runs, for the 60 Hz interrupt. A timer that the
+ * entry has in this state is not written. The loader check reads every timer.
+ */
+const KERNAL_TIMERS: ReadonlyArray<{ control: number; latch: number; counter?: number }> = [
+  { control: 0x01, latch: 0x4025 },
+  { control: 0x08, latch: 0xffff, counter: 0xffff },
+  { control: 0x08, latch: 0xffff, counter: 0xffff },
+  { control: 0x08, latch: 0xffff, counter: 0xffff },
+];
+const KERNAL_MASKS: readonly [number, number] = [0x01, 0x00];
+/** Cycles from the end of the CIA part to the entry: $00, $01, the stack pointer, the flags, A, X, Y, PLP and JMP. */
+const TAIL_CYCLES = 33;
+/** Cycles after the write that starts a CIA timer in which it does not count yet, measured in VICE. */
+const CIA_START_DELAY = 1;
+/** Cycles of one raster line of a PAL C64. */
+const LINE_CYCLES = 63;
+const PAL_LINES = 312;
+
+interface Op {
+  text: string;
+  bytes: number;
+  cycles: number;
+}
+
+/**
+ * The copier's CIA part (D63), after the raster wait: the timers and
+ * interrupt masks of the entry state. A running timer is stopped, loaded
+ * with its counter at the entry plus the cycles to the entry, started, and
+ * given its latch, so it counts to the entry's value just at the entry.
+ * Then the interrupt flags that the copy left are read away.
+ */
+export function ciaSection(state: EntryState): { ops: Op[]; plan: CiaPlan } | undefined {
+  if (state.cia === undefined) return undefined;
+  const lda = (value: number): Op => ({ text: `lda #${hex2(value)}`, bytes: 2, cycles: 2 });
+  const sta = (address: number): Op => ({ text: `sta ${hex4(address)}`, bytes: 3, cycles: 4 });
+  const limits: string[] = [];
+  const timers: CiaTimerPlan[] = [];
+  const disable: Op[] = [];
+  const loads: Array<Op | ((cycles: number[]) => Op)> = [];
+  const starts: Op[] = [];
+  const latches: Op[] = [];
+  const acks: Op[] = [];
+  const masks: Op[] = [];
+  /** For each running timer: its index in starts, and how its load value follows from the cycles after its start. */
+  const running: Array<{ start: number; counter: number; latch: number; system: boolean; name: string; plan: CiaTimerPlan }> = [];
+  state.cia.forEach((chip, index) => {
+    const id = (index + 1) as 1 | 2;
+    const base = index === 0 ? 0xdc00 : 0xdd00;
+    let touched = false;
+    for (const timer of ["A", "B"] as const) {
+      const at = timer === "A" ? 0x04 : 0x06;
+      const controlAt = base + (timer === "A" ? 0x0e : 0x0f);
+      const control = chip.registers[timer === "A" ? 0x0e : 0x0f]! & 0xef;
+      const counter = chip.registers[at]! | (chip.registers[at + 1]! << 8);
+      const latch = timer === "A" ? chip.latchA : chip.latchB;
+      const name = `CIA ${id} timer ${timer}`;
+      const plan: CiaTimerPlan = { cia: id, timer, control, latch, counterAtJump: counter };
+      timers.push(plan);
+      const kernal = KERNAL_TIMERS[index * 2 + (timer === "A" ? 0 : 1)]!;
+      const runs = (control & 0x01) !== 0;
+      if (!runs && control === kernal.control && latch === kernal.latch && counter === kernal.counter) continue;
+      touched = true;
+      // Stopped, a write of the high latch byte also loads the counter.
+      loads.push(lda(control & 0xee), sta(controlAt));
+      if (runs) {
+        // Timer A counts system cycles without bit 5, timer B without bits 5 and 6; other inputs do not count in the loader.
+        const system = timer === "A" ? (control & 0x20) === 0 : (control & 0x60) === 0;
+        const slot = running.length;
+        running.push({ start: starts.length, counter, latch, system, name, plan });
+        loads.push((values) => lda(values[slot]! & 0xff), sta(base + at), (values) => lda(values[slot]! >> 8), sta(base + at + 1));
+        starts.push(lda(control), sta(controlAt));
+        latches.push(lda(latch & 0xff), sta(base + at), lda(latch >> 8), sta(base + at + 1));
+        if (system) plan.counterAtJump = counter + 3;
+        continue;
+      }
+      loads.push(lda(counter & 0xff), sta(base + at), lda(counter >> 8), sta(base + at + 1));
+      if (latch === counter) continue;
+      if (latch >> 8 === counter >> 8) {
+        loads.push(lda(latch & 0xff), sta(base + at));
+        continue;
+      }
+      // The high byte loads the counter of a stopped timer too.
+      loads.push(lda(latch & 0xff), sta(base + at), lda(latch >> 8), sta(base + at + 1));
+      plan.counterAtJump = latch;
+      limits.push(`${name} is stopped with the counter $${counter.toString(16).padStart(4, "0")} and the latch $${latch.toString(16).padStart(4, "0")}: a stopped CIA timer loads its latch, so the counter is the latch.`);
+    }
+    const mask = chip.interruptMask;
+    if (mask !== KERNAL_MASKS[index]) {
+      disable.push(lda(0x7f), sta(base + 0x0d));
+      if (mask !== 0) masks.push(lda(0x80 | mask), sta(base + 0x0d));
+      touched = true;
+    }
+    if (touched) acks.push({ text: `lda ${hex4(base + 0x0d)}`, bytes: 3, cycles: 4 });
+    const flags = chip.registers[0x0d]! & 0x1f;
+    if (flags !== 0) limits.push(`CIA ${id} has the interrupt flags $${flags.toString(16).padStart(2, "0")} at the entry: only an event sets a flag, so the loader cannot.`);
+  });
+  if (loads.length === 0 && disable.length === 0) return { ops: [], plan: { timers, masks: [state.cia[0].interruptMask, state.cia[1].interruptMask], limits } };
+  // The cycles from each start write to the entry: what follows it here, and the tail.
+  const after = [...starts, ...latches, ...acks, ...masks];
+  const values = running.map((item) => {
+    const followers = after.slice(item.start + 2).reduce((sum, op) => sum + op.cycles, 0);
+    if (!item.system) return item.counter;
+    const load = item.counter + followers + TAIL_CYCLES - CIA_START_DELAY;
+    if (load <= 0xffff) return load;
+    limits.push(`${item.name} counts from $${item.counter.toString(16).padStart(4, "0")} at the entry: the loader cannot start it so near $ffff without an underflow, so the counter differs.`);
+    delete item.plan.counterAtJump;
+    return item.counter;
+  });
+  const pre: Op[] = state.vic === undefined ? [lda(0x35), { text: "sta $01", bytes: 2, cycles: 3 }] : [];
+  const ops = [...pre, ...disable, ...loads.map((op) => (typeof op === "function" ? op(values) : op)), ...after];
+  return { ops, plan: { timers, masks: [state.cia[0].interruptMask, state.cia[1].interruptMask], limits } };
+}
+
 export interface LoaderInput {
   /** The segments with the files that hold them, in address order. */
   segments: Array<Range & { files: string[] }>;
@@ -222,9 +380,13 @@ export function planLoader(input: LoaderInput): LoaderPlan {
     }
     at += block.range.end - block.range.start + 1;
   }
-  if (plain.length > MAX_COPIES) throw new WireFailure("invalid-input", `The loader needs ${plain.length} copies; it can do at most ${MAX_COPIES}. Join segments in the unpacker capture (--range) or write the loader by hand.`);
+  const cia = ciaSection(state);
+  const ciaSize = cia === undefined ? 0 : cia.ops.reduce((sum, op) => sum + op.bytes, 0);
+  // The CIA part takes room from the copy table in the copier's two pages.
+  const maxCopies = Math.min(MAX_COPIES, Math.floor((COPIER_LIMIT - COPIER_CODE_SIZE - (state.vic === undefined ? 0 : VIC_SIZE) - ciaSize - 2) / COPY_ENTRY));
+  if (plain.length > maxCopies) throw new WireFailure("invalid-input", `The loader needs ${plain.length} copies; it can do at most ${maxCopies}. Join segments in the unpacker capture (--range) or write the loader by hand.`);
   const copierImage = at;
-  const copierSize = COPIER_CODE_SIZE + (state.vic === undefined ? 0 : VIC_SIZE) + COPY_ENTRY * plain.length + 2;
+  const copierSize = COPIER_CODE_SIZE + (state.vic === undefined ? 0 : VIC_SIZE) + ciaSize + COPY_ENTRY * plain.length + 2;
   const end = copierImage + copierSize - 1;
   if (end > LOAD_LIMIT) throw new WireFailure("invalid-input", `The loader would end at ${hex4(end)}, after ${hex4(LOAD_LIMIT)}: loading it would write the I/O area. The image is too large for one loader file.`);
 
@@ -330,7 +492,9 @@ export function planLoader(input: LoaderInput): LoaderPlan {
     "        tax",
     "        jmp .next",
     ".done",
-    ...vicLines(state),
+    // The CIA part runs after the raster wait: the wait ends its whole lines earlier, so the entry comes in its line.
+    ...vicLines(state, Math.floor((cia?.ops.reduce((sum, op) => sum + op.cycles, 0) ?? 0) / LINE_CYCLES)),
+    ...(cia === undefined ? [] : cia.ops.map((op) => `        ${op.text}`)),
     `        lda #${hex2(port0)}`,
     "        sta $00",
     `        lda #${hex2(port1)}`,
@@ -371,6 +535,7 @@ export function planLoader(input: LoaderInput): LoaderPlan {
     stackByte,
     end,
     text: `${lines.join("\n")}\n`,
+    ...(cia === undefined ? {} : { cia: cia.plan }),
   };
 }
 
@@ -379,9 +544,9 @@ export function planLoader(input: LoaderInput): LoaderPlan {
  * display registers and the VIC bank of the entry state, then waits for the
  * entry's raster line, so the program starts in the same phase of the frame.
  */
-function vicLines(state: EntryState): string[] {
+function vicLines(state: EntryState, earlier: number): string[] {
   if (state.vic === undefined) return [];
-  const line = rasterLine(state.vic.registers);
+  const line = (rasterLine(state.vic.registers) - earlier + PAL_LINES) % PAL_LINES;
   return [
     "        lda #$35",
     "        sta $01",

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

@@ -7,7 +7,8 @@
 
 import { COVERAGE, formatC64Address } from "#src/c64.ts";
 import { WireFailure } from "#src/host-client/tools.ts";
-import { isGeneratedFile, type CommentPlacement, type RegionType } from "#src/knowledge/schema.ts";
+import { ANALYZERS } from "#src/knowledge/import.ts";
+import { isGeneratedFile, type CommentPlacement, type Origin, type RegionType } from "#src/knowledge/schema.ts";
 import { hasZeroPageForm, MNEMONICS, MODE_LENGTH, OPCODES, takesAddress, type Mode } from "./opcodes.ts";
 
 export interface Range {
@@ -23,7 +24,8 @@ export interface SourceInput {
   entry?: number;
   /** Where Ghidra decoded an instruction, with its length. */
   instructions: ReadonlyMap<number, number>;
-  symbols: ReadonlyArray<{ address: number; name: string }>;
+  /** Without an origin, a symbol counts as a user or LLM name. */
+  symbols: ReadonlyArray<{ address: number; name: string; origin?: Origin }>;
   regions: ReadonlyArray<{ start: number; end: number; type: RegionType; element?: number }>;
   comments: ReadonlyArray<{ address: number; placement: CommentPlacement; text: string }>;
   modules: ReadonlyArray<{ start: number; file: string; title?: string }>;
@@ -196,10 +198,12 @@ export function layout(input: SourceInput): Layout {
   const wanted = new Set<number>();
   const want = (address: number) => inImage(address) && wanted.add(address);
   const outside = new Set<number>();
-  const symbols = new Map(input.symbols.map((symbol) => [symbol.address, symbol.name]));
   // A platform name that knowledge gives to another address, or that reads as an instruction, is not used.
   const knowledgeNames = new Set(input.symbols.map((symbol) => symbol.name));
   const platform = new Map((input.platform ?? []).filter(({ name }) => !knowledgeNames.has(name) && !MNEMONICS.has(name.toLowerCase())).map(({ address, name }) => [address, name]));
+  // An analyzer name (DXA's ld020) gives way to the platform name (EXTCOL); a user or LLM name wins (D61).
+  const isAnalyzer = (origin: Origin | undefined) => (ANALYZERS as readonly (Origin | undefined)[]).includes(origin);
+  const symbols = new Map(input.symbols.filter((symbol) => !(isAnalyzer(symbol.origin) && platform.has(symbol.address))).map((symbol) => [symbol.address, symbol.name]));
   /** Addresses outside the image without a name of their own, inside a named platform entry of more bytes: the start of that entry (F-20). */
   const insideEntry = new Map<number, number>();
   const use = (address: number) => {

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

@@ -65,7 +65,7 @@ The analyzers take at most 1024 entry points. Knowledge routines and `--entry` c
    - Ghidra: `functions` gives the number of routines that Ghidra found (`count`) and lists the first routines (`listed`). `decompilations` gives C-like code for the requested routines.
    - If a list is not complete, `rest` gives the c64-knowledge command that lists all of them. For `candidates`, `rest` tells you to give a larger `--max-listed`.
    - `conflicts` lists the places where the analyzer and the current knowledge disagree.
-   - `idioms` tells what the script found by pattern: RTS dispatch tables (`rtsTables`), JMP tables (`jumpTables`) and BIT skips (`bitSkips`). 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 then executed (`selfModified`). For `selfModified`, the write and the execution must be in one coverage file. Each list has a `count`. The script does not write the candidates. Look at them and decide.
+   - `idioms` tells what the script found by pattern: RTS dispatch tables (`rtsTables`), JMP tables (`jumpTables`) and BIT skips (`bitSkips`). 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. Clear the memory map between the parts. Each list has a `count`. The script does not write the candidates. Look at them and decide.
    - With `--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.
 6. Give each important routine a name with the c64-knowledge skill. Then run the analysis again. The analyzers use the new names.
 

package/skills/c64-static-analysis/scripts/idioms.ts

@@ -2,8 +2,8 @@
 // JMP tables and BIT skips are found by their exact instruction patterns and
 // become heuristic findings and entry points; DOP padding and self-modified
 // opcodes are only reported. A self-modified opcode is one that one run wrote
-// and executed: a copier's writes in one run and their execution in another
-// do not count (F-16). A table's length is not known statically: entries
+// and executed, in either order, since a coverage file holds no order (R3-04):
+// a copier's writes in one run and their execution in another do not count (F-16). A table's length is not known statically: entries
 // count while each target is a plausible instruction in the program.
 
 import { COVERAGE } from "#src/c64.ts";

package/skills/c64-testing/references/scenario-format.md

@@ -73,7 +73,7 @@ An `observe` step has a checkpoint name. A scenario can have each name only one
 | `vicii` | The VIC-II state: mode, screen address, scroll and colors. |
 | `sprites` | A list of sprite numbers from 0 to 7. The script compares their position, color and flags. |
 
-A `tolerance` is the largest permitted difference for each byte. A `mask` has at most 64 rectangles. A scenario can observe the screen at most at 64 checkpoints.
+A `tolerance` is the largest permitted difference for each byte. A `mask` has at most 64 rectangles. A `mask` must not cover all of the screen: PAL is 384×272 pixels and NTSC is 384×247 pixels. A scenario can observe the screen at most at 64 checkpoints.
 
 `exclude` is a list of bytes in the observed range that the comparison does not include. Each has `at` and a `reason`, for example `{ "at": "$d01e", "reason": "latched sprite collision, not writable" }`. The result lists each excluded byte with its reason.