@esp-vision/device-core 0.1.0 → 0.2.0

package/tests/test-device-execution.mjs

@@ -0,0 +1,294 @@
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { DeviceSession } from '../src/device_session.js'
+import { EvMuxParser, makeEvMuxFrame } from '../src/evmux.js'
+import { EvRepl } from '../src/evrepl.js'
+
+function executionFixture({ short = false, failWrite = false, failStop = false, stalledReset = false } = {}) {
+  const requests = []
+  let running = false
+  let sentinel = null
+  let terminal = ''
+  let session
+  let resetRequested = false
+  let resetPolls = 0
+  let uploaded = 0
+  const stdout = (payload) => session.feedBytes(makeEvMuxFrame({
+    channel: 'repl.stdout', type: 'data', sessionId: session.sessionId, vmEpoch: session.vmEpoch, payload,
+  }))
+  const finish = () => {
+    running = false
+    if (sentinel) {
+      stdout(`${sentinel.line}${sentinel.marker}\r\n>>> `)
+      sentinel = null
+    }
+  }
+  const parser = new EvMuxParser({
+    filterFrame: (metadata, bytes) => {
+      const text = new TextDecoder().decode(bytes)
+      const payload = metadata.encoding === 'binary' ? bytes : metadata.channel.endsWith('.rpc') ? JSON.parse(text) : text
+      requests.push({ metadata, payload })
+      if (metadata.channel === 'repl.signal') return
+      if (metadata.channel === 'repl.stdin') {
+        if (text.includes('machine.soft_reset')) {
+          resetRequested = true
+          return
+        }
+        const match = /print\("(~~EVSCRIPT-END:[^"]+)"\)/.exec(text)
+        if (match) {
+          sentinel = { line: text, marker: match[1] }
+          if (short) finish()
+        } else {
+          stdout(`${text}\r\n>>> `)
+        }
+        return
+      }
+      let response = { ok: true }
+      let responseEpoch = session.vmEpoch
+      if (metadata.method === 'session.keepalive' && resetRequested) {
+        resetPolls += 1
+        responseEpoch = stalledReset || resetPolls === 1 ? 1 : 2
+        response = { ok: true, sessionId: session.sessionId, vmEpoch: responseEpoch,
+          vmReady: stalledReset || resetPolls === 1 || resetPolls >= 3 }
+      }
+      if (metadata.method === 'file.write') {
+        if (payload instanceof Uint8Array) {
+          uploaded = new DataView(payload.buffer, payload.byteOffset, payload.byteLength).getUint32(16, true) + payload.length - 20
+          response = { ok: true, writtenBytes: uploaded }
+        } else if (payload.action === 'begin') {
+          uploaded = 0; response = { ok: true, uploadId: payload.uploadId, chunkBytes: 16384 }
+        } else response = { ok: true, bytes: uploaded, complete: payload.action === 'commit' }
+      }
+      if (metadata.method === 'file.write' && failWrite) {
+        response = { ok: false, error: { code: 'WRITE_FAILED', message: 'simulated write failure' } }
+      } else if (metadata.method === 'script.run') {
+        running = true
+        stdout('streaming output\r\n')
+      } else if (metadata.method === 'device.control' && payload.action === 'stop' && failStop) {
+        response = { ok: false, error: { code: 'TX_BUSY', message: 'simulated stop failure' } }
+      }
+      session.feedBytes(makeEvMuxFrame({
+        channel: metadata.channel, type: 'rsp', method: metadata.method, seq: metadata.seq,
+        sessionId: session.sessionId, vmEpoch: responseEpoch, payload: JSON.stringify(response),
+      }))
+      if (metadata.method === 'device.control' && payload.action === 'stop' && !failStop) finish()
+    },
+  })
+  session = new DeviceSession({
+    transport: { async writeBytes(bytes) { parser.feedBytes(bytes) } },
+    EvMuxParser, makeEvMuxFrame, EvRepl, sleep: async () => {},
+    handlers: { text: (text) => { terminal += text } },
+  })
+  session.state = 'ready'
+  session.sessionId = 'a'.repeat(32)
+  session.vmEpoch = 1
+  session.vmReady = true
+  session.limits.fileWriteChunkMax = 16384
+  session.capabilities = { features: ['file.write.binary', 'script.run', 'device.control'] }
+  return { session, requests, finish, get terminal() { return terminal }, get running() { return running } }
+}
+
+test('interactive execution survives the bounded-run deadline, streams output, and completes on shared stop', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] })
+  const fixture = executionFixture()
+  t.after(() => fixture.session.close())
+  const run = await fixture.session.startScript('/main.py', 'while True: pass')
+  let completed = false
+  run.done.then(() => { completed = true })
+  t.mock.timers.tick(20000)
+  await Promise.resolve()
+  assert.equal(completed, false)
+  assert.equal(fixture.running, true)
+  assert.match(fixture.terminal, /streaming output/)
+  assert.equal(fixture.session.scriptRunSnapshot().output, '', 'interactive terminal output is not stored a second time')
+  const beforeDuplicate = fixture.requests.length
+  await assert.rejects(fixture.session.startScript('/other.py', 'pass'), /already running/)
+  assert.equal(fixture.requests.length, beforeDuplicate, 'duplicate start does not interrupt the existing run')
+  await fixture.session.control('stop')
+  assert.equal((await run.done).ok, true)
+  assert.equal(fixture.session.scriptRunSnapshot(), null)
+  assert.ok(!fixture.terminal.includes('~~EVSCRIPT-END'), 'shared completion markers never leak into terminal output')
+})
+
+test('short scripts can complete while startScript is returning', async () => {
+  const fixture = executionFixture({ short: true })
+  const run = await fixture.session.startScript('/short.py', 'print(1)')
+  assert.equal((await run.done).path, '/short.py')
+  assert.equal(fixture.session.scriptRunSnapshot(), null)
+  fixture.session.close()
+})
+
+test('parallel starts cannot overwrite the shared execution lifecycle during upload', async () => {
+  const fixture = executionFixture()
+  const starting = fixture.session.startScript('/first.py', 'pass')
+  await assert.rejects(fixture.session.startScript('/second.py', 'pass'), /already running/)
+  const first = await starting
+  assert.equal(fixture.requests.filter(({ metadata }) => metadata.method === 'script.run').length, 1)
+  fixture.finish()
+  await first.done
+  fixture.session.close()
+})
+
+test('startup errors reject the start handle without leaving an active run', async () => {
+  const fixture = executionFixture({ failWrite: true })
+  await assert.rejects(fixture.session.startScript('/main.py', 'pass'), (error) => error.code === 'WRITE_FAILED')
+  assert.equal(fixture.session.scriptRunSnapshot(), null)
+  assert.ok(!fixture.requests.some(({ metadata }) => metadata.method === 'script.run'))
+  fixture.session.close()
+})
+
+test('failed stop does not claim execution has finished', async () => {
+  const fixture = executionFixture({ failStop: true })
+  const run = await fixture.session.startScript('/main.py', 'while True: pass')
+  await assert.rejects(fixture.session.control('stop'), (error) => error.code === 'TX_BUSY')
+  assert.equal(fixture.running, true)
+  assert.notEqual(fixture.session.scriptRunSnapshot(), null)
+  fixture.finish()
+  await run.done
+  fixture.session.close()
+})
+
+test('bounded Agent execution still times out and sends a shared interrupt', async () => {
+  const fixture = executionFixture()
+  let started
+  const starting = new Promise(resolve => { started = resolve })
+  const done = fixture.session.runScript('/trial.py', 'while True: pass', { timeout: 30, onStarted: started })
+  const rejected = assert.rejects(done, (error) => error.code === 'SCRIPT_TIMEOUT')
+  await starting
+  await rejected
+  assert.equal(fixture.session.scriptRunSnapshot(), null)
+  await new Promise(resolve => setTimeout(resolve, 0))
+  assert.ok(fixture.requests.some(({ metadata, payload }) => metadata.method === 'device.control' && payload.action === 'stop'))
+  fixture.session.close()
+})
+
+test('VM reset and disconnect settle interactive completion and allow the next VM run', async () => {
+  const fixture = executionFixture()
+  const run = await fixture.session.startScript('/main.py', 'while True: pass')
+  const reset = assert.rejects(run.done, (error) => error.code === 'VM_EPOCH_CHANGED')
+  fixture.session.feedBytes(makeEvMuxFrame({
+    channel: 'user.rpc', type: 'event', method: 'hello', sessionId: fixture.session.sessionId, vmEpoch: 2,
+    payload: JSON.stringify({ ok: true, evMuxVersion: 4, vmEpoch: 2, vmReady: true, session: { id: fixture.session.sessionId, vmEpoch: 2 } }),
+  }))
+  await reset
+  const next = await fixture.session.startScript('/next.py', 'pass')
+  const lost = assert.rejects(next.done, /device disconnected/)
+  fixture.session.close(new Error('device disconnected'))
+  await lost
+})
+
+test('reset and bootloader controls use the shared RPC or framed REPL paths', async () => {
+  for (const operation of ['hard-reset', 'soft-reset', 'bootloader']) {
+    const fixture = executionFixture()
+    await fixture.session.control(operation)
+    if (operation === 'hard-reset') {
+      assert.deepEqual(fixture.requests.map(({ metadata, payload }) => [metadata.method, payload.action]), [['device.control', 'reset']])
+    } else {
+      assert.equal(fixture.requests[0].metadata.channel, 'repl.signal')
+      assert.equal(fixture.requests[1].metadata.channel, 'repl.stdin')
+      assert.match(fixture.requests[1].payload, operation === 'soft-reset' ? /machine\.soft_reset/ : /machine\.bootloader/)
+    }
+    fixture.session.close()
+  }
+})
+
+test('soft reset waits for a newer ready epoch and an actual REPL barrier', async () => {
+  const fixture = executionFixture()
+  try {
+    const result = await fixture.session.control('soft-reset')
+    assert.equal(result.acknowledged, true)
+    assert.equal(result.vmEpoch, 2)
+    const polls = fixture.requests.filter(({ metadata }) => metadata.method === 'session.keepalive')
+    assert.equal(polls.length, 3, 'old ready epoch and new unready epoch are insufficient')
+    const barrier = fixture.requests.at(-1)
+    assert.equal(barrier.metadata.channel, 'repl.stdin')
+    assert.equal(barrier.metadata.vmEpoch, 2)
+    assert.match(barrier.payload, /exec\("1"\)/)
+  } finally { fixture.session.close() }
+})
+
+test('soft reset times out without probing or running in the old epoch', async () => {
+  const fixture = executionFixture({ stalledReset: true })
+  try {
+    await assert.rejects(fixture.session.control('soft-reset', { timeout: 20 }), error => error.code === 'VM_RESET_TIMEOUT')
+    assert.equal(fixture.session.vmReady, false)
+    assert.equal(fixture.requests.filter(({ metadata }) => metadata.channel === 'repl.stdin').length, 1)
+  } finally { fixture.session.close() }
+})
+
+test('one lost keepalive acknowledgement retries within the same negotiated lease', async () => {
+  const f = executionFixture(), session = f.session
+  const scope = { sessionId: session.sessionId, generation: session.sessionGeneration, keepaliveGeneration: session.keepaliveGeneration }
+  let calls = 0
+  session.rpc = async (method, payload, options) => {
+    assert.equal(method, 'session.keepalive'); assert.deepEqual(payload, {}); assert.equal(options.timeout, 3000)
+    calls++
+    if (calls === 1) throw Object.assign(new Error('lost reply'), { code: 'TIMEOUT' })
+    return { ok: true, sessionId: scope.sessionId }
+  }
+  assert.equal((await session._keepaliveOnce(scope)).sessionId, scope.sessionId)
+  assert.equal(calls, 2)
+  session.close()
+})
+
+test('keepalive retry fails closed after a second timeout and never crosses owners', async () => {
+  for (const changeOwner of [false, true]) {
+    const f = executionFixture(), session = f.session
+    const scope = { sessionId: session.sessionId, generation: session.sessionGeneration, keepaliveGeneration: session.keepaliveGeneration }
+    let calls = 0
+    session.rpc = async () => {
+      calls++
+      if (changeOwner) session.sessionId = 'f'.repeat(32)
+      throw Object.assign(new Error('no reply'), { code: 'TIMEOUT' })
+    }
+    await assert.rejects(session._keepaliveOnce(scope), { code: 'TIMEOUT' })
+    assert.equal(calls, changeOwner ? 1 : 2)
+    session.close()
+  }
+})
+
+test('short leases and explicit owner errors do not retry keepalive', async () => {
+  for (const code of ['TIMEOUT', 'SESSION_REQUIRED']) {
+    const f = executionFixture(), session = f.session
+    session.leaseMs = 6000
+    const scope = { sessionId: session.sessionId, generation: session.sessionGeneration, keepaliveGeneration: session.keepaliveGeneration }
+    let calls = 0
+    session.rpc = async () => { calls++; throw Object.assign(new Error(code), { code }) }
+    await assert.rejects(session._keepaliveOnce(scope), { code })
+    assert.equal(calls, 1)
+    session.close()
+  }
+})
+
+test('soft reset total deadline also bounds a stalled REPL barrier', async () => {
+  const fixture = executionFixture()
+  fixture.session.repl.execPy = () => new Promise(() => {})
+  const started = Date.now()
+  try {
+    await assert.rejects(fixture.session.control('soft-reset', { timeout: 40 }), { code: 'VM_RESET_TIMEOUT' })
+    assert.ok(Date.now() - started < 500, 'must not inherit the separate five-second barrier budget')
+  } finally { fixture.session.close() }
+})
+
+test('soft reset cancellation reaches the REPL barrier', async () => {
+  const fixture = executionFixture()
+  const controller = new AbortController()
+  fixture.session.repl.execPy = (_source, { signal }) => {
+    assert.ok(signal)
+    queueMicrotask(() => controller.abort())
+    return new Promise(() => {})
+  }
+  try {
+    await assert.rejects(fixture.session.control('soft-reset', { signal: controller.signal }), { name: 'AbortError' })
+  } finally { fixture.session.close() }
+})
+
+test('soft reset deadline includes a stalled initial transport write', async () => {
+  const fixture = executionFixture()
+  fixture.session.transport.writeBytes = () => new Promise(() => {})
+  try {
+    await assert.rejects(fixture.session.control('soft-reset', { timeout: 30 }), { code: 'VM_RESET_TIMEOUT' })
+    assert.equal(fixture.requests.length, 0)
+  } finally { fixture.session.close() }
+})

