@esp-vision/device-core 0.6.0 → 0.7.0

package/tests/test-firmware-install.mjs

@@ -2,43 +2,15 @@
 // SPDX-License-Identifier: Apache-2.0
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
-import { createDevice } from '../src/index.js'
-import { firmwareSha256 } from '../src/firmware_flash.js'
-
-async function fixture() {
-  const data = new Uint8Array(0x11000).fill(0xff), calls = []
-  data.set([0xe9, 1, 2, 3], 0x2000)
-  data.set([0xaa, 0x50, 4, 5], 0x8000)
-  data.set([0xe9, 6, 7, 8], 0x10000)
-  const part = async offset => ({ offset, bytes: 4, sha256: await firmwareSha256(data.subarray(offset, offset + 4)) })
-  const release = { board: 'BOARD', version: 'new', image: {
-    evMuxVersion: 4, chipFamily: 0x3280, chipRevision: 302, ...(await part(0x10000)),
-    partitionSize: 4096, partitionTable: await part(0x8000), url: 'https://example.test/app.bin',
-  }, install: { offset: 0, bytes: data.length, flashSize: 0x1000000, chipRevisionMin: 302, chipRevisionMax: 302,
-    sha256: await firmwareSha256(data), bootloader: await part(0x2000), url: 'https://example.test/full.bin' } }
-  const flash = new Uint8Array(data.length).fill(0xff)
-  const loader = {
-    chipFamily: 0x3280, chipRevision: 302,
-    async initialize() { calls.push('initialize') },
-    async getSecurityInfo() { return { flags: 0, flashCryptCnt: 0 } },
-    async runStub() { calls.push('stub'); return loader },
-    async flashId() { calls.push('capacity'); return 0x1840ef },
-    async flashData(buffer, progress, offset) { calls.push(['write', offset]); flash.set(new Uint8Array(buffer), offset); progress(buffer.byteLength, buffer.byteLength) },
-    async readFlash(offset, count) { calls.push(['read', offset]); return flash.slice(offset, offset + count) },
-    async readRegister() { return 0 },
-    async hardReset() { calls.push('reset') },
-    async disconnect() { calls.push('close') },
-  }
-  const device = createDevice(), request = { mode: 'install', release, board: 'BOARD', data, async openLoader() { calls.push('open'); return loader } }
-  return { data, calls, release, loader, device, request, flash }
-}
+import { installFixture as fixture } from './firmware-fixtures.mjs'
 
 test('blank device installs through ROM without an EV-MUX transport or existing partition table', async () => {
   const f = await fixture(), progress = []
   const result = await f.device.firmware.update({ ...f.request, onProgress: value => progress.push(value) })
   assert.equal(result.verified, true); assert.equal(result.reconnected, false)
-  assert.deepEqual(f.flash, f.data)
-  assert.deepEqual(f.calls, ['open', 'initialize', 'stub', 'capacity', ['write', 0], ['read', 0], ['read', 65536], 'reset', 'close'])
+  assert.deepEqual(f.flash.slice(0, f.data.length), f.data)
+  assert.ok(f.flash.subarray(0x20000).every(value => value === 0xff))
+  assert.deepEqual(f.calls, ['open', 'initialize', 'stub', 'capacity', ['erase', 0x20000, 0x21000], ['read', 0x20000], ['read', 0x30000], ['read', 0x40000], ['write', 0], ['read', 0], ['read', 65536], 'reset', 'close'])
   assert.equal(progress.at(-1), 100)
 })
 
