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

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

@@ -0,0 +1,503 @@
+// The c64-source script (D48): generates ACME source from an image, current
+// 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.
+
+import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { join, posix } from "node:path";
+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, 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";
+import { localToolContext } from "#src/native/local.ts";
+import { GHIDRA_LIMITS, type AssembledSymbol, type Diagnostic } from "#src/native/types.ts";
+import { platformNames } from "#src/platform.ts";
+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";
+
+const USAGE = `generate.ts <image> --out <dir> [options]
+
+  <image>            an image.json of the c64-unpacker skill, or a PRG, relative to
+                     the project directory
+  --out <dir>        the directory for the source files, relative to the project
+  --entry <address>  an entry point for Ghidra, for example '$080d' (repeatable)
+  --coverage <file>  a coverage map of 64 KiB from c64_memmap (repeatable): code
+                     that no run executed is marked and listed; <dir>/not_executed.json
+                     has all of its ranges
+  --space <space>    the knowledge space of the image: c64 (the default), drive8, or
+                     bank0 to bank255; --coverage and --loader are for c64 only
+  --loader           also write loader.asm and loader.prg: the loader copies the
+                     segments into place, sets the entry state from entry_state.json
+                     next to image.json, and jumps to the entry; it is checked in
+                     the emulator
+
+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;
+
+function readImage(path: string): Image {
+  try {
+    return readSharedImage(path);
+  } catch (error) {
+    if (error instanceof ImageError) throw new UsageError(error.message);
+    throw error;
+  }
+}
+
+/** The knowledge of one space that the source uses, read once. */
+function readKnowledge(space: Space) {
+  const db = openForRead();
+  try {
+    return {
+      revision: currentRevision(db),
+      symbols: listSymbols(db, undefined, undefined, undefined, space),
+      regions: listRegions(db, undefined, undefined, undefined, 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();
+  }
+}
+
+/** Ghidra's instruction starts and lengths inside the image, seeded from the entry and from knowledge of any origin. */
+async function decode(image: Image, knowledge: ReturnType<typeof readKnowledge>, entries: number[]): Promise<Map<number, number>> {
+  const inImage = (address: number) => image.segments.some((segment) => address >= segment.start && address <= segment.end);
+  const seeds = new Set<number>([...(image.entry === undefined ? [] : [image.entry]), ...entries]);
+  for (const symbol of knowledge.symbols) if (symbol.kind === "routine") seeds.add(symbol.address);
+  for (const region of knowledge.regions) {
+    if (CODE_REGION_TYPES.includes(region.type)) seeds.add(region.start);
+    if (region.type === "jumps") for (let at = region.start; at + 2 <= region.end; at += 3) seeds.add(at);
+  }
+  const entryPoints = [...seeds].filter(inImage).sort((a, b) => a - b);
+  if (entryPoints.length === 0) {
+    // An entry in no segment is a capture fault: the image is data only, and the result says entryOutside (R3-01).
+    if (image.entry !== undefined && !inImage(image.entry)) return new Map();
+    throw new UsageError("Ghidra needs an entry point: give --entry, or record a routine or a code region in knowledge with the c64-knowledge skill");
+  }
+  const dataRanges = knowledge.regions
+    .filter((region) => !CODE_REGION_TYPES.includes(region.type) && region.type !== "dual-use")
+    .flatMap((region) => image.segments.filter((segment) => region.start <= segment.end && segment.start <= region.end).map((segment) => ({ start: Math.max(region.start, segment.start), end: Math.min(region.end, segment.end) })));
+  const { result } = await analyze(
+    { imageKind: image.analyzed.kind, entryPoints: entryPoints.slice(0, GHIDRA_LIMITS.entryPoints), dataRanges: dataRanges.slice(0, GHIDRA_LIMITS.dataRanges), labels: [], decompile: [] },
+    image.analyzed.bytes,
+    localToolContext(),
+  );
+  const instructions = new Map<number, number>();
+  for (const instruction of result.instructions) {
+    const bytes = Buffer.from(instruction.bytes, "hex");
+    const inside = Array.from({ length: bytes.length }, (_, offset) => instruction.address + offset).every((address, offset) => inImage(address) && image.byteAt(address) === bytes[offset]);
+    if (inside) instructions.set(instruction.address, bytes.length);
+  }
+  return instructions;
+}
+
+/** 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[] }> {
+  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: {} },
+    contents,
+    localToolContext(),
+  );
+  if (!result.assembled) return { diagnostics: result.diagnostics };
+  return { program: attachments![0]!, start: result.loadRange!.start, ...(result.symbols === undefined ? {} : { symbols: result.symbols }), diagnostics: result.diagnostics };
+}
+
+/**
+ * Assembles one instruction of each opcode form that the source uses, each
+ * in its own slot. A form that ACME refuses, or writes with other bytes, is
+ * written as bytes in the source.
+ */
+async function probe(laid: Layout): Promise<Set<string>> {
+  const asBytes = new Set<string>();
+  for (let round = 0; round < 3; round++) {
+    const forms = probeForms(laid).filter((item) => !asBytes.has(item.form.key));
+    if (forms.length === 0) return asBytes;
+    const lines = ["!cpu 6510"];
+    const lineOf = new Map<number, string>();
+    forms.forEach((item, index) => {
+      const slot = PROBE_BASE + PROBE_SLOT * index;
+      const { mode } = OPCODES[item.form.opcode]!;
+      const operand =
+        mode === "imp"
+          ? ""
+          : mode === "rel"
+            ? formatC64Address((slot + 2 + (item.bytes[1]! < 0x80 ? item.bytes[1]! : item.bytes[1]! - 0x100)) & 0xffff)
+            : literalOperand(item.form.opcode, item.bytes.length === 3 ? item.bytes[1]! | (item.bytes[2]! << 8) : item.bytes[1]!);
+      lines.push(`* = ${formatC64Address(slot)}`);
+      lines.push(`        ${instructionText(item.form.opcode, item.form.suffix, operand)}`);
+      lineOf.set(lines.length, item.form.key);
+    });
+    const built = await assembleFiles([{ name: "probe.asm", text: `${lines.join("\n")}\n` }], "probe.asm");
+    if (built.program === undefined) {
+      const refused = built.diagnostics.filter((diagnostic) => diagnostic.severity === "error" && diagnostic.line !== undefined && lineOf.has(diagnostic.line));
+      if (refused.length === 0) throw new WireFailure("operation-failed", `ACME refused the opcode probe: ${built.diagnostics.map((diagnostic) => diagnostic.message).join("; ")}`);
+      for (const diagnostic of refused) asBytes.add(lineOf.get(diagnostic.line!)!);
+      continue;
+    }
+    forms.forEach((item, index) => {
+      const offset = 2 + PROBE_BASE + PROBE_SLOT * index - built.start!;
+      const same = item.bytes.every((byte, at) => built.program![offset + at] === byte);
+      if (!same) asBytes.add(item.form.key);
+    });
+    return asBytes;
+  }
+  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;
+  result: "identical" | "different" | "not covered";
+  differences?: number;
+  firstDifference?: { address: string; built: number; image: number };
+}
+
+/** Compares the assembled program with the image, segment by segment. */
+function check(program: Buffer, start: number, image: Image): { identical: boolean; segments: SegmentCheck[] } {
+  const end = start + program.length - 3;
+  const segments = image.segments.map((segment): SegmentCheck => {
+    const shown = { start: formatC64Address(segment.start), end: formatC64Address(segment.end) };
+    if (segment.start < start || segment.end > end) return { ...shown, result: "not covered" };
+    let differences = 0;
+    let first: SegmentCheck["firstDifference"];
+    for (let address = segment.start; address <= segment.end; address++) {
+      const built = program[2 + address - start]!;
+      if (built === image.byteAt(address)) continue;
+      differences++;
+      first ??= { address: formatC64Address(address), built, image: image.byteAt(address) };
+    }
+    return differences === 0 ? { ...shown, result: "identical" } : { ...shown, result: "different", differences, firstDifference: first! };
+  });
+  return { identical: segments.every((segment) => segment.result === "identical"), segments };
+}
+
+/** Reads RAM in parts. */
+async function readRam(client: ViceSessionClient, start: number, size: number): Promise<Buffer> {
+  const parts: Buffer[] = [];
+  for (let at = start; at < start + size; at += MAX_MEMORY_READ) {
+    parts.push(Buffer.from((await client.memoryRead({ address: at, size: Math.min(MAX_MEMORY_READ, start + size - at), space: "c64", view: "ram" })).data, "hex"));
+  }
+  return Buffer.concat(parts);
+}
+
+/** Runs the loader in the emulator to the entry and compares memory, $00/$01 and the registers with the entry state. */
+/**
+ * Runs the loader in the emulator to its jump to the entry and compares the
+ * machine with the entry state there. At the jump, every byte and register is
+ * set and no interrupt has run since the PLP: the 6502 takes one only after
+ * the JMP, as the original program can take one right at its entry (F-32).
+ */
+async function runLoader(path: string, program: Buffer, plan: LoaderPlan, image: Image, state: EntryState, jump: number): Promise<{ verified: boolean; differences: string[] }> {
+  const client = await ViceSessionClient.open({ videoStandard: "pal" });
+  try {
+    await client.reset({ mode: "hard", run: false });
+    if (!(await autostartLoaded(client, path, program))) return { verified: false, differences: ["The loader was not in memory after autostart."] };
+    await client.keyboard(textToPetscii("RUN\n"));
+    const copier = await client.runUntil({ target: { kind: "address", address: plan.copier, space: "c64" }, timeoutFrames: RUN_LIMIT_FRAMES });
+    if (!copier.reached) return { verified: false, differences: [`The loader did not get to its copier at ${formatC64Address(plan.copier)}; it stopped at ${formatC64Address(copier.pc)}.`] };
+    const atJump = await client.runUntil({ target: { kind: "address", address: jump, space: "c64" }, timeoutFrames: LOADER_FRAMES });
+    if (!atJump.reached) return { verified: false, differences: [`The loader did not get to its jump to the entry at ${formatC64Address(jump)}; it stopped at ${formatC64Address(atJump.pc)}.`] };
+    const memory = await readRam(client, 0x0000, 0x10000);
+    if (memory[jump] !== 0x4c || (memory[jump + 1]! | (memory[jump + 2]! << 8)) !== state.pc) {
+      return { verified: false, differences: [`The instruction at ${formatC64Address(jump)} is not JMP ${formatC64Address(state.pc)}.`] };
+    }
+    const port = Buffer.from((await client.memoryRead({ address: 0x0000, size: 2, space: "c64", view: "cpu" })).data, "hex");
+    const registers = await client.registersGet("c64");
+    const differences: string[] = [];
+    const byte = (value: number) => `$${value.toString(16).padStart(2, "0")}`;
+    const differ = (what: string, got: number, wanted: number) => got !== wanted && differences.push(`${what} is ${byte(got)}, not ${byte(wanted)}`);
+    for (const segment of image.segments) {
+      for (let address = Math.max(segment.start, 2); address <= segment.end; address++) differ(formatC64Address(address), memory[address]!, image.byteAt(address));
+    }
+    for (let address = 2; address < 0x400; address++) if (address !== plan.stackByte) differ(formatC64Address(address), memory[address]!, state.pages[address]!);
+    differ("$00", port[0]!, state.port[0]);
+    differ("$01", port[1]!, state.port[1]);
+    differ("a", registers.a, state.a);
+    differ("x", registers.x, state.x);
+    differ("y", registers.y, state.y);
+    differ("sp", registers.sp, state.sp);
+    const flags = (["n", "v", "d", "i", "z", "c"] as const).reduce((value, name, index) => value | (registers.flags[name] ? [0x80, 0x40, 0x08, 0x04, 0x02, 0x01][index]! : 0), 0);
+    differ("flags", flags, state.flags & 0xcf);
+    if (state.vic !== undefined) {
+      // The display registers and the raster line (D60): the loader waited for the line, so the jump comes in it or the next one.
+      const vic = Buffer.from((await client.ioRead(0xd000, 0x2f)).data, "hex");
+      for (const { register, mask } of VIC_DISPLAY_REGISTERS) differ(formatC64Address(0xd000 + register), vic[register]! & mask, state.vic.registers[register]! & mask);
+      differ("the VIC bank", Buffer.from((await client.ioRead(0xdd00, 1)).data, "hex")[0]! & 0x03, state.vic.bank);
+      const line = rasterLine(vic);
+      const wanted = rasterLine(state.vic.registers);
+      if (line !== wanted && line !== wanted + 1) differences.push(`the raster line is ${line}, not ${wanted}`);
+    }
+    if (plan.cia !== undefined) {
+      // The CIA timers (D63): at the jump a running timer is 3 cycles, the JMP, before its value at the entry.
+      const chips = (await client.cia("both")).chips;
+      const word = (value: number) => `$${value.toString(16).padStart(4, "0")}`;
+      const differWord = (what: string, got: number, wanted: number) => got !== wanted && differences.push(`${what} is ${word(got)}, not ${word(wanted)}`);
+      for (const timer of plan.cia.timers) {
+        const chip = chips[timer.cia - 1]!;
+        const name = `CIA ${timer.cia} timer ${timer.timer}`;
+        const [counter, latch, control] = timer.timer === "A" ? [chip.timerA, chip.latchA, chip.controlA] : [chip.timerB, chip.latchB, chip.controlB];
+        differ(`${name} control`, control, timer.control);
+        differWord(`${name} latch`, latch, timer.latch);
+        if (timer.counterAtJump !== undefined) differWord(`${name} counter`, counter, timer.counterAtJump);
+      }
+      plan.cia.masks.forEach((mask, index) => differ(`CIA ${index + 1} interrupt mask`, chips[index]!.interruptMask, mask));
+    }
+    return { verified: differences.length === 0, differences: differences.slice(0, MAX_LISTED) };
+  } finally {
+    await client.close();
+  }
+}
+
+/** The first words of every file that the script writes. */
+const GENERATED_MARK = "; Generated by c64-source";
+/** The file with every range of instructions that no run executed (D49). */
+const NOT_EXECUTED_FILE = "not_executed.json";
+
+/** Removes the .asm files of an earlier run that this run does not write, and an earlier loader.prg and not_executed.json; other files stay. */
+function removeOldFiles(out: string, keep: ReadonlySet<string>): void {
+  const directory = resolveProjectPath(out);
+  if (!existsSync(directory)) return;
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    const name = entry.name;
+    const path = join(directory, name);
+    if (name === "loader.prg" || name === NOT_EXECUTED_FILE) rmSync(path, { force: true });
+    else if (name.endsWith(".asm") && !keep.has(name) && readFileSync(path, "utf8").startsWith(GENERATED_MARK)) rmSync(path, { force: true });
+  }
+}
+
+async function run(argv: string[]): Promise<{ output: Record<string, unknown>; failed: boolean }> {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    strict: true,
+    allowPositionals: true,
+    options: { out: { type: "string" }, entry: { type: "string", multiple: true }, coverage: { type: "string", multiple: true }, space: { type: "string" }, loader: { type: "boolean" }, help: { type: "boolean" } },
+  });
+  if (values.help) throw new UsageError("");
+  if (positionals.length !== 1) throw new UsageError("give one image");
+  if (values.out === undefined) throw new UsageError("generate needs --out <dir>");
+  try {
+    resolveProjectPath(values.out);
+  } catch {
+    throw new UsageError(`--out must be a path relative to the project directory that stays inside it, not ${values.out}`);
+  }
+  const entries = (values.entry ?? []).map((value) => {
+    try {
+      return parseC64Address(value);
+    } catch {
+      throw new UsageError(`--entry must be $ followed by four hex digits, not ${value}`);
+    }
+  });
+  const space = values.space ?? DEFAULT_SPACE;
+  if (!SPACE.test(space)) throw new UsageError("--space must be c64, drive8, or bank0 to bank255");
+  if (space !== DEFAULT_SPACE && (values.coverage !== undefined || values.loader)) throw new UsageError("--coverage and --loader work only in space c64");
+  const image = readImage(positionals[0]!);
+  const coverage = readCoverageFiles(values.coverage ?? [], (message) => {
+    throw new UsageError(message);
+  });
+  if (values.loader && (image.statePath === undefined || image.entry === undefined)) throw new UsageError("--loader needs an image.json with an entry and an entry_state.json next to it, from c64-unpacker capture");
+  // Read the entry state before the long steps, so a missing file stops the run at once.
+  const state = values.loader ? readEntryState(readProjectFile(image.statePath!).bytes.toString("utf8"), image.statePath!) : undefined;
+  const knowledge = readKnowledge(space);
+  const instructions = await decode(image, knowledge, entries);
+  const laid = layout({
+    segments: image.segments,
+    byteAt: image.byteAt,
+    ...(image.entry === undefined ? {} : { entry: image.entry }),
+    instructions,
+    symbols: knowledge.symbols,
+    regions: knowledge.regions,
+    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."];
+  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);
+  // A loader that cannot be planned does not stop the source: the source is written and checked, and the result says why.
+  let loaderRefused: string | undefined = state === undefined ? undefined : missingEntry;
+  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 {
+      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).
+  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) });
+  const inData = entriesInData(entries, knowledge.regions);
+  if (rendered.notExecuted !== undefined) {
+    const all = { image: image.path, revision: knowledge.revision, instructions: rendered.notExecuted.instructions, ranges: rendered.notExecuted.ranges.map(showRange) };
+    writeProjectFile(`${values.out}/${NOT_EXECUTED_FILE}`, Buffer.from(`${JSON.stringify(all, null, 2)}\n`, "utf8"), { what: "--out" });
+  }
+
+  const output: Record<string, unknown> = {
+    out: values.out,
+    files: files.map((file) => file.name),
+    revision: knowledge.revision,
+    instructions: rendered.instructions,
+    dataBytes: rendered.dataBytes,
+    ...(rendered.undecodedBytes === 0 ? {} : { undecodedBytes: rendered.undecodedBytes }),
+    ...(missingEntry === undefined ? {} : { entryOutside: { entry: formatC64Address(image.entry!), reason: missingEntry } }),
+    labels: { named: laid.namedLabels, generated: laid.generatedLabels },
+    // An --entry in a data region decodes nothing: the result says so, and a code region in the knowledge changes it (F-27).
+    ...(inData.length === 0
+      ? {}
+      : { entriesInData: inData.map(({ entry, region }) => ({ entry: formatC64Address(entry), region: { ...showRange(region), type: region.type }, origin: region.origin })) }),
+    ...(rendered.asBytes.length === 0
+      ? {}
+      : { asBytes: { count: rendered.asBytes.length, listed: rendered.asBytes.slice(0, MAX_LISTED).map((item) => ({ address: formatC64Address(item.address), instruction: item.text })) } }),
+    ...(rendered.notExecuted === undefined
+      ? {}
+      : {
+          notExecuted: {
+            instructions: rendered.notExecuted.instructions,
+            ranges: rendered.notExecuted.ranges.length,
+            listed: rendered.notExecuted.ranges.slice(0, MAX_LISTED).map(showRange),
+            all: `${values.out}/${NOT_EXECUTED_FILE}`,
+          },
+        }),
+    ...(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 } });
+  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 };
+  }
+  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 };
+  if (loaderRefused !== undefined) return { output: { ...output, loader: { verified: false, reason: loaderRefused } }, failed: true };
+  if (loader === undefined || state === undefined) return { output, failed: missingEntry !== undefined };
+
+  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 };
+  const program = loaderBuilt.program;
+  // The simulation: the loader in memory as it loads, then every copy in its order, byte by byte.
+  const memory = new Int16Array(0x10000).fill(-1);
+  program.subarray(2).forEach((byte, offset) => (memory[loaderBuilt.start! + offset] = byte));
+  const expected = (address: number) => (image.segments.some((segment) => address >= segment.start && address <= segment.end) ? image.byteAt(address) : state.pages[address]!);
+  const wrongPacking = loader.blocks.find((block) => {
+    for (let address = block.range.start; address <= block.range.end; address++) if (memory[block.packedAt + address - block.range.start] !== block.bytes(address)) return true;
+    return false;
+  });
+  if (loaderBuilt.start !== 0x0801 || loaderBuilt.start + program.length - 3 !== loader.end || wrongPacking !== undefined) {
+    throw new WireFailure("operation-failed", `The assembled loader does not have the planned layout${wrongPacking === undefined ? "" : ` (${wrongPacking.what})`}. This is a defect of the c64-source script.`);
+  }
+  const jumpSymbol = loaderBuilt.symbols?.find((symbol) => symbol.name === LOADER_JUMP);
+  if (jumpSymbol === undefined) throw new WireFailure("operation-failed", `The assembled loader has no ${LOADER_JUMP} label. This is a defect of the c64-source script.`);
+  const jump = jumpSymbol.kind === "address" ? jumpSymbol.address : jumpSymbol.value;
+  const wrong = simulate(memory, loader.copies, expected);
+  if (wrong !== undefined) throw new WireFailure("operation-failed", `The simulated loader writes a wrong byte at ${formatC64Address(wrong)}. This is a defect of the c64-source script.`);
+  const loaderPath = `${values.out}/loader.prg`;
+  writeProjectFile(loaderPath, program, { what: "--out" });
+  (output.files as string[]).push("loader.prg");
+  const ran = await runLoader(loaderPath, program, loader, image, state, jump);
+  output.loader = {
+    program: loaderPath,
+    copies: loader.copies.map((copy) => ({ what: copy.what, to: `${formatC64Address(copy.target.start)}-${formatC64Address(copy.target.end)}` })),
+    copier: formatC64Address(loader.copier),
+    stackByte: formatC64Address(loader.stackByte),
+    ...ran,
+    // What the loader cannot set as it was at the entry (D63).
+    ...(loader.cia === undefined || loader.cia.limits.length === 0 ? {} : { limits: loader.cia.limits }),
+  };
+  return { output, failed: !ran.verified };
+}
+
+await runScript(
+  async () => {
+    const { output, failed } = await run(process.argv.slice(2));
+    if (failed) process.exitCode = 1;
+    return output;
+  },
+  { usage: USAGE, refusals: [KnowledgeError] },
+);