package/tests/test-device-files-api.mjs

@@ -0,0 +1,202 @@
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { createFilesApi } from '../src/device_files.js'
+import { EvRepl, evReplExecInputBytes } from '../src/evrepl.js'
+
+function fixture() {
+  const calls = [], state = {}
+  const session = {
+    repl: {
+      listFs: async (path, options) => {
+        calls.push(['listFs', path, options])
+        return [{ name: 'a', path: `${path === '/' ? '' : path}/a`, type: 'file', size: 10 }]
+      },
+      readFile: async (...args) => { calls.push(['read', ...args]); return new TextEncoder().encode('你好') },
+      removeFile: async (...args) => calls.push(['removeFile', ...args]),
+      removeDir: async (...args) => calls.push(['removeDir', ...args]),
+      execPy: async (...args) => { calls.push(['execPy', ...args]); return '__EVMK__ 0\n' },
+    },
+    writeFile: async (...args) => { calls.push(['write', ...args]); return { ok: true } },
+  }
+  return { files: createFilesApi({ session, state }), session, calls, state }
+}
+
+test('file upload selects encoding and creation policy from public parameters', async () => {
+  const { files, calls } = fixture()
+  const onProgress = () => {}, signal = new AbortController().signal
+  await files.write({ path: '/model.bin', data: new Uint8Array([0, 255]), overwrite: false, onProgress, signal })
+  assert.deepEqual(calls[0], ['write', '/model.bin', new Uint8Array([0, 255]), { encoding: 'binary', mode: 'create', onProgress, signal }])
+  await files.write({ path: '/main.py', data: 'print(1)' })
+  assert.equal(calls[1][3].encoding, 'utf-8')
+  assert.equal(calls[1][3].mode, 'overwrite')
+})
+
+test('file read is binary by default with explicit UTF-8 decoding and bounded options', async () => {
+  const { files, calls } = fixture()
+  assert.ok(await files.read({ path: '/model.bin' }) instanceof Uint8Array)
+  assert.equal(await files.read({ path: '/a.txt', encoding: 'utf-8', maxBytes: 512 }), '你好')
+  assert.equal(calls[1][2].maxBytes, 512)
+})
+
+test('file listing passes scoped path and recursion without walking the entire device', async () => {
+  const { files, calls } = fixture()
+  assert.deepEqual(await files.list({ path: '/folder' }), [{ name: 'a', path: '/folder/a', type: 'file', size: 10 }])
+  assert.deepEqual(calls[0], ['listFs', '/folder', { recursive: false, signal: undefined }])
+  await files.list({ recursive: true })
+  assert.equal(calls[1][2].recursive, true)
+})
+
+test('REPL directory listing confines recursion to selected subtree and validates missing directories', async () => {
+  const repl = new EvRepl({ writeEvmux() {} })
+  const seen = []
+  repl.execPy = async source => {
+    const path = /p=("[^"\n]*")/.exec(source)[1]
+    seen.push(JSON.parse(path))
+    return '__EVLIST__' + JSON.stringify(seen.length === 1 ? [['deep', 0x4000, 0], ['a.bin', 0x8000, 12]] : [['b.bin', 0x8000, 20]])
+  }
+  assert.equal((await repl.listFs('/models')).length, 2)
+  assert.deepEqual(seen, ['/models'])
+  seen.length = 0
+  const entries = await repl.listFs('/models', { recursive: true })
+  assert.deepEqual(seen, ['/models', '/models/deep'])
+  assert.equal(entries[2].path, '/models/deep/b.bin')
+  repl.execPy = async () => '__EVLIST__2'
+  await assert.rejects(repl.listFs('/missing'), { code: 'NOT_FOUND', errno: 2 })
+  repl.execPy = async () => '__EVLIST__20'
+  await assert.rejects(repl.listFs('/models/a.bin'), { code: 'NOT_DIRECTORY' })
+})
+
+test('recursive listing cancellation prevents traversal of the next directory', async () => {
+  const repl = new EvRepl({ writeEvmux() {} })
+  const controller = new AbortController()
+  let calls = 0
+  repl.execPy = async (_source, { signal }) => {
+    assert.equal(signal, controller.signal)
+    calls++
+    controller.abort()
+    return '__EVLIST__[["deep",16384,0]]'
+  }
+  await assert.rejects(repl.listFs('/models', { recursive: true, signal: controller.signal }), { name: 'AbortError' })
+  assert.equal(calls, 1)
+})
+
+test('delete explicitly distinguishes file and directory and forwards cancellation', async () => {
+  const { files, calls } = fixture()
+  const signal = new AbortController().signal
+  await files.remove({ path: '/a', signal })
+  await files.remove({ path: '/b', type: 'directory', signal })
+  assert.deepEqual(calls, [['removeFile', '/a', { signal }], ['removeDir', '/b', { signal }]])
+})
+
+test('directory creation honors recursive mode and surfaces filesystem errors', async () => {
+  const { files, calls, session } = fixture()
+  await files.mkdir({ path: '/a/b', recursive: true })
+  assert.equal(calls.length, 2)
+  assert.match(calls[0][1], /p="\/a"/)
+  assert.match(calls[1][1], /p="\/a\/b"/)
+  assert.match(calls[0][1], /os.stat\(p\)\[0\]&16384/)
+  session.repl.execPy = async () => '__EVMK__ 28'
+  await assert.rejects(files.mkdir({ path: '/a' }), { code: 'FILESYSTEM_ERROR', errno: 28 })
+})
+
+test('rejects dangerous paths, unsupported data, mode confusion and pre-cancellation before writes', async () => {
+  const { files, calls } = fixture()
+  for (const path of ['relative', '/', '/a/../b', '/a//b', '/a\0b', '/a"b', '/a\\b', '/' + '中'.repeat(42)]) {
+    await assert.rejects(files.write({ path, data: 'x' }), { code: 'INVALID_PATH' })
+  }
+  for (const data of [null, {}, [], 12]) await assert.rejects(files.write({ path: '/a', data }), TypeError)
+  await assert.rejects(files.write({ path: '/a', data: '', overwrite: 'yes' }), TypeError)
+  await assert.rejects(files.write({ path: '/a', data: '', runAfterWrite: true }), TypeError)
+  await assert.rejects(files.write({ path: '/a', data: '', signal: AbortSignal.abort() }), { name: 'AbortError' })
+  assert.equal(calls.length, 0)
+})
+
+test('shared lock excludes concurrent filesystem work and releases after failure', async () => {
+  const { files, session, state } = fixture()
+  let fail
+  session.writeFile = async () => new Promise((_resolve, reject) => { fail = reject })
+  const writing = files.write({ path: '/a', data: 'x' })
+  await assert.rejects(files.read({ path: '/a' }), { code: 'DEVICE_BUSY' })
+  fail(new Error('disk full'))
+  await assert.rejects(writing, /disk full/)
+  assert.equal(state.operation, null)
+  await files.read({ path: '/a' })
+})
+
+test('every file operation rejects unknown fields and invalid signals before device I/O', async () => {
+  const { files, calls } = fixture()
+  for (const [method, options] of [
+    ['list', { path: '/' }], ['read', { path: '/a' }], ['write', { path: '/a', data: 'x' }],
+    ['remove', { path: '/a' }], ['mkdir', { path: '/a' }],
+  ]) {
+    await assert.rejects(files[method]({ ...options, typo: true }), /Unknown files\./)
+    await assert.rejects(files[method]({ ...options, signal: {} }), TypeError)
+  }
+  for (const maxBytes of [-1, 0.5, '1', 16 * 1024 * 1024 + 1]) await assert.rejects(files.read({ path: '/a', maxBytes }), RangeError)
+  assert.equal(calls.length, 0)
+})
+
+test('file paths and caller byte buffers are snapshotted before asynchronous writing', async () => {
+  const { files, session } = fixture()
+  let release, observed, reads = 0
+  session.writeFile = async (path, data) => {
+    await new Promise(resolve => { release = resolve })
+    observed = { path, bytes: Array.from(data) }
+  }
+  // Buffer.slice() shares backing memory; the API must copy all Uint8Array subclasses.
+  const data = Buffer.from([0, 127, 255])
+  const request = { get path() { reads++; return reads === 1 ? '/safe.bin' : '/other.bin' }, data }
+  const writing = files.write(request)
+  data.fill(1)
+  release()
+  await writing
+  assert.equal(reads, 1)
+  assert.deepEqual(observed, { path: '/safe.bin', bytes: [0, 127, 255] })
+})
+
+
+test('recursive mkdir keeps longest legal Unicode paths inside the real REPL input budget', async () => {
+  const { files, session } = fixture()
+  const commands = []
+  session.repl.execPy = async source => {
+    commands.push(source)
+    assert.ok(evReplExecInputBytes(source) <= 511, `REPL input is ${evReplExecInputBytes(source)} bytes`)
+    return '__EVMK__ 0'
+  }
+  await files.mkdir({ path: '/' + '中'.repeat(40), recursive: true })
+  await files.mkdir({ path: '/' + 'a'.repeat(59) + '/' + '中'.repeat(20), recursive: true })
+  assert.equal(commands.length, 3)
+  await files.mkdir({ path: '/' + 'é'.repeat(61), recursive: true })
+  assert.equal(commands.length, 5, 'two-byte Unicode paths split assignment from the fixed mkdir command')
+})
+
+test('recursive mkdir checks existing entry type and preserves errors for files', async () => {
+  const { files, session } = fixture()
+  const commands = []
+  session.repl.execPy = async source => { commands.push(source); return '__EVMK__ 0' }
+  await files.mkdir({ path: '/existing/child', recursive: true })
+  assert.match(commands[0], /if r==17:/)
+  assert.match(commands[0], /0 if os.stat\(p\)\[0\]&16384 else 20/)
+  session.repl.execPy = async () => '__EVMK__ 20'
+  await assert.rejects(files.mkdir({ path: '/existing-file/child', recursive: true }), { code: 'FILESYSTEM_ERROR', errno: 20 })
+  session.repl.execPy = async source => {
+    assert.ok(!source.includes('if r==17:'))
+    return '__EVMK__ 17'
+  }
+  await assert.rejects(files.mkdir({ path: '/already-exists' }), { code: 'FILESYSTEM_ERROR', errno: 17 })
+})
+
+test('recursive mkdir cancellation prevents creating the next path segment', async () => {
+  const { files, session } = fixture()
+  const controller = new AbortController()
+  let calls = 0
+  session.repl.execPy = async (_source, { signal }) => {
+    assert.equal(signal, controller.signal)
+    calls++
+    controller.abort()
+    return '__EVMK__ 0'
+  }
+  await assert.rejects(files.mkdir({ path: '/parent/child', recursive: true, signal: controller.signal }), { name: 'AbortError' })
+  assert.equal(calls, 1)
+})

