@henols/c64-re-tools 2.0.0-rc.2 → 2.0.0-rc.4

package/skills/c64-emulator/SKILL.md

@@ -44,10 +44,14 @@ Use only the MCP tools. Each MCP session has its own C64. Nothing else can chang
 | Several of these from one moment | `c64_observe` |
 | Keys, joystick | `c64_keyboard`, `c64_joystick` |
 | Program and disk media | `c64_autostart`, `c64_program_load`, `c64_disk_attach` |
-| Machine state to go back to | `c64_snapshot` |
+| Machine state to go back to, also in a later session | `c64_snapshot` (with `out` and `file`) |
 
 Each memory and register tool has a `space`. Use `c64` for the computer. Use `drive8` for the CPU of the 1541 disk drive. The memory `view` is `cpu` or `ram`. With `cpu`, you see what the CPU sees now, with ROM and I/O where the memory configuration puts them. With `ram`, you see the RAM under them.
 
+For a large result, give `out` with a path in the project. `c64_memory_read`, `c64_disassemble`, `c64_cpu_history` and `c64_screen` then write the result to that file. The answer gives only the file, the number of bytes and a SHA-256. Use it for a memory dump of more than a few hundred bytes, a long listing, or a screen that the user wants to keep.
+
+`c64_memmap` keeps RAM, ROM and I/O apart. Use action `summary` to see which code ran. Use action `read` with `out` to keep a coverage run as a file, for example `coverage/attract.bin`. Clear the map before each run that you want to keep apart.
+
 ## Workflow
 
 1. Read the project knowledge for the addresses in the question. Use the c64-knowledge skill.
