@fugloy/emu 0.0.0-stage → 0.2.0

package/src/machine/io.js

@@ -0,0 +1,290 @@
+/**
+ * TRS-80 Model III I/O System
+ *
+ * Non-disk machine port map:
+ *   0xE0-0xE3  read: interrupt latch, active-low (pending bit reads 0)
+ *              write: interrupt mask (bit set = source enabled)
+ *   0xEC-0xEF  read: acknowledge/clear the RTC interrupt
+ *              write: mode register (bit 1 = cassette motor,
+ *                     bit 2 = 32-column mode, bit 3 = alt charset)
+ *   0xF0-0xF3  floppy controller — absent; reads float to 0xFF
+ *   0xF4       drive select — absent
+ *   0xF8-0xFB  line printer (read: status, write: data byte)
+ *   0xFF       cassette port (write bits 0-1 = output level,
+ *              read bit 7 = tape input)
+ *
+ * The RTC heartbeat interrupt fires at 30 Hz; its latch bit is RTC_IRQ_BIT.
+ * The keyboard is memory-mapped at 0x3800-0x3BFF (see MemorySystem), not
+ * an I/O port.
+ */
+
+import { CassetteSystem } from "../devices/cassette.js";
+import { FDC1793 } from "../devices/fdc-wd1793.js";
+import { Printer } from "../devices/printer.js";
+
+export const RTC_IRQ_BIT = 0x04;
+// Cassette-edge interrupt sources (from the ROM's ISR at 0x35C2: E0
+// bit 0 dispatches to a handler expecting one input level, bit 1 the
+// other; each reads the level back from port 0xFF bit 0). The 1500-baud
+// reader masks in rises only (0xE0 write = 0x01) and counts full
+// cycles between interrupts.
+export const CASSETTE_RISE_IRQ_BIT = 0x01;
+export const CASSETTE_FALL_IRQ_BIT = 0x02;
+
+// NMI mask/status bits (port 0xE4)
+export const NMI_INTRQ_BIT = 0x80;
+
+// Mode register (port 0xEC write) bits
+export const MODE_32COL_BIT = 0x04; // 32-character display mode
+
+export class IOSystem {
+  constructor() {
+    this.cassette = new CassetteSystem();
+    this.fdc = new FDC1793();
+    this.printer = new Printer();
+    this.keyboardBuffer = []; // legacy internal buffer (not a Model III port)
+    this.portHandlers = new Map();
+
+    // Interrupt latch (pending sources) and mask (enabled sources)
+    this.intLatch = 0;
+    this.intMask = 0;
+
+    // NMI mask (port 0xE4 write): bit 7 = FDC INTRQ triggers NMI
+    this.nmiMask = 0;
+
+    // Mode register (port 0xEC write)
+    this.modeRegister = 0;
+
+    // Fired when a mode-register write changes the value (the display
+    // reads bit 2, so the renderer must repaint even though video RAM
+    // itself didn't change). Wired by TRS80System.
+    this.onModeWrite = null;
+
+    // Cassette output level (port 0xFF write, bits 0-1)
+    this.cassetteOut = 0;
+
+    // Cassette-out transitions for the sound driver: {t, level} stamped
+    // in CPU T-states. getCycles is wired by TRS80System; the driver
+    // drains the log every frame. Capped so an undrained log (sound off,
+    // headless run) cannot grow without bound.
+    this.getCycles = null;
+    this.soundLog = [];
+    this.SOUND_LOG_LIMIT = 100000;
+    // Raw port 0xFF write sink (cycles, value): the Machine's sound ring.
+    this.onSoundWrite = null;
+    // Called when the timeline restarts (state restore): the Machine clears its sound ring.
+    this.onSoundReset = null;
+
+    this.initializeModelIIIPorts();
+  }
+
+  initializeModelIIIPorts() {
+    // 0xE0-0xE3: interrupt latch (read, active-low) / mask (write)
+    for (let port = 0xe0; port <= 0xe3; port++) {
+      this.portHandlers.set(port, {
+        read: () => ~this.intLatch & 0xff,
+        write: (value) => {
+          this.intMask = value & 0xff;
+        },
+      });
+    }
+
+    // 0xEC-0xEF: RTC acknowledge (read) / mode register (write)
+    for (let port = 0xec; port <= 0xef; port++) {
+      this.portHandlers.set(port, {
+        read: () => {
+          this.intLatch &= ~RTC_IRQ_BIT;
+          return 0xff;
+        },
+        write: (value) => {
+          const changed = this.modeRegister !== (value & 0xff);
+          this.modeRegister = value & 0xff;
+          // Mode register bit 1 drives the cassette motor relay;
+          // CassetteSystem.control expects the motor state in bit 0.
+          this.cassette.control(
+            (value >> 1) & 0x01,
+            this.getCycles ? this.getCycles() : 0
+          );
+          if (changed && this.onModeWrite) {
+            this.onModeWrite(this.modeRegister);
+          }
+        },
+      });
+    }
+
+    // 0xE4-0xE7: disk NMI mask (write) / status (read, active-low).
+    // With no controller "present" (no disk mounted) the port floats.
+    for (let port = 0xe4; port <= 0xe7; port++) {
+      this.portHandlers.set(port, {
+        read: () => {
+          if (!this.fdc.anyDiskMounted()) return 0xff;
+          let value = 0xff;
+          if (this.fdc.intrq) value &= ~NMI_INTRQ_BIT;
+          return value;
+        },
+        write: (value) => {
+          this.nmiMask = value & 0xff;
+        },
+      });
+    }
+
+    // 0xF0-0xF3: WD1793 FDC. The controller presents as absent (floating
+    // bus) until a disk is mounted — that float is what sends the boot
+    // ROM to cassette BASIC on a driveless machine.
+    const fdcPresent = () => this.fdc.anyDiskMounted();
+    this.portHandlers.set(0xf0, {
+      read: () => (fdcPresent() ? this.fdc.readStatus() : 0xff),
+      write: (v) => {
+        if (fdcPresent()) this.fdc.writeCommand(v);
+      },
+    });
+    this.portHandlers.set(0xf1, {
+      read: () => (fdcPresent() ? this.fdc.readTrackReg() : 0xff),
+      write: (v) => {
+        if (fdcPresent()) this.fdc.writeTrackReg(v);
+      },
+    });
+    this.portHandlers.set(0xf2, {
+      read: () => (fdcPresent() ? this.fdc.readSectorReg() : 0xff),
+      write: (v) => {
+        if (fdcPresent()) this.fdc.writeSectorReg(v);
+      },
+    });
+    this.portHandlers.set(0xf3, {
+      read: () => (fdcPresent() ? this.fdc.readData() : 0xff),
+      write: (v) => {
+        if (fdcPresent()) this.fdc.writeData(v);
+      },
+    });
+
+    // 0xF4: drive select / side / density latch
+    this.portHandlers.set(0xf4, {
+      read: () => 0xff,
+      write: (v) => {
+        if (fdcPresent()) this.fdc.selectDrive(v);
+      },
+    });
+
+    // 0xF8-0xFB: line printer. Status reads ready; data writes land on
+    // the printout. Note io.reset() leaves the printout alone — paper
+    // already printed survives a reboot on the real machine too.
+    for (let port = 0xf8; port <= 0xfb; port++) {
+      this.portHandlers.set(port, {
+        read: () => this.printer.status(),
+        write: (v) => this.printer.write(v),
+      });
+    }
+
+    // 0xFF: cassette data port. Reads return the input latch in bit 7
+    // (set by tape transitions while the motor runs); ANY write clears
+    // the latch — that's the Model III's latch circuit, and it's how
+    // the ROM's read routines re-arm between pulses. Output level
+    // changes are the machine's only sound source, so they're logged
+    // for the audio driver, and they double as the recording the deck
+    // can decode back into a .cas.
+    this.portHandlers.set(0xff, {
+      read: () => {
+        const cycles = this.getCycles ? this.getCycles() : 0;
+        // Two input bits, straight from the ROM's own readers:
+        //   bit 0 — the tape signal's live LEVEL (the 1500-baud ISR
+        //           does IN A,(0xFF) / AND 0x01 / CP E per edge);
+        //   bit 7 — a rising-edge PULSE LATCH (the 500-baud reader
+        //           polls it with RLA and resets it by OUT (0xFF),A).
+        // Reading also acks the edge interrupt sources: the ISR reads
+        // 0xE0 then 0xFF and nothing else.
+        this.intLatch &= ~(CASSETTE_RISE_IRQ_BIT | CASSETTE_FALL_IRQ_BIT);
+        const level = this.cassette.tapeLevel(cycles);
+        return (this.cassette.pulseLatch ? 0x80 : 0x00) | (level ? 0x01 : 0x00);
+      },
+      write: (value) => {
+        const cycles = this.getCycles ? this.getCycles() : 0;
+        const level = value & 0x03;
+        if (this.onSoundWrite) this.onSoundWrite(cycles, value);
+        if (level !== this.cassetteOut) {
+          this.cassetteOut = level;
+          if (this.getCycles && this.soundLog.length < this.SOUND_LOG_LIMIT) {
+            this.soundLog.push({ t: cycles, level });
+          }
+          this.cassette.recordTransition(cycles, level);
+        }
+        this.cassette.clearPulseLatch(cycles);
+      },
+    });
+  }
+
+  readPort(port) {
+    port &= 0xff;
+    const handler = this.portHandlers.get(port);
+    return handler?.read ? handler.read() : 0xff;
+  }
+
+  writePort(port, value) {
+    port &= 0xff;
+    value &= 0xff;
+    const handler = this.portHandlers.get(port);
+    if (handler?.write) {
+      handler.write(value);
+    }
+  }
+
+  /** Raise the 30 Hz real-time clock interrupt line. */
+  raiseRTC() {
+    this.intLatch |= RTC_IRQ_BIT;
+  }
+
+  /** True when an enabled interrupt source is pending. */
+  pendingInterrupt() {
+    // The cassette edge is a live source: advance the pulse deck to
+    // "now" so an edge that just played raises the latch bit without
+    // waiting for a port access. Guarded, so machines without a tape
+    // playing pay one property check.
+    if (this.cassette.pulseTape && this.cassette.motorOn && this.getCycles) {
+      const edges = this.cassette.consumeEdges(this.getCycles());
+      if (edges.rise) this.intLatch |= CASSETTE_RISE_IRQ_BIT;
+      if (edges.fall) this.intLatch |= CASSETTE_FALL_IRQ_BIT;
+    }
+    return (this.intLatch & this.intMask) !== 0;
+  }
+
+  /** True when the FDC's INTRQ should raise an NMI. */
+  nmiPending() {
+    return this.fdc.intrq && (this.nmiMask & NMI_INTRQ_BIT) !== 0;
+  }
+
+  /** Hand the accumulated cassette-out transitions to the sound driver. */
+  drainSound() {
+    if (this.soundLog.length === 0) return this.soundLog;
+    const log = this.soundLog;
+    this.soundLog = [];
+    return log;
+  }
+
+  /** Clear interrupt state (system reset). Mounted disks stay mounted. */
+  reset() {
+    this.intLatch = 0;
+    this.intMask = 0;
+    this.nmiMask = 0;
+    this.modeRegister = 0;
+    this.cassetteOut = 0;
+    this.soundLog = [];
+    this.fdc.intrq = false;
+    this.fdc.pending = null;
+    this.fdc.buffer = null;
+    this.fdc.status = 0;
+    this.fdc.commandType = 1;
+  }
+
+  readKeyboard() {
+    return this.keyboardBuffer.length > 0 ? this.keyboardBuffer.shift() : 0x00;
+  }
+
+  addKey(keyCode) {
+    if (this.keyboardBuffer.length < 256) {
+      this.keyboardBuffer.push(keyCode & 0xff);
+    }
+  }
+
+  clearKeyboardBuffer() {
+    this.keyboardBuffer = [];
+  }
+}

