@esp-vision/device-core 0.5.1 → 0.6.0

package/tests/test-node-serial.mjs

@@ -102,3 +102,209 @@ test('non-POSIX serial backends do not receive the unsupported exclusive option'
   })
   assert.equal(result.status, 0, result.stderr || result.error?.message || 'Python fixture failed')
 })
+
+test('Node live retune drains without reopening and binary payload cannot become a bridge command', { skip: !python }, async t => {
+  await mkdir(tempBase, { recursive: true })
+  const root = await mkdtemp(join(tempBase, 'serial-retune-'))
+  t.after(() => rm(root, { recursive: true, force: true }))
+  const stateFile = join(root, 'state.jsonl')
+  await writeFile(join(root, 'serial.py'), `
+import json, queue
+
+class SerialException(Exception):
+    pass
+
+def record(event, **fields):
+    with open(${JSON.stringify(stateFile)}, 'a', encoding='utf-8') as stream:
+        stream.write(json.dumps(dict(event=event, **fields)) + '\\n')
+
+class Serial:
+    def __init__(self, *args, **kwargs):
+        self.queue = queue.Queue()
+        self._baudrate = kwargs['baudrate']
+    @property
+    def baudrate(self):
+        return self._baudrate
+    @baudrate.setter
+    def baudrate(self, value):
+        record('baud', value=value)
+        if value == 1500000:
+            raise ValueError('fixture unsupported baud')
+        self._baudrate = value
+    def open(self):
+        record('open', baud=self.baudrate, rts=self.rts, dtr=self.dtr)
+    def read(self, size):
+        try:
+            return self.queue.get(timeout=0.01)
+        except queue.Empty:
+            return b''
+    def write(self, data):
+        record('write', data=data.hex())
+        self.queue.put(data)
+        return len(data)
+    def flush(self):
+        record('drain')
+    def close(self):
+        record('close')
+`)
+  const previous = process.env.PYTHONPATH
+  process.env.PYTHONPATH = [root, previous].filter(Boolean).join(delimiter)
+  t.after(() => { if (previous === undefined) delete process.env.PYTHONPATH; else process.env.PYTHONPATH = previous })
+  const transport = serialTransport({ python, serial: '/dev/fixture' }), received = []
+  let finish
+  const echoed = new Promise(resolveEcho => { finish = resolveEcho })
+  const data = new Uint8Array([0, 1, 255, ...new TextEncoder().encode('\n{"id":99,"baudRate":1}\n'), 0])
+  transport.subscribe({ data(bytes) { received.push(...bytes); if (received.length === data.length) finish() } })
+  t.after(() => transport.disconnect())
+  await transport.connect({ signal: new AbortController().signal })
+  await transport.setBaudRate(2000000)
+  await transport.writeBytes(data)
+  await Promise.race([echoed, new Promise((_, reject) => { const timer = setTimeout(() => reject(new Error('Binary echo timed out')), 2000); timer.unref() })])
+  assert.deepEqual(new Uint8Array(received), data)
+  await assert.rejects(transport.setBaudRate(1500000), { code: 'SERIAL_BAUD_UNSUPPORTED' })
+  await transport.setBaudRate(115200)
+  assert.equal(transport.getDiagnostics().baudRate, 115200)
+  const state = (await readFile(stateFile, 'utf8')).trim().split('\n').map(line => JSON.parse(line))
+  assert.equal(state.filter(event => event.event === 'open').length, 1)
+  assert.deepEqual(state.filter(event => event.event === 'baud').map(event => event.value), [2000000, 1500000, 115200])
+  assert.equal(state.filter(event => event.event === 'drain').length, 3)
+  assert.deepEqual(state.find(event => event.event === 'open'), { event: 'open', baud: 115200, rts: false, dtr: true })
+})
+
+async function drainFixture(t, flushPlan = ['gate']) {
+  await mkdir(tempBase, { recursive: true })
+  const root = await mkdtemp(join(tempBase, 'serial-drain-'))
+  t.after(() => rm(root, { recursive: true, force: true }))
+  const stateFile = join(root, 'state.jsonl'), gateFile = join(root, 'flush-gate')
+  await writeFile(join(root, 'serial.py'), `
+import json, os, sys, time
+
+PLAN = json.loads(${JSON.stringify(JSON.stringify(flushPlan))})
+
+class SerialException(Exception):
+    pass
+
+def record(event, **fields):
+    with open(${JSON.stringify(stateFile)}, 'a', encoding='utf-8') as stream:
+        stream.write(json.dumps(dict(event=event, **fields)) + '\\n')
+
+class Serial:
+    def __init__(self, *args, **kwargs):
+        self.baudrate = kwargs['baudrate']
+        self.flush_count = 0
+    def open(self):
+        record('open', baud=self.baudrate)
+    def read(self, size):
+        time.sleep(0.01)
+        return b''
+    def write(self, data):
+        # Exercise the production bridge's partial serial-write loop.
+        written = min(3, len(data))
+        record('write', data=data[:written].hex())
+        return written
+    def flush(self):
+        self.flush_count += 1
+        count = self.flush_count
+        mode = PLAN[min(count - 1, len(PLAN) - 1)]
+        record('drain_start', count=count, baud=self.baudrate)
+        if mode == 'error':
+            raise SerialException('fixture drain failure: private port details')
+        if mode == 'exit':
+            raise SystemExit(2)
+        if mode == 'wrong_ack':
+            print(json.dumps({'id': 1, 'ok': True, 'baudRate': self.baudrate}), file=sys.stderr, flush=True)
+        elif mode == 'gate':
+            while not os.path.exists(${JSON.stringify(gateFile)}):
+                time.sleep(0.005)
+        else:
+            time.sleep(mode)
+        record('drain_end', count=count, baud=self.baudrate)
+    def close(self):
+        record('close')
+`)
+  const previous = process.env.PYTHONPATH
+  process.env.PYTHONPATH = [root, previous].filter(Boolean).join(delimiter)
+  t.after(() => { if (previous === undefined) delete process.env.PYTHONPATH; else process.env.PYTHONPATH = previous })
+  const transport = serialTransport({ python, serial: '/dev/fixture' })
+  t.after(() => transport.disconnect())
+  await transport.connect({ signal: new AbortController().signal })
+  const state = async () => (await readFile(stateFile, 'utf8')).trim().split('\n').map(line => JSON.parse(line))
+  const waitFor = async (event, count = 1) => {
+    const deadline = Date.now() + 3000
+    while (Date.now() < deadline) {
+      const records = await state()
+      if (records.filter(record => record.event === event).length >= count) return records
+      await new Promise(resolveWait => setTimeout(resolveWait, 5))
+    }
+    throw new Error(`Serial fixture did not reach ${event}`)
+  }
+  return { transport, state, waitFor, unblock: () => writeFile(gateFile, '') }
+}
+
+test('Node drain waits for real Python port.flush after all partial byte writes without changing baud', { skip: !python }, async t => {
+  const f = await drainFixture(t)
+  const bytes = new TextEncoder().encode('import machine; machine.bootloader()\r\n')
+  await f.transport.writeBytes(bytes)
+  let completed = false
+  const draining = f.transport.drain().then(() => { completed = true })
+  const before = await f.waitFor('drain_start')
+  assert.equal(completed, false, 'accepting the child stdin record is not a drain ACK')
+  assert.deepEqual(Buffer.from(before.filter(record => record.event === 'write').map(record => record.data).join(''), 'hex'), Buffer.from(bytes))
+  assert.equal(before.some(record => record.event === 'drain_end'), false)
+  await f.unblock()
+  await draining
+  assert.equal(f.transport.getDiagnostics().baudRate, 115200)
+  await f.transport.disconnect()
+  const after = await f.state()
+  assert.deepEqual(after.filter(record => ['open', 'drain_start', 'drain_end', 'close'].includes(record.event)).map(record => record.event), ['open', 'drain_start', 'drain_end', 'close'])
+  assert.deepEqual(after.filter(record => record.event.startsWith('drain')).map(record => record.baud), [115200, 115200])
+})
+
+test('Node drain distinguishes flush rejection and a baud-shaped ACK from successful drain', { skip: !python }, async t => {
+  const f = await drainFixture(t, ['error', 0])
+  await assert.rejects(f.transport.drain(), { code: 'SERIAL_DRAIN_FAILED', message: 'Serial adapter could not drain pending output' })
+  await f.transport.drain()
+  assert.equal(f.transport.getDiagnostics().baudRate, 115200)
+  await f.transport.disconnect()
+  const wrong = await drainFixture(t, ['wrong_ack'])
+  await assert.rejects(wrong.transport.drain(), { code: 'SERIAL_DRAIN_FAILED' })
+  assert.equal(wrong.transport.getDiagnostics().baudRate, 115200)
+})
+
+test('Node drain preserves pre-cancellation and ignores a cancelled request late ACK', { skip: !python }, async t => {
+  const f = await drainFixture(t, ['gate', 0.05])
+  const before = new AbortController(), reason = Object.assign(new Error('cancel drain'), { code: 'CANCELLED' })
+  before.abort(reason)
+  await assert.rejects(f.transport.drain({ signal: before.signal }), error => error === reason)
+  assert.equal((await f.state()).some(record => record.event === 'drain_start'), false)
+  const controller = new AbortController()
+  const pending = f.transport.drain({ signal: controller.signal })
+  const rejected = assert.rejects(pending, error => error === reason)
+  await f.waitFor('drain_start')
+  controller.abort(reason)
+  await rejected
+  const next = f.transport.drain()
+  await f.unblock()
+  await next
+  assert.equal((await f.state()).filter(record => record.event === 'drain_end').length, 2, 'the previous ID must not resolve the next request')
+})
+
+test('Node drain timeout remains distinct and its late ACK cannot resolve the next drain', { skip: !python }, async t => {
+  const f = await drainFixture(t, ['gate', 0.05])
+  await assert.rejects(f.transport.drain(), { code: 'SERIAL_DRAIN_TIMEOUT', message: 'Serial drain timed out' })
+  const next = f.transport.drain()
+  await f.unblock()
+  await next
+  assert.equal((await f.state()).filter(record => record.event === 'drain_end').length, 2)
+})
+
+test('Node drain rejects promptly on explicit disconnect or Python bridge exit', { skip: !python }, async t => {
+  const f = await drainFixture(t)
+  const pending = f.transport.drain()
+  const rejected = assert.rejects(pending, { code: 'SERIAL_CLOSED' })
+  await f.waitFor('drain_start')
+  await f.transport.disconnect()
+  await rejected
+  const exited = await drainFixture(t, ['exit'])
+  await assert.rejects(exited.transport.drain(), { code: 'SERIAL_CLOSED' })
+})