@@ -54,7 +26,7 @@ test('complete image is downloaded from install URL with the requested cancellat
   await f.device.firmware.update({ ...f.request, data: undefined, signal: controller.signal,
     async fetch(url, options) { assert.equal(url, f.release.install.url); assert.equal(options.signal, controller.signal); return { ok: true, arrayBuffer: async () => f.data.buffer } },
   })
-  assert.deepEqual(f.flash, f.data)
+  assert.deepEqual(f.flash.slice(0, f.data.length), f.data)
 })
 
 test('install selection skips app-only releases and rejects explicit unqualified versions', async () => {
@@ -97,13 +69,14 @@ for (const change of ['wrong-chip', 'wrong-revision', 'secure-boot', 'encryption
     if (change === 'unknown-flash') f.loader.flashId = async () => 0xffffff
     if (change === 'missing-capacity') delete f.loader.flashId
     await assert.rejects(f.device.firmware.update(f.request))
-    assert.ok(!f.calls.some(call => Array.isArray(call) && call[0] === 'write'))
+    assert.ok(!f.calls.some(call => Array.isArray(call) && ['write', 'erase'].includes(call[0])))
     assert.equal(f.calls.at(-1), 'close')
   })
 }
 
 test('installation with damaged readback does not reset or report success', async () => {
-  const f = await fixture(); f.loader.readFlash = async (_offset, count) => new Uint8Array(count)
+  const f = await fixture(), read = f.loader.readFlash
+  f.loader.readFlash = async (offset, count) => offset >= 0x20000 ? read(offset, count) : new Uint8Array(count)
   await assert.rejects(f.device.firmware.update(f.request), /verification failed/)
   assert.ok(!f.calls.includes('reset')); assert.equal(f.calls.at(-1), 'close')
 })

package/tests/test-firmware-source.mjs

@@ -4,19 +4,20 @@ import test from 'node:test'
 import assert from 'node:assert/strict'
 import { createDevice } from '../src/index.js'
 import { firmwareSha256 } from '../src/firmware.js'
+import { partitionTable } from './firmware-fixtures.mjs'
 
 async function fixture() {
   const full = new Uint8Array(0x11000).fill(0xff), appOffset = 0x10000, appLength = 4, calls = []
-  full.set([0xe9, 1, 2, 3], 0x2000); full.set([0xaa, 0x50, 4, 5], 0x8000); full.set([0xe9, 6, 7, 8], appOffset)
-  const segment = async offset => ({ offset, bytes: 4, sha256: await firmwareSha256(full.subarray(offset, offset + 4)) })
+  full.set([0xe9, 1, 2, 3], 0x2000); full.set(partitionTable(), 0x8000); full.set([0xe9, 6, 7, 8], appOffset)
+  const segment = async (offset, size = 4) => ({ offset, bytes: size, sha256: await firmwareSha256(full.subarray(offset, offset + size)) })
   const source = { url: 'https://example.test/full.bin', bytes: full.length, sha256: await firmwareSha256(full), offset: appOffset }
   const release = { board: 'BOARD', version: 'new', image: {
-    evMuxVersion: 4, chipFamily: 0x3280, chipRevision: 302, ...(await segment(appOffset)), partitionSize: 4096,
-    partitionTable: await segment(0x8000), url: source.url, source,
+    evMuxVersion: 4, chipFamily: 0x3280, chipRevision: 302, ...(await segment(appOffset)), partitionSize: 0x10000,
+    partitionTable: await segment(0x8000, 0xc00), url: source.url, source,
   }, install: { url: source.url, offset: 0, bytes: full.length, sha256: source.sha256, flashSize: 0x1000000,
     chipRevisionMin: 302, chipRevisionMax: 302, bootloader: await segment(0x2000) } }
-  const flash = new Uint8Array(full.length).fill(0x5a)
-  flash.set(full.subarray(0x8000, 0x8004), 0x8000)
+  const flash = new Uint8Array(0x41000).fill(0x5a)
+  flash.set(full.subarray(0x8000, 0x8c00), 0x8000)
   const before = flash.slice()
   const loader = {
     chipFamily: 0x3280, chipRevision: 302,
@@ -24,6 +25,7 @@ async function fixture() {
     async getSecurityInfo() { return { flags: 0, flashCryptCnt: 0 } },
     async runStub() { calls.push('stub'); return loader },
     async flashId() { return 0x1840ef },
+    async eraseRegion(offset, size) { calls.push(['erase', offset, size]); flash.fill(0xff, offset, offset + size) },
     async flashData(buffer, progress, offset) { calls.push(['write', offset, buffer.byteLength]); flash.set(new Uint8Array(buffer), offset); progress(buffer.byteLength, buffer.byteLength) },
     async readFlash(offset, bytes) { return flash.slice(offset, offset + bytes) },
     async readRegister() { return 0 },
@@ -89,7 +91,8 @@ test('downloaded full BIN enforces approved length during streaming before openi
 test('single BIN explicit install writes the complete container without slicing it', async () => {
   const f = await fixture()
   assert.equal((await f.device.firmware.update({ ...f.request, data: f.full, mode: 'install' })).verified, true)
-  assert.deepEqual(f.flash, f.full)
+  assert.deepEqual(f.flash.slice(0, f.full.length), f.full)
+  assert.ok(f.flash.subarray(0x20000).every(value => value === 0xff))
   assert.deepEqual(f.calls.find(call => Array.isArray(call) && call[0] === 'write'), ['write', 0, f.full.length])
 })
 test('single BIN application update still refuses changed partition layouts with no install fallback', async () => {

package/tests/test-host-checks.mjs

@@ -0,0 +1,47 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert/strict'
+import { spawnSync } from 'node:child_process'
+import { copyFile, cp, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+import { test } from 'node:test'
+import { npmCommand } from '../scripts/npm-command.mjs'
+
+const root = fileURLToPath(new URL('../', import.meta.url))
+
+test('npm execution preserves Unicode, spaces and shell metacharacters as literal arguments', async t => {
+  const directory = await mkdtemp(join(tmpdir(), 'core npm 中文 '))
+  t.after(() => rm(directory, { recursive: true, force: true }))
+  const cli = join(directory, 'npm entry.cjs')
+  await writeFile(cli, 'process.stdout.write(JSON.stringify(process.argv.slice(2))); process.exitCode = 7\n')
+  const args = ['pack', '中文 path', '& echo forbidden', '$(forbidden)', '%PATH%']
+  const env = { ...process.env, npm_execpath: cli }
+  const result = spawnSync(...npmCommand(args, env), { env, encoding: 'utf8' })
+  assert.equal(result.status, 7, result.stderr)
+  assert.deepEqual(JSON.parse(result.stdout), args)
+})
+
+test('schema check accepts checkout CRLF but rejects a real artifact change', async t => {
+  const directory = await mkdtemp(join(tmpdir(), 'core schema '))
+  t.after(() => rm(directory, { recursive: true, force: true }))
+  await mkdir(join(directory, 'scripts'))
+  await mkdir(join(directory, 'schemas'))
+  await cp(join(root, 'src'), join(directory, 'src'), { recursive: true })
+  await copyFile(join(root, 'package.json'), join(directory, 'package.json'))
+  const script = join(directory, 'scripts/generate-action-schema.mjs')
+  await copyFile(join(root, 'scripts/generate-action-schema.mjs'), script)
+  const schema = join(directory, 'schemas/device-actions-v1.json')
+  const original = (await readFile(join(root, 'schemas/device-actions-v1.json'), 'utf8')).replaceAll('\r\n', '\n')
+  await writeFile(schema, original.replaceAll('\n', '\r\n'))
+  const current = spawnSync(process.execPath, [script, '--check'], { encoding: 'utf8' })
+  assert.equal(current.status, 0, current.stderr)
+  const changed = JSON.parse(original)
+  changed.deviceCoreVersion = '0.0.0'
+  await writeFile(schema, JSON.stringify(changed, null, 2).replaceAll('\n', '\r\n') + '\r\n')
+  const stale = spawnSync(process.execPath, [script, '--check'], { encoding: 'utf8' })
+  assert.notEqual(stale.status, 0)
+  assert.match(stale.stderr, /Device Action schema artifact is stale/)
+})

package/tests/test-install-erase.mjs

@@ -0,0 +1,153 @@
+// 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 { FirmwareFlashSession, firmwareSha256 } from '../src/firmware_flash.js'
+import { installFixture, partitionTable } from './firmware-fixtures.mjs'
+
+const entries = () => [
+  { label: 'nvs', type: 1, subtype: 2, offset: 0x9000, size: 0x6000 },
+  { label: 'factory', type: 0, subtype: 0, offset: 0x10000, size: 0x10000 },
+  { label: 'ffat', type: 1, subtype: 0x81, offset: 0x20000, size: 0x21000 },
+]
+async function replaceTable(f, raw) {
+  f.data.fill(0xff, 0x8000, 0x8c00)
+  f.data.set(raw, 0x8000)
+  f.release.image.partitionTable.bytes = raw.length
+  f.release.image.partitionTable.sha256 = await firmwareSha256(raw)
+  f.release.install.sha256 = await firmwareSha256(f.data)
+}
+const destructive = f => f.calls.filter(call => Array.isArray(call) && ['erase', 'write'].includes(call[0]))
+
+for (const mutation of ['no-ffat', 'legacy-vfs', 'wrong-type', 'wrong-subtype', 'encrypted', 'readonly', 'unknown-flags',
+  'unaligned-offset', 'unaligned-size', 'zero-size', 'outside-flash', 'overlap', 'duplicate-label', 'wrong-app', 'reserved-range']) {
+  test(`install refuses ${mutation} in a hash-approved table before opening ROM`, async () => {
+    const f = await installFixture(), parts = entries(), fat = parts[2]
+    if (mutation === 'no-ffat') parts.pop()
+    if (mutation === 'legacy-vfs') fat.label = 'vfs'
+    if (mutation === 'wrong-type') fat.type = 0x40
+    if (mutation === 'wrong-subtype') fat.subtype = 0x82
+    if (mutation === 'encrypted') fat.flags = 1
+    if (mutation === 'readonly') fat.flags = 2
+    if (mutation === 'unknown-flags') fat.flags = 4
+    if (mutation === 'unaligned-offset') fat.offset++
+    if (mutation === 'unaligned-size') fat.size--
+    if (mutation === 'zero-size') fat.size = 0
+    if (mutation === 'outside-flash') fat.size = 0x1000000
+    if (mutation === 'overlap') fat.offset = 0x1f000
+    if (mutation === 'duplicate-label') parts[0].label = 'ffat'
+    if (mutation === 'wrong-app') parts[1].size = 0x1000
+    if (mutation === 'reserved-range') parts[0].offset = 0x8000
+    await replaceTable(f, partitionTable(parts))
+    await assert.rejects(f.device.firmware.update(f.request), error => ['FIRMWARE_PARTITION_INVALID', 'FIRMWARE_FATFS_UNAVAILABLE'].includes(error.code))
+    assert.deepEqual(f.calls, [])
+  })
+}
+
+for (const mutation of ['bad-magic', 'bad-md5', 'duplicate-md5', 'entry-after-md5', 'data-after-end', 'short-table', 'missing-end', 'empty']) {
+  test(`install refuses ${mutation} despite an approved outer SHA`, async () => {
+    const f = await installFixture(), raw = partitionTable(entries())
+    if (mutation === 'bad-magic') raw[0] ^= 1
+    if (mutation === 'bad-md5') raw[112] ^= 1
+    if (mutation === 'duplicate-md5') raw.copyWithin(128, 96, 128)
+    if (mutation === 'entry-after-md5') raw.copyWithin(128, 0, 32)
+    if (mutation === 'data-after-end') raw[200] = 0
+    if (mutation === 'empty') raw.fill(0xff)
+    await replaceTable(f, mutation === 'short-table' ? raw.subarray(0, 129) : mutation === 'missing-end' ? raw.subarray(0, 128) : raw)
+    await assert.rejects(f.device.firmware.update(f.request), { code: 'FIRMWARE_PARTITION_INVALID' })
+    assert.deepEqual(f.calls, [])
+  })
+}
+
+test('historical tables without MD5 are accepted with their SHA and FF end marker', async () => {
+  const f = await installFixture()
+  await replaceTable(f, partitionTable(entries(), { md5: false }))
+  assert.equal((await f.device.firmware.update(f.request)).verified, true)
+  assert.deepEqual(destructive(f), [['erase', 0x20000, 0x21000], ['write', 0]])
+})
+
+for (const failure of ['erase', 'read', 'short-read', 'not-erased', 'missing-erase', 'missing-read', 'missing-write']) {
+  test(`${failure} cannot write firmware, reset, or report complete installation`, async () => {
+    const f = await installFixture(), progress = [], read = f.loader.readFlash
+    if (failure === 'erase') f.loader.eraseRegion = async () => { f.calls.push(['erase', 0x20000, 0x21000]); throw new Error('erase denied') }
+    if (failure === 'read') f.loader.readFlash = async () => { throw new Error('port lost') }
+    if (failure === 'short-read') f.loader.readFlash = async () => new Uint8Array(1).fill(0xff)
+    if (failure === 'not-erased') f.loader.readFlash = async (offset, count) => { const result = await read(offset, count); result[0] = 0; return result }
+    if (failure === 'missing-erase') delete f.loader.eraseRegion
+    if (failure === 'missing-read') delete f.loader.readFlash
+    if (failure === 'missing-write') delete f.loader.flashData
+    await assert.rejects(f.device.firmware.update({ ...f.request, onProgress: value => progress.push(value) }))
+    assert.ok(!destructive(f).some(call => call[0] === 'write'))
+    assert.ok(!f.calls.includes('reset'))
+    assert.ok(!progress.includes(100))
+    assert.equal(f.calls.at(-1), 'close')
+    assert.ok(destructive(f).length <= 1, 'never retry an uncertain erase')
+    if (failure.startsWith('missing-')) assert.deepEqual(destructive(f), [])
+  })
+}
+
+for (const point of ['before-erase', 'during-erase', 'during-read', 'last-erase-progress', 'before-write']) {
+  test(`cancellation ${point} stops installation before any firmware write`, async () => {
+    const f = await installFixture(), controller = new AbortController(), reason = new Error('cancel install')
+    const erase = f.loader.eraseRegion, read = f.loader.readFlash
+    if (point === 'during-erase') f.loader.eraseRegion = async (...args) => { await erase(...args); controller.abort(reason) }
+    if (point === 'during-read') f.loader.readFlash = async (...args) => { const result = await read(...args); controller.abort(reason); return result }
+    await assert.rejects(f.device.firmware.update({ ...f.request, signal: controller.signal,
+      onPhase: text => { if ((point === 'before-erase' && text.startsWith('Erasing')) || (point === 'before-write' && text.startsWith('Installing'))) controller.abort(reason) },
+      onProgress: percent => { if (point === 'last-erase-progress' && percent === 20) controller.abort(reason) },
+    }), error => error === reason)
+    assert.ok(!destructive(f).some(call => call[0] === 'write'))
+    assert.ok(!f.calls.includes('reset'))
+  })
+}
+
+test('application update preserves the FAT sentinel and never reads or erases FFAT', async () => {
+  const f = await installFixture(), table = f.release.image.partitionTable
+  f.flash.set(f.data.subarray(table.offset, table.offset + table.bytes), table.offset)
+  const before = f.flash.slice()
+  await f.device.firmware.update({ ...f.request, mode: 'update', data: f.data.slice(0x10000, 0x10004) })
+  assert.deepEqual(f.flash.subarray(0x20000), before.subarray(0x20000))
+  assert.deepEqual(destructive(f), [['write', 0x10000]])
+  assert.deepEqual(f.calls.filter(call => Array.isArray(call) && call[0] === 'read'), [['read', 0x8000], ['read', 0x10000]])
+})
+
+function installationImage(f) {
+  return { ...f.release.image, ...f.release.install, application: f.release.image,
+    chipRevision: undefined, chipRevisionMin: 302, chipRevisionMax: 302 }
+}
+
+test('metadata and Buffer mutations cannot change qualified erase or write ranges', async () => {
+  const f = await installFixture(), original = f.data.slice(), buffer = Buffer.from(f.data)
+  const image = installationImage(f), session = new FirmwareFlashSession(f.loader, image, { mode: 'install' })
+  await session.connect(buffer)
+  image.sha256 = '0'.repeat(64); image.flashSize = 0x4000000; image.partitionTable.offset = 0
+  session.mode = 'update'
+  await session.flash(buffer, { onPhase: () => buffer.fill(0) })
+  assert.deepEqual(destructive(f), [['erase', 0x20000, 0x21000], ['write', 0]])
+  assert.deepEqual(f.flash.slice(0, original.length), original)
+})
+
+test('a different image after connection rejects before erase even if public metadata changes', async () => {
+  const f = await installFixture(), session = new FirmwareFlashSession(f.loader, installationImage(f), { mode: 'install' })
+  await session.connect(f.data)
+  f.data[0] ^= 1
+  session.image.sha256 = await firmwareSha256(f.data)
+  await assert.rejects(session.flash(f.data), /SHA-256/)
+  assert.deepEqual(destructive(f), [])
+})
+
+test('secure download mode refuses installation before stub or erase', async () => {
+  const f = await installFixture()
+  f.loader.getSecurityInfo = async () => ({ flags: 4, flashCryptCnt: 0 })
+  await assert.rejects(f.device.firmware.update(f.request), /signed flashing workflow/)
+  assert.deepEqual(f.calls, ['open', 'initialize', 'close'])
+})
+
+for (const security of [{ flags: -8, flashCryptCnt: 0 }, { flags: 0, flashCryptCnt: -3 }, { flags: 0x100000000, flashCryptCnt: 0 }]) {
+  test(`invalid ROM security data ${JSON.stringify(security)} rejects before erase`, async () => {
+    const f = await installFixture()
+    f.loader.getSecurityInfo = async () => security
+    await assert.rejects(f.device.firmware.update(f.request), /security mode/)
+    assert.deepEqual(f.calls, ['open', 'initialize', 'close'])
+  })
+}

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

@@ -265,10 +265,12 @@ test('recovery never repeats a previous active handoff or uses an incomplete pre
   }
 })
 
-test('same ROM or no runtime returns null without issuing a bootloader command', async () => {
+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)
   }
@@ -303,3 +305,81 @@ test('read-only recovery honors cancel and fresh-enumeration deadline', async ()
   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

@@ -6,7 +6,7 @@ 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 } = {}) {
+function fixture({ mac = 'e8f60ae75642', expected = mac, prepare, initializeError, operationError, readResult = 'QUI=', stubResult = { stubRunning: true }, holdErase = false } = {}) {
   const calls = [], requests = []
   const child = new EventEmitter()
   child.exitCode = null
@@ -15,10 +15,14 @@ function fixture({ mac = 'e8f60ae75642', expected = mac, prepare, initializeErro
     write(data, encoding, done) {
       const request = JSON.parse(data.toString())
       requests.push(request)
-      queueMicrotask(() => child.stdout.write(JSON.stringify(request.method === 'initialize' && initializeError
-        ? { id: request.id, error: 'ROM_OPERATION_FAILED', method: 'initialize', detail: initializeError }
+      const detail = request.method === 'initialize' ? initializeError
+        : typeof operationError === 'function' ? operationError(request) : operationError
+      if (request.method === 'eraseRegion' && holdErase) { done(); return }
+      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' } : null }) + '\n'))
+          ? { chipFamily: 0x3280, chipRevision: 302, chipMac: mac, connectionMode: 'no-reset' }
+          : request.method === 'read' ? readResult : request.method === 'stub' ? stubResult : null }) + '\n'))
       done()
     },
     final(done) { child.exitCode = 0; queueMicrotask(() => child.emit('exit', 0)); done() },
@@ -158,3 +162,154 @@ test('a second initialization sync failure cannot trigger a third process or han
   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() }
+})
+
+test('Node region erase requires the validated stub and sends only the exact qualified range', async () => {
+  const f = fixture(), loader = openNodeRom({ port: '/dev/runtime' }, f.dependencies)
+  try {
+    await assert.rejects(loader.eraseRegion(0x710000, 4096), { code: 'ROM_NOT_INITIALIZED' })
+    await loader.initialize()
+    await assert.rejects(loader.eraseRegion(0x710000, 4096), { code: 'ROM_STUB_REQUIRED' })
+    const stub = await loader.runStub()
+    assert.equal(stub, loader); assert.equal(stub.IS_STUB, true)
+    await stub.eraseRegion(0x710000, 0x8f0000)
+    await stub.eraseRegion(0xfffff000, 4096)
+    assert.deepEqual(f.requests.map(r => [r.method, r.args]), [
+      ['initialize', []], ['stub', []], ['eraseRegion', [0x710000, 0x8f0000]],
+      ['eraseRegion', [0xfffff000, 4096]],
+    ])
+  } finally { await loader.disconnect() }
+  assert.equal(loader.IS_STUB, false)
+  await assert.rejects(loader.eraseRegion(0x710000, 4096), { code: 'ROM_CLOSED' })
+})
+
+test('invalid Node erase ranges issue no child request', async () => {
+  const f = fixture(), loader = openNodeRom({ port: '/dev/runtime' }, f.dependencies)
+  try {
+    await loader.initialize(); await loader.runStub()
+    for (const [address, size] of [[-4096, 4096], [1, 4096], [0, 0], [0, 1], [0, 0x100000000],
+      [0xfffff000, 8192], [NaN, 4096], [true, 4096], [0, true], [0x100000000, 4096]]) {
+      await assert.rejects(loader.eraseRegion(address, size), RangeError)
+    }
+    assert.deepEqual(f.requests.map(r => r.method), ['initialize', 'stub'])
+  } finally { await loader.disconnect() }
+})
+
+test('unconfirmed Node stub responses close the process before any erase', async () => {
+  for (const stubResult of [null, {}, { stubRunning: false }, { stubRunning: 1 }]) {
+    const f = fixture({ stubResult }), loader = openNodeRom({ port: '/dev/runtime' }, f.dependencies)
+    await loader.initialize()
+    await assert.rejects(loader.runStub(), { code: 'ROM_STUB_REQUIRED' })
+    await assert.rejects(loader.eraseRegion(0x710000, 4096), { code: 'ROM_CLOSED' })
+    assert.deepEqual(f.requests.map(r => r.method), ['initialize', 'stub'])
+    assert.equal(f.child.exitCode, 0)
+  }
+})
+
+test('Node erase failure keeps official diagnostics and prevents later writes or recovery', async () => {
+  const f = fixture({ operationError: request => request.method === 'eraseRegion' ? 'Erase command rejected' : undefined })
+  let recoveries = 0
+  const loader = openNodeRom({ port: '/dev/runtime' }, { ...f.dependencies,
+    recoverPort: async () => { recoveries++; throw new Error('Erase must not recover') },
+  })
+  await loader.initialize(); await loader.runStub()
+  await assert.rejects(loader.eraseRegion(0x710000, 4096), error => error.code === 'ROM_OPERATION_FAILED'
+    && error.operation === 'eraseRegion' && error.cause === 'Erase command rejected')
+  await assert.rejects(loader.flashData(new Uint8Array([1]), () => {}, 0), { code: 'ROM_CLOSED' })
+  await assert.rejects(loader.eraseRegion(0x710000, 4096), { code: 'ROM_CLOSED' })
+  assert.equal(recoveries, 0)
+  assert.deepEqual(f.requests.map(r => r.method), ['initialize', 'stub', 'eraseRegion'])
+})
+
+test('Node erase cancellation or port loss closes the in-flight request without success or retry', async () => {
+  for (const cancelled of [true, false]) {
+    const f = fixture({ holdErase: true }), controller = new AbortController()
+    const loader = openNodeRom({ port: '/dev/runtime', signal: controller.signal }, f.dependencies)
+    await loader.initialize(); await loader.runStub()
+    const erasing = loader.eraseRegion(0x710000, 4096)
+    const failed = assert.rejects(erasing, { code: cancelled ? 'CANCELLED' : 'ROM_CLOSED' })
+    if (cancelled) controller.abort()
+    else { f.child.exitCode = 1; f.child.emit('exit', 1) }
+    await failed
+    await assert.rejects(loader.flashData(new Uint8Array([1]), () => {}, 0), { code: 'ROM_CLOSED' })
+    assert.deepEqual(f.requests.map(r => r.method), ['initialize', 'stub', 'eraseRegion'])
+  }
+})
+
+test('a previously cancelled Node erase never sends a command', async () => {
+  const f = fixture(), controller = new AbortController()
+  const loader = openNodeRom({ port: '/dev/runtime', signal: controller.signal }, f.dependencies)
+  await loader.initialize(); await loader.runStub(); controller.abort()
+  await assert.rejects(loader.eraseRegion(0x710000, 4096), { name: 'AbortError' })
+  assert.deepEqual(f.requests.map(r => r.method), ['initialize', 'stub'])
+  assert.equal(f.child.exitCode, 0)
+})