@@ -64,7 +68,11 @@ Write operations need a stopped CPU. Stop the CPU with `c64_execution` action `p
 
 Step, next and until-return work only in space `c64`. The emulator cannot stop the disk drive CPU after one instruction. To find when the drive executes an address, use `c64_run_until` with an address target in space `drive8`, or a breakpoint in space `drive8`. The drive can execute a few more instructions before it stops. The computer completes its current instruction. The `pc` in the result is the drive address where it stopped.
 
-`c64_keyboard` puts keys in the keyboard queue of the KERNAL. A program that reads the keyboard hardware directly does not see them. Many games do this. For such a program, use `c64_joystick`, or open the window and ask the user to press the key.
+`c64_keyboard` puts keys in the keyboard queue of the KERNAL. A program that reads the keyboard hardware directly does not see them. Many games do this. The emulator has no command that presses one key of the keyboard matrix. For such a program:
+
+- A wait for any key that reads all keyboard columns at one time can end without a key. Joystick port 1 uses the same lines as the keyboard.
+- For one specific key, for example F1 or RUN/STOP, open the window and ask the user to press the key.
+- Do not change the program to make it accept a key.
 
 Before a risky experiment, save the state with `c64_snapshot`. Restore it to try again from the same point.
 
@@ -108,9 +116,8 @@ If you cannot get the machine into the necessary state, say which state you coul
 - `machine-unavailable` and the message says that the VICE window closed: the session starts the emulator again. Wait a few seconds. Then do the operation again.
 - `machine-state-lost` with a different message: the emulator stopped and its state is gone. Do not continue with results from before. Tell the user to restart the MCP server.
 - `machine-unavailable` and the message names a pause or a dialog in the emulator window: this occurs only while the window is open. Do not send more operations. Tell the user to resume the emulator (Pause, Alt+P) or to close the dialog in the VICE window. Then do the operation again. The machine state does not change.
-- `machine-unavailable` with a different message: the host runtime does not run, or it does not answer. Tell the user to start the host runtime with `npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host`.
 - `machine-running`: stop the CPU first, then try again.
-- `installation-incomplete`: tell the user the message. Do not try to repair the installation.
+- `installation-incomplete`, or `machine-unavailable` with a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script. Do not try to repair the installation.
 - `c64_run_until` with `stopReason` `timeout`: the target did not occur in the frame limit. This is evidence too. Report it.
 - `c64_run_until` with `stopReason` `jam`: the CPU executed a JAM opcode and stopped. Report the address.
 

package/skills/c64-knowledge/SKILL.md

@@ -35,16 +35,41 @@ The script prints one JSON object. An error prints `{"error": {"code": ..., "mes
 | Everything known at one address | `at '$2100'` |
 | Find names and comment text | `search player` |
 | Lists in a range | `symbols`, `regions`, `comments`, `references` with `--start` and `--end` |
+| Only some origins | add `--origin semantic`, `--origin analyzer` (dxa, ghidra and heuristic), or `--origin user,llm` |
+| All knowledge in one file | `export --out exports/knowledge.json` |
 | Name the symbol at an address | `rename '$2100' update_player --kind routine` |
 | Remove a symbol | `remove-symbol '$2100'` |
 | Classify memory | `classify '$3000' '$303f' sprite` |
-| Make memory unknown again | `unclassify '$3000' '$303f'` |
+| Classify a table of records | `classify '$3000' '$303b' bytes --element 6` |
+| Many writes as one revision | `apply batch.json`, or `apply -` with the JSON on standard input |
+| Make memory unknown, and keep the analyzers out of it | `unclassify '$3000' '$303f'` |
 | Set or remove a comment | `comment '$2100' line Reads joystick 2.` / `uncomment '$2100' line` |
 | Add or remove a reference | `reference '$2000' '$2100' call` / `unreference ...` |
+| Places that a removal blocks | `suppressions` with `--start` and `--end` |
+| Start a file of generated source | `module '$2000' player.asm --title 'Player movement'` / `unmodule '$2000'` |
+| Files of generated source | `modules` |
+| The address spaces that hold knowledge | `spaces` |
 | History | `history '$2100'`, `history --name update_player`, `revisions`, `revision 12` |
 | Go back to an earlier state | `revert 12` |
 
-Symbol kinds are `label`, `routine`, `variable`, `data` and `vector`. Region types are `code`, `bytes`, `words`, `addresses`, `addresses-split`, `petscii`, `screen`, `bitmap` and `sprite`. Reference kinds are `call`, `jump`, `read`, `write` and `reference`.
+Every command takes `--space`: `c64` (the default), `drive8` for code in the 1541 drive, or `bank0` to `bank255` for cartridge banks. Drive code and banks use the same addresses as the C64, so each space has its own knowledge. A name is unique inside one space. In a batch, a write can name its own `space`.
+
+Symbol kinds are `label`, `routine`, `variable`, `data` and `vector`. Reference kinds are `call`, `jump`, `read`, `write` and `reference`.
+
+Region types:
+
+| Type | Meaning |
+|---|---|
+| `code` | Instructions. |
+| `bytes`, `words`, `petscii`, `screen`, `bitmap`, `sprite` | Data of that form. |
+| `addresses`, `addresses-split` | A table of addresses: one table of 16-bit values, or a low-byte table and then a high-byte table. |
+| `rts-addresses`, `rts-addresses-split` | The same, with each value the target minus 1, for a PHA, PHA, RTS dispatch. |
+| `jumps` | A table of `JMP abs` instructions. Each 3-byte entry is an entry point. It is code. |
+| `workspace` | RAM that the program writes at run time. Its bytes in the image do not matter. |
+| `unused` | Bytes that nothing executes or reads. |
+| `dual-use` | Code at one time and data or a vector at another time. No analyzer finding conflicts with it. |
+
+`--element` gives the bytes of one element of a table. The length of the region must be a multiple of it. The result shows `element` and `count`.
 
 ## Workflow
 
@@ -57,11 +82,35 @@ Write:
 
 1. Read the current value with `at`. Note the `revision` in the result.
 2. Decide the change. Keep observed facts apart from your conclusions.
-3. Write it with `--reason` and `--expect-revision` set to the revision you read.
+3. Write it with `--reason` and `--expect-revision` set to the revision you read. Add `--evidence` for each thing that the change rests on: `coverage:<file>`, `test:<file>`, `file:<file>` or `note:<text>`. The script keeps the SHA-256 of each file.
 4. Read the result. A `revision` of `null` means that nothing changed.
 
 Each write is one revision. A classification inside a region splits that region, so regions never overlap.
 
+For more than a few writes, put them in one JSON file and use `apply`. The file is a list of writes. Each write has `op` and the arguments of the command with the same name, for example:
+
+```json
+[
+  { "op": "rename", "address": "$2100", "name": "update_player", "kind": "routine" },
+  { "op": "classify", "start": "$3000", "end": "$303b", "type": "bytes", "element": 6 },
+  { "op": "comment", "address": "$2100", "placement": "line", "text": "Reads joystick 2." }
+]
+```
+
+The ops are `rename`, `remove-symbol`, `classify`, `unclassify`, `comment`, `uncomment`, `reference`, `unreference`, `module` and `unmodule`. All writes become one revision. If the knowledge refuses one write, the script writes nothing, and the error names the write.
+
+## Modules
+
+A module tells the c64-source skill where a file of the generated source starts. The file runs to the next module or to the end of its segment. Each address has one module, and each file name has one module. A file name has letters, digits, underscores or hyphens, and ends in `.asm`. The title becomes the first line of the file. Modules have a history, and `revert` restores them.
+
+## Removals
+
+`remove-symbol`, `unclassify` and `unreference` block the place for DXA and Ghidra. An analysis does not add a symbol at that address, a region in that range or that reference again. This applies to every removed fact, also to a fact from the LLM.
+
+- `suppressions` lists the blocked places with the reason of each removal. `at` and `history` also show them.
+- A `rename`, `classify` or `reference` at a blocked place ends the block there, because your own fact is at the place then.
+- A `revert` to a revision before the removal also ends the block.
+
 ## Knowledge
 
 Write after interpretation:
@@ -100,3 +149,4 @@ A revert makes a new revision. The history stays complete.
 
 - Runtime evidence → c64-emulator
 - Static evidence → c64-static-analysis
+- Source from the knowledge → c64-source

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

@@ -1,44 +1,63 @@
 // The c64-knowledge script: reads and writes .c64-re-tools/knowledge.db in the
 // project directory (the working directory) and prints one compact JSON result.
 
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
 import type { DatabaseSync } from "node:sqlite";
 import { parseArgs } from "node:util";
 
 import { formatC64Address, parseC64Address } from "#src/c64.ts";
+import { readProjectFile, writeProjectFile } from "#src/host-client/transfer.ts";
 import { KnowledgeError, openForRead, withWrite } from "#src/knowledge/database.ts";
 import { historyAt, historyNamed, revision, revisions, type HistoryEntry } from "#src/knowledge/history.ts";
 import {
   at,
+  currentRevision,
   listComments,
+  listModules,
+  listSpaces,
   listReferences,
   listRegions,
+  listSuppressions,
   listSymbols,
   search,
   type CommentRow,
+  type ModuleRow,
   type ReferenceRow,
   type RegionRow,
+  type SuppressionRow,
   type SymbolRow,
 } from "#src/knowledge/read.ts";
 import {
   COMMENT_PLACEMENTS,
+  DEFAULT_SPACE,
+  EVIDENCE_KINDS,
+  ORIGINS,
   REFERENCE_KINDS,
   REGION_TYPES,
+  SPACE,
   SYMBOL_KINDS,
   type CommentPlacement,
+  type Origin,
   type ReferenceKind,
   type RegionType,
   type SymbolKind,
 } from "#src/knowledge/schema.ts";
 import {
   addReference,
+  applyBatch,
   classifyRegion,
   removeComment,
+  removeModule,
   removeReference,
   removeSymbol,
   renameSymbol,
   revert,
   setComment,
+  setModule,
   unclassifyRegion,
+  type BatchOperation,
+  type Evidence,
   type WriteContext,
 } from "#src/knowledge/write.ts";
 import { runScript, UsageError } from "#src/script.ts";
@@ -48,27 +67,44 @@ const USAGE = `knowledge.ts <command> [arguments] [options]
 Read (no database needed):
   at <address>                        everything known at one address
   search <text>                       symbol names and comment texts
-  symbols [--start A --end A --kind K]
-  regions [--start A --end A --type T]
-  comments [--start A --end A]
-  references [--start A --end A --kind K]
+  symbols [--start A --end A --kind K --origin O]
+  regions [--start A --end A --type T --origin O]
+  comments [--start A --end A --origin O]
+  references [--start A --end A --kind K --origin O]
+  suppressions [--start A --end A]   places that removals keep free of analyzer facts
+  modules [--start A --end A --origin O]   where the files of generated source start
+  spaces                              the address spaces that hold knowledge
   history <address> | history --name <name>
   revisions [--limit N --before N]
   revision <id>
+  export --out <file> [--start A --end A --origin O]   all current knowledge to a project file
+
+Every command takes --space S: c64 (the default), drive8 for code in the 1541
+drive, or bank0 to bank255 for cartridge banks. A write in a batch can name its
+own space.
+
+Read option --origin O: user, llm, dxa, ghidra, heuristic, semantic (user and
+llm) or analyzer (dxa, ghidra and heuristic), or a comma list. search takes it too.
 
 Write (one revision each; creates the database when needed):
   rename <address> <name> [--kind K]
   remove-symbol <address>
-  classify <start> <end> <type>
+  classify <start> <end> <type> [--element N]
   unclassify <start> <end>
   comment <address> <line|side> <text>
   uncomment <address> <line|side>
   reference <from> <to> <kind>
   unreference <from> <to> <kind>
+  module <start> <file.asm> [--title T]   a file of generated source starts here
+  unmodule <start>
   revert <revision>
+  apply <file>             many writes from a JSON file ('-' reads standard input),
+                           all as one revision, or none when one is refused
 
 Write options:
   --reason <text>          why, kept with the revision
+  --evidence <kind:ref>    what the change rests on: coverage:<file>, test:<file>,
+                           file:<file> or note:<text> (repeatable)
   --expect-revision <N>    refuse the write if knowledge changed after revision N
   --origin user|llm        who decided (default llm)
 
@@ -94,10 +130,30 @@ function integer(value: string | undefined, what: string): number {
 }
 
 // Output shapes: addresses as $xxxx, nothing internal.
-const symbol = (row: SymbolRow) => ({ address: formatC64Address(row.address), name: row.name, kind: row.kind, origin: row.origin, revision: row.revision });
-const region = (row: RegionRow) => ({ start: formatC64Address(row.start), end: formatC64Address(row.end), type: row.type, origin: row.origin, revision: row.revision });
-const comment = (row: CommentRow) => ({ address: formatC64Address(row.address), placement: row.placement, text: row.text, origin: row.origin, revision: row.revision });
-const reference = (row: ReferenceRow) => ({ from: formatC64Address(row.from), to: formatC64Address(row.to), kind: row.kind, origin: row.origin, revision: row.revision });
+/** The space of a row, shown only when it is not the C64 (D53). */
+const spaceOf = (row: { space: string }) => (row.space === "c64" ? {} : { space: row.space });
+const symbol = (row: SymbolRow) => ({ ...spaceOf(row), address: formatC64Address(row.address), name: row.name, kind: row.kind, origin: row.origin, revision: row.revision });
+const region = (row: RegionRow) => ({
+  ...spaceOf(row),
+  start: formatC64Address(row.start),
+  end: formatC64Address(row.end),
+  type: row.type,
+  ...(row.element === undefined ? {} : { element: row.element, count: (row.end - row.start + 1) / row.element }),
+  origin: row.origin,
+  revision: row.revision,
+});
+const comment = (row: CommentRow) => ({ ...spaceOf(row), address: formatC64Address(row.address), placement: row.placement, text: row.text, origin: row.origin, revision: row.revision });
+const module = (row: ModuleRow) => ({ ...spaceOf(row), start: formatC64Address(row.start), file: row.file, ...(row.title === undefined ? {} : { title: row.title }), origin: row.origin, revision: row.revision });
+const reference = (row: ReferenceRow) => ({ ...spaceOf(row), from: formatC64Address(row.from), to: formatC64Address(row.to), kind: row.kind, origin: row.origin, revision: row.revision });
+function suppression(row: SuppressionRow) {
+  const place =
+    row.entity === "symbol"
+      ? { address: formatC64Address(row.start) }
+      : row.entity === "region"
+        ? { start: formatC64Address(row.start), end: formatC64Address(row.end) }
+        : { from: formatC64Address(row.start), to: formatC64Address(row.to!), kind: row.kind! };
+  return { ...spaceOf(row), suppresses: row.entity, ...place, origin: row.origin, revision: row.revision };
+}
 
 function historyEntry(entry: HistoryEntry) {
   const shown =
@@ -107,11 +163,27 @@ function historyEntry(entry: HistoryEntry) {
         ? region(entry.row)
         : entry.entity === "comment"
           ? comment(entry.row)
-          : reference(entry.row);
+          : entry.entity === "reference"
+            ? reference(entry.row)
+            : entry.entity === "module"
+              ? module(entry.row)
+              : suppression(entry.row);
   const { revision: _revision, ...row } = shown;
   return { entity: entry.entity, ...row, fromRevision: entry.from, ...(entry.to === undefined ? {} : { toRevision: entry.to }) };
 }
 
+/** The reason of each revision that wrote one of the rows. */
+function reasonsOf(db: DatabaseSync | undefined, rows: SuppressionRow[]): Map<number, string> {
+  const reasons = new Map<number, string>();
+  const query = db?.prepare("SELECT description FROM revisions WHERE id = ?");
+  for (const { revision } of rows) {
+    if (query === undefined || reasons.has(revision)) continue;
+    const found = query.get(revision) as { description: string | null } | undefined;
+    if (found?.description != null) reasons.set(revision, found.description);
+  }
+  return reasons;
+}
+
 function run(argv: string[]): unknown {
   const { values, positionals } = parseArgs({
     args: argv,
@@ -128,48 +200,88 @@ function run(argv: string[]): unknown {
       reason: { type: "string" },
       "expect-revision": { type: "string" },
       origin: { type: "string" },
+      element: { type: "string" },
+      evidence: { type: "string", multiple: true },
+      out: { type: "string" },
+      title: { type: "string" },
+      space: { type: "string" },
       help: { type: "boolean" },
     },
   });
   const [command, ...args] = positionals;
   if (values.help || command === undefined) throw new UsageError("");
   const range = { start: values.start === undefined ? 0x0000 : address(values.start, "--start"), end: values.end === undefined ? 0xffff : address(values.end, "--end") };
+  if (values.space !== undefined && !SPACE.test(values.space)) throw new UsageError("--space must be c64, drive8, or bank0 to bank255");
+  const space = values.space ?? DEFAULT_SPACE;
 
-  const read = new Set(["at", "search", "symbols", "regions", "comments", "references", "history", "revisions", "revision"]);
-  const write = new Set(["rename", "remove-symbol", "classify", "unclassify", "comment", "uncomment", "reference", "unreference", "revert"]);
+  const read = new Set(["at", "search", "symbols", "regions", "comments", "references", "suppressions", "modules", "spaces", "history", "revisions", "revision", "export"]);
+  const write = new Set(["rename", "remove-symbol", "classify", "unclassify", "comment", "uncomment", "reference", "unreference", "module", "unmodule", "revert", "apply"]);
   // Refuse a mistyped command before anything opens, so no database appears by accident.
   if (!read.has(command) && !write.has(command)) throw new UsageError(`unknown command: ${command}`);
   if (read.has(command)) {
+    const origins = values.origin === undefined ? undefined : originFilter(values.origin);
+    if (command === "export" && values.out === undefined) throw new UsageError("export needs --out <file>");
     const db = openForRead();
     try {
       switch (command) {
         case "at": {
-          const known = at(db, address(args[0]));
+          const known = at(db, address(args[0]), space);
           return {
+            ...(space === DEFAULT_SPACE ? {} : { space }),
             address: formatC64Address(known.address),
             ...(known.symbol === undefined ? {} : { symbol: symbol(known.symbol) }),
             ...(known.region === undefined ? {} : { region: region(known.region) }),
             comments: known.comments.map(comment),
             referencesFrom: known.referencesFrom.map(reference),
             referencesTo: known.referencesTo.map(reference),
+            ...(known.suppressions.length === 0 ? {} : { suppressions: known.suppressions.map(suppression) }),
             revision: known.revision,
           };
         }
         case "search": {
           if (args[0] === undefined || args[0] === "") throw new UsageError("search needs text");
-          const found = search(db, args[0], values.limit === undefined ? 50 : integer(values.limit, "--limit"));
+          const found = search(db, args[0], values.limit === undefined ? 50 : integer(values.limit, "--limit"), origins, space);
           return { symbols: found.symbols.map(symbol), comments: found.comments.map(comment) };
         }
         case "symbols":
-          return { symbols: listSymbols(db, range, values.kind === undefined ? undefined : oneOf(SYMBOL_KINDS, values.kind, "--kind")).map(symbol) };
+          return { symbols: listSymbols(db, range, values.kind === undefined ? undefined : oneOf(SYMBOL_KINDS, values.kind, "--kind"), origins, space).map(symbol) };
         case "regions":
-          return { regions: listRegions(db, range, values.type === undefined ? undefined : oneOf(REGION_TYPES, values.type, "--type")).map(region) };
+          return { regions: listRegions(db, range, values.type === undefined ? undefined : oneOf(REGION_TYPES, values.type, "--type"), origins, space).map(region) };
         case "comments":
-          return { comments: listComments(db, range).map(comment) };
+          return { comments: listComments(db, range, origins, space).map(comment) };
         case "references":
-          return { references: listReferences(db, range, values.kind === undefined ? undefined : oneOf(REFERENCE_KINDS, values.kind, "--kind")).map(reference) };
+          return { references: listReferences(db, range, values.kind === undefined ? undefined : oneOf(REFERENCE_KINDS, values.kind, "--kind"), origins, space).map(reference) };
+        case "export": {
+          const exported = {
+            revision: currentRevision(db),
+            ...(space === DEFAULT_SPACE ? {} : { space }),
+            symbols: listSymbols(db, range, undefined, origins, space).map(symbol),
+            regions: listRegions(db, range, undefined, origins, space).map(region),
+            comments: listComments(db, range, origins, space).map(comment),
+            references: listReferences(db, range, undefined, origins, space).map(reference),
+            suppressions: listSuppressions(db, range, space).map(suppression),
+            modules: listModules(db, range, origins, space).map(module),
+          };
+          const bytes = Buffer.from(`${JSON.stringify(exported, null, 2)}\n`, "utf8");
+          writeProjectFile(values.out!, bytes, { what: "--out" });
+          return {
+            out: values.out,
+            bytes: bytes.length,
+            counts: { symbols: exported.symbols.length, regions: exported.regions.length, comments: exported.comments.length, references: exported.references.length, suppressions: exported.suppressions.length, modules: exported.modules.length },
+            revision: exported.revision,
+          };
+        }
+        case "suppressions": {
+          const rows = listSuppressions(db, range, space);
+          const reasons = reasonsOf(db, rows);
+          return { suppressions: rows.map((row) => ({ ...suppression(row), ...(reasons.has(row.revision) ? { reason: reasons.get(row.revision) } : {}) })) };
+        }
+        case "modules":
+          return { modules: listModules(db, range, origins, space).map(module) };
+        case "spaces":
+          return { spaces: listSpaces(db) };
         case "history":
-          return { history: (values.name === undefined ? historyAt(db, address(args[0])) : historyNamed(db, values.name)).map(historyEntry) };
+          return { history: (values.name === undefined ? historyAt(db, address(args[0]), space) : historyNamed(db, values.name, space)).map(historyEntry) };
         case "revisions": {
           const options: { limit?: number; before?: number } = {};
           if (values.limit !== undefined) options.limit = integer(values.limit, "--limit");
@@ -189,18 +301,117 @@ function run(argv: string[]): unknown {
   const context: WriteContext = { origin: values.origin === undefined ? "llm" : oneOf(["user", "llm"] as const, values.origin, "--origin") };
   if (values.reason !== undefined) context.description = values.reason;
   if (values["expect-revision"] !== undefined) context.expectedRevision = integer(values["expect-revision"], "--expect-revision");
+  if (values.evidence !== undefined) context.evidence = values.evidence.map(evidenceOf);
   // Every argument is checked before the database opens: a refused write creates no database.
-  const operation = writeOperation(command, args, values.kind, context);
+  if (values.title !== undefined && command !== "module") throw new UsageError("--title works only with module");
+  const operation = command === "apply" ? applyOperation(args, context, space) : writeOperation(command, args, values.kind, values.element, context, values.title, space);
   return withWrite(operation);
 }
 
+/** --origin for reads: one origin, semantic (user and llm), analyzer (dxa and ghidra), or a comma list. */
+function originFilter(value: string): Origin[] {
+  const origins = new Set<Origin>();
+  for (const part of value.split(",")) {
+    if (part === "semantic") origins.add("user").add("llm");
+    else if (part === "analyzer") origins.add("dxa").add("ghidra").add("heuristic");
+    else origins.add(oneOf(ORIGINS, part, "--origin"));
+  }
+  return [...origins];
+}
+
+/** --evidence kind:ref. A file kind names a project file and keeps its SHA-256, so a later change of the file shows. */
+function evidenceOf(value: string): Evidence {
+  const colon = value.indexOf(":");
+  const kind = oneOf(EVIDENCE_KINDS, colon < 0 ? value : value.slice(0, colon), "--evidence kind");
+  const ref = colon < 0 ? "" : value.slice(colon + 1);
+  if (ref === "") throw new UsageError(`--evidence needs ${kind}:<${kind === "note" ? "text" : "file"}>`);
+  if (kind === "note") return { kind, ref };
+  return { kind, ref, sha256: createHash("sha256").update(readProjectFile(ref).bytes).digest("hex") };
+}
+
+/** apply <file>: the batch as BatchOperation values, checked before the database opens. */
+function applyOperation(args: string[], context: WriteContext, space: string): WriteOperation {
+  if (args.length !== 1) throw new UsageError("apply needs one file, or - for standard input");
+  const text = args[0] === "-" ? readFileSync(0, "utf8") : readProjectFile(args[0]!).bytes.toString("utf8");
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw new UsageError(`the batch is not JSON: ${(error as Error).message}`);
+  }
+  if (!Array.isArray(parsed)) throw new UsageError("the batch is a JSON list of writes, for example [{\"op\": \"rename\", \"address\": \"$2100\", \"name\": \"update_player\"}]");
+  const operations = parsed.map((item, index) => batchOperation(item, `write ${index + 1}`, space));
+  return (db) => {
+    const applied = applyBatch(db, context, operations);
+    // replaced: writes that replaced a row of another origin, as previous does for one write.
+    return { revision: applied.revision, writes: applied.steps.length, replaced: applied.steps.filter((step) => step.previous !== undefined).length };
+  };
+}
+
+const BATCH_FIELDS: Record<BatchOperation["op"], string[]> = {
+  rename: ["address", "name", "kind"],
+  "remove-symbol": ["address"],
+  classify: ["start", "end", "type", "element"],
+  unclassify: ["start", "end"],
+  comment: ["address", "placement", "text"],
+  uncomment: ["address", "placement"],
+  reference: ["from", "to", "kind"],
+  unreference: ["from", "to", "kind"],
+  module: ["start", "file", "title"],
+  unmodule: ["start"],
+};
+
+/** One write of a batch. A write names its own space, or takes the one of --space. */
+function batchOperation(item: unknown, at: string, space: string): BatchOperation {
+  const operation = batchFields(item, at);
+  const own = (item as Record<string, unknown>).space;
+  if (own !== undefined && typeof own !== "string") throw new UsageError(`${at}: space must be a string`);
+  return { ...operation, space: own ?? space };
+}
+
+/** The fields of one write of a batch, with its addresses parsed. */
+function batchFields(item: unknown, at: string): BatchOperation {
+  if (typeof item !== "object" || item === null || Array.isArray(item)) throw new UsageError(`${at}: a write is an object with op`);
+  const fields = item as Record<string, unknown>;
+  const op = oneOf(Object.keys(BATCH_FIELDS) as Array<BatchOperation["op"]>, String(fields.op), `${at}: op`);
+  const unknown = Object.keys(fields).filter((key) => key !== "op" && key !== "space" && !BATCH_FIELDS[op].includes(key));
+  if (unknown.length > 0) throw new UsageError(`${at}: ${op} takes ${BATCH_FIELDS[op].join(", ")}, not ${unknown.join(", ")}`);
+  const text = (key: string) => {
+    if (typeof fields[key] !== "string") throw new UsageError(`${at}: ${key} must be a string`);
+    return fields[key] as string;
+  };
+  const place = (key: string) => address(text(key), `${at}: ${key}`);
+  switch (op) {
+    case "rename":
+      return { op, address: place("address"), name: text("name"), ...(fields.kind === undefined ? {} : { kind: oneOf(SYMBOL_KINDS, text("kind"), `${at}: kind`) }) };
+    case "remove-symbol":
+      return { op, address: place("address") };
+    case "classify": {
+      if (fields.element !== undefined && typeof fields.element !== "number") throw new UsageError(`${at}: element must be a number`);
+      return { op, start: place("start"), end: place("end"), type: oneOf(REGION_TYPES, text("type"), `${at}: type`), ...(fields.element === undefined ? {} : { element: fields.element as number }) };
+    }
+    case "unclassify":
+      return { op, start: place("start"), end: place("end") };
+    case "comment":
+      return { op, address: place("address"), placement: oneOf(COMMENT_PLACEMENTS, text("placement"), `${at}: placement`), text: text("text") };
+    case "uncomment":
+      return { op, address: place("address"), placement: oneOf(COMMENT_PLACEMENTS, text("placement"), `${at}: placement`) };
+    case "module":
+      return { op, start: place("start"), file: text("file"), ...(fields.title === undefined ? {} : { title: text("title") }) };
+    case "unmodule":
+      return { op, start: place("start") };
+    default:
+      return { op, from: place("from"), to: place("to"), kind: oneOf(REFERENCE_KINDS, text("kind"), `${at}: kind`) };
+  }
+}
+
 type WriteOperation = (db: DatabaseSync) => unknown;
 
-function writeOperation(command: string, args: string[], kind: string | undefined, context: WriteContext): WriteOperation {
+function writeOperation(command: string, args: string[], kind: string | undefined, element: string | undefined, context: WriteContext, title: string | undefined, space: string): WriteOperation {
   switch (command) {
     case "rename": {
       if (args[1] === undefined) throw new UsageError("name is missing");
-      const request: { address: number; name: string; kind?: SymbolKind } = { address: address(args[0]), name: args[1] };
+      const request: { space: string; address: number; name: string; kind?: SymbolKind } = { space, address: address(args[0]), name: args[1] };
       if (kind !== undefined) request.kind = oneOf(SYMBOL_KINDS, kind, "--kind");
       return (db) => {
         const result = renameSymbol(db, context, request);
@@ -208,43 +419,61 @@ function writeOperation(command: string, args: string[], kind: string | undefine
       };
     }
     case "remove-symbol": {
-      const request = { address: address(args[0]) };
+      const request = { space, address: address(args[0]) };
       return (db) => ({ revision: removeSymbol(db, context, request).revision });
     }
     case "classify": {
-      const request = { start: address(args[0], "start"), end: address(args[1], "end"), type: oneOf(REGION_TYPES, args[2], "type") as RegionType };
+      const request = {
+        space,
+        start: address(args[0], "start"),
+        end: address(args[1], "end"),
+        type: oneOf(REGION_TYPES, args[2], "type") as RegionType,
+        ...(element === undefined ? {} : { element: integer(element, "--element") }),
+      };
       return (db) => {
         const result = classifyRegion(db, context, request);
         return { revision: result.revision, regions: result.current.map(region), ...(result.previous === undefined ? {} : { previous: result.previous.map(region) }) };
       };
     }
     case "unclassify": {
-      const request = { start: address(args[0], "start"), end: address(args[1], "end") };
+      const request = { space, start: address(args[0], "start"), end: address(args[1], "end") };
       return (db) => ({ revision: unclassifyRegion(db, context, request).revision });
     }
     case "comment": {
       if (args.length < 3) throw new UsageError("text is missing");
-      const request = { address: address(args[0]), placement: oneOf(COMMENT_PLACEMENTS, args[1], "placement") as CommentPlacement, text: args.slice(2).join(" ") };
+      const request = { space, address: address(args[0]), placement: oneOf(COMMENT_PLACEMENTS, args[1], "placement") as CommentPlacement, text: args.slice(2).join(" ") };
       return (db) => {
         const result = setComment(db, context, request);
         return { revision: result.revision, comment: comment(result.current) };
       };
     }
     case "uncomment": {
-      const request = { address: address(args[0]), placement: oneOf(COMMENT_PLACEMENTS, args[1], "placement") };
+      const request = { space, address: address(args[0]), placement: oneOf(COMMENT_PLACEMENTS, args[1], "placement") };
       return (db) => ({ revision: removeComment(db, context, request).revision });
     }
     case "reference": {
-      const request = { from: address(args[0], "from"), to: address(args[1], "to"), kind: oneOf(REFERENCE_KINDS, args[2], "kind") as ReferenceKind };
+      const request = { space, from: address(args[0], "from"), to: address(args[1], "to"), kind: oneOf(REFERENCE_KINDS, args[2], "kind") as ReferenceKind };
       return (db) => {
         const result = addReference(db, context, request);
         return { revision: result.revision, reference: reference(result.current) };
       };
     }
     case "unreference": {
-      const request = { from: address(args[0], "from"), to: address(args[1], "to"), kind: oneOf(REFERENCE_KINDS, args[2], "kind") };
+      const request = { space, from: address(args[0], "from"), to: address(args[1], "to"), kind: oneOf(REFERENCE_KINDS, args[2], "kind") };
       return (db) => ({ revision: removeReference(db, context, request).revision });
     }
+    case "module": {
+      if (args[1] === undefined) throw new UsageError("file is missing");
+      const request = { space, start: address(args[0], "start"), file: args[1], ...(title === undefined ? {} : { title }) };
+      return (db) => {
+        const result = setModule(db, context, request);
+        return { revision: result.revision, module: module(result.current) };
+      };
+    }
+    case "unmodule": {
+      const request = { space, start: address(args[0], "start") };
+      return (db) => ({ revision: removeModule(db, context, request).revision });
+    }
     case "revert": {
       const request = { revision: integer(args[0], "revision") };
       return (db) => ({ revision: revert(db, context, request).revision });

package/skills/c64-memory-map/SKILL.md

@@ -24,6 +24,7 @@ The script looks up local reference data. It does not use the host runtime.
 node <skill>/scripts/memmap.ts at '$d020' '$0314' '$ffd2'
 node <skill>/scripts/memmap.ts decode '$d018' '$15' --bank '$97'
 node <skill>/scripts/memmap.ts list vic
+node <skill>/scripts/memmap.ts export --out src/hw.asm
 ```
 
 | Command | Result |
@@ -31,6 +32,7 @@ node <skill>/scripts/memmap.ts list vic
 | `at <address> ...` | For each address: `kind` (`platform` or `application`), the area, the name and the meaning. |
 | `decode <register> <value>` | The meaning of the value. Use `--bank` with the value of `$DD00` to get the addresses for `$D018`. |
 | `list <vic\|sid\|cia1\|cia2\|kernal\|system>` | All entries of that group. |
+| `export --out <file>` | Writes all platform names to a project file as an ACME include: one `NAME = $xxxx` line for each name, with its meaning as a comment. |
 
 Write an address or a value as `$` and hex digits, as a decimal number, or as `%` and binary digits. Put a `$` value in single quotes in a shell.
 
@@ -45,6 +47,7 @@ The script prints one JSON object.
 3. For an I/O register, `mirrorOf` shows the register that a mirror address repeats. `visible` tells that an address in `$D000`-`$DFFF` is visible only when `$01` shows I/O at `$D000`. This area holds the chip registers, the color RAM and the cartridge I/O areas.
 4. For a byte in a multi-byte entry, for example the high byte of a vector, `entryStart` gives the first address of the entry.
 5. To understand a value in a register, run `decode`. For the memory configuration, decode the value of `$01`.
+6. For source that you write by hand, run `export` and include the file with `!source`. The c64-source skill uses the same names without the file.
 
 The decoders are for `$01`, `$D010`, `$D011`, `$D015` to `$D01F` (the sprite and interrupt bits), `$D016`, `$D018`, `$DC0D`, `$DD00` and `$DD0D`.
 
@@ -59,7 +62,7 @@ A conclusion about the application can be project knowledge. For example: "the p
 
 ## Result
 
-The platform meaning of each address, or the decoded meaning of a register value.
+The platform meaning of each address, or the decoded meaning of a register value. For `export`: the file, the count of names and the bytes.
 
 The exit status is 0 for a result. The exit status is 2 for a wrong argument.