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

package/src/host-client/vice-session.ts

@@ -0,0 +1,316 @@
+// The long-lived Host Runtime connection an MCP process owns: one connection,
+// one VICE. Exposes C64-domain operations only.
+
+import { ProtocolError, WireFailure, type VideoStandard } from "../protocol/messages.ts";
+import { validateViceResult, type Breakpoint, type BreakpointParams, type PointRemoved, type Watchpoint, type WatchpointParams, type ExecutionParams, type ExecutionResult, type JoystickState, type MachineStatus, type MemmapRange, type MemoryWriteParams, type RegisterValues, type ResetMode, type RunState, type RunTarget, type RunUntilResult, type MemoryReadParams, type MemoryReadResult, type Registers, type Space, type ViceOperation, type ViceOperations } from "../protocol/vice.ts";
+import { HostConnection } from "./connect.ts";
+import { readProjectFile } from "./transfer.ts";
+
+const HOST_LOST =
+  "The connection to the c64-re-tools host runtime was lost. The emulator and its machine state are gone: memory, registers, breakpoints, snapshots and the loaded program. " +
+  "The next call starts a new machine when the Host Runtime (c64-re-tools-host) runs. Load the program again and set the breakpoints again.";
+const SESSION_CLOSED = "The C64 session is closed because the c64-re-tools MCP server stops.";
+const LOST_BEFORE_ANSWER = "The connection to the c64-re-tools host runtime was lost before the emulator answered. No machine state was lost. Do the call again.";
+
+/**
+ * The loss of a session that never answered (D57): it had no machine state,
+ * so the caller can do the call again on a new session.
+ */
+export class LostBeforeAnswer extends WireFailure {
+  constructor() {
+    super("machine-unavailable", LOST_BEFORE_ANSWER);
+  }
+}
+
+interface Pending {
+  op: ViceOperation;
+  resolve: (value: unknown, attachments: Buffer[]) => void;
+  reject: (error: Error) => void;
+}
+
+export class ViceSessionClient {
+  /** Settles when the session is gone, whether we closed it or the host went away. */
+  readonly closed: Promise<void>;
+  readonly #connection: HostConnection;
+  readonly #pending = new Map<number, Pending>();
+  #nextId = 1;
+  #lost: WireFailure | undefined;
+  #answered = false;
+  #lossReported = false;
+
+  private constructor(connection: HostConnection) {
+    this.#connection = connection;
+    connection.onMessage((message, attachments) => {
+      // Anything but a reply after the handshake breaks the contract.
+      if (message.type !== "reply") return this.#fail();
+      const pending = this.#pending.get(message.id);
+      if (pending === undefined) return; // not ours; ignore
+      this.#pending.delete(message.id);
+      this.#answered = true;
+      if ("error" in message) {
+        pending.reject(new WireFailure(message.error.code, message.error.message));
+        return;
+      }
+      try {
+        pending.resolve(validateViceResult(pending.op, message.result), attachments);
+      } catch (error) {
+        pending.reject(
+          new WireFailure(
+            "operation-failed",
+            error instanceof ProtocolError ? "The c64-re-tools host runtime sent an invalid reply." : "The c64-re-tools MCP server could not read the reply of the host runtime.",
+          ),
+        );
+        this.#fail();
+      }
+    });
+    this.closed = connection.closed.then(() => {
+      this.#lost ??= this.#answered ? new WireFailure("machine-state-lost", HOST_LOST) : new LostBeforeAnswer();
+      this.#lossReported = this.#pending.size > 0;
+      for (const pending of this.#pending.values()) pending.reject(this.#lost);
+      this.#pending.clear();
+    });
+  }
+
+  /** Connects and waits until the host has started this session's emulator; `signal` stops the wait at once. */
+  static async open(options: { videoStandard: VideoStandard; env?: NodeJS.ProcessEnv; signal?: AbortSignal }): Promise<ViceSessionClient> {
+    const connection = await HostConnection.open({
+      role: "vice-session",
+      videoStandard: options.videoStandard,
+      ...(options.env === undefined ? {} : { env: options.env }),
+      ...(options.signal === undefined ? {} : { signal: options.signal }),
+    });
+    return new ViceSessionClient(connection);
+  }
+
+  status(): Promise<MachineStatus> {
+    return this.#request("status", {});
+  }
+
+  memoryRead(params: MemoryReadParams): Promise<MemoryReadResult> {
+    return this.#request("memoryRead", params);
+  }
+
+  /** The I/O registers at $d000-$dfff as the chips hold them, without side effects. */
+  ioRead(address: number, size: number): Promise<MemoryReadResult> {
+    return this.#request("ioRead", { address, size });
+  }
+
+  registersGet(space: Space): Promise<Registers> {
+    return this.#request("registersGet", { space });
+  }
+
+  memoryWrite(params: MemoryWriteParams): Promise<{ address: number; bytesWritten: number }> {
+    return this.#request("memoryWrite", params);
+  }
+
+  memorySearch(params: ViceOperations["memorySearch"]["params"]): Promise<{ matches: number[] }> {
+    return this.#request("memorySearch", params);
+  }
+
+  memoryCompare(params: ViceOperations["memoryCompare"]["params"]): Promise<ViceOperations["memoryCompare"]["result"]> {
+    return this.#request("memoryCompare", params);
+  }
+
+  disassemble(params: ViceOperations["disassemble"]["params"]): Promise<ViceOperations["disassemble"]["result"]> {
+    return this.#request("disassemble", params);
+  }
+
+  registersSet(space: Space, values: RegisterValues): Promise<Registers> {
+    return this.#request("registersSet", { space, values });
+  }
+
+  execution(params: ExecutionParams): Promise<ExecutionResult> {
+    return this.#request("execution", params);
+  }
+
+  runUntil(params: { target: RunTarget; timeoutFrames: number }): Promise<RunUntilResult> {
+    return this.#request("runUntil", params);
+  }
+
+  /** Loads a project PRG into memory without reset or start; finishes stopped. */
+  async programLoad(params: { path: string; address?: number }): Promise<{ state: RunState; loadAddress: number; size: number }> {
+    const file = readProjectFile(params.path);
+    return this.#request("programLoad", params.address === undefined ? {} : { address: params.address }, [file.bytes]);
+  }
+
+  /** Autostarts a project program or image, as VICE's autostart does. */
+  async autostart(params: { path: string; index: number; run: boolean }): Promise<{ state: RunState; emulatorFlaw?: string }> {
+    const file = readProjectFile(params.path);
+    return this.#request("autostart", { type: file.type, index: params.index, run: params.run }, [file.bytes]);
+  }
+
+  /** Attaches a project disk image to drive 8. */
+  async diskAttach(params: { path: string }): Promise<{ attached: boolean }> {
+    const file = readProjectFile(params.path);
+    return this.#request("diskAttach", { type: file.type }, [file.bytes]);
+  }
+
+  reset(params: { mode: ResetMode; run: boolean }): Promise<{ state: RunState; pc?: number }> {
+    return this.#request("reset", params);
+  }
+
+  /** Queues PETSCII bytes for the C64 keyboard. */
+  keyboard(petscii: Uint8Array): Promise<{ queuedBytes: number }> {
+    return this.#request("keyboard", { data: Buffer.from(petscii).toString("hex") });
+  }
+
+  joystick(state: JoystickState): Promise<JoystickState> {
+    return this.#request("joystick", state);
+  }
+
+  /** Action list gives all breakpoints, remove gives `{removed, id}`; add, enable and disable give the one breakpoint. */
+  breakpoint(params: Extract<BreakpointParams, { action: "list" }>): Promise<{ breakpoints: Breakpoint[] }>;
+  breakpoint(params: Extract<BreakpointParams, { action: "remove" }>): Promise<PointRemoved>;
+  breakpoint(params: Exclude<BreakpointParams, { action: "list" | "remove" }>): Promise<Breakpoint>;
+  breakpoint(params: BreakpointParams): Promise<Breakpoint | PointRemoved | { breakpoints: Breakpoint[] }> {
+    return this.#request("breakpoint", params);
+  }
+
+  /** Action list gives all watchpoints, remove gives `{removed, id}`; add, enable and disable give the one watchpoint. */
+  watchpoint(params: Extract<WatchpointParams, { action: "list" }>): Promise<{ watchpoints: Watchpoint[] }>;
+  watchpoint(params: Extract<WatchpointParams, { action: "remove" }>): Promise<PointRemoved>;
+  watchpoint(params: Exclude<WatchpointParams, { action: "list" | "remove" }>): Promise<Watchpoint>;
+  watchpoint(params: WatchpointParams): Promise<Watchpoint | PointRemoved | { watchpoints: Watchpoint[] }> {
+    return this.#request("watchpoint", params);
+  }
+
+  cpuHistory(params: ViceOperations["cpuHistory"]["params"]): Promise<ViceOperations["cpuHistory"]["result"]> {
+    return this.#request("cpuHistory", params);
+  }
+
+  backtrace(params: ViceOperations["backtrace"]["params"]): Promise<ViceOperations["backtrace"]["result"]> {
+    return this.#request("backtrace", params);
+  }
+
+  timing(action: ViceOperations["timing"]["params"]["action"]): Promise<ViceOperations["timing"]["result"]> {
+    return this.#request("timing", { action });
+  }
+
+  profile(limit: number): Promise<ViceOperations["profile"]["result"]> {
+    return this.#request("profile", { limit });
+  }
+
+  /** Action read gives the ranges; action clear gives cleared. */
+  memmap(params: Extract<ViceOperations["memmap"]["params"], { action: "read" }>): Promise<{ ranges: MemmapRange[]; next?: number }>;
+  memmap(params: { action: "clear" }): Promise<{ cleared: boolean }>;
+  memmap(params: ViceOperations["memmap"]["params"]): Promise<ViceOperations["memmap"]["result"]> {
+    return this.#request("memmap", params);
+  }
+
+  vicii(): Promise<ViceOperations["vicii"]["result"]> {
+    return this.#request("vicii", {});
+  }
+
+  /** Empty `indexes` means all eight sprites. */
+  sprites(indexes: number[]): Promise<ViceOperations["sprites"]["result"]> {
+    return this.#request("sprites", { indexes });
+  }
+
+  cia(which: ViceOperations["cia"]["params"]["which"]): Promise<ViceOperations["cia"]["result"]> {
+    return this.#request("cia", { which });
+  }
+
+  sid(): Promise<ViceOperations["sid"]["result"]> {
+    return this.#request("sid", {});
+  }
+
+  observe(params: ViceOperations["observe"]["params"]): Promise<ViceOperations["observe"]["result"]> {
+    return this.#request("observe", params);
+  }
+
+  /** The last frame the VIC-II drew, as a base64 PNG with its size. */
+  screenCapture(baseline?: string): Promise<ViceOperations["screenCapture"]["result"]> {
+    return this.#request("screenCapture", baseline === undefined ? {} : { baseline });
+  }
+
+  screenCompare(params: ViceOperations["screenCompare"]["params"]): Promise<ViceOperations["screenCompare"]["result"]> {
+    return this.#request("screenCompare", params);
+  }
+
+  snapshot(params: ViceOperations["snapshot"]["params"]): Promise<ViceOperations["snapshot"]["result"]> {
+    return this.#request("snapshot", params);
+  }
+
+  /** The bytes of a named snapshot, as a .vsf file holds them (D41). */
+  async snapshotExport(name: string): Promise<Buffer> {
+    const { attachments } = await this.#requestWithAttachments("snapshotFile", { action: "export", name });
+    const [bytes] = attachments;
+    if (bytes === undefined || attachments.length !== 1) throw new WireFailure("operation-failed", "The c64-re-tools host runtime sent no snapshot file.");
+    return bytes;
+  }
+
+  /** Restores the machine from the bytes of a .vsf file; the CPU stays stopped. */
+  snapshotRestore(bytes: Uint8Array): Promise<ViceOperations["snapshotFile"]["result"]> {
+    return this.#request("snapshotFile", { action: "restore" }, [bytes]);
+  }
+
+  screenBaselines(): Promise<{ baselines: string[] }> {
+    return this.#request("screenBaselines", {});
+  }
+
+  screenDiscard(baseline: string): Promise<{ discarded: boolean }> {
+    return this.#request("screenDiscard", { baseline });
+  }
+
+  warp(enabled: boolean): Promise<{ enabled: boolean }> {
+    return this.#request("warp", { enabled });
+  }
+
+  /** Moves the machine into a VICE with a window (open) or back into a headless one (close). */
+  window(action: ViceOperations["window"]["params"]["action"]): Promise<ViceOperations["window"]["result"]> {
+    return this.#request("window", { action });
+  }
+
+  /** True when the connection to the host is gone, whatever the reason. */
+  get lost(): boolean {
+    return this.#lost !== undefined;
+  }
+
+  /** True when the emulator answered a request: then the session had machine state to lose (D57). */
+  get answered(): boolean {
+    return this.#answered;
+  }
+
+  /** The loss of a lost session, when no request got it; undefined while the session lives (D57). */
+  get unreportedLoss(): WireFailure | undefined {
+    return this.#lost?.code === "machine-state-lost" && !this.#lossReported ? this.#lost : undefined;
+  }
+
+  /** Ends the session; the host stops its emulator. Open and later requests fail as closed. */
+  async close(): Promise<void> {
+    this.#lost ??= new WireFailure("machine-unavailable", SESSION_CLOSED);
+    await this.#connection.close();
+    await this.closed;
+  }
+
+  async #request<O extends ViceOperation>(
+    op: O,
+    params: ViceOperations[O]["params"],
+    attachments: readonly Uint8Array[] = [],
+  ): Promise<ViceOperations[O]["result"]> {
+    return (await this.#requestWithAttachments(op, params, attachments)).result;
+  }
+
+  /** One request; the reply's result and the attachments that came with it. */
+  #requestWithAttachments<O extends ViceOperation>(
+    op: O,
+    params: ViceOperations[O]["params"],
+    attachments: readonly Uint8Array[] = [],
+  ): Promise<{ result: ViceOperations[O]["result"]; attachments: Buffer[] }> {
+    if (this.#lost !== undefined) {
+      this.#lossReported = true;
+      return Promise.reject(this.#lost);
+    }
+    const id = this.#nextId;
+    this.#nextId = this.#nextId >= 0xffff_ffff ? 1 : this.#nextId + 1;
+    return new Promise((resolve, reject) => {
+      this.#pending.set(id, { op, resolve: (result, received) => resolve({ result: result as ViceOperations[O]["result"], attachments: received }), reject });
+      this.#connection.send({ type: "request", id, op, params }, attachments);
+    });
+  }
+
+  /** Drops a connection whose host broke the protocol; pending work fails as lost. */
+  #fail(): void {
+    void this.#connection.close();
+  }
+}

