@henols/c64-re-tools 2.0.0-rc.3 → 2.0.0-rc.5

package/skills/c64-knowledge/SKILL.md

@@ -35,33 +35,96 @@ 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
 
 Read:
 
 1. Use `at` for the addresses in the question before other work.
-2. Use `history` when the current knowledge is surprising or disputed.
+2. Use `history` when the current knowledge is surprising or disputed. Each row gives the `reason` and the `evidence` of the revision that wrote it.
 
 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 and their fields:
+
+| op | Fields |
+|---|---|
+| `rename` | `address`, `name`, `kind` (optional) |
+| `remove-symbol` | `address` |
+| `classify` | `start`, `end`, `type`, `element` (optional) |
+| `unclassify` | `start`, `end` |
+| `comment` | `address`, `placement` (`line` or `side`), `text` |
+| `uncomment` | `address`, `placement` |
+| `reference`, `unreference` | `from`, `to`, `kind` |
+| `module` | `start`, `file`, `title` (optional) |
+| `unmodule` | `start` |
+
+A `line` comment is a line of its own above the address. A `side` comment is at the end of the line of the address. All writes become one revision. If the knowledge refuses one write, the script writes nothing, and the error names the write.
+
+## 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. A `module` write without a title keeps the title that the module has. 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 +163,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 { historyAt, historyNamed, revision, revisionNote, 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,91 @@ 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) };
+          // Each row with the reason and the evidence of the revision that wrote it (F-26).
+          return {
+            history: (values.name === undefined ? historyAt(db, address(args[0]), space) : historyNamed(db, values.name, space)).map((entry) => ({ ...historyEntry(entry), ...revisionNote(db, entry.from) })),
+          };
         case "revisions": {
           const options: { limit?: number; before?: number } = {};
           if (values.limit !== undefined) options.limit = integer(values.limit, "--limit");
@@ -189,18 +304,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 +422,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.