@esp-vision/device-core 0.5.1 → 0.6.1

package/tests/test-node-rom-port.mjs

@@ -0,0 +1,385 @@
+// SPDX-FileCopyrightText: 2026 ESP-VISION-IDE
+// SPDX-License-Identifier: Apache-2.0
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { prepareNodeRomPort, recoverNodeRomPort } from '../src/node_rom_port.js'
+
+const MAC = 'e8f60ae75642'
+const native = (path = '/dev/ttyACM0', extra = {}) => ({ path, vendorId: 0x303a, productId: 0x4003, serialNumber: MAC, location: '1-2:1.0', ...extra })
+const rom = (path = '/dev/ttyACM1', extra = {}) => native(path, { productId: 18, location: '1-2', ...extra })
+const failure = (code, message = code) => Object.assign(new Error(message), { code })
+function fixture(options = {}) {
+  let clock = 0, enumerations = 0
+  const calls = { connect: [], control: [], python: [], disconnect: 0, creates: 0, realpath: [], enumerate: [] }
+  const controller = options.controller ?? new AbortController()
+  const connected = { identity: { deviceId: MAC }, capabilities: { sinks: [
+    { id: 'usb', kind: 'usb_otg_cdc', owner: true, state: 'active', ready: true },
+  ] }, ...options.connected }
+  const device = {
+    async connect(request) { calls.connect.push(request); if (options.connectError) throw options.connectError; return connected },
+    python: { async execute(request) { calls.python.push(request); return options.pythonResult ?? { ok: true, outputTruncated: false, output: `__EV_ROM_ID__${MAC}\n` } } },
+    async control(request) {
+      calls.control.push(request)
+      if (options.control) return options.control(controller)
+      if (options.controlError) throw options.controlError
+      return { ok: true, operation: 'bootloader', acknowledged: false, outcome: 'unknown' }
+    },
+    async disconnect() { calls.disconnect += 1; if (options.cleanupError) throw options.cleanupError },
+  }
+  const snapshots = options.snapshots ?? [[native()], [rom()]]
+  const dependencies = {
+    now: () => clock,
+    async sleep(ms, signal) { clock += ms; if (options.onSleep) options.onSleep(controller, clock); signal?.throwIfAborted() },
+    async realpath(path) { calls.realpath.push(path); return options.realpath ? options.realpath(path, clock) : path },
+    async listSerial(request) {
+      calls.enumerate.push(request)
+      if (options.onEnumerate) options.onEnumerate(controller, ++enumerations)
+      if (options.enumerationError) throw options.enumerationError
+      if (options.enumerationDelay) clock += options.enumerationDelay
+      return snapshots[Math.min(enumerations++ , snapshots.length - 1)]
+    },
+    serialTransport(request) { return request },
+    createDevice(request) { calls.creates += 1; calls.transport = request.transport; return device },
+  }
+  const run = (overrides = {}) => prepareNodeRomPort({ port: '/dev/ttyACM0', python: 'selected-python', timeout: 200, signal: controller.signal, ...overrides }, dependencies)
+  const recover = (previous, overrides = {}) => recoverNodeRomPort(previous, { python: 'selected-python', timeout: 200, signal: controller.signal, ...overrides }, dependencies)
+  return { calls, run, recover, controller, now: () => clock }
+}
+
+test('imports are passive; ROM, USJ, UART and unknown selections never create an EV-MUX session', async () => {
+  for (const descriptor of [rom('/dev/ttyACM0'), native('/dev/ttyACM0', { productId: 0x1001 }),
+    native('/dev/ttyACM0', { vendorId: 0x10c4, productId: 0xea60 }), native('/dev/ttyACM0', { vendorId: null, productId: null })]) {
+    const f = fixture({ snapshots: [[descriptor]] })
+    const result = await f.run()
+    assert.equal(result.port, '/dev/ttyACM0')
+    assert.equal(f.calls.creates, 0)
+    assert.equal(f.calls.control.length, 0)
+    assert.equal(result.expectedMac, descriptor.productId === 18 ? MAC : null)
+  }
+})
+
+test('a missing exact by-id path may settle, then existing ROM uses its canonical OS path', async () => {
+  const selected = '/dev/serial/by-id/exact-selected'
+  const f = fixture({ realpath: (_, time) => { if (time < 100) throw failure('ENOENT'); return '/dev/ttyACM1' }, snapshots: [[rom()]] })
+  const result = await f.run({ port: selected })
+  assert.equal(result.port, '/dev/ttyACM1')
+  assert.equal(result.expectedMac, MAC)
+  assert.equal(result.transition.requested, false)
+  assert.equal(result.transition.location, '1-2')
+  assert.equal(f.calls.creates, 0)
+  assert.ok(f.calls.realpath.every(path => path === selected))
+})
+
+test('a vanished selected by-id never authorizes filename-based selection of another board', async () => {
+  const f = fixture({ realpath: () => { throw failure('ENOENT') }, snapshots: [[rom('/dev/ttyACM8')]] })
+  await assert.rejects(f.run({ port: `/dev/serial/by-id/usb-${MAC}` }), { code: 'ROM_PORT_LOST' })
+  assert.equal(f.calls.creates, 0)
+  assert.equal(f.calls.enumerate.length, 0)
+  assert.equal(f.now(), 200)
+})
+
+test('verified native runtime transitions once and binds only matching ROM serial plus location', async () => {
+  const f = fixture()
+  const result = await f.run()
+  assert.equal(result.port, '/dev/ttyACM1')
+  assert.equal(result.expectedMac, MAC)
+  assert.deepEqual(result.transition.command, { attempted: true, acknowledged: false, outcome: 'unknown' })
+  assert.equal(result.transition.observed, 'rom')
+  assert.equal(result.transition.cleanup.ok, true)
+  assert.equal(f.calls.connect.length, 1)
+  assert.deepEqual(f.calls.transport, { serial: '/dev/ttyACM0', role: 'usb', python: 'selected-python' })
+  assert.equal(f.calls.connect[0].probeRepl, false)
+  assert.equal(f.calls.connect[0].autoBaud, false)
+  assert.equal(f.calls.connect[0].role, 'usb')
+  assert.equal(f.calls.control.length, 1)
+  assert.equal(f.calls.disconnect, 1)
+  assert.equal(f.calls.python.length, 0)
+})
+
+test('legacy null deviceId uses one small public Python unique_id probe before bootloader', async () => {
+  const f = fixture({ connected: { identity: { deviceId: null } } })
+  const result = await f.run()
+  assert.equal(result.transition.identitySource, 'machine.unique_id')
+  assert.equal(f.calls.python.length, 1)
+  assert.ok(Buffer.byteLength(f.calls.python[0].source) < 511)
+  assert.equal(f.calls.python[0].completion, 'wait')
+  assert.equal(f.calls.control.length, 1)
+})
+
+test('wrong or malformed non-null identity never falls back to Python or resets', async () => {
+  for (const id of ['e8f60ae75653', 'unknown']) {
+    const f = fixture({ connected: { identity: { deviceId: id } } })
+    await assert.rejects(f.run(), { code: 'ROM_RUNTIME_IDENTITY_MISMATCH' })
+    assert.equal(f.calls.python.length, 0)
+    assert.equal(f.calls.control.length, 0)
+    assert.equal(f.calls.disconnect, 1)
+  }
+})
+
+test('incomplete legacy unique_id output cannot authorize reset', async () => {
+  for (const result of [{ ok: true, outputTruncated: true, output: `__EV_ROM_ID__${MAC}\n` },
+    { ok: true, outputTruncated: false, output: `__EV_ROM_ID__${MAC}\n__EV_ROM_ID__${MAC}\n` },
+    { ok: true, outputTruncated: false, output: 'Traceback\n' }]) {
+    const f = fixture({ connected: { identity: { deviceId: null } }, pythonResult: result })
+    await assert.rejects(f.run(), { code: 'ROM_RUNTIME_IDENTITY_UNAVAILABLE' })
+    assert.equal(f.calls.control.length, 0)
+    assert.equal(f.calls.disconnect, 1)
+  }
+})
+
+test('missing serial or location and ambiguous selected descriptors fail without opening a device', async () => {
+  for (const extra of [{ serialNumber: null }, { serialNumber: 'non-MAC' }, { location: null }]) {
+    const f = fixture({ snapshots: [[native('/dev/ttyACM0', extra)]] })
+    await assert.rejects(f.run(), { code: 'ROM_PORT_IDENTITY_REQUIRED' })
+    assert.equal(f.calls.creates, 0)
+  }
+  const f = fixture({ snapshots: [[native(), native()]] })
+  await assert.rejects(f.run(), { code: 'ROM_PORT_AMBIGUOUS' })
+  assert.equal(f.calls.creates, 0)
+})
+
+test('an inactive USB owner or different owner cannot authorize bootloader', async () => {
+  for (const sinks of [[{ id: 'usb', kind: 'usb_otg_cdc', owner: true, state: 'idle', ready: true }],
+    [{ id: 'usj', kind: 'usb_serial_jtag', owner: true, state: 'active', ready: true }]]) {
+    const f = fixture({ connected: { capabilities: { sinks } } })
+    await assert.rejects(f.run(), { code: 'ROM_RUNTIME_INTERFACE_MISMATCH' })
+    assert.equal(f.calls.control.length, 0)
+    assert.equal(f.calls.disconnect, 1)
+  }
+})
+
+test('other MACs or physical locations never replace the selected device', async () => {
+  const f = fixture({ snapshots: [[native()], [rom('/dev/ttyACM1', { serialNumber: 'e8f60ae75653' }), rom('/dev/ttyACM2', { location: '1-3' })]] })
+  await assert.rejects(f.run(), { code: 'ROM_PORT_REBIND_TIMEOUT' })
+  assert.equal(f.calls.creates, 1)
+  assert.equal(f.calls.control.length, 1)
+  assert.equal(f.calls.disconnect, 1)
+  assert.equal(f.now(), 200)
+})
+
+test('two matching ROM interfaces are ambiguous and never selected', async () => {
+  const f = fixture({ snapshots: [[native()], [rom('/dev/ttyACM1'), rom('/dev/ttyACM2')]] })
+  await assert.rejects(f.run(), { code: 'ROM_PORT_AMBIGUOUS' })
+  assert.equal(f.calls.control.length, 1)
+})
+
+test('unknown command outcome and cleanup failure remain separate from observed ROM', async () => {
+  const controlError = Object.assign(failure('TIMEOUT'), { reset: { outcome: 'unknown', acknowledged: false } })
+  const f = fixture({ controlError, cleanupError: failure('SESSION_RELEASE_TIMEOUT') })
+  const result = await f.run()
+  assert.equal(result.transition.observed, 'rom')
+  assert.equal(result.transition.command.acknowledged, false)
+  assert.equal(result.transition.command.outcome, 'unknown')
+  assert.equal(result.transition.command.error.code, 'TIMEOUT')
+  assert.equal(result.transition.cleanup.ok, false)
+  assert.equal(result.transition.cleanup.error.code, 'SESSION_RELEASE_TIMEOUT')
+  assert.equal(f.calls.control.length, 1)
+})
+
+test('ordinary handshake or command errors are returned without bootloader retry', async () => {
+  const error = failure('SESSION_BUSY')
+  const f = fixture({ connectError: error })
+  await assert.rejects(f.run(), value => value === error)
+  assert.equal(f.calls.control.length, 0)
+  assert.equal(f.calls.disconnect, 1)
+  const other = fixture({ controlError: failure('TIMEOUT') })
+  await assert.rejects(other.run(), { code: 'TIMEOUT' })
+  assert.equal(other.calls.control.length, 1)
+  assert.equal(other.calls.enumerate.length, 1)
+})
+
+test('Windows COM aliases and pyserial interface suffixes bind the same physical USB port', async () => {
+  const f = fixture({ snapshots: [[native('COM8', { location: '1-5:x.0' })], [rom('COM9', { location: '1-5' })]] })
+  const result = await f.run({ port: '\\\\.\\com8' })
+  assert.equal(result.port, 'COM9')
+  assert.equal(result.expectedMac, MAC)
+  assert.equal(f.calls.realpath.length, 0)
+})
+
+test('enumeration finishing after the deadline does not accept a late ROM match', async () => {
+  const f = fixture({ enumerationDelay: 250 })
+  await assert.rejects(f.run(), { code: 'ROM_PORT_REBIND_TIMEOUT' })
+  assert.equal(f.calls.control.length, 1)
+})
+
+test('cancel before entry, during command, and during rebind never replays control', async () => {
+  const reason = Object.assign(new Error('cancelled'), { name: 'AbortError' })
+  const before = fixture(); before.controller.abort(reason)
+  await assert.rejects(before.run(), value => value === reason)
+  assert.equal(before.calls.creates, 0)
+  const during = fixture({ control(controller) { controller.abort(reason); throw reason } })
+  await assert.rejects(during.run(), value => value === reason)
+  assert.equal(during.calls.control.length, 1)
+  assert.equal(during.calls.disconnect, 1)
+  const poll = fixture({ snapshots: [[native()], []], onSleep(controller) { controller.abort(reason) } })
+  await assert.rejects(poll.run(), value => value === reason)
+  assert.equal(poll.calls.control.length, 1)
+  assert.equal(poll.calls.disconnect, 1)
+})
+
+test('unavailable descriptors leave the exact canonical selection untouched and unprobed', async () => {
+  const f = fixture({ enumerationError: failure('SERIAL_UNAVAILABLE'), realpath: () => '/dev/ttyACM7' })
+  const result = await f.run({ port: '/dev/serial/by-id/exact' })
+  assert.deepEqual(result, { port: '/dev/ttyACM7', expectedMac: null, transition: null })
+  assert.equal(f.calls.creates, 0)
+})
+
+
+const previousRom = (extra = {}) => ({ port: '/dev/ttyACM0', expectedMac: MAC,
+  transition: { observed: 'rom', requested: false, serial: MAC, location: '1-2' }, ...extra })
+
+test('confirmed UVC runtime PID4023 uses the same identity-verified one-shot handoff', async () => {
+  const f = fixture({ snapshots: [[native('/dev/ttyACM0', { productId: 0x4023 })], [rom()]] })
+  const result = await f.run()
+  assert.equal(result.expectedMac, MAC)
+  assert.equal(result.transition.observed, 'rom')
+  assert.equal(f.calls.control.length, 1)
+  const other = fixture({ snapshots: [[native('/dev/ttyACM0', { productId: 0x4021 })]] })
+  assert.equal((await other.run()).transition, null)
+  assert.equal(other.calls.creates, 0)
+})
+
+test('read-only initialization recovery verifies same-board runtime and reuses production handoff once', async () => {
+  for (const productId of [0x4003, 0x4023]) {
+    const runtime = native('/dev/ttyACM2', { productId })
+    const f = fixture({ snapshots: [[runtime], [runtime], [rom('/dev/ttyACM3')]] })
+    const result = await f.recover(previousRom())
+    assert.equal(result.port, '/dev/ttyACM3')
+    assert.equal(result.expectedMac, MAC)
+    assert.deepEqual(result.transition.recovery, { previousPort: '/dev/ttyACM0', runtimePid: productId })
+    assert.equal(f.calls.transport.serial, '/dev/ttyACM2')
+    assert.equal(f.calls.control.length, 1)
+    assert.equal(f.calls.disconnect, 1)
+  }
+})
+
+test('recovery never repeats a previous active handoff or uses an incomplete previous binding', async () => {
+  for (const previous of [previousRom({ expectedMac: 'unknown' }), previousRom({ transition: null }),
+    previousRom({ transition: { observed: 'rom', requested: true, serial: MAC, location: '1-2' } }),
+    previousRom({ transition: { observed: 'rom', requested: false, serial: 'e8f60ae75653', location: '1-2' } }),
+    previousRom({ transition: { observed: 'rom', requested: false, serial: MAC, location: null } })]) {
+    const f = fixture()
+    assert.equal(await f.recover(previous), null)
+    assert.equal(f.calls.enumerate.length, 0)
+    assert.equal(f.calls.creates, 0)
+  }
+})
+
+test('persistent ROM or absence exhausts only passive observation before returning null', async () => {
+  for (const snapshot of [[rom('/dev/ttyACM1')], [], [native('/dev/ttyACM8', { serialNumber: 'e8f60ae75653', location: '2-3' })]]) {
+    const f = fixture({ snapshots: [snapshot] })
+    assert.equal(await f.recover(previousRom()), null)
+    assert.equal(f.now(), 200)
+    assert.equal(f.calls.enumerate.length, 4)
+    assert.equal(f.calls.creates, 0)
+    assert.equal(f.calls.control.length, 0)
+  }
+})
+
+test('recovery rejects wrong MAC, moved location and ambiguous matching runtimes', async () => {
+  for (const runtime of [native('/dev/ttyACM2', { serialNumber: 'e8f60ae75653' }), native('/dev/ttyACM2', { location: '2-3' })]) {
+    const f = fixture({ snapshots: [[runtime]] })
+    await assert.rejects(f.recover(previousRom()), { code: 'ROM_RUNTIME_IDENTITY_MISMATCH' })
+    assert.equal(f.calls.creates, 0)
+  }
+  const f = fixture({ snapshots: [[native('/dev/ttyACM2'), native('/dev/ttyACM3')]] })
+  await assert.rejects(f.recover(previousRom()), { code: 'ROM_PORT_AMBIGUOUS' })
+  assert.equal(f.calls.creates, 0)
+})
+
+test('recovery rechecks identity before connecting when a selected OS path was reused', async () => {
+  const correct = native('/dev/ttyACM2')
+  const wrong = native('/dev/ttyACM2', { serialNumber: 'e8f60ae75653' })
+  const f = fixture({ snapshots: [[correct], [wrong]] })
+  await assert.rejects(f.recover(previousRom()), { code: 'ROM_RUNTIME_IDENTITY_MISMATCH' })
+  assert.equal(f.calls.creates, 0)
+  assert.equal(f.calls.control.length, 0)
+})
+
+test('read-only recovery honors cancel and fresh-enumeration deadline', async () => {
+  const reason = Object.assign(new Error('cancelled'), { name: 'AbortError' })
+  const cancelled = fixture(); cancelled.controller.abort(reason)
+  await assert.rejects(cancelled.recover(previousRom()), value => value === reason)
+  assert.equal(cancelled.calls.creates, 0)
+  const late = fixture({ snapshots: [[native()]], enumerationDelay: 250 })
+  await assert.rejects(late.recover(previousRom()), { code: 'ROM_PORT_REBIND_TIMEOUT' })
+  assert.equal(late.calls.creates, 0)
+})
+
+
+test('read-only recovery observes a real 2.4-second missing-device window before one handoff', async () => {
+  const runtime = native('/dev/ttyACM2', { productId: 0x4023 })
+  const f = fixture({ snapshots: [...Array.from({ length: 48 }, () => []), [runtime], [runtime], [rom('/dev/ttyACM3')]] })
+  const result = await f.recover(previousRom(), { timeout: 5000 })
+  assert.equal(f.now(), 2400)
+  assert.equal(result.port, '/dev/ttyACM3')
+  assert.equal(result.transition.recovery.runtimePid, 0x4023)
+  assert.equal(f.calls.control.length, 1)
+  assert.equal(f.calls.connect.length, 1)
+  assert.equal(f.calls.disconnect, 1)
+  assert.equal(f.calls.enumerate[48].timeout, 2600)
+})
+
+test('a stale ROM followed by disappearance is observed passively until the same runtime returns', async () => {
+  const runtime = native('/dev/ttyACM2')
+  const snapshots = [...Array.from({ length: 10 }, () => [rom('/dev/ttyACM0')]),
+    ...Array.from({ length: 38 }, () => []), [runtime], [runtime], [rom('/dev/ttyACM3')]]
+  const f = fixture({ snapshots })
+  const result = await f.recover(previousRom(), { timeout: 5000 })
+  assert.equal(f.now(), 2400)
+  assert.equal(result.port, '/dev/ttyACM3')
+  assert.equal(f.calls.creates, 1)
+  assert.equal(f.calls.control.length, 1)
+  assert.equal(f.calls.disconnect, 1)
+})
+
+test('a conflicting MAC or location seen after waiting fails before opening any runtime', async () => {
+  for (const conflicting of [native('/dev/ttyACM2', { serialNumber: 'e8f60ae75653' }),
+    native('/dev/ttyACM2', { location: '2-3' }), rom('/dev/ttyACM2', { serialNumber: 'e8f60ae75653' }),
+    rom('/dev/ttyACM2', { location: '2-3' })]) {
+    const f = fixture({ snapshots: [[], [], [conflicting]] })
+    await assert.rejects(f.recover(previousRom()), { code: 'ROM_RUNTIME_IDENTITY_MISMATCH' })
+    assert.equal(f.now(), 100)
+    assert.equal(f.calls.creates, 0)
+    assert.equal(f.calls.control.length, 0)
+  }
+})
+
+test('late duplicate runtime or simultaneous ROM/runtime descriptors remain ambiguous', async () => {
+  for (const second of [native('/dev/ttyACM3'), rom('/dev/ttyACM3')]) {
+    const f = fixture({ snapshots: [[], [native('/dev/ttyACM2'), second]] })
+    await assert.rejects(f.recover(previousRom()), { code: 'ROM_PORT_AMBIGUOUS' })
+    assert.equal(f.now(), 50)
+    assert.equal(f.calls.creates, 0)
+    assert.equal(f.calls.control.length, 0)
+  }
+})
+
+test('cancel during passive recovery sleep never creates a session or sends bootloader', async () => {
+  const reason = Object.assign(new Error('cancelled during native USB observation'), { name: 'AbortError' })
+  const f = fixture({ snapshots: [[]], onSleep(controller, clock) { if (clock >= 150) controller.abort(reason) } })
+  await assert.rejects(f.recover(previousRom(), { timeout: 5000 }), value => value === reason)
+  assert.equal(f.now(), 150)
+  assert.equal(f.calls.creates, 0)
+  assert.equal(f.calls.control.length, 0)
+})
+
+test('late runtime enumeration does not start handoff after the passive deadline', async () => {
+  const runtime = native('/dev/ttyACM2')
+  const f = fixture({ snapshots: [[runtime]], enumerationDelay: 201 })
+  await assert.rejects(f.recover(previousRom()), { code: 'ROM_PORT_REBIND_TIMEOUT' })
+  assert.equal(f.calls.creates, 0)
+  assert.equal(f.calls.control.length, 0)
+})
+
+test('a runtime handshake error after settling is propagated without another observation or handoff', async () => {
+  const runtime = native('/dev/ttyACM2')
+  const reason = failure('SESSION_BUSY')
+  const f = fixture({ snapshots: [[], [runtime], [runtime]], connectError: reason })
+  await assert.rejects(f.recover(previousRom()), value => value === reason)
+  assert.equal(f.now(), 50)
+  assert.equal(f.calls.connect.length, 1)
+  assert.equal(f.calls.creates, 1)
+  assert.equal(f.calls.control.length, 0)
+  assert.equal(f.calls.disconnect, 1)
+})

