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

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

@@ -3,27 +3,51 @@
 // release is a PRG or an unpacker image.json (D50). With --run, each release
 // runs in its own emulator, and each listed difference gets its first access
 // and whether the run changed it. The separate command gives evidence from
-// one release (D51).
+// one release (D51). The routine and match commands keep routines that several
+// programs share in a library folder and find them in a program (D71).
 
-import { posix } from "node:path";
+import { basename, posix, relative } from "node:path";
 import { parseArgs } from "node:util";
 
 import { formatC64Address, parseC64Address } from "#src/c64.ts";
 import { readCoverageFiles } from "#src/host-client/coverage.ts";
+import { ImageError, readImage, type Image } from "#src/host-client/image.ts";
 import { checkActionSteps, type ActionStep } from "#src/host-client/steps.ts";
 import { MAX_EXECUTION_COUNT, 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 { listReferences, listRegions } from "#src/knowledge/read.ts";
-import { CODE_REGION_TYPES } from "#src/knowledge/schema.ts";
+import {
+  commentsAt,
+  listComments,
+  listModules,
+  listOperands,
+  listReferences,
+  listRegions,
+  listSymbols,
+  operandAt,
+  referencesFrom,
+  referenceSuppressed,
+  regionsOverlapping,
+  suppressionsOverlapping,
+  symbolAt,
+  symbolNamed,
+  symbolSuppressed,
+} from "#src/knowledge/read.ts";
+import { CODE_REGION_TYPES, type Origin } from "#src/knowledge/schema.ts";
+import { platformNames } from "#src/platform.ts";
+import { projectRoot } from "#src/project.ts";
 import { runScript, UsageError } from "#src/script.ts";
 import { compareReleases, shiftSuggestion, suggestShifts, type Range, type Release } from "./compare.ts";
+import { findRoutine, libraryFolder, LibraryError, readLibrary, routineFrom, saveRoutine, suggest } from "./library.ts";
 import { watchRelease, type ImageState, type Start } from "./runtime.ts";
 import { separate } from "./separate.ts";
 
 const USAGE = `provenance.ts <release> <release> [<release> ...] [options]
 provenance.ts separate <release> [--coverage <file> ...] [--out <file>] [--max-listed <n>]
+provenance.ts routine <image> --library <folder> (--module <address> | --start <address> --end <address>)
+                      [--name <name>] [--title <text>] [--replace]
+provenance.ts match <image> --library <folder> [--out <file>] [--max-listed <n>]
 
   --shift <n>:<bytes>   move release n (1 = the first) by a number of bytes, for example 2:-256
   --from <address>      compare from this address
@@ -38,9 +62,22 @@ jump references in knowledge reach each code region from the entry, and what the
 program reads or executes outside the image. --out writes all ranges to a file;
 the result lists at most --max-listed of each list (default 50) and its count.
 
+routine saves a routine of the project to a library: a plain folder of routine
+files, beside the projects (--library, relative to the working directory, as
+--project). It takes a module (D48) of the knowledge, or --start and --end. Its
+code regions give the instructions; the user and LLM names, regions, comments,
+references and operand expressions go into the file at offsets. --name defaults
+to the user or LLM name at the start, --title to the module title.
+
+match finds each routine of the library in an image: the opcodes and other
+fixed bytes equal, and the addresses into the routine moved by one shift.
+Operands that address something outside the routine may differ; the result
+lists them. --out writes the names of the routines at the found addresses as a
+batch for knowledge.ts apply, and the result lists what it left out.
+
 A release is a PRG, placed at its load address, or an image.json of the
 c64-unpacker skill, compared inside its segments. Paths are relative to the
-project directory. The result is one JSON object.`;
+project folder. The result is one JSON object.`;
 
 function address(text: string, option: string): number {
   try {
@@ -158,17 +195,38 @@ async function run(argv: string[]): Promise<unknown> {
       coverage: { type: "string", multiple: true },
       out: { type: "string" },
       "max-listed": { type: "string" },
+      library: { type: "string" },
+      module: { type: "string" },
+      start: { type: "string" },
+      end: { type: "string" },
+      name: { type: "string" },
+      title: { type: "string" },
+      replace: { type: "boolean" },
       help: { type: "boolean" },
     },
   });
   if (values.help) throw new UsageError("");
+  /** Refuses the options that `command` does not take. */
+  const only = (command: string, allowed: readonly string[]) => {
+    const used = Object.keys(values).filter((option) => option !== "help" && !allowed.includes(option));
+    if (used.length > 0) throw new UsageError(`${command} does not take --${used.join(", --")}`);
+  };
   if (positionals[0] === "separate") {
-    const used = ["shift", "from", "to", "run", "steps"].filter((option) => values[option as keyof typeof values] !== undefined);
-    if (used.length > 0) throw new UsageError(`separate does not take --${used.join(", --")}`);
+    only("separate", ["coverage", "out", "max-listed"]);
     if (positionals.length !== 2) throw new UsageError("separate needs one release");
     return separateCommand(positionals[1]!, values.coverage ?? [], values.out, values["max-listed"]);
   }
-  if (values.coverage !== undefined || values.out !== undefined || values["max-listed"] !== undefined) throw new UsageError("--coverage, --out and --max-listed work only with separate");
+  if (positionals[0] === "routine") {
+    only("routine", ["library", "module", "start", "end", "name", "title", "replace"]);
+    if (positionals.length !== 2) throw new UsageError("routine needs one image");
+    return routineCommand(positionals[1]!, values);
+  }
+  if (positionals[0] === "match") {
+    only("match", ["library", "out", "max-listed"]);
+    if (positionals.length !== 2) throw new UsageError("match needs one image");
+    return matchCommand(positionals[1]!, values.library, values.out, values["max-listed"]);
+  }
+  only("a comparison", ["shift", "from", "to", "run", "steps"]);
   if (positionals.length < 2) throw new UsageError("give two or more releases");
   const shifts = new Map<number, number>();
   for (const text of values.shift ?? []) {
@@ -331,4 +389,138 @@ function separateCommand(path: string, coveragePaths: string[], out: string | un
   };
 }
 
-await runScript(() => run(process.argv.slice(2)), { usage: USAGE, refusals: [KnowledgeError] });
+const SEMANTIC: readonly Origin[] = ["user", "llm"];
+
+function imageOf(path: string): Image {
+  try {
+    return readImage(path);
+  } catch (error) {
+    if (error instanceof ImageError) throw new UsageError(error.message);
+    throw error;
+  }
+}
+
+const platform = () => new Map(platformNames().map((entry) => [entry.name, entry.address]));
+
+/** routine: saves a module or a range of the project, with its knowledge, as a routine of the library (D71). */
+function routineCommand(path: string, values: { library?: string; module?: string; start?: string; end?: string; name?: string; title?: string; replace?: boolean }): unknown {
+  if (values.library === undefined) throw new UsageError("routine needs --library <folder>");
+  if (values.module !== undefined && (values.start !== undefined || values.end !== undefined)) throw new UsageError("routine takes --module, or --start and --end, not both");
+  if (values.module === undefined && values.start === undefined && values.end === undefined) throw new UsageError("routine needs --module <address>, or --start and --end");
+  if (values.module === undefined && (values.start === undefined || values.end === undefined)) throw new UsageError("routine needs both --start and --end");
+  const image = imageOf(path);
+  const segmentOf = (at: number) => image.segments.find((segment) => at >= segment.start && at <= segment.end);
+  const db = openForRead();
+  try {
+    let start: number;
+    let end: number;
+    let title = values.title;
+    if (values.module !== undefined) {
+      start = address(values.module, "--module");
+      const modules = listModules(db);
+      const module = modules.find((item) => item.start === start);
+      if (module === undefined) throw new LibraryError("not-found", `No module starts at ${formatC64Address(start)}. List the modules with knowledge.ts modules, or give --start and --end.`);
+      const segment = segmentOf(start);
+      if (segment === undefined) throw new UsageError(`The module at ${formatC64Address(start)} is outside the segments of ${path}.`);
+      end = (modules.find((item) => item.start > start && item.start <= segment.end)?.start ?? segment.end + 1) - 1;
+      title ??= module.title;
+    } else {
+      start = address(values.start!, "--start");
+      end = address(values.end!, "--end");
+      if (end < start) throw new UsageError("--end is before --start");
+      if (segmentOf(start) === undefined || segmentOf(start) !== segmentOf(end)) throw new UsageError(`${formatC64Address(start)}-${formatC64Address(end)} is not inside one segment of ${path}.`);
+    }
+    const range = { start, end };
+    const name = values.name ?? listSymbols(db, { start, end: start }, undefined, SEMANTIC)[0]?.name;
+    if (name === undefined) throw new UsageError(`The knowledge has no user or LLM name at ${formatC64Address(start)}: give --name.`);
+    const { routine, leftOut } = routineFrom({
+      name,
+      ...(title === undefined ? {} : { title }),
+      program: basename(projectRoot()),
+      image: path,
+      start,
+      end,
+      byteAt: image.byteAt,
+      analyzed: listRegions(db, range),
+      symbols: listSymbols(db, range, undefined, SEMANTIC),
+      regions: listRegions(db, range, undefined, SEMANTIC),
+      comments: listComments(db, range, SEMANTIC),
+      references: listReferences(db, range, undefined, SEMANTIC),
+      operands: listOperands(db, range, SEMANTIC),
+      platform: platform(),
+    });
+    const file = saveRoutine(libraryFolder(values.library, { create: true }), routine, values.replace === true);
+    return {
+      routine: routine.name,
+      file: relative(process.cwd(), file),
+      start: formatC64Address(start),
+      end: formatC64Address(end),
+      length: routine.bytes.length,
+      instructions: routine.instructions.length,
+      relocations: routine.relocations.length,
+      variable: routine.variable.length,
+      counts: { symbols: routine.symbols.length, regions: routine.regions.length, comments: routine.comments.length, references: routine.references.length, operands: routine.operands.length },
+      ...(leftOut.length === 0 ? {} : { leftOut }),
+    };
+  } finally {
+    db?.close();
+  }
+}
+
+/** match: finds the routines of the library in an image, and with --out writes their names there as an apply batch (D71). */
+function matchCommand(path: string, library: string | undefined, out: string | undefined, maxListed: string | undefined): unknown {
+  if (library === undefined) throw new UsageError("match needs --library <folder>");
+  const max = maxListed ?? "50";
+  if (!/^\d{1,5}$/.test(max)) throw new UsageError(`--max-listed must be a whole number, not ${max}`);
+  const listed = <T>(items: T[]) => ({ count: items.length, listed: items.slice(0, Number(max)) });
+  const routines = readLibrary(libraryFolder(library, { create: false }));
+  if (routines.length === 0) throw new LibraryError("not-found", `The library ${library} has no routine files. Save a routine with routine first.`);
+  const image = imageOf(path);
+  const found = routines.map((routine) => ({ routine, matches: findRoutine(routine, image) }));
+  const show = (value: number, size: 1 | 2) => `$${value.toString(16).padStart(2 * size, "0")}`;
+  const matches = found
+    .flatMap(({ routine, matches: each }) =>
+      each.map((match) => ({
+        routine: match.routine,
+        start: formatC64Address(match.start),
+        end: formatC64Address(match.start + routine.bytes.length - 1),
+        shift: match.shift,
+        differing: match.differing.map((operand) => ({ address: formatC64Address(operand.address), library: show(operand.library, operand.size), program: show(operand.program, operand.size) })),
+      })),
+    )
+    .sort((a, b) => a.start.localeCompare(b.start));
+  const result: Record<string, unknown> = { library, routines: routines.length, matches: listed(matches) };
+  if (out === undefined) return result;
+  const db = openForRead();
+  let suggestions: ReturnType<typeof suggest>;
+  try {
+    suggestions = suggest(
+      found,
+      {
+        symbolAt: (at) => symbolAt(db, at),
+        symbolNamed: (name) => symbolNamed(db, name),
+        regionsOverlapping: (start, end) => regionsOverlapping(db, start, end),
+        commentsAt: (at) => commentsAt(db, at),
+        referencesFrom: (at) => referencesFrom(db, at),
+        operandAt: (at) => operandAt(db, at),
+        symbolSuppressed: (at) => symbolSuppressed(db, at),
+        regionSuppressed: (start, end) => suppressionsOverlapping(db, "region", start, end).length > 0,
+        referenceSuppressed: (reference) => referenceSuppressed(db, reference),
+      },
+      image,
+      platform(),
+    );
+  } finally {
+    db?.close();
+  }
+  const { batch, known, leftOut } = suggestions;
+  writeProjectFile(out, Buffer.from(batch.length === 0 ? "[]\n" : `[\n${batch.map((write) => ` ${JSON.stringify(write)}`).join(",\n")}\n]\n`), { what: "--out" });
+  const operands = batch.some((write) => write.op === "operand");
+  return {
+    ...result,
+    batch: { out, writes: batch.length, known, leftOut: listed(leftOut) },
+    ...(batch.length === 0 ? {} : { apply: `knowledge.ts apply ${out}${operands ? ` --image ${path}` : ""} --reason "names of library routines"` }),
+  };
+}
+
+await runScript((argv) => run(argv), { usage: USAGE, refusals: [KnowledgeError, LibraryError] });

package/skills/c64-reverse-engineering/SKILL.md

@@ -26,6 +26,15 @@ This skill does not do the specialist work itself.
 
 This skill uses the other skills. It does not use the host runtime or the emulator directly.
 
+### Project folder
+
+One repository can hold several programs, with one project folder for each program. A project folder holds `.c64-re-tools/`. Work on one project at a time:
+
+- From the root of the repository, give `--project <folder>` to each skill script, and `project` to each emulator tool with a path.
+- Write all files in the project folder. Do not write files at the root of the repository.
+- Keep the results, batches and step files that you save for yourself in `.c64-re-tools/local/` of the project. Git ignores that folder.
+- Write the knowledge only with the c64-knowledge script. Do not write or edit the files in `.c64-re-tools/knowledge/` yourself.
+
 ## Workflow
 
 Select the path for the scope:
@@ -48,6 +57,7 @@ Select the path for the scope:
 | The routines, code, data and references of the program | c64-static-analysis |
 | The platform meaning of an address or a register | c64-memory-map |
 | Differences between releases of the program | c64-provenance |
+| A routine that another program of the workspace has, for example a music driver | c64-provenance, with the library |
 | Source code from the knowledge | c64-source |
 | Source code to build | c64-assembler |
 | Proof that a rebuild behaves as the original | c64-testing |
@@ -68,16 +78,18 @@ Do the stages in this sequence. Go to the next stage only when its exit check is
 | 4. Unpack | c64-unpacker: examine the program. Capture a packed program into `unpacked/`. | `image.json` and `entry_state.json` exist, or the evidence shows no packer. |
 | 5. Run | c64-emulator and the run of c64-testing: run each part that the scope names. Write a coverage file for each part into `coverage/`. | Each part that the scope names has a coverage file. |
 | 6. Analyze | c64-static-analysis with `--coverage` for each coverage file. | No coverage conflict is open. |
-| 7. Name | c64-knowledge and c64-memory-map: name each routine in the scope and give it a comment. Record the modules. | Each routine in the scope has a name and a comment. |
+| 7. Name | c64-provenance: if the workspace has a library, find its routines with `match` and apply the batch. Then c64-knowledge and c64-memory-map: name each routine in the scope and give it a comment. Record the modules. | Each routine in the scope has a name and a comment. |
 | 8. Generate | c64-source with `--coverage` into `src/`. For an unpacked program, add `--loader`. | `check.identical` is true. For an unpacked program, `loader.verified` is true. |
 | 9. Build and test | c64-assembler with `--compare` into `build/`. c64-testing scenarios in `tests/`. | The criteria of stage 1 are true. |
 | 10. Report | Write `report.md`. | The report has all its sections. |
 
 In stage 5, if you cannot get to a part of the program, ask the user how to get to it. Do stages 7 and 8 again until the source is clear. Each run of c64-source writes the source again.
 
+After stage 7, save each routine that other programs can have to the library with c64-provenance `routine`. Examples are a music driver, a decruncher and a loader. Ask the user before you make a library.
+
 ### Deliverables of a full rebuild
 
-- `.c64-re-tools/knowledge.db` with the names, regions, comments and modules
+- `.c64-re-tools/knowledge/` with the names, regions, comments and modules
 - the image and the entry state
 - the coverage files
 - the generated source
@@ -113,6 +125,8 @@ report.md      the report
 
 If the project has a layout, use that layout.
 
+A workspace with several projects keeps its library of routines in `library/` beside the projects. The library is not a project folder.
+
 ## Knowledge
 
 Read:

package/skills/c64-source/SKILL.md

@@ -7,14 +7,14 @@ 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.
 
 ## Inputs
 
-- The image: an `image.json` from c64-unpacker capture, or a PRG. The path is relative to the project directory.
-- The output directory for the source files, relative to the project directory.
+- The image: an `image.json` from c64-unpacker capture, or a PRG. The path is relative to the project folder.
+- The output directory for the source files, relative to the project folder.
 - Optional entry points for Ghidra.
 - For the loader: the `entry_state.json` next to `image.json`.
 
@@ -36,6 +36,13 @@ node <skill>/scripts/generate.ts unpacked/image.json --out src --loader
 | `--space drive8` | Generate the source of drive code or a cartridge bank from the knowledge of that space. `--coverage` and `--loader` are only for `c64`, and platform names are only for `c64`. |
 | `--loader` | Also write `loader.asm` and `loader.prg`. This needs `image.json` with an entry, and `entry_state.json`. |
 
+### Project folder
+
+- Paths are relative to the project folder. The project folder is the nearest folder at or above the working directory that holds `.c64-re-tools/`.
+- If the working directory is not in a project and has projects below it, the script refuses and lists them. Then give `--project <folder>` to each script.
+- Keep the results, batches and step files that you save for yourself in `.c64-re-tools/local/` of the project. Git ignores that folder.
+- A shell redirect (`>`) is relative to the working directory, not to the project folder. From the folder above the project, write `<folder>/.c64-re-tools/local/result.json`.
+
 ## Workflow
 
 1. Get the image. For a packed program, use c64-unpacker capture. For a program without a packer, use the PRG.
@@ -51,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`.
+- `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.
@@ -63,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:
@@ -86,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.
@@ -104,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
 
@@ -119,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.