package/tests/test-npm-release-policy.mjs

@@ -0,0 +1,62 @@
+// 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, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { test } from 'node:test'
+
+const source = fileURLToPath(new URL('../scripts/', import.meta.url))
+async function fixture(t, published, version = '1.2.3', type = 'patch') {
+  const root = await mkdtemp(join(tmpdir(), 'core-release-policy-'))
+  t.after(() => rm(root, { recursive: true, force: true }))
+  const scripts = join(root, 'scripts'), log = join(root, 'calls')
+  await mkdir(scripts)
+  await copyFile(join(source, 'release-npm.mjs'), join(scripts, 'release-npm.mjs'))
+  await copyFile(join(source, 'verify-registry.mjs'), join(scripts, 'verify-registry.mjs'))
+  await copyFile(join(source, 'version-policy.mjs'), join(scripts, 'version-policy.mjs'))
+  await writeFile(join(root, 'package.json'), JSON.stringify({ name: '@esp-vision/device-core', version, espVisionReleaseType: type, license: 'Apache-2.0', publishConfig: { access: 'public', registry: 'https://registry.npmjs.org/' } }))
+  const loader = join(root, 'registry.mjs'), npm = join(root, 'npm.cjs')
+  // Invoke the fixture with Node on every platform, without shell/PATH resolution.
+  await writeFile(loader, `import childProcess from 'node:child_process';
+import { syncBuiltinESMExports } from 'node:module';
+const spawnSync = childProcess.spawnSync;
+childProcess.spawnSync = (command, ...args) => command === 'npm'
+  ? spawnSync(process.execPath, [${JSON.stringify(npm)}, ...args[0]], args[1])
+  : spawnSync(command, ...args);
+syncBuiltinESMExports();
+let reads = 0; globalThis.fetch = async () => { reads++; const found = ${published} || reads === 2 || reads >= 4; return {ok:found,status:found?200:404,json:async()=>reads===2?({versions:{'1.2.2':{}}}):({dist:{integrity:'sha512-fixture'}})} }`)
+  await writeFile(npm, `const fs = require('node:fs'); const args = process.argv.slice(2); fs.appendFileSync(process.env.CALL_LOG, args[0] + '\\n');
+if (args[0] === 'whoami') process.stdout.write('esp-vision');
+else if (args[0] === 'pack') process.stdout.write(JSON.stringify([{name:'@esp-vision/device-core',version:'1.2.3',filename:'core.tgz',integrity:'sha512-fixture',files:[{path:'LICENSE'},{path:'NOTICE'}]}]));
+else if (args[0] !== 'publish') process.exit(2);
+`)
+  const env = { ...process.env, TMPDIR: root, TMP: root, TEMP: root, CALL_LOG: log,
+    NODE_OPTIONS: `--import ${pathToFileURL(loader).href}`, NPM_PUBLISH_TOKEN: 'fixture', CI_PIPELINE_SOURCE: 'push',
+    CI_DEFAULT_BRANCH: 'master', CI_COMMIT_BRANCH: 'master', CI_COMMIT_REF_PROTECTED: 'true' }
+  const result = spawnSync(process.execPath, [resolve(scripts, 'release-npm.mjs')], { cwd: root, env, encoding: 'utf8' })
+  return { result, calls: await readFile(log, 'utf8').catch(() => '') }
+}
+
+test('an existing Core version is skipped without npm writes', async t => {
+  const { result, calls } = await fixture(t, true)
+  assert.equal(result.status, 0, result.stderr)
+  assert.match(result.stdout, /already exists; no new version to publish/)
+  assert.equal(calls, '')
+})
+
+test('a new Core version is published once and its registry integrity verified', async t => {
+  const { result, calls } = await fixture(t, false)
+  assert.equal(result.status, 0, result.stderr)
+  assert.match(result.stdout, /Published and verified/)
+  assert.deepEqual(calls.trim().split('\n'), ['pack', 'whoami', 'publish'])
+})
+
+test('a misclassified Core version is rejected before packaging or publication', async t => {
+  const { result, calls } = await fixture(t, false, '1.3.0', 'patch')
+  assert.notEqual(result.status, 0)
+  assert.match(result.stderr, /A patch release after 1.2.2 must be 1.2.3/)
+  assert.equal(calls, '')
+})

