@henols/c64-re-tools 2.0.0-rc.10 → 2.0.0-rc.11

package/package.json

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

package/skills/c64-knowledge/SKILL.md

@@ -47,6 +47,8 @@ The script prints one JSON object. An error prints `{"error": {"code": ..., "mes
 | Add or remove a reference | `reference '$2000' '$2100' call` / `unreference ...` |
 | Places that a removal blocks | `suppressions` with `--start` and `--end` |
 | Start a file of generated source | `module '$2000' player.asm --title 'Player movement'` / `unmodule '$2000'` |
+| Write the operand of an instruction as an expression | `operand '$8079' --lo irq_handler --image unpacked/image.json` / `unoperand '$8079'` |
+| Operand expressions | `operands` with `--start` and `--end` |
 | Files of generated source | `modules` |
 | The address spaces that hold knowledge | `spaces` |
 | History | `history '$2100'`, `history --name update_player`, `revisions`, `revision 12` |
@@ -54,7 +56,7 @@ The script prints one JSON object. An error prints `{"error": {"code": ..., "mes
 
 Every command takes `--space`: `c64` (the default), `drive8` for code in the 1541 drive, or `bank0` to `bank255` for cartridge banks. Drive code and banks use the same addresses as the C64, so each space has its own knowledge. A name is unique inside one space. In a batch, a write can name its own `space`.
 
-Symbol kinds are `label`, `routine`, `variable`, `data` and `vector`. Reference kinds are `call`, `jump`, `read`, `write` and `reference`.
+Symbol kinds are `label`, `routine`, `variable`, `data` and `vector`. Reference kinds are `call`, `jump`, `read`, `write`, `reference` and `pointer`. Only an operand expression writes a `pointer` reference.
 
 Region types:
 
@@ -110,6 +112,8 @@ The ops and their fields:
 | `reference`, `unreference` | `from`, `to`, `kind` |
 | `module` | `start`, `file`, `title` (optional) |
 | `unmodule` | `start` |
+| `operand` | `address`, `select` (`lo`, `hi`, `value` or `expr`), `symbol` and `offset` (optional), or `expression` for `expr` |
+| `unoperand` | `address` |
 
 A `line` comment is a line of its own above the address. A `side` comment is at the end of the line of the address. All writes become one revision. If the knowledge refuses one write, the script writes nothing, and the error names the write.
 
@@ -117,6 +121,28 @@ A `line` comment is a line of its own above the address. A `side` comment is at
 
 A module tells the c64-source skill where a file of the generated source starts. The file runs to the next module or to the end of its segment. Each address has one module, and each file name has one module. A file name has letters, digits, underscores or hyphens, and ends in `.asm`. The c64-source skill writes `main.asm`, `loader.asm` and `constants.asm` itself. Thus a module cannot have one of these names, in upper or lower case. The title becomes the first line of the file. A `module` write without a title keeps the title that the module has. Modules have a history, and `revert` restores them.
 
+## Operand expressions
+
+An operand expression tells the c64-source skill how to write the operand of one instruction. The source then has a name, not a number. When code or data changes its length, the operand follows the address that moved.
+
+Give one selector:
+
+| Option | Operand | Source |
+|---|---|---|
+| `--lo <symbol>` | The low byte of the symbol plus the offset | `lda #<irq_handler` |
+| `--hi <symbol>` | The high byte of the symbol plus the offset | `lda #>(sprite_bank+$1000)` |
+| `--value <symbol>` | The symbol plus the offset | `lda bar_colours-1,x` |
+| `--expr <text>` | ACME expression text with names and numbers | `lda #(sprite_bank + 5*64) / 64` |
+
+- `--offset` adds a whole number to the symbol. Write a negative offset as `--offset=-1`.
+- A name is a symbol of the knowledge or a platform name of the c64-memory-map skill.
+- `--expr` takes `$`, `%` and decimal numbers, names, brackets, the operators `+ - * / % << >> >>> & | XOR`, and `<`, `>`, `-` and `!` before an operand.
+- The script compares the value of the expression with the operand in the image. If they are not equal, the script refuses the write. Give the image with `--image`: an `image.json` of the c64-unpacker skill or a PRG. `apply` with an `operand` write also needs `--image`.
+- Each name in the expression gets a `pointer` reference from the instruction. Thus `at` on the named address shows the code that uses the address.
+- A `rename` of a symbol changes the name in each expression. The knowledge refuses `remove-symbol` while an expression uses the symbol. Use `unoperand` first.
+
+Write an operand expression for each immediate that is a byte of an address. Also write one for each table read through the byte before the table. The pointer candidates of the c64-static-analysis skill show many of these places.
+
 ## Removals
 
 `remove-symbol`, `unclassify` and `unreference` block the place for DXA and Ghidra. An analysis does not add a symbol at that address, a region in that range or that reference again. This applies to every removed fact, also to a fact from the LLM.
@@ -146,7 +172,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 `apply`, `replaced` lists each write that replaced a row. Each item has the number of the write, its `op` and its `previous`.
+For a write: the new revision and the current value after the write. If the write replaces a symbol, a region or an operand expression 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

@@ -7,14 +7,17 @@ import type { DatabaseSync } from "node:sqlite";
 import { parseArgs } from "node:util";
 
 import { formatC64Address, parseC64Address } from "#src/c64.ts";
+import { ImageError, readImage } from "#src/host-client/image.ts";
 import { readProjectFile, writeProjectFile } from "#src/host-client/transfer.ts";
 import { KnowledgeError, openForRead, withWrite } from "#src/knowledge/database.ts";
+import { operandText } from "#src/knowledge/expression.ts";
 import { historyAt, historyNamed, revision, revisionNote, revisions, type HistoryEntry } from "#src/knowledge/history.ts";
 import {
   at,
   currentRevision,
   listComments,
   listModules,
+  listOperands,
   listSpaces,
   listReferences,
   listRegions,
@@ -23,6 +26,7 @@ import {
   search,
   type CommentRow,
   type ModuleRow,
+  type OperandRow,
   type ReferenceRow,
   type RegionRow,
   type SuppressionRow,
@@ -32,12 +36,14 @@ import {
   COMMENT_PLACEMENTS,
   DEFAULT_SPACE,
   EVIDENCE_KINDS,
+  OPERAND_SELECTS,
   ORIGINS,
   REFERENCE_KINDS,
   REGION_TYPES,
   SPACE,
   SYMBOL_KINDS,
   type CommentPlacement,
+  type OperandSelect,
   type Origin,
   type ReferenceKind,
   type RegionType,
@@ -49,17 +55,21 @@ import {
   classifyRegion,
   removeComment,
   removeModule,
+  removeOperand,
   removeReference,
   removeSymbol,
   renameSymbol,
   revert,
   setComment,
   setModule,
+  setOperand,
   unclassifyRegion,
   type BatchOperation,
   type Evidence,
+  type OperandImage,
   type WriteContext,
 } from "#src/knowledge/write.ts";
+import { platformNames } from "#src/platform.ts";
 import { runScript, UsageError } from "#src/script.ts";
 
 const USAGE = `knowledge.ts <command> [arguments] [options]
@@ -73,6 +83,7 @@ Read (no database needed):
   references [--start A --end A --kind K --origin O]
   suppressions [--start A --end A]   places that removals keep free of analyzer facts
   modules [--start A --end A --origin O]   where the files of generated source start
+  operands [--start A --end A --origin O]  operand expressions of instructions
   spaces                              the address spaces that hold knowledge
   history <address> | history --name <name>
   revisions [--limit N --before N]
@@ -97,9 +108,18 @@ Write (one revision each; creates the database when needed):
   unreference <from> <to> <kind>
   module <start> <file.asm> [--title T]   a file of generated source starts here
   unmodule <start>
+  operand <address> --lo|--hi|--value <symbol> [--offset N] --image <file>
+  operand <address> --expr <text> --image <file>
+                           write the operand of the instruction at <address> as
+                           an expression: the low or high byte of symbol + N, the
+                           value symbol + N, or ACME expression text; refused when
+                           it does not give the operand in the image (image.json
+                           or PRG); give a negative offset as --offset=-1
+  unoperand <address>
   revert <revision>
   apply <file>             many writes from a JSON file ('-' reads standard input),
-                           all as one revision, or none when one is refused
+                           all as one revision, or none when one is refused;
+                           operand writes need --image <file>
 
 Write options:
   --reason <text>          why, kept with the revision
@@ -144,6 +164,17 @@ const region = (row: RegionRow) => ({
 });
 const comment = (row: CommentRow) => ({ ...spaceOf(row), address: formatC64Address(row.address), placement: row.placement, text: row.text, origin: row.origin, revision: row.revision });
 const module = (row: ModuleRow) => ({ ...spaceOf(row), start: formatC64Address(row.start), file: row.file, ...(row.title === undefined ? {} : { title: row.title }), origin: row.origin, revision: row.revision });
+const operand = (row: OperandRow) => ({
+  ...spaceOf(row),
+  address: formatC64Address(row.address),
+  select: row.select,
+  ...(row.symbol === undefined ? {} : { symbol: row.symbol }),
+  ...(row.offset === 0 ? {} : { offset: row.offset }),
+  ...(row.expression === undefined ? {} : { expression: row.expression }),
+  text: operandText(row),
+  origin: row.origin,
+  revision: row.revision,
+});
 const reference = (row: ReferenceRow) => ({ ...spaceOf(row), from: formatC64Address(row.from), to: formatC64Address(row.to), kind: row.kind, origin: row.origin, revision: row.revision });
 function suppression(row: SuppressionRow) {
   const place =
@@ -167,7 +198,9 @@ function historyEntry(entry: HistoryEntry) {
             ? reference(entry.row)
             : entry.entity === "module"
               ? module(entry.row)
-              : suppression(entry.row);
+              : entry.entity === "operand"
+                ? operand(entry.row)
+                : suppression(entry.row);
   const { revision: _revision, ...row } = shown;
   return { entity: entry.entity, ...row, fromRevision: entry.from, ...(entry.to === undefined ? {} : { toRevision: entry.to }) };
 }
@@ -205,6 +238,12 @@ function run(argv: string[]): unknown {
       out: { type: "string" },
       title: { type: "string" },
       space: { type: "string" },
+      lo: { type: "string" },
+      hi: { type: "string" },
+      value: { type: "string" },
+      expr: { type: "string" },
+      offset: { type: "string" },
+      image: { type: "string" },
       help: { type: "boolean" },
     },
   });
@@ -214,8 +253,8 @@ function run(argv: string[]): unknown {
   if (values.space !== undefined && !SPACE.test(values.space)) throw new UsageError("--space must be c64, drive8, or bank0 to bank255");
   const space = values.space ?? DEFAULT_SPACE;
 
-  const read = new Set(["at", "search", "symbols", "regions", "comments", "references", "suppressions", "modules", "spaces", "history", "revisions", "revision", "export"]);
-  const write = new Set(["rename", "remove-symbol", "classify", "unclassify", "comment", "uncomment", "reference", "unreference", "module", "unmodule", "revert", "apply"]);
+  const read = new Set(["at", "search", "symbols", "regions", "comments", "references", "suppressions", "modules", "operands", "spaces", "history", "revisions", "revision", "export"]);
+  const write = new Set(["rename", "remove-symbol", "classify", "unclassify", "comment", "uncomment", "reference", "unreference", "module", "unmodule", "operand", "unoperand", "revert", "apply"]);
   // Refuse a mistyped command before anything opens, so no database appears by accident.
   if (!read.has(command) && !write.has(command)) throw new UsageError(`unknown command: ${command}`);
   if (read.has(command)) {
@@ -234,6 +273,7 @@ function run(argv: string[]): unknown {
             comments: known.comments.map(comment),
             referencesFrom: known.referencesFrom.map(reference),
             referencesTo: known.referencesTo.map(reference),
+            ...(known.operand === undefined ? {} : { operand: operand(known.operand) }),
             ...(known.suppressions.length === 0 ? {} : { suppressions: known.suppressions.map(suppression) }),
             revision: known.revision,
           };
@@ -261,13 +301,14 @@ function run(argv: string[]): unknown {
             references: listReferences(db, range, undefined, origins, space).map(reference),
             suppressions: listSuppressions(db, range, space).map(suppression),
             modules: listModules(db, range, origins, space).map(module),
+            operands: listOperands(db, range, origins, space).map(operand),
           };
           const bytes = Buffer.from(`${JSON.stringify(exported, null, 2)}\n`, "utf8");
           writeProjectFile(values.out!, bytes, { what: "--out" });
           return {
             out: values.out,
             bytes: bytes.length,
-            counts: { symbols: exported.symbols.length, regions: exported.regions.length, comments: exported.comments.length, references: exported.references.length, suppressions: exported.suppressions.length, modules: exported.modules.length },
+            counts: { symbols: exported.symbols.length, regions: exported.regions.length, comments: exported.comments.length, references: exported.references.length, suppressions: exported.suppressions.length, modules: exported.modules.length, operands: exported.operands.length },
             revision: exported.revision,
           };
         }
@@ -278,6 +319,8 @@ function run(argv: string[]): unknown {
         }
         case "modules":
           return { modules: listModules(db, range, origins, space).map(module) };
+        case "operands":
+          return { operands: listOperands(db, range, origins, space).map(operand) };
         case "spaces":
           return { spaces: listSpaces(db) };
         case "history":
@@ -307,7 +350,16 @@ function run(argv: string[]): unknown {
   if (values.evidence !== undefined) context.evidence = values.evidence.map(evidenceOf);
   // Every argument is checked before the database opens: a refused write creates no database.
   if (values.title !== undefined && command !== "module") throw new UsageError("--title works only with module");
-  const operation = command === "apply" ? applyOperation(args, context, space) : writeOperation(command, args, values.kind, values.element, context, values.title, space);
+  for (const option of ["lo", "hi", "value", "expr", "offset"] as const) {
+    if (values[option] !== undefined && command !== "operand") throw new UsageError(`--${option} works only with operand`);
+  }
+  if (values.image !== undefined && command !== "operand" && command !== "apply") throw new UsageError("--image works only with operand and apply");
+  const operation =
+    command === "apply"
+      ? applyOperation(args, context, space, values.image)
+      : command === "operand"
+        ? operandOperation(args, values, context, space)
+        : writeOperation(command, args, values.kind, values.element, context, values.title, space);
   return withWrite(operation);
 }
 
@@ -332,8 +384,54 @@ function evidenceOf(value: string): Evidence {
   return { kind, ref, sha256: createHash("sha256").update(readProjectFile(ref).bytes).digest("hex") };
 }
 
+/**
+ * The image that operand writes are checked against (D65), with the platform
+ * names. A byte outside the segments of the image is no operand.
+ */
+function operandImage(path: string | undefined, what: string): OperandImage {
+  if (path === undefined) throw new UsageError(`${what} checks each operand expression against the image: give --image <image.json|prg>`);
+  let image: ReturnType<typeof readImage>;
+  try {
+    image = readImage(path);
+  } catch (error) {
+    if (error instanceof ImageError) throw new UsageError(error.message);
+    throw error;
+  }
+  const inside = (at: number) => image.segments.some((segment) => at >= segment.start && at <= segment.end);
+  return { byteAt: (at) => (inside(at) ? image.byteAt(at) : undefined), platform: new Map(platformNames().map((entry) => [entry.name, entry.address])) };
+}
+
+/** An offset: a whole number in decimal or $ hex, with an optional minus sign. */
+function offsetOf(value: unknown, what: string): number {
+  if (typeof value === "number" && Number.isInteger(value)) return value;
+  const match = typeof value === "string" ? /^(-?)(\$[0-9A-Fa-f]{1,4}|[0-9]{1,5})$/.exec(value) : null;
+  if (match === null) throw new UsageError(`${what} must be a whole number such as 1, -1 or '$1000'`);
+  const size = match[2]!.startsWith("$") ? Number.parseInt(match[2]!.slice(1), 16) : Number(match[2]);
+  return match[1] === "-" ? -size : size;
+}
+
+/** operand <address> with one of --lo, --hi, --value or --expr. */
+function operandOperation(args: string[], values: Record<string, unknown>, context: WriteContext, space: string): WriteOperation {
+  const given = (["lo", "hi", "value", "expr"] as const).filter((option) => values[option] !== undefined);
+  if (given.length !== 1) throw new UsageError("operand needs exactly one of --lo, --hi, --value or --expr");
+  const select: OperandSelect = given[0]!;
+  const request: { space: string; address: number; select: OperandSelect; symbol?: string; offset?: number; expression?: string } = { space, address: address(args[0]), select };
+  if (select === "expr") {
+    if (values.offset !== undefined) throw new UsageError("--offset works with --lo, --hi and --value, not with --expr");
+    request.expression = values.expr as string;
+  } else {
+    request.symbol = values[select] as string;
+    if (values.offset !== undefined) request.offset = offsetOf(values.offset, "--offset");
+  }
+  const image = operandImage(values.image as string | undefined, "operand");
+  return (db) => {
+    const result = setOperand(db, { ...context, image }, request);
+    return { revision: result.revision, operand: operand(result.current), ...(result.previous === undefined ? {} : { previous: operand(result.previous) }) };
+  };
+}
+
 /** apply <file>: the batch as BatchOperation values, checked before the database opens. */
-function applyOperation(args: string[], context: WriteContext, space: string): WriteOperation {
+function applyOperation(args: string[], context: WriteContext, space: string, imagePath: string | undefined): WriteOperation {
   if (args.length !== 1) throw new UsageError("apply needs one file, or - for standard input");
   const text = args[0] === "-" ? readFileSync(0, "utf8") : readProjectFile(args[0]!).bytes.toString("utf8");
   let parsed: unknown;
@@ -344,11 +442,14 @@ function applyOperation(args: string[], context: WriteContext, space: string): W
   }
   if (!Array.isArray(parsed)) throw new UsageError("the batch is a JSON list of writes, for example [{\"op\": \"rename\", \"address\": \"$2100\", \"name\": \"update_player\"}]");
   const operations = parsed.map((item, index) => batchOperation(item, `write ${index + 1}`, space));
+  const withImage = operations.some((operation) => operation.op === "operand") ? { ...context, image: operandImage(imagePath, "apply with operand writes") } : context;
   return (db) => {
-    const applied = applyBatch(db, context, operations);
+    const applied = applyBatch(db, withImage, operations);
     // 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) }],
+      step.previous === undefined
+        ? []
+        : [{ write: index + 1, op: operations[index]!.op, previous: Array.isArray(step.previous) ? step.previous.map(region) : "select" in step.previous ? operand(step.previous) : symbol(step.previous) }],
     );
     return { revision: applied.revision, writes: applied.steps.length, replaced };
   };
@@ -365,6 +466,8 @@ const BATCH_FIELDS: Record<BatchOperation["op"], string[]> = {
   unreference: ["from", "to", "kind"],
   module: ["start", "file", "title"],
   unmodule: ["start"],
+  operand: ["address", "select", "symbol", "offset", "expression"],
+  unoperand: ["address"],
 };
 
 /** One write of a batch. A write names its own space, or takes the one of --space. */
@@ -406,7 +509,21 @@ function batchFields(item: unknown, at: string): BatchOperation {
       return { op, start: place("start"), file: text("file"), ...(fields.title === undefined ? {} : { title: text("title") }) };
     case "unmodule":
       return { op, start: place("start") };
-    default:
+    case "operand": {
+      const select = oneOf(OPERAND_SELECTS, text("select"), `${at}: select`);
+      return {
+        op,
+        address: place("address"),
+        select,
+        ...(fields.symbol === undefined ? {} : { symbol: text("symbol") }),
+        ...(fields.offset === undefined ? {} : { offset: offsetOf(fields.offset, `${at}: offset`) }),
+        ...(fields.expression === undefined ? {} : { expression: text("expression") }),
+      };
+    }
+    case "unoperand":
+      return { op, address: place("address") };
+    case "reference":
+    case "unreference":
       return { op, from: place("from"), to: place("to"), kind: oneOf(REFERENCE_KINDS, text("kind"), `${at}: kind`) };
   }
 }
@@ -480,6 +597,10 @@ function writeOperation(command: string, args: string[], kind: string | undefine
       const request = { space, start: address(args[0], "start") };
       return (db) => ({ revision: removeModule(db, context, request).revision });
     }
+    case "unoperand": {
+      const request = { space, address: address(args[0]) };
+      return (db) => ({ revision: removeOperand(db, context, request).revision });
+    }
     case "revert": {
       const request = { revision: integer(args[0], "revision") };
       return (db) => ({ revision: revert(db, context, request).revision });

package/skills/c64-source/SKILL.md

@@ -58,6 +58,8 @@ node <skill>/scripts/generate.ts unpacked/image.json --out src --loader
 - `lda+2 $0012` is an absolute operand below $0100. `+1` is a zero-page operand with a label.
 - `sta NMINV+1` is an address inside a platform entry of more than one byte, for example the high byte of a vector.
 - `name = * + 1` is a label inside an instruction, for example for code that changes its own operand.
+- `lda #<irq_handler` and `lda bar_colours-1,x` are operand expressions of the knowledge. The script writes each name of an expression with the name of its address in the source. An operand expression in a non-immediate mode that starts with a bracket gets `0+` before it, because ACME reads `(...)` as indirect.
+- `; = <irq_handler` at the end of an instruction with a number: the source cannot use this operand expression. `operandsAsNumbers` gives the reason.
 - `!byte` with an instruction as its comment: ACME writes this instruction with a different opcode. The bytes keep the source identical.
 - `not decoded` marks bytes in a code region that Ghidra did not decode.
 - `; not executed $xxxx-$yyyy` starts code that no run of the `--coverage` files executed. The range is the same as in `not_executed.json`.
@@ -75,6 +77,8 @@ Do not edit the generated files. The next run writes over them.
 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 copy table, the copier and the jump to the entry use labels, not numbers. `loader_from_xxxx` and `loader_end_xxxx` are around each packed segment, and `loader_to_xxxx` is its first address in place. The jump goes to the label of the entry. Thus a segment can change its length, and the loader still copies it and jumps to the entry that moved. The display values, the raster line and the CIA values stay numbers. They are the entry state, not addresses of the program.
+
 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. 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.
@@ -82,7 +86,7 @@ The script simulates the copies first. Then it runs `loader.prg` in the emulator
 ## Knowledge
 
 Read:
-- symbols, regions, comments, references and modules of all origins.
+- symbols, regions, comments, references, modules and operand expressions of all origins.
 
 Automatic write:
 - none.
@@ -99,6 +103,8 @@ One JSON object:
 - `labels`: `named` labels from the knowledge and `generated` labels `l_xxxx`.
 - `entriesInData`: each `--entry` in a data region of the knowledge, with the `region` and its `origin`. Ghidra does not decode an entry in a data region.
 - `asBytes`: the instructions that the source has as bytes.
+- `operandExpressions`: the count of instructions that the source has with an operand expression.
+- `operandsAsNumbers`: the operand expressions that the source has as a number with a side comment, each with its `address`, `expression` and `reason`. An expression becomes a number when no instruction with an operand value is at the address, or when a name has no address. An expression that ACME refuses or does not assemble to the image also becomes a number. Then the script assembles the source again, at most three times.
 - `unusedModules`: modules in the knowledge whose start is in no segment of the image. Often this tells that the image does not hold code that the knowledge describes.
 - `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.
@@ -111,6 +117,7 @@ The exit status is 0 when the source is identical and the emulator check of the
 
 - `check.diagnostics`: ACME did not assemble the source. A name in the knowledge can be wrong for ACME. Read the diagnostics and change the name with c64-knowledge.
 - `check.identical: false`: the script has a defect. Give the result to the user.
+- `operandsAsNumbers`: read each `reason`. Correct the expression with `operand` of the c64-knowledge skill, or remove it with `unoperand`.
 - `invalid-input` that names a symbol or a module: change that symbol or module in the knowledge.
 - `entryOutside`: the run fails, but the script still writes and checks the source. With `--loader`, `loader.verified` is `false` with the same `reason`. Capture the image again with c64-unpacker `loads` or `capture`. Make sure that a segment holds the entry.
 - `entriesInData`: an analyzer region of data hides the code at the entry. If the entry is code, record a code region at the entry with the c64-knowledge skill, for example `classify '$0500' '$05ff' code`. A region of the user or the LLM replaces the analyzer region. Then generate again.

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

@@ -12,11 +12,12 @@ import { parseArgs } from "node:util";
 import { formatC64Address, parseC64Address, prgRange, textToPetscii } from "#src/c64.ts";
 import { autostartLoaded, RUN_LIMIT_FRAMES } from "#src/host-client/autostart.ts";
 import { readCoverageFiles } from "#src/host-client/coverage.ts";
+import { ImageError, readImage as readSharedImage, type Image } from "#src/host-client/image.ts";
 import { MAX_MEMORY_READ, WireFailure } from "#src/host-client/tools.ts";
 import { readProjectFile, writeProjectFile } from "#src/host-client/transfer.ts";
 import { ViceSessionClient } from "#src/host-client/vice-session.ts";
 import { KnowledgeError, openForRead } from "#src/knowledge/database.ts";
-import { currentRevision, listComments, listModules, listReferences, listRegions, listSymbols } from "#src/knowledge/read.ts";
+import { currentRevision, listComments, listModules, listOperands, listReferences, listRegions, listSymbols } from "#src/knowledge/read.ts";
 import { CODE_REGION_TYPES, DEFAULT_SPACE, SPACE, type Space } from "#src/knowledge/schema.ts";
 import { assemble } from "#src/native/acme.ts";
 import { analyze } from "#src/native/ghidra/analyze.ts";
@@ -27,7 +28,7 @@ import { resolveProjectPath } from "#src/project.ts";
 import { runScript, UsageError } from "#src/script.ts";
 import { LOADER_JUMP, planLoader, rasterLine, readEntryState, simulate, VIC_DISPLAY_REGISTERS, type EntryState, type LoaderPlan } from "./loader.ts";
 import { OPCODES } from "./opcodes.ts";
-import { entriesInData, entryOutsideImage, instructionText, layout, literalOperand, probeForms, render, type Layout, type Range } from "./source.ts";
+import { entriesInData, entryOutsideImage, instructionText, layout, literalOperand, probeForms, render, type Layout, type Range, type Rendered } from "./source.ts";
 
 const USAGE = `generate.ts <image> --out <dir> [options]
 
@@ -48,58 +49,20 @@ const USAGE = `generate.ts <image> --out <dir> [options]
 The result is one JSON object. Addresses are $ and four hex digits.`;
 
 const MAX_LISTED = 20;
+/** Rounds of assembly that move operand expressions to numbers (D65). */
+const OPERAND_ROUNDS = 3;
 const PROBE_BASE = 0x1000;
 const PROBE_SLOT = 4;
 /** The copies of a full 64 KiB take about 140 frames. */
 const LOADER_FRAMES = 1500;
 
-interface Image {
-  path: string;
-  segments: Range[];
-  byteAt: (address: number) => number;
-  /** The bytes that Ghidra analyzes, and how. */
-  analyzed: { bytes: Buffer; kind: "prg" | "flat64k" };
-  entry?: number;
-  /** entry_state.json next to image.json, when it exists. */
-  statePath?: string;
-}
-
 function readImage(path: string): Image {
-  const { bytes } = readProjectFile(path);
-  if (!path.endsWith(".json")) {
-    let range: ReturnType<typeof prgRange>;
-    try {
-      range = prgRange(bytes);
-    } catch (error) {
-      throw new UsageError(`${path}: ${(error as Error).message}`);
-    }
-    return { path, segments: [{ start: range.start, end: range.end }], byteAt: (address) => range.body[address - range.start]!, analyzed: { bytes, kind: "prg" } };
-  }
-  const fail = (what: string): never => {
-    throw new UsageError(`${path} is not an image.json of the c64-unpacker skill: ${what}`);
-  };
-  let manifest: Record<string, unknown>;
   try {
-    manifest = JSON.parse(bytes.toString("utf8")) as Record<string, unknown>;
+    return readSharedImage(path);
   } catch (error) {
-    return fail((error as Error).message);
+    if (error instanceof ImageError) throw new UsageError(error.message);
+    throw error;
   }
-  const address = (value: unknown, what: string) => (typeof value === "string" && /^\$[0-9a-f]{4}$/i.test(value) ? Number.parseInt(value.slice(1), 16) : fail(`${what} is not a $ address`));
-  if (typeof manifest.image !== "string") fail("it has no image");
-  if (!Array.isArray(manifest.segments) || manifest.segments.length === 0) fail("it has no segments");
-  const segments = (manifest.segments as Array<Record<string, unknown>>)
-    .map((segment, index) => ({ start: address(segment.start, `segment ${index + 1} start`), end: address(segment.end, `segment ${index + 1} end`) }))
-    .sort((a, b) => a.start - b.start);
-  segments.forEach((segment, index) => {
-    if (segment.end < segment.start) fail(`the segment at ${formatC64Address(segment.start)} ends before it starts`);
-    if (index > 0 && segment.start <= segments[index - 1]!.end) fail(`the segments at ${formatC64Address(segments[index - 1]!.start)} and ${formatC64Address(segment.start)} overlap`);
-  });
-  const directory = posix.dirname(path);
-  const memory = readProjectFile(posix.join(directory, manifest.image as string)).bytes;
-  if (memory.length !== 0x10000) fail(`its image has ${memory.length} bytes, not 65536`);
-  const image: Image = { path, segments, byteAt: (at) => memory[at]!, analyzed: { bytes: memory, kind: "flat64k" }, statePath: posix.join(directory, "entry_state.json") };
-  if (manifest.entry !== undefined) image.entry = address(manifest.entry, "entry");
-  return image;
 }
 
 /** The knowledge of one space that the source uses, read once. */
@@ -113,6 +76,7 @@ function readKnowledge(space: Space) {
       comments: listComments(db, undefined, undefined, space),
       modules: listModules(db, undefined, undefined, space),
       references: listReferences(db, undefined, undefined, undefined, space),
+      operands: listOperands(db, undefined, undefined, space),
     };
   } finally {
     db?.close();
@@ -205,6 +169,34 @@ async function probe(laid: Layout): Promise<Set<string>> {
   throw new WireFailure("operation-failed", "ACME refused the opcode probe three times.");
 }
 
+/**
+ * The operand expressions that made the assembly fail or that ACME assembled
+ * to other bytes than the image, with the reason (D65). `markLines` is the
+ * number of lines added before the rendered text of each file.
+ */
+function blame(rendered: Rendered, built: Awaited<ReturnType<typeof assembleFiles>>, image: Image, markLines: number): Map<number, string> {
+  const blamed = new Map<number, string>();
+  if (built.program === undefined) {
+    const lines = new Map(rendered.expressions.map((item) => [`${item.file}:${item.line + markLines}`, item.address]));
+    for (const diagnostic of built.diagnostics) {
+      if (diagnostic.severity !== "error" || diagnostic.file === undefined || diagnostic.line === undefined) continue;
+      const address = lines.get(`${diagnostic.file}:${diagnostic.line}`);
+      if (address !== undefined) blamed.set(address, `ACME refuses it: ${diagnostic.message}`);
+    }
+    return blamed;
+  }
+  const end = built.start! + built.program.length - 3;
+  const word = (at: (address: number) => number, item: Rendered["expressions"][number]) => (item.length === 3 ? at(item.address + 1) | (at(item.address + 2) << 8) : at(item.address + 1));
+  const show = (value: number, length: number) => `$${value.toString(16).padStart(length === 3 ? 4 : 2, "0")}`;
+  for (const item of rendered.expressions) {
+    if (item.address + item.length - 1 > end || item.address < built.start!) continue;
+    const assembled = word((address) => built.program![2 + address - built.start!]!, item);
+    const original = word(image.byteAt, item);
+    if (assembled !== original) blamed.set(item.address, `ACME assembles it to ${show(assembled, item.length)}, and the image has ${show(original, item.length)}.`);
+  }
+  return blamed;
+}
+
 interface SegmentCheck {
   start: string;
   end: string;
@@ -371,14 +363,13 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
     comments: knowledge.comments,
     modules: knowledge.modules,
     referenceTargets: knowledge.references.map((reference) => reference.to),
+    operands: knowledge.operands,
     ...(coverage === undefined ? {} : { coverage }),
     // The platform names are C64 names: drive code and banks get none.
     ...(space === DEFAULT_SPACE ? { platform: platformNames() } : {}),
   });
   const asBytes = await probe(laid);
   const header = [`Generated by c64-source from ${image.path}${space === DEFAULT_SPACE ? "" : ` in space ${space}`} and knowledge revision ${knowledge.revision}.`, "Change names, comments, regions and modules in knowledge, then generate again."];
-  const rendered = render(laid, asBytes, header);
-  const files = [...rendered.files];
   let loader: LoaderPlan | undefined;
   // An image without its entry has no program: the source is still written and checked, but the run fails (R2-02).
   const missingEntry = entryOutsideImage(image.entry, image.segments);
@@ -387,15 +378,29 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
   if (state !== undefined && missingEntry === undefined) {
     const segments = image.segments.map((segment) => ({ ...segment, files: laid.pieces.filter((piece) => piece.start >= segment.start && piece.start <= segment.end).map((piece) => piece.file) }));
     try {
-      loader = planLoader({ segments, byteAt: image.byteAt, state, entry: image.entry!, header: [`Loader generated by c64-source from ${image.path}.`, "It copies the segments into place, sets the entry state and jumps to the entry."] });
-      files.push({ name: "loader.asm", text: loader.text });
+      const entryName = laid.names.get(image.entry!);
+      loader = planLoader({ segments, byteAt: image.byteAt, state, entry: image.entry!, ...(entryName === undefined ? {} : { entryName }), header: [`Loader generated by c64-source from ${image.path}.`, "It copies the segments into place, sets the entry state and jumps to the entry."] });
     } catch (error) {
       if (!(error instanceof WireFailure)) throw error;
       loaderRefused = error.message;
     }
   }
   // Every generated file starts with the mark, so a later run knows its own files and removes the ones it does not write again (F-25).
-  for (const [index, file] of files.entries()) if (!file.text.startsWith(GENERATED_MARK)) files[index] = { ...file, text: `${GENERATED_MARK}. Do not edit: change the knowledge and generate again.\n${file.text}` };
+  const marked = (list: Array<{ name: string; text: string }>) => list.map((file) => ({ ...file, text: `${GENERATED_MARK}. Do not edit: change the knowledge and generate again.\n${file.text}` }));
+  const loaderFiles = loader === undefined ? [] : [{ name: "loader.asm", text: loader.text }];
+  // An operand expression that ACME refuses, or assembles to other bytes, is written as its number, and the source is assembled again (D65).
+  const numbers = new Map<number, string>();
+  let rendered = render(laid, asBytes, header, numbers);
+  let files = marked([...rendered.files, ...loaderFiles]);
+  let built = await assembleFiles(files, "main.asm");
+  for (let round = 0; round < OPERAND_ROUNDS && rendered.expressions.length > 0; round++) {
+    const blamed = blame(rendered, built, image, 1);
+    if (blamed.size === 0) break;
+    for (const [address, reason] of blamed) numbers.set(address, reason);
+    rendered = render(laid, asBytes, header, numbers);
+    files = marked([...rendered.files, ...loaderFiles]);
+    built = await assembleFiles(files, "main.asm");
+  }
   removeOldFiles(values.out, new Set(files.map((file) => file.name)));
   for (const file of files) writeProjectFile(`${values.out}/${file.name}`, Buffer.from(file.text, "utf8"), { what: "--out" });
   const showRange = (range: Range) => ({ start: formatC64Address(range.start), end: formatC64Address(range.end) });
@@ -432,10 +437,18 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
           },
         }),
     ...(laid.unusedModules.length === 0 ? {} : { unusedModules: laid.unusedModules.map((module) => ({ start: formatC64Address(module.start), file: module.file })) }),
+    ...(rendered.expressions.length === 0 && rendered.operandsAsNumbers.length === 0 ? {} : { operandExpressions: rendered.expressions.length }),
+    ...(rendered.operandsAsNumbers.length === 0
+      ? {}
+      : {
+          operandsAsNumbers: {
+            count: rendered.operandsAsNumbers.length,
+            listed: rendered.operandsAsNumbers.slice(0, MAX_LISTED).map((item) => ({ address: formatC64Address(item.address), expression: item.expression, reason: item.reason })),
+          },
+        }),
   };
   // The loader includes the source, so it is built only from a source that is identical to the image.
   const notBuilt = (reason: string) => (state === undefined ? {} : { loader: { verified: false, reason: loaderRefused ?? reason } });
-  const built = await assembleFiles(files, "main.asm");
   if (built.program === undefined) {
     return { output: { ...output, check: { identical: false, diagnostics: built.diagnostics.slice(0, MAX_LISTED) }, ...notBuilt("The source does not assemble, and the loader includes it.") }, failed: true };
   }