@esp-vision/device-core 0.6.0 → 0.7.0

package/tests/test-device-functional-checks.mjs

@@ -1,16 +1,21 @@
 // SPDX-License-Identifier: Apache-2.0
 import test from 'node:test'
 import assert from 'node:assert/strict'
-import { readFile, mkdtemp, rm } from 'node:fs/promises'
+import { readFile, mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { EV_REPL_INPUT_MAX_BYTES, evReplExecInputBytes } from '../src/evrepl.js'
 import { tmpdir } from 'node:os'
+import { existsSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
 import { parseArgs } from './hardware-check.mjs'
-import { DEVICE_CHECKS, parseCheckResult, runDeviceChecks, saveJpeg } from './device-checks.mjs'
+import { DEFAULT_ESPDL_MODEL, DEFAULT_ESPDL_SHA256, DEVICE_CHECKS, parseCheckResult, runDeviceChecks, saveJpeg } from './device-checks.mjs'
 import { jpegFixture } from './jpeg-fixtures.mjs'
 
 function devicePeer({ results = {}, board = 'TEST', screenFails = false } = {}) {
   const files = new Map(), calls = [], listeners = new Map()
+  let modelNonce, modelBytes, modelPath, modelOffset = 0
   return {
     calls, files, listeners,
     async inspect({ fields }) { calls.push(['inspect', fields]); return { identity: { board, firmwareVersion: 'test' }, capabilities: { protocol: { evMuxVersion: 4 }, features: ['storage.writer.lease'], limits: { replInputMax: EV_REPL_INPUT_MAX_BYTES } }, runtime: { vmReady: true }, storage: { flash: { present: true, mounted: false, writable: false } } } },
@@ -21,6 +26,26 @@ function devicePeer({ results = {}, board = 'TEST', screenFails = false } = {})
     }),
     python: { async execute({ source }) {
       calls.push(['execute', source])
+      if (source.includes("={'_source':[],'_fixture_nonce':")) modelNonce = JSON.parse(source.slice(source.indexOf("'_fixture_nonce':") + 17, -1))
+      const model = /\['model_command'\]\((.*)\)$/.exec(source)
+      if (model) {
+        const [operation, ...args] = JSON.parse('[' + model[1] + ']')
+        let data
+        if (operation === 'begin') {
+          ;[modelNonce, modelBytes, modelPath] = args
+          modelOffset = 0
+          data = { size: modelBytes, offset: 0, path: modelPath }
+        } else if (operation === 'append') {
+          const [offset, encoded] = args, bytes = Buffer.from(encoded, 'base64').length
+          modelOffset = offset + bytes
+          data = { offset, end: modelOffset, bytes, current: modelOffset }
+        } else if (operation === 'mount') data = { path: modelPath, bytes: modelBytes, sha256: args[0] }
+        else data = { bytes: 0, offset: 0, mounted: false }
+        return { ok: true, output: '__EVHILACK__' + JSON.stringify([modelNonce, operation, data]) }
+      }
+      if (source.startsWith('assert ') && source.includes('__EVHILACK__')) {
+        return { ok: true, output: JSON.parse(source.slice(source.indexOf(';print(') + 7, -1)) }
+      }
       const name = /\['run_check'\]\("([a-z_]+)"/.exec(source)?.[1]
       if (!name) return { ok: true, output: '' }
       const result = results[name] ?? { name, status: 'PASS', data: { width: 240, height: 320 } }
@@ -147,10 +172,257 @@ test('identity and RAM checks do not require optional storage inspection support
 })
 
 test('P4 issue regressions are included in the strict target-check path', async () => {
-  const required = ['camera_display_lifecycle', 'image_copy_to_fb', 'image_transform_argument', 'sensor_snapshot_buffer', 'memory_policy']
+  const required = ['camera_display_lifecycle', 'image_copy_to_fb', 'image_transform_argument', 'sensor_snapshot_buffer', 'memory_policy', 'isp_ccm_frames', 'isp_lsc_display']
   assert.ok(required.every(name => DEVICE_CHECKS.includes(name)))
   const device = devicePeer(), reports = []
   await runDeviceChecks(device, parseArgs(['--tcp', 'test', '--checks', required.join(','), '--require-all']),
     { nonce: 'issue910', report: value => reports.push(value) })
   assert.deepEqual(reports.at(-1), { check: 'summary', passed: required.length, failed: 0, skipped: 0 })
 })
+
+test('ESP-DL inference streams a model into RAM, respects the live REPL limit and never touches persistent storage', async () => {
+  const directory = await mkdtemp(join(tmpdir(), 'esp-vision-model-'))
+  const model = join(directory, 'model.espdl'), bytes = Buffer.from(Array.from({ length: 1024 }, (_, index) => index & 255))
+  try {
+    await writeFile(model, bytes)
+    const device = devicePeer(), reports = [], inspect = device.inspect
+    device.inspect = async request => {
+      assert.ok(!request.fields.includes('storage'))
+      const info = await inspect(request)
+      info.capabilities.limits.replInputMax = 256
+      return info
+    }
+    await runDeviceChecks(device, parseArgs(['--tcp', 'test', '--checks', 'espdl_inference', '--model', model, '--require-all']), { nonce: 'abc123', report: value => reports.push(value) })
+    const commands = device.calls.filter(call => call[0] === 'execute').map(call => call[1])
+    assert.ok(commands.every(source => evReplExecInputBytes(source) <= 256))
+    const uploaded = commands.filter(source => source.includes("['model_command'](\"append\",")).map(source => Buffer.from(JSON.parse('[' + source.slice(source.indexOf('](') + 2, -1) + ']')[2], 'base64'))
+    assert.deepEqual(Buffer.concat(uploaded), bytes)
+    assert.ok(commands.some(source => source.includes("['model_command'](\"mount\",\"" + createHash('sha256').update(bytes).digest('hex'))))
+    assert.ok(commands.some(source => source.includes('modelPath\\\":\\\"/evhil_abc123/model.espdl')))
+    assert.ok(commands.some(source => source.includes("['model_command'](\"close\")")))
+    assert.equal(reports.find(result => result.check === 'espdl_inference').data.modelBytes, bytes.length)
+    assert.equal(reports.find(result => result.check === 'espdl_inference').data.modelStorage, 'ram-vfs')
+    assert.equal(device.files.size, 0)
+  } finally { await rm(directory, { recursive: true, force: true }) }
+})
+
+test('missing ESP-DL model skips only optional acceptance and malformed expected hashes are rejected', async () => {
+  assert.throws(() => parseArgs(['--tcp', 'test', '--model-sha256', 'bad']), { code: 'ARGUMENT' })
+  for (const strict of [false, true]) {
+    const device = devicePeer(), results = []
+    const run = runDeviceChecks(device, parseArgs(['--tcp', 'test', '--checks', 'espdl_inference', '--model', join(tmpdir(), 'missing-esp-vision.espdl'), ...(strict ? ['--require-all'] : [])]), { nonce: 'abc123', report: value => results.push(value) })
+    if (strict) await assert.rejects(run, { code: 'DEVICE_CHECKS_FAILED' })
+    else await run
+    assert.equal(results.find(result => result.check === 'espdl_inference').status, strict ? 'FAIL' : 'SKIP')
+    assert.ok(!device.calls.some(call => call[0] === 'execute'))
+  }
+})
+
+test('ESP-DL model hash mismatch is rejected before device mutation', async () => {
+  const directory = await mkdtemp(join(tmpdir(), 'esp-vision-model-'))
+  try {
+    const model = join(directory, 'model.espdl'), device = devicePeer(), reports = []
+    await writeFile(model, Buffer.from([1, 2, 3]))
+    await assert.rejects(runDeviceChecks(device, parseArgs(['--tcp', 'test', '--checks', 'espdl_inference', '--model', model, '--model-sha256', '0'.repeat(64)]), { nonce: 'abc123', report: value => reports.push(value) }), { code: 'DEVICE_CHECKS_FAILED' })
+    assert.equal(reports.find(result => result.check === 'espdl_inference').error.code, 'MODEL_HASH_MISMATCH')
+    assert.equal(device.calls.length, 0)
+  } finally { await rm(directory, { recursive: true, force: true }) }
+})
+
+test('partial model upload, inference failure and cleanup failure cannot report success', async () => {
+  const directory = await mkdtemp(join(tmpdir(), 'esp-vision-model-'))
+  try {
+    const model = join(directory, 'model.espdl')
+    await writeFile(model, Buffer.alloc(1024))
+    for (const stage of ['append_model', 'espdl_inference', 'close_model']) {
+      const device = devicePeer(), execute = device.python.execute, reports = []
+      device.python.execute = async request => {
+        if (request.source.includes(`['model_command']("${stage.replace('_model', '')}"`) || (stage === 'espdl_inference' && request.source.includes("['run_check'](\"espdl_inference\""))) {
+          device.calls.push(['failed-execute', request.source])
+          throw new Error('injected failure')
+        }
+        return execute(request)
+      }
+      await assert.rejects(runDeviceChecks(device, parseArgs(['--tcp', 'test', '--checks', 'espdl_inference', '--model', model, '--require-all']), { nonce: 'abc123', report: value => reports.push(value) }), { code: 'DEVICE_CHECKS_FAILED' })
+      assert.equal(reports.find(result => result.check === 'espdl_inference').status, 'FAIL')
+      assert.ok(device.calls.some(call => call[1]?.includes("['model_command'](\"close\")")))
+      assert.ok(device.calls.some(call => call[1]?.includes(".get('close_model',lambda:None)()")))
+    }
+  } finally { await rm(directory, { recursive: true, force: true }) }
+})
+
+test('model transfer cancellation releases RAM resources with an independent cleanup signal', async () => {
+  const directory = await mkdtemp(join(tmpdir(), 'esp-vision-model-'))
+  try {
+    const model = join(directory, 'model.espdl'), device = devicePeer(), execute = device.python.execute, controller = new AbortController()
+    await writeFile(model, Buffer.alloc(1024))
+    let cleaned = false
+    device.python.execute = async request => {
+      if (request.source.includes("['model_command'](\"append\",")) controller.abort(new Error('cancelled transfer'))
+      if (request.source.includes("['model_command'](\"close\")")) { assert.equal(request.signal.aborted, false); cleaned = true }
+      return execute(request)
+    }
+    await assert.rejects(runDeviceChecks(device, parseArgs(['--tcp', 'test', '--checks', 'espdl_inference', '--model', model]), { signal: controller.signal, nonce: 'abc123', report() {} }), /cancelled transfer/)
+    assert.equal(cleaned, true)
+  } finally { await rm(directory, { recursive: true, force: true }) }
+})
+
+// Installed npm packages run these tests without the repository's models directory.
+async function modelCase(callback, size = 1024) {
+  const directory = await mkdtemp(join(tmpdir(), 'esp-vision-model-ack-'))
+  try {
+    const model = join(directory, 'model.espdl'), bytes = typeof size === 'number' ? Buffer.alloc(size, 42) : Buffer.from(size)
+    await writeFile(model, bytes)
+    await callback({ model, bytes, device: devicePeer(), reports: [] })
+  } finally { await rm(directory, { recursive: true, force: true }) }
+}
+
+test('model upload retries a complete public execute only for uncertain TIMEOUT and reports recovery', async () => {
+  for (const executed of [false, true]) await modelCase(async ({ model, device, reports }) => {
+    const execute = device.python.execute, attempts = []
+    let first = true
+    device.python.execute = async request => {
+      if (request.source.includes('[\'model_command\']("append",')) {
+        attempts.push(request.source)
+        if (first) {
+          first = false
+          if (executed) await execute(request)
+          throw Object.assign(new Error('uncertain acknowledgement'), { code: 'TIMEOUT' })
+        }
+      }
+      return execute(request)
+    }
+    await runDeviceChecks(device, parseArgs(['--tcp', 'test', '--checks', 'espdl_inference', '--model', model, '--require-all']), { nonce: 'acktest', report: value => reports.push(value) })
+    assert.equal(attempts[0], attempts[1])
+    const data = reports.find(result => result.check === 'espdl_inference').data
+    assert.equal(data.modelRetries, 1)
+    assert.deepEqual(data.modelRetryOffsets, [{ offset: 0, retries: 1 }])
+    assert.equal(attempts.length, data.modelChunks + 1)
+  })
+})
+
+test('model upload limits timeout attempts to three and never retries cancellation or semantic errors', async () => {
+  for (const mode of ['timeout', 'error', 'abort']) await modelCase(async ({ model, device, reports }) => {
+    const execute = device.python.execute, controller = new AbortController()
+    let attempts = 0
+    device.python.execute = async request => {
+      if (request.source.includes('[\'model_command\']("append",')) {
+        attempts++
+        const error = Object.assign(new Error(mode), { code: mode === 'error' ? 'DATA_CONFLICT' : 'TIMEOUT' })
+        if (mode === 'abort') controller.abort(error)
+        throw error
+      }
+      return execute(request)
+    }
+    await assert.rejects(runDeviceChecks(device, parseArgs(['--tcp', 'test', '--checks', 'espdl_inference', '--model', model, '--require-all']), { signal: controller.signal, nonce: 'acktest', report: value => reports.push(value) }))
+    assert.equal(attempts, mode === 'timeout' ? 3 : 1)
+  })
+})
+
+test('every model operation requires a semantic ACK even when Python prints an exception with ok true', async () => {
+  for (const operation of ['begin', 'append', 'mount', 'close', 'cleanup']) await modelCase(async ({ model, device, reports }) => {
+    const execute = device.python.execute
+    let attempts = 0
+    device.python.execute = async request => {
+      if (request.source.includes(`['model_command']("${operation}"`) || (operation === 'cleanup' && request.source.startsWith('assert '))) {
+        attempts++
+        return { ok: true, output: 'Traceback (most recent call last):\nOSError: injected failure\n' }
+      }
+      return execute(request)
+    }
+    await assert.rejects(runDeviceChecks(device, parseArgs(['--tcp', 'test', '--checks', 'espdl_inference', '--model', model, '--require-all']), { nonce: 'acktest', report: value => reports.push(value) }), { code: 'DEVICE_CHECKS_FAILED' })
+    assert.equal(attempts, 1)
+    assert.ok(reports.some(result => result.status === 'FAIL'))
+  })
+})
+
+test('upload ACK rejects stale nonce, wrong offset, duplicate markers and malformed output without retry', async () => {
+  for (const invalid of ['nonce', 'offset', 'duplicate', 'malformed']) await modelCase(async ({ model, device, reports }) => {
+    const execute = device.python.execute
+    let attempts = 0
+    device.python.execute = async request => {
+      const response = await execute(request)
+      if (request.source.includes('[\'model_command\']("append",')) {
+        attempts++
+        const ack = JSON.parse(response.output.slice('__EVHILACK__'.length))
+        if (invalid === 'nonce') ack[0] = 'stale'
+        if (invalid === 'offset') ack[2].current++
+        response.output = '__EVHILACK__' + JSON.stringify(ack)
+        if (invalid === 'duplicate') response.output += '\n' + response.output
+        if (invalid === 'malformed') response.output = '__EVHILACK__broken'
+      }
+      return response
+    }
+    await assert.rejects(runDeviceChecks(device, parseArgs(['--tcp', 'test', '--checks', 'espdl_inference', '--model', model]), { nonce: 'acktest', report: value => reports.push(value) }), { code: 'DEVICE_CHECKS_FAILED' })
+    assert.equal(attempts, 1)
+    assert.equal(reports.find(result => result.check === 'espdl_inference').error.code, 'MODEL_ACK_INVALID')
+  })
+})
+
+test('begin timeout before its body preserves the original error and still acknowledges empty cleanup', async () => {
+  await modelCase(async ({ model, device, reports }) => {
+    const execute = device.python.execute
+    device.python.execute = async request => {
+      if (request.source.includes('[\'model_command\']("begin",')) throw Object.assign(new Error('begin preparation timeout'), { code: 'TIMEOUT' })
+      return execute(request)
+    }
+    await assert.rejects(runDeviceChecks(device, parseArgs(['--tcp', 'test', '--checks', 'espdl_inference', '--model', model]), { nonce: 'acktest', report: value => reports.push(value) }), { code: 'DEVICE_CHECKS_FAILED' })
+    assert.equal(reports.find(result => result.check === 'espdl_inference').error.code, 'TIMEOUT')
+    assert.equal(reports.at(-1).failed, 1)
+  })
+})
+
+test('full-sized model upload reserves the largest offset and final block within both live REPL budgets', async () => {
+  const modelBytes = existsSync(DEFAULT_ESPDL_MODEL) ? await readFile(DEFAULT_ESPDL_MODEL) : Buffer.alloc(495840, 42)
+  for (const limit of [256, 511]) await modelCase(async ({ model, device, reports, bytes }) => {
+    const inspect = device.inspect
+    device.inspect = async request => { const result = await inspect(request); result.capabilities.limits.replInputMax = limit; return result }
+    try { await runDeviceChecks(device, parseArgs(['--tcp', 'test', '--checks', 'espdl_inference', '--model', model]), { nonce: '0123456789abcdef', report: value => reports.push(value) }) }
+    catch { assert.fail(JSON.stringify({ limit, reports })) }
+    const commands = device.calls.filter(call => call[0] === 'execute').map(call => call[1])
+    assert.ok(commands.every(source => evReplExecInputBytes(source) <= limit))
+    const chunks = commands.filter(source => source.includes('[\'model_command\']("append",')).map(source => JSON.parse('[' + source.slice(source.indexOf('](') + 2, -1) + ']'))
+    let offset = 0
+    for (const [, actualOffset, encoded] of chunks) { assert.equal(actualOffset, offset); offset += Buffer.from(encoded, 'base64').length }
+    assert.equal(offset, bytes.length)
+    assert.deepEqual(Buffer.concat(chunks.map(chunk => Buffer.from(chunk[2], 'base64'))), bytes)
+    assert.equal(reports.find(result => result.check === 'espdl_inference').data.modelChunks, limit === 511 ? 1517 : 3673)
+  }, modelBytes)
+})
+
+test('repository checkouts provide the default ESP-DL model', { skip: !existsSync(new URL('../../../models/', import.meta.url)) }, async () => {
+  const bytes = await readFile(DEFAULT_ESPDL_MODEL)
+  assert.equal(bytes.length, 495840)
+  assert.equal(createHash('sha256').update(bytes).digest('hex'), DEFAULT_ESPDL_SHA256)
+})
+
+test('ISP cleanup releases camera and collects memory even when display deinit fails', t => {
+  const python = [process.env.PYTHON, 'python3', 'python'].filter(Boolean).find(command => spawnSync(command, ['-c', 'pass'], { windowsHide: true }).status === 0)
+  if (!python) return t.skip('Python is required to execute the device-side cleanup fixture')
+  const source = `
+import runpy, sys, types
+fixture = runpy.run_path(sys.argv[1])
+for display_fails, camera_fails in ((False, False), (True, False), (False, True), (True, True)):
+    events = []
+    class Display:
+        def deinit(self):
+            events.append('display')
+            if display_fails:
+                raise RuntimeError('display cleanup failed')
+    def shutdown():
+        events.append('camera')
+        if camera_fails:
+            raise RuntimeError('camera cleanup failed')
+    sys.modules['sensor'] = types.SimpleNamespace(shutdown=shutdown)
+    sys.modules['gc'] = types.SimpleNamespace(collect=lambda: events.append('collect'))
+    try:
+        fixture['isp_release_camera_lcd'](Display())
+    except RuntimeError:
+        assert display_fails or camera_fails
+    else:
+        assert not display_fails and not camera_fails
+    assert events == ['display', 'camera', 'collect'], events
+`
+  const result = spawnSync(python, ['-c', source, fileURLToPath(new URL('./fixtures/device-checks.py', import.meta.url))], { encoding: 'utf8', windowsHide: true })
+  assert.equal(result.status, 0, result.stderr)
+})

package/tests/test-device-v4-alignment.mjs

@@ -10,6 +10,37 @@ function fixture(options = {}) {
   return new DeviceSession({ transport: { async writeBytes() {} }, EvMuxParser, makeEvMuxFrame, EvRepl, ...options })
 }
 
+async function flushMicrotasks() {
+  for (let i = 0; i < 20; i++) await Promise.resolve()
+}
+
+async function advance(t, ms) {
+  t.mock.timers.tick(ms)
+  await flushMicrotasks()
+}
+
+function startupFixture(t, { signal, progressMs = 12000, totalMs = 12000 } = {}) {
+  t.mock.timers.enable({ apis: ['setTimeout', 'Date'], now: 0 })
+  const stats = { writes: 0, requests: 0, disconnects: 0, settled: false, firstRequestAt: null }
+  const diagnostics = []
+  const session = fixture({
+    transport: { async writeBytes() { stats.writes += 1 }, async disconnect() { stats.disconnects += 1 } },
+    handlers: { diagnostic: event => diagnostics.push(event) },
+  })
+  session.parser.setLimits({ frameProgressTimeoutMs: progressMs, frameTotalTimeoutMs: totalMs })
+  session.rpc = async () => {
+    stats.requests += 1
+    stats.firstRequestAt = Date.now()
+    throw new Error('first request reached')
+  }
+  const result = session.negotiate({ role: 'usb', signal }).then(
+    () => { throw new Error('unexpected successful fixture negotiation') },
+    error => { stats.settled = true; return error },
+  )
+  t.after(() => { session.close(); session.parser.reset() })
+  return { session, stats, diagnostics, result }
+}
+
 test('Unicode Python is ASCII on the wire and length preflight includes escapes', async () => {
   let command
   const repl = new EvRepl({ writeEvmux() {} })
@@ -73,16 +104,239 @@ test('startup drain parses split frames without adopting old sessions', async ()
   session.close()
 })
 
-test('unfinished startup frames close the transport before any request', async () => {
-  let session, writes = 0, disconnects = 0
+test('startup waits for a valid frame split across 299/301 ms without accepting old sessions', async t => {
+  const f = startupFixture(t)
+  const frame = makeEvMuxFrame({ channel: 'user.rpc', type: 'event', method: 'hello',
+    sessionId: 'a'.repeat(32), vmEpoch: 9,
+    payload: JSON.stringify({ evMuxVersion: 4, session: { id: 'a'.repeat(32), vmEpoch: 9 }, vmEpoch: 9 }) })
+  await advance(t, 299)
+  f.session.feedBytes(frame.subarray(0, 20))
+  await advance(t, 1)
+  assert.equal(f.stats.settled, false)
+  assert.equal(f.stats.requests, 0)
+  assert.equal(f.session.draining, true)
+  assert.equal(f.session.sessionId, null)
+  assert.equal(f.session.vmEpoch, null)
+  const snapshot = f.session.parser.getDiagnostics()
+  assert.equal(snapshot.partialFrame.startedAt, 299)
+  snapshot.partialFrame.totalDeadline = 0
+  assert.equal(f.session.parser.getDiagnostics().partialFrame.totalDeadline, 12299)
+  await advance(t, 1)
+  const staleLog = makeEvMuxFrame({ channel: 'log.idf', payload: 'old startup text' })
+  f.session.feedBytes(Buffer.concat([frame.subarray(20), staleLog]))
+  assert.match((await f.result).message, /first request reached/)
+  assert.equal(f.stats.firstRequestAt, 301)
+  assert.equal(f.stats.disconnects, 0)
+  assert.equal(f.session.sessionId, null)
+  assert.equal(f.session.vmEpoch, null)
+  assert.equal(f.session.parser.getDiagnostics().droppedFrames, 2)
+  assert.equal(f.session.parser.getDiagnostics().bufferedBytes, 0)
+  assert.equal(f.session.startupDrainWait, null)
+  assert.equal(f.session.draining, false)
+})
+
+test('a frame complete before 300 ms adds no startup wait', async t => {
+  const f = startupFixture(t)
+  await advance(t, 299)
+  f.session.feedBytes(makeEvMuxFrame({ channel: 'log.idf', payload: 'complete' }))
+  await advance(t, 1)
+  assert.match((await f.result).message, /first request reached/)
+  assert.equal(f.stats.firstRequestAt, 300)
+  assert.equal(f.session.startupDrainWait, null)
+  assert.equal(f.diagnostics.some(event => event.event === 'negotiate.startup_frame_wait'), false)
+})
+
+for (const [kind, makePartial] of [
+  ['header', frame => frame.subarray(0, 20)],
+  ['body', frame => frame.subarray(0, -1)],
+]) {
+  test(`a truncated startup ${kind} times out before any request, even after the parser empties it`, async t => {
+    const f = startupFixture(t, { progressMs: 500, totalMs: 2000 })
+    const frame = makeEvMuxFrame({ channel: 'user.rpc', type: 'event', method: 'hello', payload: '{}' })
+    await advance(t, 299)
+    f.session.feedBytes(makePartial(frame))
+    await advance(t, 1)
+    assert.equal(f.session.draining, true)
+    assert.equal(f.stats.requests, 0)
+    await advance(t, 498)
+    assert.equal(f.stats.settled, false)
+    await advance(t, 1)
+    assert.equal((await f.result).code, 'SERIAL_STARTUP_INCOMPLETE_FRAME')
+    assert.equal(f.stats.requests, 0)
+    assert.equal(f.stats.writes, 0)
+    assert.equal(f.stats.disconnects, 1)
+    assert.equal(f.session.state, 'disconnected')
+    assert.equal(f.session.startupDrainWait, null)
+    const error = f.diagnostics.find(event => event.event === 'negotiate.startup_incomplete')
+    assert.equal(error.parser.incompleteFrameTimeouts, 1)
+    assert.equal(error.parser.bufferedBytes, 0)
+  })
+}
+
+test('successive coalesced startup frames cannot extend the initial partial-frame deadline', async t => {
+  const f = startupFixture(t, { progressMs: 1000, totalMs: 500 })
+  const frame = makeEvMuxFrame({ channel: 'log.idf', payload: 'ongoing output' })
+  await advance(t, 299)
+  f.session.feedBytes(frame.subarray(0, 20))
+  await advance(t, 1)
+  await advance(t, 1)
+  f.session.feedBytes(Buffer.concat([frame.subarray(20), frame.subarray(0, 20)]))
+  await advance(t, 299)
+  f.session.feedBytes(Buffer.concat([frame.subarray(20), frame.subarray(0, 20)]))
+  await advance(t, 198)
+  assert.equal(f.stats.settled, false)
+  assert.equal(f.session.draining, true)
+  assert.equal(f.stats.requests, 0)
+  await advance(t, 1)
+  assert.equal((await f.result).code, 'SERIAL_STARTUP_INCOMPLETE_FRAME')
+  assert.equal(Date.now(), 799)
+  assert.equal(f.stats.requests, 0)
+  assert.equal(f.stats.writes, 0)
+  assert.equal(f.stats.disconnects, 1)
+  const error = f.diagnostics.find(event => event.event === 'negotiate.startup_incomplete')
+  assert.equal(error.parser.partialFrame.startedAt, 600)
+  assert.equal(error.parser.incompleteFrameTimeouts, 0)
+})
+
+test('back-to-back adapter notifications cannot send hello between a completed tail and another prefix', async t => {
+  const f = startupFixture(t)
+  const frame = makeEvMuxFrame({ channel: 'log.idf', payload: 'adjacent chunks' })
+  await advance(t, 299)
+  f.session.feedBytes(frame.subarray(0, 20))
+  await advance(t, 1)
+  await advance(t, 1)
+  f.session.feedBytes(frame.subarray(20))
+  f.session.feedBytes(frame.subarray(0, 20))
+  await flushMicrotasks()
+  assert.equal(f.stats.requests, 0)
+  assert.equal(f.session.draining, true)
+  assert.notEqual(f.session.startupDrainWait, null)
+  await advance(t, 1)
+  f.session.feedBytes(frame.subarray(20))
+  assert.match((await f.result).message, /first request reached/)
+  assert.equal(f.stats.firstRequestAt, 302)
+  assert.equal(f.session.startupDrainWait, null)
+})
+
+test('actual startup progress refreshes the idle budget within the fixed total deadline', async t => {
+  const f = startupFixture(t, { progressMs: 100, totalMs: 2000 })
+  const frame = makeEvMuxFrame({ channel: 'log.idf', payload: 'progress' })
+  await advance(t, 299)
+  f.session.feedBytes(frame.subarray(0, 20))
+  await advance(t, 1)
+  await advance(t, 50)
+  f.session.feedBytes(frame.subarray(20, 21))
+  await advance(t, 99)
+  assert.equal(f.stats.settled, false)
+  await advance(t, 1)
+  assert.equal((await f.result).code, 'SERIAL_STARTUP_INCOMPLETE_FRAME')
+  assert.equal(Date.now(), 450)
+  assert.equal(f.stats.requests, 0)
+  assert.equal(f.stats.disconnects, 1)
+})
+
+test('a receive timeout inside the initial 300 ms cannot become an empty successful drain', async t => {
+  const f = startupFixture(t, { progressMs: 100, totalMs: 1000 })
+  await advance(t, 1)
+  f.session.feedBytes(new TextEncoder().encode('\x1eEVMUX/1 h='))
+  await advance(t, 100)
+  assert.equal(f.session.parser.hasPartialFrame(), false)
+  assert.equal(f.session.parser.getDiagnostics().incompleteFrameTimeouts, 1)
+  await advance(t, 199)
+  assert.equal((await f.result).code, 'SERIAL_STARTUP_INCOMPLETE_FRAME')
+  assert.equal(f.stats.requests, 0)
+  assert.equal(f.stats.writes, 0)
+  assert.equal(f.stats.disconnects, 1)
+})
+
+test('a complete tail received after an expired idle budget cannot bypass the queued timeout', async t => {
+  const f = startupFixture(t, { progressMs: 100, totalMs: 2000 })
+  const frame = makeEvMuxFrame({ channel: 'log.idf', payload: 'late tail' })
+  await advance(t, 299)
+  f.session.feedBytes(frame.subarray(0, 20))
+  await advance(t, 1)
+  // Model a busy event loop: the wall clock passes the idle deadline before
+  // either timer callback runs, then an already queued read delivers the tail.
+  t.mock.timers.setTime(400)
+  f.session.feedBytes(frame.subarray(20))
+  assert.equal((await f.result).code, 'SERIAL_STARTUP_INCOMPLETE_FRAME')
+  assert.equal(f.stats.requests, 0)
+  assert.equal(f.stats.writes, 0)
+  assert.equal(f.stats.disconnects, 1)
+})
+
+test('dripping bytes of one startup frame cannot extend its total budget', async t => {
+  const f = startupFixture(t, { progressMs: 150, totalMs: 400 })
+  const frame = makeEvMuxFrame({ channel: 'log.idf', payload: 'progress' })
+  await advance(t, 299)
+  f.session.feedBytes(frame.subarray(0, 20))
+  await advance(t, 1)
+  for (let i = 0; i < 3; i++) {
+    await advance(t, 100)
+    f.session.feedBytes(frame.subarray(20 + i, 21 + i))
+  }
+  await advance(t, 98)
+  assert.equal(f.stats.settled, false)
+  await advance(t, 1)
+  assert.equal((await f.result).code, 'SERIAL_STARTUP_INCOMPLETE_FRAME')
+  assert.equal(Date.now(), 699)
+  assert.equal(f.stats.requests, 0)
+  assert.equal(f.stats.writes, 0)
+  assert.equal(f.stats.disconnects, 1)
+})
+
+for (const action of ['cancel', 'close']) {
+  test(`${action} promptly clears the startup boundary waiter without sending a request`, async t => {
+    const controller = new AbortController()
+    const f = startupFixture(t, { signal: controller.signal })
+    await advance(t, 299)
+    f.session.feedBytes(new TextEncoder().encode('\x1eEVMUX/1 h='))
+    await advance(t, 1)
+    assert.notEqual(f.session.startupDrainWait, null)
+    const reason = new Error(`test ${action}`)
+    if (action === 'cancel') controller.abort(reason)
+    else f.session.close(reason)
+    assert.equal(await f.result, reason)
+    assert.equal(f.session.startupDrainWait, null)
+    assert.equal(f.session.draining, false)
+    assert.equal(f.session.negotiateController, null)
+    await advance(t, 13000)
+    assert.equal(f.stats.requests, 0)
+    assert.equal(f.stats.writes, 0)
+    assert.equal(f.diagnostics.some(event => event.event === 'negotiate.startup_incomplete'), false)
+  })
+}
+
+test('injected legacy parsers keep the conservative incomplete-frame failure without private budget methods', async () => {
+  class LegacyParser {
+    constructor(handlers) { this.parser = new EvMuxParser(handlers) }
+    feedBytes(bytes) { this.parser.feedBytes(bytes) }
+    hasPartialFrame() { return this.parser.hasPartialFrame() }
+    reset() { this.parser.reset() }
+  }
+  let session, disconnects = 0, requests = 0
   session = fixture({
-    transport: { async writeBytes() { writes += 1 }, async disconnect() { disconnects += 1 } },
-    sleep: async () => { session.feedBytes(new TextEncoder().encode('\x1eEVMUX/1 h=100 p=0 c=00000000\r\n{')) },
+    EvMuxParser: LegacyParser,
+    transport: { async writeBytes() {}, async disconnect() { disconnects += 1 } },
+    sleep: async () => session.feedBytes(new TextEncoder().encode('\x1eEVMUX/1 h=')),
   })
-  await assert.rejects(session.negotiate({ drainMs: 300 }), error => error.code === 'SERIAL_STARTUP_INCOMPLETE_FRAME')
-  assert.equal(writes, 0)
+  session.rpc = async () => { requests += 1; throw new Error('unexpected request') }
+  await assert.rejects(session.negotiate(), error => error.code === 'SERIAL_STARTUP_INCOMPLETE_FRAME')
+  assert.equal(requests, 0)
   assert.equal(disconnects, 1)
-  assert.equal(session.state, 'disconnected')
+  assert.equal(session.startupDrainWait, null)
+  session.close()
+})
+
+test('injected parsers without optional startup diagnostics or boundary methods remain supported', async () => {
+  class MinimalParser extends EvMuxParser {
+    constructor(handlers) { super(handlers); this.hasPartialFrame = undefined; this.getDiagnostics = undefined }
+  }
+  const session = fixture({ EvMuxParser: MinimalParser, sleep: async () => {} })
+  session.rpc = async () => { throw new Error('first request reached') }
+  await assert.rejects(session.negotiate(), /first request reached/)
+  session.close()
+  session.parser.reset()
 })
 
 test('plain console tails do not fail drain and TCP does not wait for drain', async () => {

package/tests/test-firmware-flash.mjs

@@ -1,9 +1,9 @@
 import assert from 'node:assert/strict'
 import { test } from 'node:test'
 import { FirmwareFlashSession, firmwareSha256, validateFirmwareImage } from '../src/firmware_flash.js'
-async function fixture() {
+async function fixture(chipFamily = 0x3280) {
   const bytes = new Uint8Array([0xe9, 1, 2, 3]), table = new Uint8Array([4, 5, 6]), calls = []
-  const image = { evMuxVersion: 4, chipFamily: 0x3280, chipRevision: 302, offset: 0x10000, bytes: 4, partitionSize: 0x700000, sha256: await firmwareSha256(bytes), partitionTable: { offset: 0x8000, bytes: 3, sha256: await firmwareSha256(table) } }
+  const image = { evMuxVersion: 4, chipFamily, chipRevision: chipFamily === 0x3231 ? 0 : 302, offset: 0x10000, bytes: 4, partitionSize: 0x700000, sha256: await firmwareSha256(bytes), partitionTable: { offset: 0x8000, bytes: 3, sha256: await firmwareSha256(table) } }
   const stub = { async readFlash(offset) { calls.push(['read', offset]); return offset === 0x8000 ? table : bytes }, async readRegister() { return 0x1dfbc7f8 }, async writeRegister() { throw new Error('unexpected register write') }, async flashData(_data, progress, offset, compress) { calls.push(['write', offset, compress]); progress(4, 4) } }
   const loader = { chipFamily: image.chipFamily, chipRevision: image.chipRevision, async initialize() { calls.push(['initialize']) }, async getSecurityInfo() { return { flags: 0, flashCryptCnt: 0 } }, async runStub(skip) { calls.push(['stub', skip]); return stub }, async readRegister() { return 0x1dfbc7f8 }, async writeRegister() { throw new Error('unexpected register write') }, async hardReset() { calls.push(['reset']) }, async disconnect() { calls.push(['close']) } }
   return { bytes, table, image, calls, loader, stub, session: new FirmwareFlashSession(loader, image) }
@@ -69,21 +69,23 @@ test('unsigned application updates refuse secure boot and flash encryption befor
 })
 
 
-test('P4 software download latch is cleared with a mask and verified before reset', async () => {
-  const f = await fixture(), registers = []; let register = 0x1dfbc7fc
-  f.stub.readRegister = async address => { registers.push(['read', address]); return register }
-  f.stub.writeRegister = async (address, value, mask) => { registers.push(['write', address, value, mask]); register &= ~mask }
-  f.loader.hardReset = async () => { assert.equal(register, 0x1dfbc7f8); f.calls.push(['reset']) }
-  await f.session.connect(f.bytes); await f.session.flash(f.bytes)
-  assert.equal(register, 0x1dfbc7f8)
-  assert.deepEqual(registers, [['read', 0x50110008], ['write', 0x50110008, 0, 4], ['read', 0x50110008]])
-  assert.ok(f.calls.some(([operation]) => operation === 'reset'))
-})
-test('P4 latch clear failure does not reset and retains manual recovery guidance', async () => {
-  const f = await fixture(), messages = []
-  f.stub.readRegister = async () => 0x1dfbc7fc
-  f.stub.writeRegister = async () => {}
-  await f.session.connect(f.bytes); await f.session.flash(f.bytes, { onPhase: message => messages.push(message) })
-  assert.ok(!f.calls.some(([operation]) => operation === 'reset'))
-  assert.match(messages.at(-1), /verified.*RESET/)
-})
+for (const [name, family, address] of [['P4', 0x3280, 0x50110008], ['S31', 0x3231, 0x20700008]]) {
+  test(`${name} software download latch is cleared with a mask and verified before reset`, async () => {
+    const f = await fixture(family), registers = []; let register = 0x1dfbc7fc
+    f.stub.readRegister = async address => { registers.push(['read', address]); return register }
+    f.stub.writeRegister = async (address, value, mask) => { registers.push(['write', address, value, mask]); register &= ~mask }
+    f.loader.hardReset = async () => { assert.equal(register, 0x1dfbc7f8); f.calls.push(['reset']) }
+    await f.session.connect(f.bytes); await f.session.flash(f.bytes)
+    assert.equal(register, 0x1dfbc7f8)
+    assert.deepEqual(registers, [['read', address], ['write', address, 0, 4], ['read', address]])
+    assert.ok(f.calls.some(([operation]) => operation === 'reset'))
+  })
+  test(`${name} latch clear failure does not reset and retains manual recovery guidance`, async () => {
+    const f = await fixture(family), messages = []
+    f.stub.readRegister = async () => 0x1dfbc7fc
+    f.stub.writeRegister = async () => {}
+    await f.session.connect(f.bytes); await f.session.flash(f.bytes, { onPhase: message => messages.push(message) })
+    assert.ok(!f.calls.some(([operation]) => operation === 'reset'))
+    assert.match(messages.at(-1), /verified.*RESET/)
+  })
+}