package/tests/test-observed-capture.mjs

@@ -0,0 +1,131 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// 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 { createDeviceOperations } from '../src/device_operations.js'
+import { DeviceActionRegistry } from '../src/device_actions.js'
+import { bindSessionDeviceActions } from '../src/device_bindings.js'
+import { EvMuxParser, makeEvMuxFrame } from '../src/evmux.js'
+import { EvRepl } from '../src/evrepl.js'
+import { jpegFixture } from './jpeg-fixtures.mjs'
+
+const safeFeature = 'debug.capture_frame.observed.v1'
+function fixture({ features = ['debug.capture_frame', safeFeature, 'debug.capture_screen', 'device.control'], cameraError = null, pending = false } = {}) {
+  let session
+  const requests = [], id = 'a'.repeat(32), state = {}
+  const jpeg = jpegFixture('small').data
+  const replyImage = (request, { sessionId = request.sessionId, vmEpoch = request.vmEpoch } = {}) => session.feedBytes(makeEvMuxFrame({
+    channel: request.channel, type: 'rsp', method: request.method, seq: request.seq, sessionId, vmEpoch,
+    contentType: 'image/jpeg', encoding: 'binary', width: 4, height: 3, payload: jpeg,
+  }))
+  const parser = new EvMuxParser({ filterFrame(metadata, bytes) {
+    const payload = JSON.parse(new TextDecoder().decode(bytes))
+    requests.push({ ...metadata, payload })
+    if (metadata.method === 'debug.capture_frame' && pending) return false
+    if (metadata.method === 'debug.capture_screen' || (metadata.method === 'debug.capture_frame' && !cameraError)) replyImage(metadata)
+    else session.feedBytes(makeEvMuxFrame({ channel: metadata.channel, type: 'rsp', method: metadata.method, seq: metadata.seq,
+      sessionId: metadata.sessionId, vmEpoch: metadata.vmEpoch ?? session.vmEpoch,
+      payload: JSON.stringify(cameraError && metadata.method === 'debug.capture_frame'
+        ? { ok: false, error: { code: cameraError, message: 'No safe camera observation is available' } } : { ok: true }) }))
+    return false
+  } })
+  session = new DeviceSession({ transport: { async writeBytes(bytes) { parser.feedBytes(bytes) } }, EvMuxParser, makeEvMuxFrame, EvRepl })
+  session.state = 'ready'
+  session.sessionId = id
+  session.vmEpoch = 1
+  session.vmReady = true
+  session.capabilities = { features }
+  return { session, requests, replyImage, state, jpeg, api: createDeviceOperations({ session, state }) }
+}
+
+test('old unsafe camera firmware is rejected before public, RPC, raw-frame or action requests are sent', async t => {
+  for (const features of [[], ['debug.capture_frame'], [safeFeature]]) {
+    const f = fixture({ features }); t.after(() => f.session.close())
+    const denied = error => error.code === 'UNSUPPORTED_OPERATION' && /update.*firmware/i.test(error.message)
+    await assert.rejects(f.api.capture({ source: 'camera' }), denied)
+    await assert.rejects(f.session.captureImage('debug.capture_frame'), denied)
+    await assert.rejects(f.session.rpc('debug.capture_frame'), denied)
+    await assert.rejects(f.session.writeFrame('debug.rpc', 'req', 'debug.capture_frame', '{}'), denied)
+    const registry = new DeviceActionRegistry()
+    bindSessionDeviceActions(registry)
+    await assert.rejects(registry.handler('frame.capture')({ timeoutMs: 1000 }, { session: f.session }), denied)
+    assert.deepEqual(f.requests, [])
+    assert.equal(f.session.pendingRpc.size, 0)
+    assert.equal(f.state.operation, undefined)
+  }
+})
+
+test('negotiated camera observation returns correlated JPEG bytes and forwards quality', async t => {
+  const f = fixture(); t.after(() => f.session.close())
+  const image = await f.api.capture({ source: 'camera', quality: 73 })
+  assert.deepEqual(image.data, f.jpeg)
+  assert.equal(image.mimeType, 'image/jpeg')
+  assert.equal(image.metadata.width, 4)
+  assert.equal(image.metadata.height, 3)
+  assert.equal(f.requests.length, 1)
+  assert.equal(f.requests[0].method, 'debug.capture_frame')
+  assert.deepEqual(f.requests[0].payload, { quality: 73 })
+  assert.equal(f.state.operation, null)
+})
+
+test('no published camera frame and observer allocation failures retain explicit firmware errors', async t => {
+  for (const cameraError of ['CAMERA_FRAME_NOT_READY', 'NO_MEM']) {
+    const f = fixture({ cameraError }); t.after(() => f.session.close())
+    await assert.rejects(f.api.capture({ source: 'camera' }), { code: cameraError })
+    assert.equal(f.requests.length, 1, 'no sensor initialization, retry or capture fallback is synthesized')
+    assert.equal(f.session.lastDebugImage, null)
+    assert.equal(f.state.operation, null)
+  }
+})
+
+test('screen capture retains its independent capability without a camera observation feature', async t => {
+  const f = fixture({ features: ['debug.capture_frame', 'debug.capture_screen'] }); t.after(() => f.session.close())
+  assert.deepEqual((await f.api.capture({ source: 'screen' })).data, f.jpeg)
+  await assert.rejects(f.api.capture({ source: 'camera' }), { code: 'UNSUPPORTED_OPERATION' })
+  assert.deepEqual(f.requests.map(request => request.method), ['debug.capture_screen'])
+})
+
+test('camera cancellation and timeout release the operation and ignore stale binary responses', async t => {
+  const f = fixture({ pending: true }); t.after(() => f.session.close())
+  const controller = new AbortController()
+  const capture = f.api.capture({ source: 'camera', signal: controller.signal })
+  const cancelled = assert.rejects(capture, { name: 'AbortError' })
+  await new Promise(setImmediate)
+  controller.abort()
+  await cancelled
+  assert.equal(f.state.operation, null)
+  assert.equal(f.session.pendingRpc.size, 0)
+  f.replyImage(f.requests[0])
+  assert.deepEqual((await f.api.capture({ source: 'screen' })).data, f.jpeg)
+  await assert.rejects(f.api.capture({ source: 'camera', timeout: 20 }), { code: 'TIMEOUT' })
+  assert.equal(f.state.operation, null)
+  assert.equal(f.session.pendingRpc.size, 0)
+})
+
+test('soft-reset epochs invalidate a pending camera observation and reject the old image', async t => {
+  const f = fixture({ pending: true }); t.after(() => f.session.close())
+  const before = f.api.capture({ source: 'camera' })
+  const invalidated = assert.rejects(before, { code: 'VM_EPOCH_CHANGED' })
+  await new Promise(setImmediate)
+  f.session.feedBytes(makeEvMuxFrame({ channel: 'user.rpc', type: 'event', method: 'hello', sessionId: f.session.sessionId, vmEpoch: 2,
+    payload: JSON.stringify({ evMuxVersion: 4, session: { id: f.session.sessionId, vmEpoch: 2 }, vmEpoch: 2, vmReady: true }) }))
+  await invalidated
+  f.replyImage(f.requests[0])
+  assert.equal(f.session.vmEpoch, 2)
+  assert.deepEqual((await f.api.capture({ source: 'screen' })).data, f.jpeg)
+  assert.equal(f.requests.at(-1).vmEpoch, 2)
+})
+
+test('acknowledged hard reset discards a pending safe camera response and its old session', async t => {
+  const f = fixture({ pending: true }); t.after(() => f.session.close())
+  const capture = f.session.captureImage('debug.capture_frame')
+  const invalidated = assert.rejects(capture, { code: 'DEVICE_RESET' })
+  await new Promise(setImmediate)
+  await f.session.control('hard-reset')
+  await invalidated
+  f.replyImage(f.requests[0])
+  assert.equal(f.session.state, 'disconnected')
+  assert.equal(f.session.sessionId, null)
+  assert.equal(f.session.pendingRpc.size, 0)
+})

