@henols/c64-re-tools 2.0.0-rc.12 → 2.0.0-rc.13

package/skills/c64-source/SKILL.md

@@ -7,7 +7,7 @@ description: Use this skill to generate ACME source code for a C64 program from
 
 ## Purpose
 
-Generate ACME source from an image and the knowledge. The same knowledge gives the same source. Make the source better through the knowledge: names, comments, regions and modules. Then generate again.
+Generate ACME source from an image and the knowledge. The same knowledge gives the same source. Make the source better through the knowledge: names, comments, regions, modules and macros. Change the program through patches. Then generate again.
 
 This skill does not change the knowledge.
 
@@ -58,7 +58,8 @@ 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`. 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` and `table`. `address` is an immediate operand expression. `table` is an entry in a table of addresses.
+- `constants.asm` holds the names of addresses outside the image, 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 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.
@@ -70,9 +71,24 @@ node <skill>/scripts/generate.ts unpacked/image.json --out src --loader
 - `!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`.
+- `+inc16 ptr` is a use of a macro of the knowledge. `macros.asm` holds the macros. `main.asm` and `loader.asm` include it. The comments inside a use go to its side comment.
+- `!zone patch_CRACK_100e` starts a patch of the knowledge. `!if CRACK` has the code of the patch and NOP to the end of the range. `else` has the original code. The labels inside the range come before the zone as `name = * + n`. Thus both builds have them.
 
 Do not edit the generated files. The next run writes over them.
 
+## Switches and macros
+
+A switch changes the program only when the build defines it. Thus the source without a define stays identical to the image.
+
+1. The script checks the default build with `check`.
+2. Then it builds each switch on its own, with the switch as 1. It does not build two switches together.
+3. The build of a switch must have the same length as the default build. It can change bytes only in the ranges of its patches.
+4. Build the program with a switch on with the c64-assembler skill: `--define CRACK=1`.
+
+The script writes a patch only when its range is complete items of one file. A patch cannot cut an instruction. Its switch name cannot be a name of the source.
+
+The script writes a macro use only when the use gives the bytes of the image. First it assembles each use alone at its address. Then it checks the full build. A use that fails stays instructions, and `macrosAsInstructions` gives the reason. A label inside the range of a use also keeps the instructions, because the macro line has no place for the label.
+
 ## The loader
 
 `--loader` writes `loader.asm` and assembles it to `loader.prg`. The loader does these steps:
@@ -93,7 +109,7 @@ The script simulates the copies first. Then it runs `loader.prg` in the emulator
 ## Knowledge
 
 Read:
-- symbols, regions, comments, references, modules and operand expressions of all origins.
+- symbols, regions, comments, references, modules, operand expressions, patches, macros and macro uses of all origins.
 
 Automatic write:
 - none.
@@ -111,14 +127,18 @@ One JSON object:
 - `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.
+- `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 six 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.
+- `macroUses`: the count of macro uses that the source has.
+- `macrosAsInstructions`: the macro uses that the source has as instructions, each with its `start`, `end`, `macro` and `reason`.
+- `patchesNotWritten`: the patches that the source does not have, each with its range, `switch` and `reason`.
 - `check`: `identical`, and the result for each segment. A different segment gives its first different address.
+- `switches`: the build of each switch. Each item has the `define` for the c64-assembler skill, the patches and the `result` of the build with the switch on. `fits` tells that the build is good, and `changedBytes` counts the changed bytes. `overflow` tells that the code of a patch is longer than its range. `changes outside` gives the first byte outside the ranges that changed. `does not assemble` gives the diagnostics of ACME. `insideNames` lists the labels inside a patch. Code that writes to one of these labels changes the patch when the switch is on.
 - `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.
+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. A patch that the source does not have, or a switch that does not fit, also gives 1. The exit status is 2 for a wrong argument.
 
 ## Failure and conflicts
 
@@ -126,6 +146,10 @@ The exit status is 0 when the source is identical and the emulator check of the
 - `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.
