@fugloy/emu 0.2.0 → 0.3.0

package/README.md

@@ -1,18 +1,23 @@
 # @fugloy/emu
 
-Headless, deterministic TRS-80 emulator core (Model III; Model I and 4 to come) in plain
+Headless, deterministic TRS-80 emulator core (the Model III and, since emu phase 6, the Model I) in plain
 JavaScript, for Node and the browser alike. Emu phase 0 brought in the core of
 [cschweda/trs80-emulator](https://github.com/cschweda/trs80-emulator) (v1.6.0):
 the Z80 CPU (`src/cpu/`), the Model III memory map, I/O ports, and system
 (`src/machine/`), the keyboard matrix, cassette, WD1793 disk controller, disk
 images, and printer (`src/devices/`), the `.CAS` and `.CMD` formats
-(`src/loaders/`), and save states (`src/debug/`). Model III only for now.
-Phases 0–4 of the spec's eight are done: the Z80 core passes ZEXDOC and
+(`src/loaders/`), and save states (`src/debug/`). Emu phase 6 added the
+Model I with its Expansion Interface (unreleased; the Model 4 is split off into
+a plan of its own: a Model 4 ROM is now local, from the cpmarchives TRS32 ROM
+set, whose `MODEL4P.ROM` is an emulator's stand-in rather than Tandy's 4P ROM;
+the Model 4 phase is planned next, and its native mode still needs an LS-DOS 6
+or TRSDOS 6 boot disk).
+Phases 0–7 of the spec's eight are done (6 for the Model I, 7 for the Model III): the Z80 core passes ZEXDOC and
 ZEXALL, the `Machine` below runs real programs, `m.debug` writes the label
 and coverage file, and phase 4, the MCP server
 [`@fugloy/mcp`](https://github.com/cschweda/fugloy/blob/main/packages/mcp/README.md),
-drives it for an AI assistant. Version 0.2.0, its first npm release pending
-(once published, `npm i @fugloy/emu`; until then, use it from a clone; Node 22 or later, or any browser bundler: it has no
+drives it for an AI assistant. Version 0.3.0 (first released 2026-10-18; 0.2.0 is the version on npm until it is published)
+(`npm i @fugloy/emu`; or use it from a clone for development; Node 22 or later, or any browser bundler: it has no
 dependencies).
 
 The renderer, the WebAudio driver, the turbo throttle, the web UI, and every
@@ -30,7 +35,7 @@ not implement.
 ## Using the machine
 
 ```js
-import { readFileSync } from 'node:fs'
+import { readFileSync, writeFileSync } from 'node:fs'
 import { Machine, CPU_CLOCK_HZ } from '@fugloy/emu'
 
 const m = new Machine({ roms: { level2: readFileSync('model3.rom') } })   // Model III, 48K; you supply the ROM
@@ -48,8 +53,68 @@ m.run({ cycles: 5 * second })
 console.log(m.video.text().join('\n'))     // the screen, 16 lines
 ```
 
+A disk image (JV1, JV3, or DMK, detected from its content) goes in a drive
+with `m.fdc.mount(drive, bytes)`, or through `m.load.dsk(bytes)`, which mounts
+it in drive 0 and resets so the ROM boots from it:
+
+```js
+m.load.dsk(readFileSync('game.dmk'))       // → { format: 'dsk', container: 'dmk', drive: 0, boot: true, blocks: [] }
+m.fdc.drives                               // [{ drive: 0, container: 'dmk', tracks, sides, sectorsPerTrack, writeProtected }, null, null, null]
+writeFileSync('saved.dmk', m.fdc.export(0)) // the disk as DMK bytes, with what the program wrote to it
+```
+
+Writes stay in memory; `m.fdc.export(drive)` returns the disk as a DMK file,
+whatever container it was mounted from (read JV1, JV3, and DMK; write DMK). A snapshot carries each disk's bytes and container, so a
+disk the session formatted restores as it was. With a disk loaded through
+`m.load.dsk` the label file lists no load blocks and `m.debug.labelFile()`
+needs a `name`.
+
+The WD1793 behind the drives follows the Western Digital FD179X data sheet in
+T-states (spec §5): heads step at the programmed rate, sectors come round at
+300 rpm, and bytes arrive one byte time apart, so a disk loads as slowly as it
+does on a real drive, and a program that misses a byte sees Lost Data.
+Give a disk session room: the ROM reaches the boot sector about a quarter
+second after the reset, a loader reading a game takes seconds (Scarfman's
+title is up about 8 s after the reset), and a sector that is not there costs
+about a second. Check the screen between slices of `run` rather than in an
+`until` callback, which reads it after every instruction.
+
 `step`, `run`, the registers, memory, the keyboard (matrix typing and a ROM
-keyboard hook), sound events, and the three loaders are described in spec §3.
+keyboard hook), sound events, the loaders, and the disk drives are described
+in spec §3.
+
+### The Model I
+
+`model: 1` builds a Model I (unreleased, emu phase 6): the 12K Level II ROM
+(1.2 and 1.3 are recognised; a Model III ROM given for it is refused naming its
+model), 4, 16, 32, or 48K of RAM (`ram`, default 48), and the Expansion
+Interface (`expansion`, default `true`) with its 40 Hz clock in the latch at
+`$37E0`, its WD1771 disk controller at `$37EC`–`$37EF`, and its printer.
+`expansion: false` is a bare keyboard unit: no clock, no disk, `$37E0`–`$37EF`
+read `$FF`. The stock video RAM has no bit 6, so lowercase reads back and shows
+as punctuation and a program's mixed-case title in capitals; `lowercase: true`
+fits the lowercase modification. Its clock is 1,774,080 Hz, `clockHz(1)`
+(`CPU_CLOCK_HZ` stays the Model III's):
+
+```js
+import { Machine } from '@fugloy/emu'
+
+const m1 = new Machine({ model: 1, roms: { level2: readFileSync('level2-model1.rom') } })
+const sec = m1.clockHz                                     // clockHz(1): 1,774,080 T-states an emulated second
+m1.run({ until: shows('SIZE?'), cycles: sec })             // MEMORY SIZE? (MEM SIZE? in Level II 1.3); no Cass?
+m1.keyboard.type('\n')
+m1.run({ until: shows('READY'), cycles: 5 * sec })
+m1.load.cmd(readFileSync('elimin8a.cmd'))                  // Eliminator's Model I-only build
+m1.run({ cycles: 2 * sec })                                // "BY: WAYNE WESTMORELAND & TERRY GILMAN"
+m1.load.dsk(readFileSync('rrgarddb.dmk'))                  // or a disk: the ROM reads track 0, sector 0 to $4200
+```
+
+Type at 10 characters a second on the Model I (`m1.keyboard.type(text, {
+cps: 10 })`): the Level II keyboard routine drops every other key at the
+default 20. T-states, `m.sound` stamps included, are the model's own
+(`m.clockHz`). A label file records its model, and `mergeLabelFiles` refuses
+a Model I file with a Model III one. Cassettes play at 500 baud only. Real programs that run on it, and
+what is still unverified against the Model I manual, are in spec §5.
 
 ## Debugging
 
@@ -95,13 +160,64 @@ process, on the laptop that built phase 3):
 | Debugging off | about 42× real time (41.5–43.3× over three runs; phase 2 measured about 43×) |
 | Coverage and a 10,000-deep trace | about 30× real time (29.5–30.7×) |
 
-`test/integration/benchmark.test.js` asserts at least 20× for both.
+`test/integration/benchmark.test.js` asserts at least 20× for both, but only
+when asked: `FUGLOY_BENCH=1 pnpm exec vitest run
+packages/emu/test/integration/benchmark.test.js`, by itself on a quiet machine
+(`./publish.sh check` runs it that way after the suite). In the full parallel
+suite, beside the other ROM tests, it measured 12–15× against about 40× alone,
+so it is skipped there. On the laptop that built phase 6 it measured 40× (off)
+and 29× (debug); Sea Dragon on the Model I runs at about 48×.
 
 - Spec: [`docs/fugloy-emu-spec.md`](https://github.com/cschweda/fugloy/blob/main/docs/fugloy-emu-spec.md) (phases 0–7 in §11)
 - Label and coverage file shared with `mcp` and `disasm`: [`docs/label-format.md`](https://github.com/cschweda/fugloy/blob/main/docs/label-format.md)
 - ROM images are never bundled or committed; `roms/` here is gitignored and
   paths are supplied by the caller.
 
+## Differential testing
+
+Emu phase 7 runs a program here and in [trsjs](https://trsjs.48k.ca/)
+(Peter Phillips's JavaScript conversion of George Phillips's trs80gp) in
+lockstep, and compares the two after every instruction: PC, every register
+(F bit by bit, R as 7 bits), IFF1/2, IM, the T-states, and every memory
+write, with video RAM at checkpoints and at the end. Keys go into both
+keyboard matrices at the same T-state. trsjs has no license, so it is never
+committed or bundled: `pnpm trsjs:install` fetches it into the gitignored
+`tools/trsjs/`, pinned by SHA-256, and the tests that need it are opt-in.
+
+```sh
+pnpm trsjs:install
+FUGLOY_TRSJS=1 pnpm vitest run packages/emu/test/diff                     # about a minute: the harness tests and six game sessions
+FUGLOY_TRSJS=1 FUGLOY_TRSJS_SWEEP=1 pnpm vitest run packages/emu/test/diff --silent=false # also every other .CMD in examples/ and fixtures/real/, logging each one's class counts and the sum
+pnpm diff examples/sea-dragon/seadrg01.cmd --instructions 10000000        # one program, with a report
+```
+
+`pnpm diff <program> [--keys <script.json>] [--instructions N] [--from-cycle C] [--strict | --strict-all]`
+boots the Model III ROM from `fugloy.mcp.json`, loads the `.CMD` or `.BAS`,
+and prints the count of each known difference and the first divergence, if
+any, with ten instructions disassembled on each side. Exit status 0 means no
+divergence, 1 a divergence, 2 a usage or setup error (an unexpected error,
+such as the ROM not reaching READY or trsjs throwing, counts as one).
+
+Where the two differ, trsjs is the inaccurate side, and the harness says so
+explicitly. Some differences it corrects in the reference (a write to ROM or
+the keyboard, a byte stored wider than 8 bits, PC running past `$FFFF`, a
+repeating CPDR's T-states, a DD or FD prefix trsjs skips); the rest are known classes in
+`test/diff/known.js`, each with the evidence for it, counted rather than
+reported (flag bits 3 and 5; BIT's S and P/V; R on an interrupt and on
+DDCB/FDCB; the HALT return address; carry after CPI/CPD/CPIR/CPDR; and three
+interrupt timings). Everything else is a divergence. On the six sessions
+(Sea Dragon, Eliminator c and e, Rear Guard 5 and 4, Armored Patrol, 10
+million instructions each) there is none. The harness found two bugs on our
+side, both now fixed: a halted CPU did not count R, and port `FF` did not
+read port `EC`'s bits back. After those fixes, every remaining difference is
+trsjs's. The harness cannot see a bug both machines share: where the two
+agree, both may be wrong, so behaviour such as EI's one-instruction delay is
+pinned by our own unit tests (against Zilog UM0080 and Young §5.5) as well as
+compared. One is a judgment call rather than a trsjs error: port `FF` bit 6,
+which the Model III Technical Reference Manual calls undefined; we read it as
+1, as trsjs and trs80gp do. Details in spec §10 and §11 (phase 7). The Model I waits
+for a Model I reference; trsjs is Model III only.
+
 ## Testing the Z80 core
 
 ZEXDOC and ZEXALL, Frank Cringle's Z80 instruction exercisers, are GPL-2.0, so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fugloy/emu",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Headless, deterministic TRS-80 emulator core, Model III today (see docs/fugloy-emu-spec.md)",
   "license": "MIT",
   "type": "module",

package/src/cpu/z80cpu.js

@@ -243,6 +243,8 @@ export class Z80CPU {
   executeInstruction() {
     this.afterPrefix = false;
     if (this.halted) {
+      // A halted Z80 keeps running NOP M1 cycles for refresh (Zilog UM0080), and R counts every M1
+      this.incrementR();
       this.lastOpCycles = 4;
       this.cycles += 4;
       return 4;
@@ -315,10 +317,14 @@ export class Z80CPU {
   }
 
   /**
-   * Non-maskable interrupt: always taken, saves IFF1 into IFF2 so RETN
-   * can restore it, jumps to 0x0066.
+   * Non-maskable interrupt: saves IFF1 into IFF2 so RETN can restore it,
+   * jumps to 0x0066. Not taken right after a lone DD or FD prefix (one the
+   * next prefix or ED made a no-op), as a maskable interrupt is not (Young
+   * §3.6); the caller keeps the request pending.
+   * @returns {boolean} true when the NMI was taken
    */
   nmi() {
+    if (this.afterPrefix) return false;
     this.halted = false;
     this.IFF2 = this.IFF1;
     this.IFF1 = false;
@@ -332,6 +338,7 @@ export class Z80CPU {
     this.registers.PC = 0x0066;
     this.wz = 0x0066; // MEMPTR, as for CALL
     this.cycles += 11;
+    return true;
   }
 
   // Decode and execute opcode

package/src/debug/debugger.js

@@ -84,7 +84,7 @@ export class Debugger {
   #machine;
   /** @type {any} The Z80CPU whose accessors are swapped. */
   #cpu;
-  /** @type {{ readMemory: (a: number) => number, writeMemory: (a: number, v: number) => void, readPort: (p: number) => number, writePort: (p: number, v: number) => void }} The CPU's own accessors, restored when nothing listens. */
+  /** @type {{ readMemory: (a: number) => number, writeMemory: (a: number, v: number) => void, readPort: (p: number) => number, writePort: (p: number, v: number) => void, peek: (a: number) => number }} The CPU's own accessors, restored when nothing listens, and `peek`, a read with no device side effect (memory.peekByte) for the debugger's own looks at memory. */
   #plain;
   /** @type {Map<number, BreakEntry[]>} */
   #breaks = new Map();
@@ -159,7 +159,18 @@ export class Debugger {
     this.#machine = machine;
     const cpu = machine.system.cpu;
     this.#cpu = cpu;
-    this.#plain = { readMemory: cpu.readMemory, writeMemory: cpu.writeMemory, readPort: cpu.readPort, writePort: cpu.writePort };
+    const memory = machine.system.memory;
+    // The debugger's own reads (an old value, the look-ahead, the trace, the label file) peek: a
+    // CPU read of the Model I's $37E0 clears the latch's clock bit, and one of $37EC drops the
+    // WD1771's INTRQ. With no Expansion Interface (every Model III) a read has no side effect, and
+    // the CPU's own accessor serves.
+    this.#plain = {
+      readMemory: cpu.readMemory,
+      writeMemory: cpu.writeMemory,
+      readPort: cpu.readPort,
+      writePort: cpu.writePort,
+      peek: memory.expansion === null ? cpu.readMemory : (/** @type {number} */ a) => memory.peekByte(a),
+    };
     const dbg = this;
     /** @param {string} name @param {unknown} f */
     const check = (name, f) => {
@@ -308,7 +319,7 @@ export class Debugger {
     this.#loaded = { manifest: JSON.parse(JSON.stringify(manifest)), sha256: sha256Hex(bytes) };
     // A copy of what landed, so the label file can tell which loaded bytes changed since (a
     // block still `predicted` has not landed). Read after the loader, so a later block wins.
-    const read = this.#plain.readMemory;
+    const read = this.#plain.peek;
     this.#placed = manifest.blocks
       .filter((/** @type {any} */ b) => !b.predicted)
       .map((/** @type {any} */ b) => {
@@ -331,7 +342,7 @@ export class Debugger {
    */
   labelFile({ name, started, input } = {}) {
     const bits = this.#bits.slice();
-    const read = this.#plain.readMemory;
+    const read = this.#plain.peek;
     for (const { addr, bytes } of this.#placed) {
       for (let i = 0; i < bytes.length; i++) {
         const a = (addr + i) & 0xffff;
@@ -347,6 +358,7 @@ export class Debugger {
       bits,
       callerMap: this.callerMap(),
       cycles: this.#cpu.cycles,
+      model: this.#machine.model,
     });
   }
 
@@ -525,9 +537,8 @@ export class Debugger {
       this.#len = 0;
       return;
     }
-    // The look-ahead assumes reads have no side effects: true on the Model III; the Model I's $37E0
-    // interrupt latch (phase 6) clears on read and will need a side-effect-free peek.
-    const info = instructionInfo(this.#plain.readMemory, pc);
+    // The look-ahead peeks, so it clears no device latch (the Model I's $37E0 and $37EC).
+    const info = instructionInfo(this.#plain.peek, pc);
     const len = info.len;
     this.#len = len;
     if (this.#covOn) {
@@ -577,7 +588,7 @@ export class Debugger {
   /** Open the next trace entry for the instruction at `pc`: its bytes and registers before it runs; `afterInstruction` adds its T-states. */
   #traceStart(/** @type {number} */ pc) {
     const i = this.#tHead;
-    const read = this.#plain.readMemory;
+    const read = this.#plain.peek;
     const len = instructionInfo(read, pc).len;
     this.#tPcs[i] = pc;
     this.#tLens[i] = len;
@@ -630,7 +641,7 @@ export class Debugger {
     addr &= 0xffff;
     value &= 0xff;
     const watched = (this.#watchMask[addr] & 2) !== 0;
-    const prev = watched || this.#onMemWrite !== null ? this.#plain.readMemory(addr) : 0;
+    const prev = watched || this.#onMemWrite !== null ? this.#plain.peek(addr) : 0;
     this.#plain.writeMemory(addr, value);
     if (this.#marking) this.#bits[addr] |= WRITE;
     if (watched) this.#hit('write', addr, value, prev);

package/src/debug/label-file.js

@@ -97,10 +97,11 @@ export function decodeRle(text) {
  * Write the §8 object from a debugger session.
  * @param {{ name?: string, started?: string, input?: string,
  *   loaded: { manifest: any, sha256: string } | null, userLabels: Label[], bits: Uint8Array,
- *   callerMap: Map<number, CallerEdge[]>, cycles: number }} session
+ *   callerMap: Map<number, CallerEdge[]>, cycles: number, model?: 1 | 3 }} session
+ *   `model` is the machine's (default 3, the Model III), recorded as `program.model`
  * @returns {LabelFile}
  */
-export function writeLabelFile({ name, started, input, loaded, userLabels, bits, callerMap, cycles }) {
+export function writeLabelFile({ name, started, input, loaded, userLabels, bits, callerMap, cycles, model = 3 }) {
   if (name !== undefined && (typeof name !== 'string' || name === '')) throw new Error(`labelFile: name must be a non-empty string, not ${String(name)}`);
   if (started !== undefined && typeof started !== 'string') throw new Error(`labelFile: started must be a string (the core reads no clock; pass the time yourself), not ${String(started)}`);
   if (input !== undefined && typeof input !== 'string') throw new Error(`labelFile: input must be a string, not ${String(input)}`);
@@ -111,7 +112,7 @@ export function writeLabelFile({ name, started, input, loaded, userLabels, bits,
   }
 
   /** @type {LabelFile['program']} */
-  const program = loaded === null ? { name: programName, model: 3 } : { name: programName, sha256: loaded.sha256, model: 3 };
+  const program = loaded === null ? { name: programName, model } : { name: programName, sha256: loaded.sha256, model };
   /** @type {LabelFile['load']} */
   const load = [];
   if (manifest !== undefined) {
@@ -321,7 +322,8 @@ function labelKey(l) {
 }
 
 /**
- * Merge two label files by the §8 rule: coverage unioned per key; labels by address with `user`
+ * Merge two label files by the §8 rule (refused when both name a `program.sha256` and they differ,
+ * or their `program.model`s differ): coverage unioned per key; labels by address with `user`
  * over `observed` over `disasm` over `loader` (`b` wins a tie); `load` unioned without duplicates;
  * `entry` is `a`'s unless null; callers unioned with counts summed per `(from, kind)`; sessions
  * appended, `a`'s first. Unknown top-level keys are kept, `a`'s winning.
@@ -335,6 +337,10 @@ export function mergeLabelFiles(a, b) {
   const sa = fa.program.sha256;
   const sb = fb.program.sha256;
   if (sa !== undefined && sb !== undefined && sa !== sb) throw new Error(`mergeLabelFiles: the files are for different programs (sha256 ${sa} and ${sb})`);
+  // Two models' files would union the coverage of two different ROMs at the same addresses.
+  const ma = fa.program.model;
+  const mb = fb.program.model;
+  if (ma !== mb) throw new Error(`mergeLabelFiles: the files are for different models (${ma} and ${mb}), whose ROMs and hardware differ`);
 
   const { name, sha256: _s, model, ...programRest } = fa.program;
   const sha256 = sa ?? sb;

package/src/debug/state.js

@@ -11,8 +11,13 @@
  */
 
 import { DiskImage } from "../devices/disk-image.js";
+import { MODELS } from "../machine/models.js";
+
+/** Model names by save-state machine id ("trs80-model1": "Model I"). */
+const MODELS_BY_STATE = Object.fromEntries(Object.values(MODELS).map((d) => [d.stateMachine, d.name]));
 
 export const STATE_VERSION = 1;
+/** The Model III's machine id; a state carries its system's model's (`model.stateMachine`, models.js). */
 export const STATE_MACHINE = "trs80-model3";
 
 // Base64 without platform APIs, so the core runs anywhere (spec §2.1).
@@ -75,8 +80,11 @@ const FDC_SCALARS = [
   "status",
   "intrq",
   "commandType",
-  "bufferPos",
-  "writing",
+  "command",
+  "stepDir",
+  "headLoaded",
+  "idlePulses",
+  "intrqCond",
   "writeDeleted",
   "mfm",
   "indexClock",
@@ -94,7 +102,7 @@ export function serializeState(system) {
 
   const state = {
     version: STATE_VERSION,
-    machine: STATE_MACHINE,
+    machine: system.model?.stateMachine ?? STATE_MACHINE,
     cpu: { registers },
     memory: {
       ram: toBase64(system.memory.ram),
@@ -123,7 +131,14 @@ export function serializeState(system) {
     printer: { bytes: [...io.printer.bytes] },
     disks: [],
     nextRtcAt: system.nextRtcAt,
+    // The NMI edge latch: true while the INTRQ NMI already fired and its line is still up, so a
+    // restore neither fires it again nor loses one still pending.
+    nmiWasPending: system._nmiWasPending,
   };
+  // The Model I's Expansion Interface latch at $37E0 (absent from Model III states, which stay as
+  // they were, and from a Model I's without the interface) and its lowercase modification
+  if (io.latch) state.latch = io.latch.bits;
+  if (system.model?.id === 1) state.lowercase = !!system.lowercase;
   for (const key of CPU_SCALARS) state.cpu[key] = cpu[key];
   for (const key of IO_SCALARS) state.io[key] = io[key];
   for (const key of FDC_SCALARS) state.fdc[key] = fdc[key];
@@ -134,6 +149,11 @@ export function serializeState(system) {
       drive,
       name: disk.name,
       bytes: toBase64(disk.bytes),
+      // The container and a JV1's directory track, so a restore parses the bytes as what they
+      // are rather than detecting again (a JV3 the session formatted may hold too few sectors for
+      // detection, and a JV1's track 0 may have been rewritten since the mount read its byte 2).
+      format: disk.format,
+      dirTrack: disk.format === "jv1" ? disk.dirTrack : undefined,
       sectorBase: disk.sectorBase,
       writeProtected: disk.writeProtected,
     });
@@ -147,12 +167,37 @@ export function serializeState(system) {
  * Throws on version/machine mismatch rather than resuming garbage.
  */
 export function restoreState(system, state) {
-  if (!state || state.machine !== STATE_MACHINE) {
-    throw new Error("Not a TRS-80 Model III save state");
+  const machine = system.model?.stateMachine ?? STATE_MACHINE;
+  if (!state || state.machine !== machine) {
+    const name = system.model?.name ?? "Model III";
+    const from = typeof state?.machine === "string" && Object.hasOwn(MODELS_BY_STATE, state.machine) ? MODELS_BY_STATE[state.machine] : undefined;
+    // A state of a model the emulator builds says which; anything else keeps the old sentence.
+    if (from !== undefined && name !== "Model III") {
+      throw new Error(`This is a ${from} save state; the machine is a ${name}, and a state restores only into the model that saved it.`);
+    }
+    throw new Error(`Not a TRS-80 ${name} save state`);
   }
   if (state.version !== STATE_VERSION) {
     throw new Error(`Unsupported save-state version ${state.version}`);
   }
+  const ram = fromBase64(state.memory.ram);
+  if (ram.length !== system.memory.ram.length) {
+    throw new Error(`This ${system.model?.name ?? "Model III"} save state has ${ram.length / 1024}K of RAM; the machine has ${system.memory.ram.length / 1024}K, and a state restores only into a machine with the same RAM`);
+  }
+
+  // A Model I state restores only into a Model I fitted the same way: the Expansion Interface
+  // (its latch, its disk controller) and the lowercase modification (what video RAM holds).
+  if (system.model?.id === 1) {
+    const saved = Object.hasOwn(state, "latch");
+    const fitted = system.io.latch !== null;
+    if (saved !== fitted) {
+      throw new Error(`This Model I save state was saved ${saved ? "with" : "without"} the Expansion Interface; the machine has ${fitted ? "one" : "none"}, and a state restores only into a machine fitted the same way (expansion: ${saved}).`);
+    }
+    const lowercase = state.lowercase ?? false;
+    if (lowercase !== !!system.lowercase) {
+      throw new Error(`This Model I save state was saved ${lowercase ? "with" : "without"} the lowercase modification; the machine has ${system.lowercase ? "it" : "none"}, and a state restores only into a machine fitted the same way (lowercase: ${lowercase}).`);
+    }
+  }
 
   const cpu = system.cpu;
   const io = system.io;
@@ -166,13 +211,19 @@ export function restoreState(system, state) {
   cpu.afterPrefix ??= false; // likewise
   for (const key of IO_SCALARS) io[key] = state.io[key];
 
-  system.memory.ram.set(fromBase64(state.memory.ram));
+  system.memory.ram.set(ram);
   system.memory.videoRam.set(fromBase64(state.memory.videoRam));
   system.memory.videoDirty = true;
 
   for (const key of FDC_SCALARS) fdc[key] = state.fdc[key];
   fdc.writeDeleted = !!fdc.writeDeleted; // absent in version-1 saves from before DAM support
   fdc.mfm = state.fdc.mfm ?? true; // absent before WRITE TRACK support
+  // Absent before the emu phase 5 datasheet model: the defaults a reset leaves.
+  fdc.command ??= 0;
+  fdc.stepDir ??= 1;
+  fdc.headLoaded ??= false;
+  fdc.idlePulses ??= 0;
+  fdc.intrqCond ??= 0;
   fdc.physicalTrack = [...state.fdc.physicalTrack];
   fdc.pending = state.fdc.pending ? { ...state.fdc.pending } : null;
   fdc.buffer = state.fdc.buffer ? fromBase64(state.fdc.buffer) : null;
@@ -197,15 +248,23 @@ export function restoreState(system, state) {
 
   fdc.drives = [null, null, null, null];
   for (const entry of state.disks) {
-    const disk = new DiskImage(fromBase64(entry.bytes), entry.name);
-    // Carry over learned/derived flags the constructor can't know
-    disk.sectorBase = entry.sectorBase;
+    // Saves from before emu phase 5's final fixes carry no format: detected, as they were made.
+    const disk = new DiskImage(fromBase64(entry.bytes), entry.name, {
+      format: entry.format ?? undefined,
+      dirTrack: entry.dirTrack ?? undefined,
+    });
+    // Carry over flags the constructor can't know: write protection set at mount, and a JV1's
+    // sector base (fixed by its geometry since emu phase 5; older saves may hold null, meaning the
+    // geometry's, or a base learned by the fallback the reader then had).
+    if (entry.sectorBase != null) disk.sectorBase = entry.sectorBase;
     disk.writeProtected = entry.writeProtected;
     fdc.drives[entry.drive & 3] = disk;
   }
 
+  if (io.latch) io.latch.bits = state.latch ?? 0;
   system.nextRtcAt = state.nextRtcAt;
-  system._nmiWasPending = false;
+  system._nmiWasPending = state.nmiWasPending ?? false; // absent before emu phase 5
+  system._fdcAhead = 0;
   system.keyboard.reset(); // held keys don't survive a restore
   io.soundLog = [];
   io.onSoundReset?.(); // the Machine's raw sound ring belongs to the old timeline

package/src/devices/cassette.js

@@ -43,6 +43,10 @@ export class CassetteSystem {
     this.recordLog = [];
     this.RECORD_LIMIT = 400000;
     this.restoredRecording = null; // decoded bytes carried in by a save state
+    // The pulse codec (cassette-tape.js) counts Model III T-states; a machine
+    // with another clock (the Model I) sets this to the Model III's clock over
+    // its own, so a recording decodes at the times it took in real time.
+    this.timeScale = 1;
 
     this.BUFFER_ADDRESS = 0x4300;
     this.BUFFER_SIZE = 256;
@@ -130,7 +134,7 @@ export class CassetteSystem {
    */
   recordedCas() {
     if (this.recordLog.length) {
-      return pulsesToBytes(this.recordLog.map((r) => r.t));
+      return pulsesToBytes(this.recordLog.map((r) => r.t * this.timeScale));
     }
     if (this.restoredRecording) {
       return { bytes: this.restoredRecording, baud: null };