package/tests/test-uart-baud.mjs

@@ -0,0 +1,180 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { createDevice } from '../src/index.js'
+import { DeviceSession, UART_BAUD_CANDIDATES, EV_MUX_DEFAULT_LIMITS, EV_MUX_REQUIRED_CHANNELS, EV_MUX_REQUIRED_FEATURES } from '../src/device_session.js'
+import { EvMuxParser, makeEvMuxFrame } from '../src/evmux.js'
+import { EvRepl } from '../src/evrepl.js'
+
+function peer({ owner = 'uart', support = true, rejectSpeeds = [], corruptSpeeds = [], corruptFrames = [], silentSpeeds = [], dropCommit = false, lostPrepare = false, lostCommitAndRelease = false, resetOnChange = false } = {}) {
+  let listener, session, hostBaud = 115200, deviceBaud = 115200, active = false, token, commitDrops = 0
+  const id = 'a'.repeat(32), requests = [], changed = [], diagnostics = [], sleeps = []
+  const caps = { ok: true, protocol: { evMuxVersion: 4 }, features: EV_MUX_REQUIRED_FEATURES,
+    channels: EV_MUX_REQUIRED_CHANNELS, limits: { ...EV_MUX_DEFAULT_LIMITS, txLargePayloadMax: 262144 },
+    session: { policy: 'firstCome', leaseMs: 15000, keepaliveMs: 5000 },
+    ...(support ? { uartBaud: { baseline: 115200, current: 115200, candidates: UART_BAUD_CANDIDATES, probeBytes: 512, timeoutMs: 5000, switchDelayMs: 100 } } : {}),
+  }
+  const reset = () => { active = false; deviceBaud = 115200; token = null }
+  const reader = new EvMuxParser({ filterFrame(metadata, bytes) {
+    if (hostBaud !== deviceBaud) return false
+    const payload = JSON.parse(new TextDecoder().decode(bytes))
+    requests.push({ method: metadata.method, payload, baudRate: hostBaud, state: session?.state })
+    let result = { ok: true }, acquired = false
+    if (metadata.method === 'hello') {
+      if (payload.acquire) { active = true; acquired = true }
+      result = { ok: true, evMuxVersion: 4, deviceId: 'test', hostname: 'test', vmReady: false,
+        session: active ? { id, owner, vmEpoch: 1, leaseMs: 15000, keepaliveMs: 5000 } : null }
+    } else if (metadata.method === 'capabilities') result = caps
+    else if (metadata.method === 'transport.uart.prepare') {
+      token = payload.token
+      if (lostPrepare && payload.baudRate === 2000000) { deviceBaud = payload.baudRate; return false }
+      result = { ok: true, ...payload, timeoutMs: 5000, switchDelayMs: 100 }
+    } else if (metadata.method === 'transport.uart.probe') {
+      if (silentSpeeds.includes(hostBaud)) return false
+      result = { ok: true, token, data: corruptSpeeds.includes(hostBaud) ? payload.data + 'x' : payload.data }
+    } else if (metadata.method === 'transport.uart.commit') {
+      if (lostCommitAndRelease && hostBaud === 2000000) return false
+      if (dropCommit && commitDrops++ === 0) return false
+      result = { ok: true, token, baudRate: deviceBaud }
+    }
+    if (metadata.method === 'session.release' && lostCommitAndRelease && hostBaud === 2000000) return false
+    const response = makeEvMuxFrame({ channel: metadata.channel, type: 'rsp', method: metadata.method, seq: metadata.seq,
+      ...((acquired || !['hello', 'capabilities'].includes(metadata.method)) ? { sessionId: id, vmEpoch: 1 } : {}), payload: JSON.stringify(result) })
+    if (metadata.method === 'transport.uart.probe' && corruptFrames.includes(hostBaud)) response[response.length - 2] ^= 1
+    listener.data(response)
+    if (metadata.method === 'transport.uart.prepare') deviceBaud = payload.baudRate
+    if (metadata.method === 'session.release') reset()
+    return false
+  } })
+  const transport = {
+    subscribe(value) { listener = value; return () => { listener = null } },
+    async connect() { hostBaud = 115200 },
+    async disconnect() {},
+    async writeBytes(bytes) { reader.feedBytes(bytes) },
+    async setBaudRate(speed) {
+      changed.push(speed)
+      if (rejectSpeeds.includes(speed)) throw Object.assign(new Error('unsupported speed'), { code: 'SERIAL_BAUD_UNSUPPORTED' })
+      hostBaud = speed
+      if (resetOnChange && speed !== 115200) reset()
+    },
+  }
+  const sleep = async ms => { sleeps.push(ms); if (ms >= 1000) reset() }
+  session = new DeviceSession({ transport, EvMuxParser, makeEvMuxFrame, EvRepl, sleep, handlers: { diagnostic: event => diagnostics.push(event) } })
+  listener = { data: bytes => session.feedBytes(bytes) }
+  return { transport, session, requests, changed, diagnostics, sleeps }
+}
+
+test('runtime tests 2 Mbps first with varied bidirectional probes and stops after success', async () => {
+  const p = peer()
+  try {
+    await p.session.negotiate({ drainMs: 0, probeRepl: false })
+    assert.deepEqual(p.changed, [2000000])
+    assert.deepEqual(p.requests.filter(x => x.method === 'transport.uart.probe').map(x => x.payload.data.length), [32, 32, 128, 128, 512, 512])
+    assert.equal(p.requests.filter(x => x.method === 'transport.uart.commit').length, 1)
+    assert.equal(p.session.capabilities.uartBaud.current, 2000000)
+    assert.ok(p.requests.every(x => x.state !== 'ready'), 'no request or event can observe ready before verification')
+    assert.equal(p.session.state, 'ready')
+  } finally { p.session.close() }
+})
+
+test('corrupt echoes and adapter rejection recover at baseline and select first passing lower speed', async () => {
+  const p = peer({ corruptSpeeds: [2000000], rejectSpeeds: [1500000] })
+  try {
+    await p.session.negotiate({ drainMs: 0, probeRepl: false })
+    assert.deepEqual(p.changed, [2000000, 115200, 1500000, 115200, 921600])
+    assert.deepEqual(p.requests.filter(x => x.method === 'transport.uart.prepare').map(x => x.payload.baudRate), [2000000, 1500000, 921600])
+    assert.equal(p.requests.filter(x => x.method === 'hello' && x.payload.acquire).length, 3)
+    assert.equal(p.session.capabilities.uartBaud.current, 921600)
+  } finally { p.session.close() }
+})
+
+test('all high speeds can fail while retaining a fully verified 115200 connection', async () => {
+  const p = peer({ corruptSpeeds: UART_BAUD_CANDIDATES.slice(0, -1) })
+  try {
+    await p.session.negotiate({ drainMs: 0, probeRepl: false })
+    assert.deepEqual(p.requests.filter(x => x.method === 'transport.uart.prepare').map(x => x.payload.baudRate), UART_BAUD_CANDIDATES)
+    assert.equal(p.session.capabilities.uartBaud.current, 115200)
+    assert.equal(p.session.state, 'ready')
+  } finally { p.session.close() }
+})
+
+test('a timed out new-rate probe and a reopen-triggered reset both recover before the next candidate', async () => {
+  for (const options of [{ silentSpeeds: [2000000] }, { corruptFrames: [2000000] }, { resetOnChange: true }]) {
+    const p = peer(options)
+    try {
+      await p.session.negotiate({ drainMs: 0, probeRepl: false })
+      assert.equal(p.session.capabilities.uartBaud.current, options.resetOnChange ? 115200 : 1500000)
+      assert.ok(p.sleeps.some(ms => ms >= (options.resetOnChange ? 1000 : 150)), 'wait for release completion or independent rollback before reacquiring')
+    } finally { p.session.close() }
+  }
+})
+
+test('a lost commit acknowledgement retries the idempotent token without downgrading', async () => {
+  const p = peer({ dropCommit: true })
+  try {
+    await p.session.negotiate({ drainMs: 0, probeRepl: false })
+    assert.deepEqual(p.changed, [2000000])
+    const commits = p.requests.filter(x => x.method === 'transport.uart.commit')
+    assert.equal(commits.length, 2)
+    assert.equal(commits[0].payload.token, commits[1].payload.token)
+  } finally { p.session.close() }
+})
+
+test('lost prepare and committed-session ACKs wait full rollback bounds after the last failed release', async () => {
+  for (const options of [{ lostPrepare: true }, { lostCommitAndRelease: true }]) {
+    const p = peer(options)
+    try {
+      await p.session.negotiate({ drainMs: 0, probeRepl: false })
+      assert.ok(p.sleeps.includes(options.lostPrepare ? 5250 : 15250), 'prepare delay and lease renewal must not shorten the recovery window')
+      assert.equal(p.session.capabilities.uartBaud.current, 1500000)
+    } finally { p.session.close() }
+  }
+})
+
+test('a timed out adapter retune receives cancellation before baseline recovery', async () => {
+  const p = peer(), original = p.transport.setBaudRate
+  let aborted = false
+  p.transport.setBaudRate = (speed, options) => speed !== 2000000 ? original(speed, options) : new Promise((_, reject) => {
+    options.signal.addEventListener('abort', () => { aborted = true; reject(options.signal.reason) }, { once: true })
+  })
+  try {
+    await p.session.negotiate({ drainMs: 0, probeRepl: false })
+    assert.equal(aborted, true)
+    assert.equal(p.session.capabilities.uartBaud.current, 1500000)
+  } finally { p.session.close() }
+})
+
+test('USB owners, old firmware and transports lacking a retune method keep baseline', async () => {
+  for (const options of [{ owner: 'usb' }, { owner: 'usj' }, { owner: 'tcp' }, { support: false }, { noAdapter: true }]) {
+    const p = peer(options)
+    if (options.noAdapter) delete p.transport.setBaudRate
+    try {
+      await p.session.negotiate({ drainMs: 0, probeRepl: false })
+      assert.deepEqual(p.changed, [])
+      assert.ok(!p.requests.some(x => x.method.startsWith('transport.uart.')))
+    } finally { p.session.close() }
+  }
+})
+
+test('public connect publishes ready only after runtime speed selection', async () => {
+  const p = peer(), events = []
+  const device = createDevice({ transport: p.transport })
+  device.on('state', event => events.push(event.state))
+  device.on('diagnostic', event => { if (event.event === 'uart.baud.selected') events.push('selected') })
+  try {
+    await device.connect({ probeRepl: false })
+    assert.ok(events.indexOf('selected') >= 0)
+    assert.ok(events.indexOf('ready') > events.indexOf('selected'))
+  } finally { await device.disconnect() }
+})
+
+test('public passive identity probes can explicitly disable retuning', async () => {
+  const p = peer(), device = createDevice({ transport: p.transport })
+  for (const autoBaud of [null, 'false', 0]) await assert.rejects(device.connect({ autoBaud }), { name: 'TypeError' })
+  try {
+    await device.connect({ probeRepl: false, autoBaud: false })
+    assert.deepEqual(p.changed, [])
+    assert.ok(!p.requests.some(x => x.method.startsWith('transport.uart.')))
+  } finally { await device.disconnect() }
+})