package/tests/test-device-firmware.mjs

@@ -0,0 +1,133 @@
+/* SPDX-FileCopyrightText: 2026 ESP-VISION-IDE
+ * 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([0xe9, 1, 2, 3]), table = new Uint8Array([4, 5]), calls = []
+  const release = { board: 'BOARD', version: '2026.10.15', image: { evMuxVersion: 4, chipFamily: 0x3280, chipRevision: 302, offset: 65536, bytes: 4, partitionSize: 4096, sha256: await firmwareSha256(data), partitionTable: { offset: 32768, bytes: 2, sha256: await firmwareSha256(table) }, url: 'https://example.test/app.bin' } }
+  const stub = { async readFlash(offset) { return offset === 32768 ? table : data }, async readRegister() { return 0 }, async flashData() { calls.push('write') } }
+  const loader = { chipFamily: 0x3280, chipRevision: 302, async initialize() { calls.push('initialize') }, async getSecurityInfo() { return { flags: 0, flashCryptCnt: 0 } }, async runStub() { return stub }, async hardReset() { calls.push('reset') }, async disconnect() { calls.push('close') } }
+  const device = createDevice(), request = { release, board: 'BOARD', data, async openLoader() { calls.push('open'); return loader } }
+  return { device, release, request, data, calls, loader, stub }
+}
+test('firmware check works offline and preserves catalog order for calendar/git versions', async () => {
+  const f = await fixture(), identity = { board: 'BOARD', firmwareVersion: '2026.08.27-18-gabc' }
+  const catalog = { schemaVersion: 1, releases: [f.release, { ...f.release, version: '0.9' }] }
+  const result = await f.device.firmware.check({ catalog, identity })
+  assert.equal(result.available, true); assert.equal(result.release.version, '2026.10.15')
+  result.release.image.sha256 = 'x'; assert.notEqual(catalog.releases[0].image.sha256, 'x')
+  assert.deepEqual(f.calls, [])
+})
+test('firmware check distinguishes current firmware and unavailable board', async () => {
+  const f = await fixture(), catalog = { schemaVersion: 1, releases: [f.release] }
+  const current = await f.device.firmware.check({ catalog, identity: { board: 'BOARD', firmwareVersion: f.release.version } })
+  assert.equal(current.available, false); assert.ok(current.release)
+  const missing = await f.device.firmware.check({ catalog, identity: { board: 'OTHER', firmwareVersion: 'v1' } })
+  assert.equal(missing.available, false); assert.equal(missing.release, null)
+})
+test('firmware catalog download propagates cancellation and HTTP errors without connecting', async () => {
+  const f = await fixture(), controller = new AbortController()
+  const request = { catalog: 'https://example.test/releases.json', identity: { board: 'BOARD', firmwareVersion: 'v1' }, signal: controller.signal,
+    async fetch(url, options) { assert.equal(options.signal, controller.signal); assert.equal(options.cache, 'no-store'); return { ok: false, status: 503 } } }
+  await assert.rejects(f.device.firmware.check(request), { code: 'FIRMWARE_DOWNLOAD_FAILED' })
+  controller.abort(); await assert.rejects(f.device.firmware.check(request), { name: 'AbortError' })
+  assert.deepEqual(f.calls, [])
+})
+test('invalid catalog, wrong protocol and unknown arguments are rejected', async () => {
+  const f = await fixture(), identity = { board: 'BOARD', firmwareVersion: 'v1' }
+  for (const catalog of [{}, { schemaVersion: 1, releases: [{ ...f.release, image: { ...f.release.image, evMuxVersion: 3 } }] }]) await assert.rejects(f.device.firmware.check({ catalog, identity }), TypeError)
+  await assert.rejects(f.device.firmware.check({ catalog: 'http://example.test/releases.json', identity }), /HTTPS/)
+  await assert.rejects(f.device.firmware.check({ identity, typo: true }), /Unknown/)
+})
+test('firmware update verifies image and physical board before opening ROM', async () => {
+  const f = await fixture()
+  await assert.rejects(f.device.firmware.update({ ...f.request, board: 'OTHER' }), /board/)
+  await assert.rejects(f.device.firmware.update({ ...f.request, data: new Uint8Array(4) }), /SHA-256/)
+  assert.deepEqual(f.calls, [])
+})
+test('firmware update uses application-only verified ROM flow and returns explicit reconnect state', async () => {
+  const f = await fixture(), result = await f.device.firmware.update(f.request)
+  assert.deepEqual(result, { verified: true, needsReset: false, board: 'BOARD', version: f.release.version, reconnected: false })
+  assert.deepEqual(f.calls, ['open', 'initialize', 'write', 'reset', 'close'])
+})
+test('firmware update downloads raw application image through injected fetch', async () => {
+  const f = await fixture()
+  await f.device.firmware.update({ ...f.request, data: undefined, async fetch(url) { assert.equal(url, f.release.image.url); return { ok: true, async arrayBuffer() { return f.data.buffer } } } })
+  assert.ok(f.calls.includes('write'))
+})
+test('cancel after loader acquisition closes port without writing', async () => {
+  const f = await fixture(), controller = new AbortController()
+  await assert.rejects(f.device.firmware.update({ ...f.request, signal: controller.signal, async openLoader() { controller.abort(); return f.loader } }), { name: 'AbortError' })
+  assert.deepEqual(f.calls, ['close'])
+})
+test('active update excludes connect and concurrent update; failures release the reservation', async () => {
+  const f = await fixture(); let unblock
+  const waiting = new Promise(resolve => { unblock = resolve })
+  const active = f.device.firmware.update({ ...f.request, async openLoader() { await waiting; throw new Error('port unavailable') } })
+  await assert.rejects(f.device.connect(), { code: 'DEVICE_BUSY' })
+  await assert.rejects(f.device.firmware.update(f.request), { code: 'DEVICE_BUSY' })
+  unblock(); await assert.rejects(active, /port unavailable/)
+  assert.equal((await f.device.firmware.update(f.request)).verified, true)
+})
+test('failed readback never reports verified or resets the device', async () => {
+  const f = await fixture(); f.stub.readFlash = async offset => offset === 32768 ? new Uint8Array([4, 5]) : new Uint8Array(4)
+  await assert.rejects(f.device.firmware.update(f.request), /verification failed/)
+  assert.ok(!f.calls.includes('reset')); assert.equal(f.calls.at(-1), 'close')
+})
+test('reset failure returns verified with explicit manual reset requirement', async () => {
+  const f = await fixture(); f.loader.hardReset = async () => { throw new Error('reset unavailable') }
+  assert.equal((await f.device.firmware.update(f.request)).needsReset, true)
+})
+
+test('firmware check lists all board versions and selects an explicit older version', async () => {
+  const f = await fixture(), older = { ...f.release, version: '2026.08.27' }
+  const request = { catalog: { schemaVersion: 1, releases: [f.release, { ...f.release, board: 'OTHER' }, older] }, identity: { board: 'BOARD', firmwareVersion: f.release.version } }
+  const history = await f.device.firmware.check(request)
+  assert.deepEqual(history.releases.map(item => item.version), [f.release.version, older.version])
+  assert.equal(history.available, false)
+  const selected = await f.device.firmware.check({ ...request, version: older.version })
+  assert.equal(selected.available, true); assert.equal(selected.release.version, older.version)
+  assert.equal((await f.device.firmware.update({ ...f.request, release: selected.release })).version, older.version)
+})
+test('an unavailable or ambiguous requested version never falls back to the latest build', async () => {
+  const f = await fixture(), request = { catalog: { schemaVersion: 1, releases: [f.release] }, identity: { board: 'BOARD', firmwareVersion: 'old' } }
+  await assert.rejects(f.device.firmware.check({ ...request, version: 'missing' }), { code: 'FIRMWARE_VERSION_UNAVAILABLE' })
+  for (const version of ['', 4, null]) await assert.rejects(f.device.firmware.check({ ...request, version }), /version must/)
+  request.catalog.releases.push({ ...f.release })
+  await assert.rejects(f.device.firmware.check(request), /duplicate versions/)
+  assert.deepEqual(f.calls, [])
+})
+
+test('default update check reads official dl config and lists legacy releases without enabling unqualified writes', async () => {
+  const f = await fixture(), urls = []
+  const result = await f.device.firmware.check({ identity: { board: 'BOARD', firmwareVersion: 'old' }, async fetch(url) {
+    urls.push(url)
+    if (url.endsWith('config.toml')) return { ok: true, text: async () => 'firmware_images_url = "https://dl.espressif.com/AE/esp-vision/bin/"\n[esp-vision.image]\nBOARD = "latest.bin"\n[website]\nrelease = "new"\nreleases = ["new", "old"]\nbinaryNameTemplate = "esp-vision-{board}-{tag}.bin"\n' }
+    if (url.endsWith('/new.json')) return { ok: true, json: async () => ({ ...f.release, version: 'new', image: { ...f.release.image, url: 'https://dl.espressif.com/AE/esp-vision/bin/new-app.bin' } }) }
+    return { ok: false, status: 404 }
+  } })
+  assert.equal(result.available, true); assert.equal(result.release.version, 'new')
+  assert.equal(result.releases.length, 2); assert.equal(result.releases[1].compatible, false)
+  assert.equal(urls[0], 'https://dl.espressif.com/AE/esp-vision/config.toml')
+})
+test('unqualified historical version remains visible but is never selected for flashing', async () => {
+  const f = await fixture(), request = { identity: { board: 'BOARD', firmwareVersion: 'x' }, catalog: { schemaVersion: 1, releases: [{ board: 'BOARD', version: 'old', compatible: false, reason: 'UPDATE_METADATA_UNAVAILABLE' }] } }
+  const result = await f.device.firmware.check(request)
+  assert.equal(result.available, false); assert.equal(result.release, null); assert.equal(result.releases.length, 1)
+  await assert.rejects(f.device.firmware.check({ ...request, version: 'old' }), { code: 'FIRMWARE_INCOMPATIBLE' })
+  await assert.rejects(f.device.firmware.update({ ...f.request, release: result.releases[0] }), /metadata/)
+  assert.deepEqual(f.calls, [])
+})
+test('approved silicon revision interval is checked before any write', async () => {
+  const f = await fixture(); delete f.release.image.chipRevision
+  f.release.image.chipRevisionMin = 301; f.release.image.chipRevisionMax = 399
+  assert.equal((await f.device.firmware.update(f.request)).verified, true)
+  const bad = await fixture(); delete bad.release.image.chipRevision
+  bad.release.image.chipRevisionMin = 303; bad.release.image.chipRevisionMax = 399
+  await assert.rejects(bad.device.firmware.update(bad.request), /revision/)
+  assert.ok(!bad.calls.includes('write'))
+})