+- `switches` with `overflow`: make the code of the patch shorter, or make the range of the patch larger, with `patch` of the c64-knowledge skill.
+- `switches` with `does not assemble`: read the diagnostics and correct the code of the patch.
+- `patchesNotWritten`: read each `reason`. Move the start or the end of the patch to an instruction, or give the switch another name.
+- `macrosAsInstructions`: read each `reason`. Correct the macro or the args, or remove the use with `unuse`. The source stays identical, so this is not a failure.
 - `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.
 - `loader.verified: false` with a `reason`: the script did not make the loader. The script still writes and checks the source. When no copy order or no free pages exist, or the loader needs too many copies, the reason gives the ranges. Capture the image again with fewer segments, or write the loader by hand.

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

@@ -2,8 +2,10 @@
 // knowledge and Ghidra's instructions, which it runs itself, and checks with
 // ACME that the source assembles to the image byte by byte. With --loader it
 // also writes a loader that recreates the entry state, simulates it, and
-// checks it in the emulator. Exit status: 0 when every check passes, 1 when
-// one fails, 2 for a bad call.
+// checks it in the emulator. Each switch of the patches (D72) is built on
+// alone and checked. A macro use (D73) that does not give the bytes of the
+// image is written as its instructions. Exit status: 0 when every check
+// passes, 1 when one fails, 2 for a bad call.
 
 import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { join, posix } from "node:path";
@@ -18,7 +20,8 @@ import { readProjectFile, writeProjectFile } from "#src/host-client/transfer.ts"
 import { ViceSessionClient } from "#src/host-client/vice-session.ts";
 import { conflicts } from "#src/knowledge/conflicts.ts";
 import { KnowledgeError, openForRead } from "#src/knowledge/database.ts";
-import { currentRevision, listComments, listModules, listOperands, listReferences, listRegions, listSymbols } from "#src/knowledge/read.ts";
+import { identifiers } from "#src/knowledge/expression.ts";
+import { currentRevision, listComments, listMacros, listMacroUses, listModules, listOperands, listPatches, 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";
@@ -29,7 +32,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, type Rendered } from "./source.ts";
+import { entriesInData, entryOutsideImage, instructionText, layout, literalOperand, probeForms, render, switchesOf, type Layout, type PatchBlock, type Range, type Rendered } from "./source.ts";
 
 const USAGE = `generate.ts <image> --out <dir> [options]
 
@@ -50,8 +53,8 @@ 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;
+/** Rounds of assembly that move operand expressions to numbers (D65) and macro uses to instructions (D73). */
+const ROUNDS = 6;
 const PROBE_BASE = 0x1000;
 const PROBE_SLOT = 4;
 /** The copies of a full 64 KiB take about 140 frames. */