package/tests/test-node-rom.mjs

@@ -0,0 +1,231 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { EventEmitter } from 'node:events'
+import { PassThrough, Writable } from 'node:stream'
+import { openNodeRom } from '../src/node_rom.js'
+
+function fixture({ mac = 'e8f60ae75642', expected = mac, prepare, initializeError, operationError, readResult = 'QUI=' } = {}) {
+  const calls = [], requests = []
+  const child = new EventEmitter()
+  child.exitCode = null
+  child.stdout = new PassThrough()
+  child.stdin = new Writable({
+    write(data, encoding, done) {
+      const request = JSON.parse(data.toString())
+      requests.push(request)
+      const detail = request.method === 'initialize' ? initializeError : operationError
+      queueMicrotask(() => child.stdout.write(JSON.stringify(detail
+        ? { id: request.id, error: 'ROM_OPERATION_FAILED', method: request.method, detail }
+        : { id: request.id, result: request.method === 'initialize'
+          ? { chipFamily: 0x3280, chipRevision: 302, chipMac: mac, connectionMode: 'no-reset' } : request.method === 'read' ? readResult : null }) + '\n'))
+      done()
+    },
+    final(done) { child.exitCode = 0; queueMicrotask(() => child.emit('exit', 0)); done() },
+  })
+  child.kill = () => { child.exitCode = 1; child.emit('exit', 1) }
+  const selected = { port: '/dev/rebound-rom', expectedMac: expected, transition: { requested: true } }
+  const dependencies = {
+    async preparePort(options) { calls.push(['prepare', options]); return prepare ? prepare(options) : selected },
+    spawn(...args) { calls.push(['spawn', ...args]); return child },
+  }
+  return { calls, requests, child, selected, dependencies }
+}
+
+test('Node ROM process uses the qualified rebound port and verifies its actual MAC before writes', async () => {
+  const f = fixture(), loader = openNodeRom({ port: '/dev/runtime', python: 'test-python' }, f.dependencies)
+  try {
+    await loader.initialize()
+    assert.equal(f.calls[1][2][2], '/dev/rebound-rom')
+    assert.equal(loader.port, '/dev/rebound-rom')
+    assert.equal(loader.chipMac, 'e8f60ae75642')
+    assert.equal(loader.connectionMode, 'no-reset')
+    assert.deepEqual(loader.usbTransition, { requested: true })
+    await loader.flashData(new Uint8Array([1, 2]), () => {}, 65536)
+    assert.deepEqual(f.requests.map(r => r.method), ['initialize', 'write'])
+  } finally { await loader.disconnect() }
+})
+
+test('a ROM MAC mismatch closes the process and cannot be followed by a write', async () => {
+  const f = fixture({ expected: '001122334455' }), loader = openNodeRom({ port: '/dev/runtime' }, f.dependencies)
+  await assert.rejects(loader.initialize(), { code: 'ROM_IDENTITY_CHANGED' })
+  await assert.rejects(loader.flashData(new Uint8Array([1]), () => {}, 65536), { code: 'ROM_CLOSED' })
+  assert.deepEqual(f.requests.map(r => r.method), ['initialize'])
+  assert.equal(f.child.exitCode, 0)
+})
+
+test('initialization is single use and never repeats a bootloader handoff', async () => {
+  const f = fixture(), loader = openNodeRom({ port: '/dev/runtime' }, f.dependencies)
+  try {
+    await loader.initialize()
+    await assert.rejects(loader.initialize(), { code: 'ROM_ALREADY_INITIALIZED' })
+    assert.equal(f.calls.filter(c => c[0] === 'prepare').length, 1)
+    assert.equal(f.calls.filter(c => c[0] === 'spawn').length, 1)
+  } finally { await loader.disconnect() }
+})
+
+test('flash operations before initialization fail without spawning or sending a process request', async () => {
+  const f = fixture(), loader = openNodeRom({ port: '/dev/runtime' }, f.dependencies)
+  await assert.rejects(loader.flashData(new Uint8Array([1]), () => {}, 65536), { code: 'ROM_NOT_INITIALIZED' })
+  assert.equal(f.calls.length, 0)
+  assert.equal(f.requests.length, 0)
+  await loader.disconnect()
+})
+
+test('disconnect cancels a pending port handoff before any ROM process can start', async () => {
+  const f = fixture({ prepare: ({ signal }) => new Promise((resolve, reject) => {
+    signal.addEventListener('abort', () => reject(signal.reason), { once: true })
+  }) })
+  const loader = openNodeRom({ port: '/dev/runtime' }, f.dependencies)
+  const initializing = loader.initialize()
+  const rejected = assert.rejects(initializing, { code: 'ROM_CLOSED' })
+  await loader.disconnect()
+  await rejected
+  assert.equal(f.calls.filter(c => c[0] === 'spawn').length, 0)
+})
+
+test('handoff failure retains its cause and cannot replay on the same loader', async () => {
+  const reason = Object.assign(new Error('ROM did not re-enumerate'), { code: 'ROM_PORT_LOST' })
+  const f = fixture({ prepare: () => { throw reason } }), loader = openNodeRom({ port: '/dev/runtime' }, f.dependencies)
+  await assert.rejects(loader.initialize(), error => error === reason)
+  await assert.rejects(loader.initialize(), { code: 'ROM_CLOSED' })
+  assert.equal(f.calls.length, 1)
+})
+
+test('underlying ROM initialization diagnostics survive cleanup and prevent writes', async () => {
+  const f = fixture({ initializeError: 'No serial data received' }), loader = openNodeRom({ port: '/dev/runtime' }, f.dependencies)
+  await assert.rejects(loader.initialize(), error => error.code === 'ROM_OPERATION_FAILED'
+    && error.operation === 'initialize' && error.cause === 'No serial data received')
+  await assert.rejects(loader.flashData(new Uint8Array([1]), () => {}, 65536), { code: 'ROM_CLOSED' })
+  assert.equal(f.requests.length, 1)
+})
+
+test('one read-only ROM sync failure may hand off the verified same runtime before any write', async () => {
+  const first = fixture({ initializeError: 'No serial data received' }), second = fixture()
+  const oldPort = { port: '/dev/rom', expectedMac: 'e8f60ae75642', transition: { observed: 'rom', requested: false } }
+  const rebound = { port: '/dev/rebound', expectedMac: oldPort.expectedMac, transition: { observed: 'rom', requested: true } }
+  let starts = 0, recoveries = 0
+  const loader = openNodeRom({ port: '/dev/rom' }, {
+    preparePort: async () => oldPort,
+    recoverPort: async previous => { assert.equal(previous, oldPort); recoveries++; return rebound },
+    spawn: () => (++starts === 1 ? first.child : second.child),
+  })
+  try {
+    await loader.initialize()
+    assert.equal(starts, 2)
+    assert.equal(recoveries, 1)
+    assert.equal(loader.usbTransition.previousInitialization.detail, 'No serial data received')
+    assert.deepEqual(first.requests.map(r => r.method), ['initialize'])
+    assert.deepEqual(second.requests.map(r => r.method), ['initialize'])
+    await loader.flashData(new Uint8Array([1]), () => {}, 65536)
+    assert.deepEqual(second.requests.map(r => r.method), ['initialize', 'write'])
+  } finally { await loader.disconnect() }
+})
+
+test('an initialization that already requested bootloader cannot request it again', async () => {
+  const f = fixture({ initializeError: 'Still no serial data' })
+  f.selected.transition = { observed: 'rom', requested: true }
+  let recoveries = 0
+  const loader = openNodeRom({ port: '/dev/runtime' }, { ...f.dependencies,
+    recoverPort: async () => { recoveries++; throw Error('Must not replay bootloader') },
+  })
+  await assert.rejects(loader.initialize(), error => error.cause === 'Still no serial data')
+  assert.equal(recoveries, 0)
+  assert.equal(f.calls.filter(c => c[0] === 'spawn').length, 1)
+})
+
+test('absence of a confirmed runtime preserves the initial ROM sync failure without replay', async () => {
+  const f = fixture({ initializeError: 'No serial data received' })
+  f.selected.transition = { observed: 'rom', requested: false }
+  const loader = openNodeRom({ port: '/dev/rom' }, { ...f.dependencies, recoverPort: async () => null })
+  await assert.rejects(loader.initialize(), error => error.code === 'ROM_OPERATION_FAILED'
+    && error.operation === 'initialize' && error.cause === 'No serial data received')
+  assert.equal(f.requests.length, 1)
+})
+
+test('a second initialization sync failure cannot trigger a third process or handoff', async () => {
+  const first = fixture({ initializeError: 'First sync failed' }), second = fixture({ initializeError: 'Second sync failed' })
+  const selected = { port: '/dev/rom', expectedMac: 'e8f60ae75642', transition: { observed: 'rom', requested: false } }
+  let starts = 0, recoveries = 0
+  const loader = openNodeRom({ port: '/dev/rom' }, {
+    preparePort: async () => selected,
+    recoverPort: async () => { recoveries++; return { ...selected, transition: { observed: 'rom', requested: true } } },
+    spawn: () => (++starts === 1 ? first.child : second.child),
+  })
+  await assert.rejects(loader.initialize(), error => error.cause === 'Second sync failed'
+    && error.transition.previousInitialization.detail === 'First sync failed')
+  assert.equal(starts, 2)
+  assert.equal(recoveries, 1)
+  assert.equal(first.requests.length + second.requests.length, 2)
+})
+
+
+test('post-initialize read or write failures never start recovery, a second process, or replay data', async () => {
+  for (const method of ['read', 'write']) {
+    const f = fixture({ operationError: 'Original operation failed' })
+    f.selected.transition = { observed: 'rom', requested: false }
+    let recoveries = 0, progresses = 0
+    const loader = openNodeRom({ port: '/dev/rom' }, { ...f.dependencies,
+      recoverPort: async () => { recoveries++; throw Error('Read/write must not recover') },
+    })
+    try {
+      await loader.initialize()
+      const operation = method === 'read' ? loader.readFlash(0x8000, 1024)
+        : loader.flashData(new Uint8Array([1, 2, 3]), () => { progresses++ }, 0x10000)
+      await assert.rejects(operation, error => error.code === 'ROM_OPERATION_FAILED'
+        && error.operation === method && error.cause === 'Original operation failed')
+      assert.equal(recoveries, 0)
+      assert.equal(progresses, 0)
+      assert.equal(f.calls.filter(c => c[0] === 'spawn').length, 1)
+      assert.deepEqual(f.requests.map(r => r.method), ['initialize', method])
+    } finally { await loader.disconnect() }
+  }
+})
+
+
+test('Node ROM reads forward default and explicit budgets and report progress only after complete data', async () => {
+  const f = fixture(), loader = openNodeRom({ port: '/dev/runtime' }, f.dependencies)
+  const progress = []
+  try {
+    await loader.initialize()
+    assert.deepEqual(await loader.readFlash(0x8000, 2, (...args) => progress.push(args)), new Uint8Array([65, 66]))
+    assert.deepEqual(await loader.readFlash(0x10000, 2, undefined,
+      { chunkSize: 65536, blockSize: 4096, maxInFlight: 2 }), new Uint8Array([65, 66]))
+    assert.deepEqual(f.requests.map(r => [r.method, r.args]), [['initialize', []],
+      ['read', [0x8000, 2, { blockSize: 1024, maxInFlight: 1 }]],
+      ['read', [0x10000, 2, { blockSize: 4096, maxInFlight: 2 }]]])
+    assert.equal(progress.length, 1)
+    assert.deepEqual(progress[0], [new Uint8Array([65, 66]), 2, 2])
+  } finally { await loader.disconnect() }
+})
+
+test('invalid read ranges, progress, or packet budgets never issue a child process RPC', async () => {
+  const f = fixture(), loader = openNodeRom({ port: '/dev/runtime' }, f.dependencies)
+  try {
+    await loader.initialize()
+    for (const [offset, count, progress, options] of [[-1, 2], [0, 0], [0, 0x100000000], [0xffffffff, 2], [0, 2, null],
+      [0, 2, undefined, null], [0, 2, undefined, []], [0, 2, undefined, { blockSize: 512 }],
+      [0, 2, undefined, { blockSize: true }], [0, 2, undefined, { blockSize: null }], [0, 2, undefined, { maxInFlight: 0 }],
+      [0, 2, undefined, { maxInFlight: 65 }], [0, 2, undefined, { maxInFlight: null }], [0, 2, undefined, { maxInFlight: 1.5 }],
+      [0, 2, undefined, { unknown: 1 }], [0, 2, undefined, { chunkSize: 1 }]]) {
+      await assert.rejects(loader.readFlash(offset, count, progress, options), error => error instanceof TypeError || error instanceof RangeError)
+    }
+    assert.deepEqual(f.requests.map(r => r.method), ['initialize'])
+  } finally { await loader.disconnect() }
+})
+
+test('incomplete read results are rejected without progress, recovery, or duplicate read', async () => {
+  const f = fixture({ readResult: 'QQ==' })
+  let recovered = 0, progressed = 0
+  const loader = openNodeRom({ port: '/dev/runtime' }, { ...f.dependencies,
+    recoverPort: async () => { recovered++; throw Error('Read must not recover') },
+  })
+  try {
+    await loader.initialize()
+    await assert.rejects(loader.readFlash(0, 2, () => { progressed++ }), { code: 'ROM_READ_LENGTH', operation: 'read' })
+    assert.equal(recovered, 0)
+    assert.equal(progressed, 0)
+    assert.deepEqual(f.requests.map(r => r.method), ['initialize', 'read'])
+  } finally { await loader.disconnect() }
+})