package/src/knowledge/database.ts

@@ -0,0 +1,132 @@
+// The one place that opens .c64-re-tools/knowledge.db.
+
+import { existsSync, mkdirSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { join } from "node:path";
+
+import { projectRoot } from "../project.ts";
+import { checkVersion, ensureSchema, schemaVersion } from "./schema.ts";
+
+export const KNOWLEDGE_DIRECTORY = ".c64-re-tools";
+export const KNOWLEDGE_FILE = "knowledge.db";
+
+export const KNOWLEDGE_ERROR_CODES = [
+  "invalid-input",
+  "not-found",
+  "conflict",
+  "stale-revision",
+  "invalid-database",
+  "unsupported-schema",
+] as const;
+export type KnowledgeErrorCode = (typeof KNOWLEDGE_ERROR_CODES)[number];
+
+/** A refused knowledge operation, with a stable code and an actionable message. */
+export class KnowledgeError extends Error {
+  override name = "KnowledgeError";
+  readonly code: KnowledgeErrorCode;
+
+  constructor(code: KnowledgeErrorCode, message: string) {
+    super(message);
+    this.code = code;
+  }
+}
+
+export function knowledgePath(root: string = projectRoot()): string {
+  return join(root, KNOWLEDGE_DIRECTORY, KNOWLEDGE_FILE);
+}
+
+function configure(db: DatabaseSync): void {
+  // A committed write must be complete in knowledge.db itself: rollback journal, never WAL.
+  db.exec("PRAGMA journal_mode = DELETE; PRAGMA foreign_keys = ON; PRAGMA busy_timeout = 5000;");
+}
+
+function open(path: string, readOnly: boolean): DatabaseSync {
+  let db: DatabaseSync;
+  try {
+    db = new DatabaseSync(path, { readOnly });
+    configure(db);
+    db.prepare("SELECT count(*) FROM sqlite_master").get();
+  } catch (error) {
+    throw new KnowledgeError("invalid-database", `${KNOWLEDGE_DIRECTORY}/${KNOWLEDGE_FILE} is not a readable SQLite database: ${(error as Error).message}`);
+  }
+  return db;
+}
+
+/**
+ * Opens the project's knowledge database read-only, as it is: a read never
+ * migrates and never writes. Returns undefined when the database does not
+ * exist or has no schema yet: that reads as empty knowledge, and a read
+ * creates nothing. Refuses a schema version other than this build's.
+ */
+export function openForRead(root: string = projectRoot()): DatabaseSync | undefined {
+  const path = knowledgePath(root);
+  if (!existsSync(path)) return undefined;
+  const db = open(path, true);
+  try {
+    const version = schemaVersion(db);
+    if (version === 0) {
+      db.close();
+      return undefined;
+    }
+    checkVersion(version);
+  } catch (error) {
+    db.close();
+    throw error;
+  }
+  return db;
+}
+
+/**
+ * Opens the project's knowledge database for a write, creating
+ * .c64-re-tools/knowledge.db and its schema when needed. Refuses a schema
+ * version other than this build's.
+ */
+export function openForWrite(root: string = projectRoot()): DatabaseSync {
+  mkdirSync(join(root, KNOWLEDGE_DIRECTORY), { recursive: true });
+  const db = open(knowledgePath(root), false);
+  try {
+    ensureSchema(db);
+  } catch (error) {
+    db.close();
+    throw error;
+  }
+  return db;
+}
+
+/**
+ * Runs one write on the project's knowledge database and closes it. When the
+ * project has no knowledge.db yet, `work` first runs on an empty database in
+ * memory: a write that is refused there creates no .c64-re-tools/. `work`
+ * must change nothing outside the database it gets.
+ */
+export function withWrite<T>(work: (db: DatabaseSync) => T, root: string = projectRoot()): T {
+  if (!existsSync(knowledgePath(root))) {
+    const trial = new DatabaseSync(":memory:");
+    try {
+      configure(trial);
+      ensureSchema(trial);
+      work(trial);
+    } finally {
+      trial.close();
+    }
+  }
+  const db = openForWrite(root);
+  try {
+    return work(db);
+  } finally {
+    db.close();
+  }
+}
+
+/** Runs `work` in one immediate transaction: all of it commits, or none of it does. */
+export function transaction<T>(db: DatabaseSync, work: () => T): T {
+  db.exec("BEGIN IMMEDIATE");
+  try {
+    const result = work();
+    db.exec("COMMIT");
+    return result;
+  } catch (error) {
+    db.exec("ROLLBACK");
+    throw error;
+  }
+}

package/src/knowledge/expression.ts

@@ -0,0 +1,209 @@
+// Operand expressions (D65): the part of ACME's expression syntax that names
+// an operand by symbols and numbers. Knowledge checks an expression against
+// the image with it, and c64-source writes it with the names of its layout.
+//
+// Priorities are ACME's, from high to low: unary - and !, then * / %, + -,
+// << >> >>>, unary < and >, &, XOR, |. A unary < or > takes everything of a
+// higher priority after it, so <a+1 is the low byte of a+1.
+
+/** An expression that does not parse, or that names a symbol with no value. */
+export class ExpressionError extends Error {
+  override name = "ExpressionError";
+}
+
+/** The selectors of an operand expression: a byte of a symbol, its value, or free expression text. */
+export const OPERAND_SELECTS = ["lo", "hi", "value", "expr"] as const;
+export type OperandSelect = (typeof OPERAND_SELECTS)[number];
+
+/** An operand expression as knowledge stores it: a symbol with an offset, or text for expr. */
+export interface OperandExpression {
+  select: OperandSelect;
+  symbol?: string;
+  offset?: number;
+  expression?: string;
+}
+
+type Node =
+  | { kind: "number"; value: number }
+  | { kind: "name"; name: string }
+  | { kind: "unary"; operator: string; operand: Node }
+  | { kind: "binary"; operator: string; left: Node; right: Node };
+
+/** Binary operators by priority (higher binds tighter); unary < and > sit at LOW_HIGH. */
+const BINARY: Record<string, number> = { "*": 10, "/": 10, "%": 10, "+": 9, "-": 9, "<<": 8, ">>": 8, ">>>": 8, "&": 4, XOR: 3, "|": 2 };
+const LOW_HIGH = 7;
+const NAME = /^[A-Za-z_.][A-Za-z0-9_]*/;
+const MAX_TEXT = 200;
+
+interface Token {
+  text: string;
+  at: number;
+}
+
+/** The expression as tokens with their offsets; context decides % (binary literal or remainder). */
+function tokenize(text: string): Token[] {
+  const tokens: Token[] = [];
+  let at = 0;
+  let operandNext = true;
+  while (at < text.length) {
+    const rest = text.slice(at);
+    const space = /^\s+/.exec(rest);
+    if (space) {
+      at += space[0].length;
+      continue;
+    }
+    const number: RegExpExecArray | null = operandNext ? /^(\$[0-9A-Fa-f]+|%[01]+|[0-9]+)/.exec(rest) : null;
+    const match: RegExpExecArray | null = number ?? /^(>>>|<<|>>|XOR\b)/.exec(rest) ?? NAME.exec(rest) ?? /^[-+*/%&|!<>()]/.exec(rest);
+    if (!match) throw new ExpressionError(`"${text}" has an unknown character at position ${at + 1}: "${rest[0]}".`);
+    const token: string = match[0];
+    tokens.push({ text: token, at });
+    at += token.length;
+    // After an operand or a ), an operator comes next; after anything else, an operand.
+    operandNext = !(number !== null || (NAME.test(token) && token !== "XOR") || token === ")");
+  }
+  return tokens;
+}
+
+function parse(text: string): Node {
+  if (text.trim().length === 0) throw new ExpressionError("An expression is empty.");
+  if (text.length > MAX_TEXT) throw new ExpressionError(`An expression has at most ${MAX_TEXT} characters.`);
+  const tokens = tokenize(text);
+  let index = 0;
+  const peek = () => tokens[index]?.text;
+  const fail = (what: string): never => {
+    throw new ExpressionError(`"${text}" ${what}.`);
+  };
+
+  const operand = (): Node => {
+    const token = tokens[index++]?.text ?? fail("ends where an operand is missing");
+    if (token === "(") {
+      const inner = binary(0);
+      if (tokens[index++]?.text !== ")") fail("has a ( with no )");
+      return inner;
+    }
+    if (token === "-" || token === "!") return { kind: "unary", operator: token, operand: operand() };
+    if (token === "<" || token === ">") return { kind: "unary", operator: token, operand: binary(LOW_HIGH + 1) };
+    if (token.startsWith("$")) return { kind: "number", value: Number.parseInt(token.slice(1), 16) };
+    if (token.startsWith("%")) return { kind: "number", value: Number.parseInt(token.slice(1), 2) };
+    if (/^[0-9]/.test(token)) return { kind: "number", value: Number.parseInt(token, 10) };
+    if (NAME.test(token) && token !== "XOR") return { kind: "name", name: token };
+    return fail(`has "${token}" where an operand must be`);
+  };
+
+  const binary = (minimum: number): Node => {
+    let left = operand();
+    for (;;) {
+      const operator = peek();
+      const priority = operator === undefined ? undefined : BINARY[operator];
+      if (priority === undefined || priority < minimum) return left;
+      index++;
+      left = { kind: "binary", operator: operator!, left, right: binary(priority + 1) };
+    }
+  };
+
+  const tree = binary(0);
+  if (index < tokens.length) fail(`has "${tokens[index]!.text}" after the end of the expression`);
+  return tree;
+}
+
+function names(node: Node, into: string[]): string[] {
+  if (node.kind === "name" && !into.includes(node.name)) into.push(node.name);
+  if (node.kind === "unary") names(node.operand, into);
+  if (node.kind === "binary") {
+    names(node.left, into);
+    names(node.right, into);
+  }
+  return into;
+}
+
+function value(node: Node, resolve: (name: string) => number | undefined): number {
+  switch (node.kind) {
+    case "number":
+      return node.value;
+    case "name": {
+      const found = resolve(node.name);
+      if (found === undefined) throw new ExpressionError(`"${node.name}" is no symbol of the knowledge and no platform name.`);
+      return found;
+    }
+    case "unary": {
+      const inner = value(node.operand, resolve);
+      if (node.operator === "-") return -inner;
+      if (node.operator === "!") return ~inner;
+      return node.operator === "<" ? inner & 0xff : (inner >> 8) & 0xff;
+    }
+    case "binary": {
+      const left = value(node.left, resolve);
+      const right = value(node.right, resolve);
+      switch (node.operator) {
+        case "*":
+          return left * right;
+        case "/":
+        case "%":
+          if (right === 0) throw new ExpressionError("An expression divides by zero.");
+          return node.operator === "/" ? Math.trunc(left / right) : left % right;
+        case "+":
+          return left + right;
+        case "-":
+          return left - right;
+        case "<<":
+          return left << right;
+        case ">>":
+          return left >> right;
+        case ">>>":
+          return left >>> right;
+        case "&":
+          return left & right;
+        case "XOR":
+          return left ^ right;
+        default:
+          return left | right;
+      }
+    }
+  }
+}
+
+/** Throws ExpressionError when the text is no expression of this syntax. */
+export function checkExpression(text: string): void {
+  parse(text);
+}
+
+/** The value of the expression; `resolve` gives the value of a name, or undefined. */
+export function evaluate(text: string, resolve: (name: string) => number | undefined): number {
+  return value(parse(text), resolve);
+}
+
+/** The names the expression uses, each once, in their order. */
+export function identifiers(text: string): string[] {
+  return names(parse(text), []);
+}
+
+/**
+ * The text with each name replaced by `replace(name)` (a name it returns
+ * unchanged stays). Spaces and other tokens stay as written.
+ */
+export function replaceIdentifiers(text: string, replace: (name: string) => string): string {
+  parse(text);
+  let out = "";
+  let from = 0;
+  for (const token of tokenize(text)) {
+    if (!NAME.test(token.text) || token.text === "XOR") continue;
+    out += text.slice(from, token.at) + replace(token.text);
+    from = token.at + token.text.length;
+  }
+  return out + text.slice(from);
+}
+
+function offsetText(offset: number): string {
+  const size = Math.abs(offset);
+  return `${offset < 0 ? "-" : "+"}${size < 10 ? String(size) : `$${size.toString(16)}`}`;
+}
+
+/** ACME text of an operand expression, for example <irq_handler, >(sprite_bank+$1000) or bar_colours-1. */
+export function operandText(operand: OperandExpression): string {
+  if (operand.select === "expr") return operand.expression!;
+  const offset = operand.offset ?? 0;
+  const sum = offset === 0 ? operand.symbol! : `${operand.symbol!}${offsetText(offset)}`;
+  if (operand.select === "value") return sum;
+  const selector = operand.select === "lo" ? "<" : ">";
+  return offset === 0 ? `${selector}${sum}` : `${selector}(${sum})`;
+}