package/src/machine/machine.js

@@ -0,0 +1,295 @@
+/**
+ * The spec §3 `Machine`: the public face of the emulator, over a TRS80System. Phase 2 builds
+ * the Model III with 48K; execution, state access, and ROM identification live here, and the
+ * device, loader, and debug surfaces arrive in later tasks.
+ */
+import { TRS80System } from './trs80-system.js';
+import { ROM_HASHES } from './rom-hashes.js';
+import { sha256Hex } from './sha256.js';
+import { Video } from '../devices/video.js';
+import { Sound } from '../devices/sound.js';
+import { loadBas } from '../loaders/bas.js';
+import { cassetteDeck, loadCas, loadCmd } from '../loaders/load.js';
+import { Debugger } from '../debug/debugger.js';
+import { KeyQueue, romKeyReturn } from '../devices/key-queue.js';
+
+/**
+ * @typedef {{ a: number, f: number, b: number, c: number, d: number, e: number, h: number, l: number,
+ *   a2: number, f2: number, b2: number, c2: number, d2: number, e2: number, h2: number, l2: number,
+ *   ix: number, iy: number, sp: number, pc: number, i: number, r: number,
+ *   iff1: boolean, iff2: boolean, im: number }} Regs
+ * @typedef {{ s: boolean, z: boolean, h: boolean, pv: boolean, n: boolean, c: boolean }} Flags
+ * @typedef {'halt' | ((m: Machine) => boolean)} Until
+ */
+
+export class Machine {
+  /** @type {TRS80System} The wrapped system: an escape hatch to the devices, outside the stable API. */
+  system;
+  /** @type {{ bytes: number, sha256: string, recognized: string | null }} */
+  rom;
+  /** @type {{ readonly regs: Regs, readonly flags: Flags }} */
+  cpu;
+  /** @type {{ read(addr: number, len: number): Uint8Array, write(addr: number, bytes: ArrayLike<number>): void, readonly ram: Uint8Array }} */
+  mem;
+  /** @type {{ in(port: number): number, out(port: number, value: number): void }} */
+  io;
+  /** @type {Video} The text readout of video RAM. */
+  video;
+  /** @type {Sound} Every port $FF write, raw and stamped in T-states. */
+  sound;
+  /** @type {KeyQueue} Key presses now, cycle-timed typing through the matrix, and the ROM keyboard-scan hook's feed. */
+  keyboard;
+  /**
+   * @type {{ bas(bytes: Uint8Array): ReturnType<typeof loadBas>, cmd(bytes: Uint8Array): ReturnType<typeof loadCmd>,
+   *   cas(bytes: Uint8Array, opts?: { baud?: 500 | 1500, via?: 'rom' | 'fast' }): ReturnType<typeof loadCas> }}
+   * Program loaders; each returns a manifest of where the bytes land and why.
+   */
+  load;
+  /** @type {ReturnType<typeof cassetteDeck>} The cassette deck: insert a .CAS at a baud, rewind, read the motor relay. */
+  cassette;
+  /** @type {Debugger} Breakpoints, watchpoints, hooks, coverage, the instruction trace, snapshots, labels, and the label file (spec §7, §8). */
+  debug;
+
+  /** True inside `run`, false inside `step`, which ignores breakpoints. */
+  #checkBreaks = false;
+  /** True until a run's first boundary has passed; that boundary is never checked, so a run resumes past a break. */
+  #firstBoundary = false;
+  /** @type {number | null} The PC where the last run stopped for a breakpoint: the next run's first boundary skips the check there only. */
+  #resumePc = null;
+  /** True while `step` or `run` executes, so a callback cannot re-enter either. */
+  #busy = false;
+  /** Set by the hook when a breakpoint held the boundary, read by `run`. */
+  #stopped = false;
+
+  /**
+   * @param {{ model?: 3, ram?: 48, roms: { level2: Uint8Array }, log?: (level: string, text: string) => void }} opts
+   */
+  constructor({ model = 3, ram = 48, roms, log } = /** @type {any} */ ({})) {
+    if (model !== 3 || ram !== 48) {
+      throw new Error(`phase 2 builds the Model III with 48K; got model ${model} with ${ram}K (the Model I, the Model 4, and other RAM sizes come in later phases)`);
+    }
+    const level2 = roms?.level2;
+    if (!ArrayBuffer.isView(level2) || level2.BYTES_PER_ELEMENT !== 1) throw new Error('Machine needs roms.level2, the ROM image as a Uint8Array');
+
+    this.system = new TRS80System({ romData: level2, log });
+    const sha256 = sha256Hex(level2);
+    this.rom = { bytes: level2.length, sha256, recognized: ROM_HASHES[sha256] ?? null };
+
+    const sys = this.system;
+    const cpu = sys.cpu;
+    this.cpu = {
+      get regs() {
+        const r = cpu.registers;
+        return {
+          a: r.A, f: r.F, b: r.B, c: r.C, d: r.D, e: r.E, h: r.H, l: r.L,
+          a2: r.A_, f2: r.F_, b2: r.B_, c2: r.C_, d2: r.D_, e2: r.E_, h2: r.H_, l2: r.L_,
+          ix: cpu.IX, iy: cpu.IY, sp: r.SP, pc: r.PC, i: r.I, r: r.R,
+          iff1: cpu.IFF1, iff2: cpu.IFF2, im: cpu.interruptMode,
+        };
+      },
+      get flags() {
+        const f = cpu.registers.F;
+        return { s: (f & 0x80) !== 0, z: (f & 0x40) !== 0, h: (f & 0x10) !== 0, pv: (f & 0x04) !== 0, n: (f & 0x02) !== 0, c: (f & 0x01) !== 0 };
+      },
+    };
+    this.mem = {
+      read(addr, len) {
+        const out = new Uint8Array(len);
+        for (let k = 0; k < len; k++) out[k] = sys.memory.readByte((addr + k) & 0xffff);
+        return out;
+      },
+      write(addr, bytes) {
+        for (let k = 0; k < bytes.length; k++) sys.memory.writeByte((addr + k) & 0xffff, bytes[k]);
+      },
+      get ram() {
+        return sys.memory.ram;
+      },
+    };
+    this.video = new Video(sys);
+    this.sound = new Sound();
+    sys.io.onSoundWrite = (cycle, value) => this.sound.record(cycle, value);
+    sys.io.onSoundReset = () => this.sound.clear();
+    this.keyboard = new KeyQueue(sys.keyboard, () => sys.cpu.cycles);
+    this.debug = new Debugger(this);
+    // Each load records its manifest and the bytes' hash for the label file (the last one wins).
+    const record = (/** @type {any} */ manifest, /** @type {Uint8Array} */ bytes) => {
+      this.debug.recordLoad(manifest, bytes);
+      return manifest;
+    };
+    this.load = {
+      bas: (bytes) => record(loadBas(this, bytes), bytes),
+      cmd: (bytes) => record(loadCmd(this, bytes), bytes),
+      cas: (bytes, opts) => record(loadCas(this, bytes, opts), bytes),
+    };
+    this.cassette = cassetteDeck(this);
+    this.io = {
+      in: (port) => sys.io.readPort(port),
+      out: (port, value) => sys.io.writePort(port, value),
+    };
+  }
+
+  /** Total T-states since the last reset. */
+  get cycles() {
+    return this.system.cpu.cycles;
+  }
+
+  /** Hardware reset: CPU to $0000, cycle count to 0, RAM kept (TRS80System.reset). */
+  reset() {
+    this.system.reset();
+    this.#resumePc = null;
+    this.sound.clear();
+    this.keyboard.clear();
+  }
+
+  /**
+   * Internal: a restore starts a fresh timeline, so the PC where the last run stopped for a
+   * breakpoint is forgotten, and the key queue and sound ring (whose cycle stamps belong to the
+   * old timeline) are cleared.
+   */
+  newTimeline() {
+    this.#resumePc = null;
+    this.sound.clear();
+    this.keyboard.clear();
+  }
+
+  /**
+   * The internal per-instruction hook, run at every instruction boundary (after interrupt
+   * delivery, before the instruction executes) by both `step` and `run`: deliver the matrix key
+   * events now due, then, with a fed character waiting and the PC at the ROM's keyboard scan
+   * ($002B) or wait-for-key ($0049), return from that routine with the character as the ROM
+   * would (spec §6, "Keyboard-scan hook"). That return stands in for the boundary's instruction,
+   * as one RET (10 T-states); a halted CPU idles instead, as it does for any instruction, so the next boundary is at the caller's return address.
+   * Between draining and the keyboard hook, a breakpoint hit (only while `debug.active`, and
+   * never in `step`) stops the boundary: nothing executes. Last, with memory accesses watched or
+   * hooked, the debugger is told an instruction starts at PC, so its fetches are not taken for
+   * reads and its accesses carry its PC; the keyboard hook's stand-in and a halted CPU's idle
+   * start none (the idle reads nothing; the stand-in's stack reads carry the CPU's PC).
+   * @returns {boolean | 'stop'} true when the hook stood in for the instruction, 'stop' when a breakpoint holds the boundary
+   */
+  #beforeInstruction() {
+    const cpu = this.system.cpu;
+    const kb = this.keyboard;
+    if (cpu.cycles >= kb.nextAt) kb.drain(cpu.cycles);
+    // A run's first boundary skips the check only at the PC its predecessor stopped at; a halted
+    // CPU idles at HALT+1 on every boundary, so it is never checked.
+    const pc = cpu.registers.PC;
+    const first = this.#firstBoundary && pc === this.#resumePc;
+    this.#firstBoundary = false;
+    this.#resumePc = null;
+    if (this.debug.active && this.#checkBreaks && !cpu.halted && this.debug.beforeInstruction(pc, first)) {
+      this.#stopped = true;
+      this.#resumePc = pc;
+      return 'stop';
+    }
+    if (cpu.halted) return false;
+    if (kb.hasFeed && (pc === 0x002b || pc === 0x0049)) {
+      const debug = this.debug;
+      if (debug.tracksAccess) {
+        debug.standIn(true);
+        try {
+          romKeyReturn(cpu, pc, kb.takeFeed());
+        } finally {
+          debug.standIn(false);
+        }
+      } else romKeyReturn(cpu, pc, kb.takeFeed());
+      return true;
+    }
+    if (this.debug.startsInstruction) this.debug.startInstruction(pc);
+    return false;
+  }
+
+  /** Bound once, so the hot loop passes the same function every instruction. */
+  #hook = () => this.#beforeInstruction();
+
+  /**
+   * Execute `n` whole instructions (an interrupt response counts with the instruction after it).
+   * @param {number} [n]
+   * @returns {{ cycles: number, halted: boolean }}
+   */
+  step(n = 1) {
+    const sys = this.system;
+    const start = sys.cpu.cycles;
+    const debug = this.debug;
+    if (this.#busy) throw new Error('step: the machine is already running; step and run cannot be called from a when or until callback');
+    this.#busy = true;
+    this.#checkBreaks = false;
+    try {
+      for (let k = 0; k < n; k++) {
+        sys.stepInstruction(this.#hook);
+        if (debug.active) debug.afterInstruction();
+      }
+    } catch (e) {
+      // A hook or callback that threw leaves no instruction open, no edge recorded for it, and no stop pending for the next call.
+      if (debug.active) {
+        debug.endInstruction();
+        debug.afterInstruction();
+      }
+      throw e;
+    } finally {
+      this.#busy = false;
+    }
+    return { cycles: sys.cpu.cycles - start, halted: sys.cpu.halted };
+  }
+
+  /**
+   * Run until a T-state budget is spent or a condition holds, both checked after each
+   * instruction; at least one instruction always runs. The condition wins a tie with the budget.
+   * A breakpoint stops the run before its instruction executes, and the next run starts past it
+   * (only at that PC, so hit counts do not depend on how a session is split into runs). A
+   * breakpoint at a run's first boundary that it did not just stop at stops with `cycles: 0`
+   * (an interrupt response at that boundary counts). Breakpoints are not checked while halted.
+   * A watch with `stop` returns after the instruction whose access hit it; after an instruction
+   * the order is watch stop, then `until`, then the budget. `step` logs watch hits but never stops.
+   * A stop watch hit by an interrupt response at a boundary a breakpoint then holds stays pending:
+   * the next run returns `'watch'` after the held instruction (a `step` in between drops it).
+   * @param {{ cycles?: number, until?: Until }} opts
+   * @returns {{ reason: 'cycles' | 'halt' | 'predicate', cycles: number } | { reason: 'break' | 'watch', id: number, cycles: number }}
+   */
+  run({ cycles, until } = {}) {
+    if (cycles === undefined && until === undefined) throw new Error('run needs cycles, until, or both; with neither it would never stop');
+    if (cycles !== undefined && !(Number.isFinite(cycles) && cycles >= 0)) throw new Error(`run: cycles must be a finite number of T-states, 0 or more, not ${String(cycles)}`);
+    if (until !== undefined && until !== 'halt' && typeof until !== 'function') throw new Error(`run: until must be 'halt' or a function, not ${String(until)}`);
+    const sys = this.system;
+    const cpu = sys.cpu;
+    const start = cpu.cycles;
+    const target = cycles === undefined ? Infinity : start + cycles;
+    const debug = this.debug;
+    if (this.#busy) throw new Error('run: the machine is already running; step and run cannot be called from a when or until callback');
+    this.#busy = true;
+    this.#checkBreaks = true;
+    this.#firstBoundary = true;
+    this.#stopped = false;
+    try {
+      for (;;) {
+        sys.stepInstruction(this.#hook);
+        if (this.#stopped) {
+          this.#stopped = false;
+          // A watch stop from this boundary's interrupt response stays pending: the next run returns it after the held instruction.
+          debug.endInstruction();
+          const id = /** @type {number} */ (debug.stopId);
+          debug.stopId = null;
+          return { reason: 'break', id, cycles: cpu.cycles - start };
+        }
+        if (debug.active) {
+          const w = debug.afterInstruction();
+          if (w !== null) return { reason: 'watch', id: w, cycles: cpu.cycles - start };
+        }
+        if (until === 'halt') {
+          if (cpu.halted) return { reason: 'halt', cycles: cpu.cycles - start };
+        } else if (until !== undefined && until(this)) {
+          return { reason: 'predicate', cycles: cpu.cycles - start };
+        }
+        if (cpu.cycles >= target) return { reason: 'cycles', cycles: cpu.cycles - start };
+      }
+    } catch (e) {
+      // A hook or callback that threw leaves no instruction open, no edge recorded for it, and no stop pending for the next call.
+      if (debug.active) {
+        debug.endInstruction();
+        debug.afterInstruction();
+      }
+      throw e;
+    } finally {
+      this.#busy = false;
+    }
+  }
+}