package/tests/test-version-policy.mjs

@@ -0,0 +1,37 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import { cliBundlesCore, declaredCoreSupports, highestStableVersion, inMinorRange, minorRange, validateVersionStep } from '../scripts/version-policy.mjs'
+
+test('minor dependency ranges accept patch updates and reject adjacent minor or major versions', () => {
+  for (const version of ['0.5.0', '0.5.1', '0.5.99']) assert.equal(inMinorRange('~0.5.0', version), true)
+  for (const version of ['0.4.9', '0.6.0', '1.5.0']) assert.equal(inMinorRange('~0.5.0', version), false)
+  for (const value of ['^0.5.0', '0.5.1', '~0.5.1', '*', '~0.05.0']) assert.throws(() => minorRange(value))
+  assert.equal(declaredCoreSupports('0.5.1', '0.5.1'), true)
+  assert.equal(declaredCoreSupports('0.5.1', '0.5.2'), false)
+  assert.equal(declaredCoreSupports('~0.5.0', '0.5.2'), true)
+})
+
+test('only the next patch, minor or major version matches its declared release type', () => {
+  for (const [kind, next] of [['patch', '0.5.2'], ['minor', '0.6.0'], ['major', '1.0.0']]) {
+    assert.doesNotThrow(() => validateVersionStep('0.5.1', next, kind))
+  }
+  for (const [kind, next] of [['patch', '0.6.0'], ['patch', '0.5.3'], ['minor', '0.5.2'], ['minor', '0.7.0'], ['major', '0.6.0'], ['major', '1.1.0'], ['feature', '0.6.0']]) {
+    assert.throws(() => validateVersionStep('0.5.1', next, kind))
+  }
+  assert.throws(() => validateVersionStep('0.5.1', '0.5.2-rc.1', 'patch'))
+})
+
+test('registry baseline is the numerically highest stable published version', () => {
+  assert.equal(highestStableVersion(['0.9.9', '0.10.1', '0.10.0', '0.11.0-beta.1', '0.0.0-stage', '1.0.0']), '1.0.0')
+  assert.equal(highestStableVersion(['0.0.0-stage']), undefined)
+})
+
+test('a bundled CLI identifies the actual Core patch even when its range allows others', () => {
+  const cli = { devDependencies: { '@esp-vision/device-core': '~0.5.0' }, espVision: { resolved: { deviceCore: '0.5.1' } } }
+  assert.equal(cliBundlesCore(cli, '0.5.1'), true)
+  assert.equal(cliBundlesCore(cli, '0.5.2'), false)
+  assert.equal(cliBundlesCore({ devDependencies: { '@esp-vision/device-core': '0.5.1' } }, '0.5.1'), true)
+  assert.equal(cliBundlesCore({ devDependencies: { '@esp-vision/device-core': '~0.5.0' } }, '0.5.1'), false)
+})