@@ -81,6 +84,9 @@ function readKnowledge(space: Space) {
       modules: listModules(db, undefined, undefined, space),
       references: listReferences(db, undefined, undefined, undefined, space),
       operands: listOperands(db, undefined, undefined, space),
+      patches: listPatches(db, undefined, undefined, undefined, space),
+      macros: listMacros(db, undefined, space),
+      macroUses: listMacroUses(db, undefined, undefined, undefined, space),
     };
   } finally {
     db?.close();
@@ -120,10 +126,14 @@ async function decode(image: Image, knowledge: ReturnType<typeof readKnowledge>,
 }
 
 /** Assembles files given as text with ACME; the program or the diagnostics. */
-async function assembleFiles(files: Array<{ name: string; text: string }>, entry: string): Promise<{ program?: Buffer; start?: number; symbols?: AssembledSymbol[]; diagnostics: Diagnostic[] }> {
+async function assembleFiles(
+  files: Array<{ name: string; text: string }>,
+  entry: string,
+  defines: Record<string, number> = {},
+): Promise<{ program?: Buffer; start?: number; symbols?: AssembledSymbol[]; diagnostics: Diagnostic[] }> {
   const contents = files.map((file) => Buffer.from(file.text, "utf8"));
   const { result, attachments } = await assemble(
-    { files: files.map((file, index) => ({ path: file.name, size: contents[index]!.length })), entrySource: entry, includeDirs: [], defines: {} },
+    { files: files.map((file, index) => ({ path: file.name, size: contents[index]!.length })), entrySource: entry, includeDirs: [], defines },
     contents,
     localToolContext(),
   );
@@ -173,12 +183,88 @@ async function probe(laid: Layout): Promise<Set<string>> {
   throw new WireFailure("operation-failed", "ACME refused the opcode probe three times.");
 }
 
+/** The macro uses that an ACME error names: its line, or a line of the macro body in macros.asm, which every use of that macro shares. */
+function usesInErrors(diagnostics: Diagnostic[], lineOf: ReadonlyMap<string, number>, uses: ReadonlyArray<{ start: number; macro: string }>, macroLines: Rendered["macroLines"], markLines: number): Map<number, string> {
+  const blamed = new Map<number, string>();
+  for (const diagnostic of diagnostics) {
+    if (diagnostic.severity !== "error" || diagnostic.file === undefined || diagnostic.line === undefined) continue;
+    const start = lineOf.get(`${diagnostic.file}:${diagnostic.line}`);
+    if (start !== undefined) blamed.set(start, `ACME refuses it: ${diagnostic.message}`);
+    if (diagnostic.file !== "macros.asm") continue;
+    for (const [macro, lines] of macroLines) {
+      if (diagnostic.line < lines.first + markLines || diagnostic.line > lines.last + markLines) continue;
+      for (const use of uses) if (use.macro === macro) blamed.set(use.start, `ACME refuses the macro ${macro}: ${diagnostic.message}`);
+    }
+  }
+  return blamed;
+}
+
+/** The first address where two byte runs differ, as a reason. */
+function firstDifference(start: number, built: (address: number) => number, original: (address: number) => number, end: number): string | undefined {
+  for (let address = start; address <= end; address++) {
+    if (built(address) !== original(address)) return `ACME assembles it to other bytes than the image: at ${formatC64Address(address)} it gives $${built(address).toString(16).padStart(2, "0")}, and the image has $${original(address).toString(16).padStart(2, "0")}.`;
+  }
+  return undefined;
+}
+
+/**
+ * Assembles each macro use alone at its own address, with the constants and
+ * the macros, and gives the uses that ACME refuses or assembles to other bytes
+ * than the image, with the reason (D73). A use of another length moves no
+ * other use, so each one is checked on its own, as the opcode probe does.
+ */
+async function probeUses(laid: Layout, rendered: Rendered, image: Image): Promise<Map<number, string>> {
+  const blamed = new Map<number, string>();
+  const support = rendered.files.filter((file) => file.name === "constants.asm" || file.name === "macros.asm");
+  for (let round = 0; round < 3; round++) {
+    const uses = [...laid.macroUses.values()].filter((use) => !blamed.has(use.start));
+    if (uses.length === 0) return blamed;
+    // The labels of the image that the args name, with their values: the probe has no other source.
+    const labels = new Map<string, number>();
+    for (const [address, name] of laid.names) if (laid.inImage(address)) labels.set(name, address);
+    const used = [...new Set(uses.flatMap((use) => use.args.flatMap((arg) => identifiers(arg))))].filter((name) => labels.has(name)).sort();
+    const lines = ["!cpu 6510", '!source "constants.asm"', '!source "macros.asm"', ...used.map((name) => `${name} = ${labels.get(name)! < 0x100 ? `$${labels.get(name)!.toString(16).padStart(2, "0")}` : formatC64Address(labels.get(name)!)}`), `* = ${formatC64Address(PROBE_BASE)}`];
+    const lineOf = new Map<string, number>();
+    uses.forEach((use, index) => {
+      lines.push(`!pseudopc ${formatC64Address(use.start)} {`, `        +${use.macro}${use.args.length === 0 ? "" : ` ${use.args.join(", ")}`}`);
+      lineOf.set(`probe.asm:${lines.length}`, use.start);
+      lines.push(`probe_end_${index}`, "}");
+    });
+    const built = await assembleFiles([...support, { name: "probe.asm", text: `${lines.join("\n")}\n` }], "probe.asm");
+    if (built.program === undefined) {
+      const refused = usesInErrors(built.diagnostics, lineOf, uses, rendered.macroLines, 0);
+      if (refused.size === 0) throw new WireFailure("operation-failed", `ACME refused the macro probe: ${built.diagnostics.map((diagnostic) => diagnostic.message).join("; ")}`);
+      for (const [start, reason] of refused) blamed.set(start, reason);
+      continue;
+    }
+    const ends = new Map((built.symbols ?? []).map((symbol) => [symbol.name, symbol.kind === "address" ? symbol.address : symbol.value]));
+    let offset = 2 + PROBE_BASE - built.start!;
+    uses.forEach((use, index) => {
+      const length = ends.get(`probe_end_${index}`)! - use.start;
+      const wanted = use.end - use.start + 1;
+      const program = built.program!;
+      const at = offset;
+      offset += length;
+      if (length !== wanted) {
+        blamed.set(use.start, `ACME assembles it to ${length} bytes, and the range has ${wanted}.`);
+        return;
+      }
+      const reason = firstDifference(use.start, (address) => program[at + address - use.start]!, image.byteAt, use.end);
+      if (reason !== undefined) blamed.set(use.start, reason);
+    });
+    return blamed;
+  }
+  throw new WireFailure("operation-failed", "ACME refused the macro 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.
+ * The operand expressions (D65) and macro uses (D73) that made the assembly
+ * fail or that ACME assembled to other bytes than the image, with the
+ * reason. `markLines` is the number of lines added before the rendered text of
+ * each file. A use of another length moves every byte after it: then only the
+ * first use that differs is blamed, and no operand.
  */
-function blame(rendered: Rendered, built: Awaited<ReturnType<typeof assembleFiles>>, image: Image, markLines: number): Map<number, string> {
+function blame(rendered: Rendered, built: Awaited<ReturnType<typeof assembleFiles>>, image: Image, markLines: number): { numbers: Map<number, string>; uses: 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]));
@@ -187,9 +273,20 @@ function blame(rendered: Rendered, built: Awaited<ReturnType<typeof assembleFile
       const address = lines.get(`${diagnostic.file}:${diagnostic.line}`);
       if (address !== undefined) blamed.set(address, `ACME refuses it: ${diagnostic.message}`);
     }
-    return blamed;
+    const useLines = new Map(rendered.uses.map((use) => [`${use.file}:${use.line + markLines}`, use.start]));
+    return { numbers: blamed, uses: usesInErrors(built.diagnostics, useLines, rendered.uses, rendered.macroLines, markLines) };
   }
   const end = built.start! + built.program.length - 3;
+  const at = (address: number) => (address >= built.start! && address <= end ? built.program![2 + address - built.start!]! : -1);
+  const uses = new Map<number, string>();
+  const imageEnd = Math.max(...image.segments.map((segment) => segment.end));
+  for (const use of rendered.uses) {
+    const reason = firstDifference(use.start, at, image.byteAt, use.end);
+    if (reason === undefined) continue;
+    uses.set(use.start, reason);
+    if (end !== imageEnd) break;
+  }
+  if (uses.size > 0) return { numbers: blamed, uses };
   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) {
@@ -198,7 +295,7 @@ function blame(rendered: Rendered, built: Awaited<ReturnType<typeof assembleFile
     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;
+  return { numbers: blamed, uses };
 }
 
 interface SegmentCheck {
@@ -228,6 +325,57 @@ function check(program: Buffer, start: number, image: Image): { identical: boole
   return { identical: segments.every((segment) => segment.result === "identical"), segments };
 }
 
+/** What a build with one switch on gives (D72). */
+interface SwitchCheck {
+  name: string;
+  define: string;
+  patches: Array<{ start: string; end: string; bytes: number; insideNames?: string[] }>;
+  result: "fits" | "overflow" | "changes outside" | "does not assemble";
+  changedBytes?: number;
+  outside?: { count: number; first: { address: string; built: number; default: number } };
+  overflow?: Array<{ start: string; message: string }>;
+  diagnostics?: Diagnostic[];
+}
+
+/**
+ * Builds the source with one switch on and compares it with the default
+ * build: only the ranges of its patches may change, and the program keeps its
+ * start and length. A patch longer than its range stops ACME with !error.
+ */
+async function checkSwitch(name: string, patches: PatchBlock[], files: Array<{ name: string; text: string }>, base: { program: Buffer; start: number }, names: Layout["names"]): Promise<SwitchCheck> {
+  const shown: SwitchCheck = {
+    name,
+    define: `--define ${name}=1`,
+    patches: patches.map((patch) => {
+      const inside = patch.inner.map((address) => names.get(address)!);
+      return { start: formatC64Address(patch.start), end: formatC64Address(patch.end), bytes: patch.end - patch.start + 1, ...(inside.length === 0 ? {} : { insideNames: inside }) };
+    }),
+    result: "fits",
+  };
+  const built = await assembleFiles(files, "main.asm", { [name]: 1 });
+  if (built.program === undefined) {
+    const overflow = built.diagnostics.flatMap((diagnostic) => {
+      const found = /The patch \S+ at (\$[0-9a-f]{4}) has .*/.exec(diagnostic.message);
+      return found === null ? [] : [{ start: found[1]!, message: found[0] }];
+    });
+    if (overflow.length > 0) return { ...shown, result: "overflow", overflow };
+    return { ...shown, result: "does not assemble", diagnostics: built.diagnostics.slice(0, MAX_LISTED) };
+  }
+  const inside = (address: number) => patches.some((patch) => address >= patch.start && address <= patch.end);
+  let changed = 0;
+  let outside: SwitchCheck["outside"];
+  const end = Math.max(base.start + base.program.length, built.start! + built.program.length) - 2;
+  for (let address = Math.min(base.start, built.start!); address < end; address++) {
+    const at = (program: Buffer, start: number) => (address >= start && address < start + program.length - 2 ? program[2 + address - start]! : -1);
+    const now = at(built.program, built.start!);
+    const before = at(base.program, base.start);
+    if (now === before) continue;
+    if (inside(address)) changed++;
+    else outside = { count: (outside?.count ?? 0) + 1, first: outside?.first ?? { address: formatC64Address(address), built: now, default: before } };
+  }
+  return outside === undefined ? { ...shown, changedBytes: changed } : { ...shown, result: "changes outside", changedBytes: changed, outside };
+}
+
 /** Reads RAM in parts. */
 async function readRam(client: ViceSessionClient, start: number, size: number): Promise<Buffer> {
   const parts: Buffer[] = [];
@@ -368,6 +516,9 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
     modules: knowledge.modules,
     referenceTargets: knowledge.references.map((reference) => reference.to),
     operands: knowledge.operands,
+    patches: knowledge.patches,
+    macros: knowledge.macros,
+    macroUses: knowledge.macroUses,
     ...(coverage === undefined ? {} : { coverage }),
     // The platform names are C64 names: drive code and banks get none.
     ...(space === DEFAULT_SPACE ? { platform: platformNames(), describe: describeAddress } : {}),
@@ -383,7 +534,7 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
     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 {
       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."] });
+      loader = planLoader({ segments, byteAt: image.byteAt, state, entry: image.entry!, ...(entryName === undefined ? {} : { entryName }), macros: laid.macros.length > 0, 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;
@@ -392,16 +543,21 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
   // 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).
   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).
+  // An operand expression that ACME refuses, or assembles to other bytes, is written as its number, and a macro use as its
+  // instructions; then the source is assembled again (D65, D73).
   const numbers = new Map<number, string>();
-  let rendered = render(laid, asBytes, header, numbers);
+  const asInstructions = new Map<number, string>();
+  let rendered = render(laid, asBytes, header, numbers, asInstructions);
+  if (laid.macroUses.size > 0) for (const [start, reason] of await probeUses(laid, rendered, image)) asInstructions.set(start, reason);
+  if (asInstructions.size > 0) rendered = render(laid, asBytes, header, numbers, asInstructions);
   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++) {
+  for (let round = 0; round < ROUNDS && (rendered.expressions.length > 0 || rendered.uses.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);
+    if (blamed.numbers.size === 0 && blamed.uses.size === 0) break;
+    for (const [address, reason] of blamed.numbers) numbers.set(address, reason);
+    for (const [start, reason] of blamed.uses) asInstructions.set(start, reason);
+    rendered = render(laid, asBytes, header, numbers, asInstructions);
     files = marked([...rendered.files, ...loaderFiles]);
     built = await assembleFiles(files, "main.asm");
   }
@@ -450,6 +606,25 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
             listed: rendered.operandsAsNumbers.slice(0, MAX_LISTED).map((item) => ({ address: formatC64Address(item.address), expression: item.expression, reason: item.reason })),
           },
         }),
+    ...(rendered.uses.length === 0 && rendered.macrosAsInstructions.length === 0 ? {} : { macroUses: rendered.uses.length }),
+    // A macro use that the source writes as its instructions does not fail the run: the source stays identical (D73).
+    ...(rendered.macrosAsInstructions.length === 0
+      ? {}
+      : {
+          macrosAsInstructions: {
+            count: rendered.macrosAsInstructions.length,
+            listed: rendered.macrosAsInstructions.slice(0, MAX_LISTED).map((item) => ({ start: formatC64Address(item.start), end: formatC64Address(item.end), macro: item.macro, reason: item.reason })),
+          },
+        }),
+    // A patch that the source cannot write fails the run: the switch would miss a part (D72).
+    ...(laid.patchesNotWritten.length === 0
+      ? {}
+      : {
+          patchesNotWritten: {
+            count: laid.patchesNotWritten.length,
+            listed: laid.patchesNotWritten.slice(0, MAX_LISTED).map((item) => ({ start: formatC64Address(item.start), end: formatC64Address(item.end), switch: item.switch, 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 } });
@@ -459,8 +634,13 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
   const checked = check(built.program, built.start!, image);
   output.check = checked;
   if (!checked.identical) return { output: { ...output, ...notBuilt("The source does not assemble to the image, and the loader includes it.") }, failed: true };
+  // Each switch on alone, against the default build (D72); combinations are not built.
+  const switches: SwitchCheck[] = [];
+  for (const [name, patches] of switchesOf(laid)) switches.push(await checkSwitch(name, patches, files, { program: built.program, start: built.start! }, laid.names));
+  if (switches.length > 0) output.switches = switches;
+  const sourceFailed = laid.patchesNotWritten.length > 0 || switches.some((item) => item.result !== "fits");
   if (loaderRefused !== undefined) return { output: { ...output, loader: { verified: false, reason: loaderRefused } }, failed: true };
-  if (loader === undefined || state === undefined) return { output, failed: missingEntry !== undefined };
+  if (loader === undefined || state === undefined) return { output, failed: missingEntry !== undefined || sourceFailed };
 
   const loaderBuilt = await assembleFiles(files, "loader.asm");
   if (loaderBuilt.program === undefined) return { output: { ...output, loader: { verified: false, reason: "loader.asm does not assemble.", diagnostics: loaderBuilt.diagnostics.slice(0, MAX_LISTED) } }, failed: true };
@@ -494,7 +674,7 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
     // 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 };
+  return { output, failed: !ran.verified || sourceFailed };
 }
 
 await runScript(

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

@@ -357,6 +357,8 @@ export interface LoaderInput {
   /** The label of the entry in the source: the loader jumps to it, so the jump follows the code when it moves (D66). */
   entryName?: string;
   header: string[];
+  /** The source has macros.asm (D73): the loader includes it after the constants. */
+  macros?: boolean;
 }
 
 /** The label of a block (D66): its first byte and the byte after it in the loader file, and its first address where it runs. */
@@ -419,7 +421,7 @@ export function planLoader(input: LoaderInput): LoaderPlan {
   const copyBlocks = order.map((index) => blockOf[index]!);
 
   const stackByte = 0x0100 + state.sp;
-  const lines: string[] = [...input.header.map((line) => `; ${line}`), "", "!cpu 6510", '!source "constants.asm"', "", `* = ${hex4(LOAD)}`];
+  const lines: string[] = [...input.header.map((line) => `; ${line}`), "", "!cpu 6510", '!source "constants.asm"', ...(input.macros ? ['!source "macros.asm"'] : []), "", `* = ${hex4(LOAD)}`];
   lines.push(`        !byte $0b,$08,$0a,$00,$9e,${[...String(STUB)].map((digit) => hex2(digit.charCodeAt(0))).join(",")},$00,$00,$00 ; 10 SYS ${STUB}`);
   lines.push(
     "!zone loader_stub {",

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

@@ -61,7 +61,7 @@ export function isZeroPageMode(mode: Mode): boolean {
 }
 
 /** How an instruction uses the address of its operand, in the order a summary lists them. */
-export const USE_KINDS = ["read", "written", "modified", "called", "jumped to", "jumped through", "branched to", "pointer", "address", "table"] as const;
+export const USE_KINDS = ["read", "written", "modified", "called", "jumped to", "jumped through", "branched to", "pointer", "address", "table", "macro argument"] as const;
 export type UseKind = (typeof USE_KINDS)[number];
 
 const WRITES = new Set(["sta", "stx", "sty", "sax", "sha", "shx", "shy", "tas"]);