mobile-debug-mcp 0.34.0 → 0.35.0

package/test/unit/debugger/protocol.test.ts

@@ -0,0 +1,15 @@
+import assert from 'node:assert/strict'
+import { parseWorkerMessage } from '../../../src/debugger/protocol.js'
+
+const event = { event: 'stopped', stop_id: 'stop-1', thread_id: 'thread-1', stops: [] }
+assert.deepEqual(parseWorkerMessage(event), { kind: 'event', value: event })
+assert.deepEqual(parseWorkerMessage({ id: 1, result: { locals: [] } }), { kind: 'reply', id: 1, result: { locals: [] } })
+assert.deepEqual(parseWorkerMessage({ id: 2, error: { code: 'DEBUGGER_STALE_REFERENCE' } }), {
+  kind: 'reply', id: 2, result: {}, error: { code: 'DEBUGGER_STALE_REFERENCE' }
+})
+for (const invalid of [null, [], { event: 42 }, { event: 'stopped', stop_id: 42 },
+  { id: '1', result: {} }, { id: -1, result: {} }, { id: 1.2, result: {} },
+  { id: 1, result: 'private-debuggee-value' }, { id: 1, error: { code: 42 } }]) {
+  assert.throws(() => parseWorkerMessage(invalid), /^Error: INVALID_WORKER_/, 'malformed worker input is rejected without exposing its contents')
+}
+console.log('PASS validated worker events/replies and content-free protocol errors')

package/test/unit/debugger/sessions.test.ts

@@ -2,7 +2,7 @@ import assert from 'node:assert/strict'
 import { DebuggerSessions, debuggerExpiry } from '../../../src/debugger/sessions.js'
 import { DebuggerError, type WorkerEvent } from '../../../src/debugger/worker.js'
 import type { DebugNative, DebugTarget } from '../../../src/debugger/android.js'
-import { debuggerContracts, debuggerTools } from '../../../src/server/debugger-schema.js'
+import { debuggerContracts, debuggerTools } from '../../../src/server/schemas/debugger-schema.js'
 assert.equal(debuggerExpiry(0, 0, 0, 59999), null)
 assert.equal(debuggerExpiry(0, 60000, 0, 60000), 'pause_limit', 'polling cannot extend pause expiry')
 assert.equal(debuggerExpiry(0, 0, undefined, 300000), 'idle_limit')

package/test/unit/interact/adjustment_service.test.ts

@@ -0,0 +1,42 @@
+import assert from 'node:assert/strict'
+import { adjustControl } from '../../../src/interact/adjustment/adjustment.js'
+import type { AdjustmentDependencies } from '../../../src/interact/adjustment/adjustment-context.js'
+import type { ActionTargetResolved, DeviceInfo } from '../../../src/types.js'
+import type { UiElement } from '../../../src/interact/model.js'
+
+const device: DeviceInfo = { platform: 'android', id: 'fixture', model: 'fixture', osVersion: 'fixture', simulator: true }
+let value = 10
+const calls: string[] = []
+const element = (): UiElement => ({ visible: true, enabled: true, role: 'slider', stable_id: 'duration', bounds: [0, 0, 300, 40],
+  state: { value, value_range: { min: 0, max: 100 } }, actions: ['set_value'] })
+const handle = { elementId: 'handle', platform: 'android' as const, deviceId: device.id, bounds: [0, 0, 300, 40] as [number, number, number, number], index: 0, stable_id: 'duration' }
+const target = (): ActionTargetResolved => ({ elementId: 'handle', text: null, resource_id: null, accessibility_id: null, class: 'Slider', bounds: handle.bounds, index: 0 })
+const deps: AdjustmentDependencies = {
+  observe: async () => ({ device, elements: [element()] }), fingerprint: async () => 'fingerprint',
+  getHandle: () => handle, currentHandle: () => ({ el: element(), index: 0 }), target,
+  wait: async () => { throw new Error('handle targeting must not use selector waits') },
+  find: async () => { throw new Error('handle targeting must not use semantic search') },
+  expectState: async input => {
+    calls.push('verify')
+    return { success: true, element_id: 'handle', expected_state: { property: input.property, expected: input.expected },
+      observed_state: { property: input.property, value }, trace: { action_id: 'assertion', steps: [], final_outcome: 'success', attempts: 1 } }
+  },
+  service: async () => ({ resolved: { id: device.id }, interact: { setAdjustableValue: async () => { calls.push('semantic'); return { success: false } } } }),
+  tap: async () => { calls.push('coordinate'); value = 20; return { success: true, device } },
+  swipe: async () => { throw new Error('a converged coordinate adjustment must not dispatch a gesture') }
+}
+const already = await adjustControl({ element_id: 'handle', targetValue: 10 }, deps)
+assert.equal(already.success, true)
+assert.equal(already.attempts, 0)
+assert.deepEqual(calls, [])
+const adjusted = await adjustControl({ element_id: 'handle', targetValue: 20 }, deps)
+assert.equal(adjusted.success, true)
+assert.equal(adjusted.attempts, 2)
+assert.equal(adjusted.adjustment_mode, 'coordinate')
+assert.deepEqual(calls, ['semantic', 'coordinate', 'verify'], 'failed direct capability falls back in the established order')
+calls.length = 0
+const stale = await adjustControl({ element_id: 'missing', targetValue: 20 }, { ...deps, getHandle: () => undefined })
+assert.equal(stale.success, false)
+assert.equal(stale.failure_code, 'STALE_REFERENCE')
+assert.deepEqual(calls, [], 'missing handles cannot dispatch native input')
+console.log('PASS injected adjustment service: read-only convergence, strategy order, attempt accounting and stale-handle rejection')

package/test/unit/interact/adjustment_verification.test.ts

@@ -0,0 +1,35 @@
+import assert from 'node:assert/strict'
+import type { ExpectStateResponse } from '../../../src/types.js'
+import { verifyAdjustment, type AdjustmentVerificationInput } from '../../../src/interact/adjustment/adjustment-verification.js'
+
+const input: AdjustmentVerificationInput = {
+  labeled: false, currentEl: { state: { value: 10 } },
+  actualState: { property: 'value', value: 10 }, property: 'value', target: 20, tolerance: 0.5,
+  expectation: { element_id: 'control', property: 'value', expected: 20, platform: 'android', deviceId: 'fixture' }
+}
+let observations = 0
+let assertions = 0
+const verified = await verifyAdjustment(input, {
+  observe: async () => { throw new Error('ordinary verification must use the assertion boundary') },
+  expectState: async args => {
+    assertions++
+    assert.equal(args.element_id, 'control')
+    return { success: false, observed_state: { value: 20.25 }, reason: 'exact comparison failed' } as ExpectStateResponse
+  }
+})
+assert.equal(assertions, 1)
+assert.equal(verified.withinTolerance, true, 'numeric tolerance is independent of exact assertion success')
+assert.equal(verified.observedState?.value, 20.25)
+const stale = await verifyAdjustment({ ...input, labeled: true, actualState: { property: 'value', value: 20 } }, {
+  observe: async () => { observations++; return { elements: [] } },
+  expectState: async () => { throw new Error('label verification must acquire a new tree') }
+})
+assert.equal(observations, 1)
+assert.equal(stale.withinTolerance, false, 'fallback state must not establish fresh convergence')
+assert.equal(stale.verification.success, false)
+assert.equal(stale.observedState?.value, 20, 'last readable state remains available for diagnostics')
+await assert.rejects(verifyAdjustment(input, {
+  observe: async () => null,
+  expectState: async () => { throw new Error('ACTION_TIMEOUT') }
+}), /ACTION_TIMEOUT/, 'timeouts propagate without manufacturing an observation')
+console.log('PASS adjustment verification dependencies, tolerance, freshness and timeout preservation')

package/test/unit/interact/clock_dependencies.test.ts

@@ -0,0 +1,63 @@
+import assert from 'node:assert/strict'
+import type { Clock } from '../../../src/runtime/clock.js'
+import type { UiTree } from '../../../src/interact/observation.js'
+import { waitForUI } from '../../../src/interact/waits/ui-wait.js'
+import { waitForScreenChange } from '../../../src/interact/waits/screen-wait.js'
+import { findElement } from '../../../src/interact/targeting/find-element.js'
+import { expectState } from '../../../src/interact/assertions/state-assertion.js'
+import { _resolvedTargetFromElement } from '../../../src/interact/targeting/element-helpers.js'
+
+function fakeClock() {
+  let now = 1000
+  const delays: number[] = []
+  const clock: Clock = { now: () => now, sleep: async ms => { delays.push(ms); now += ms } }
+  return { clock, delays }
+}
+const resolve = (_platform: string, _device: string | undefined, element: NonNullable<UiTree['elements']>[number], index: number) => _resolvedTargetFromElement('test-id', element, index)
+const present = (clock: Clock): UiTree => ({ captured_at_ms: clock.now(), elements: [{ text: 'Button', state: { enabled: true } }] })
+
+{
+  const { clock, delays } = fakeClock()
+  const result = await waitForUI({ selector: { text: 'Button' }, timeout_ms: 500, poll_interval_ms: 50 }, {
+    clock, observe: async () => present(clock), resolve
+  })
+  assert.equal(result?.status, 'success')
+  assert.deepEqual(result?.metrics, { latency_ms: 50, poll_count: 2, attempts: 1 })
+  assert.deepEqual(delays, [50])
+}
+{
+  const { clock, delays } = fakeClock()
+  const result = await waitForUI({ selector: { text: 'missing' }, timeout_ms: 100, poll_interval_ms: 50,
+    retry: { max_attempts: 2, backoff_ms: 20 } }, { clock, observe: async () => ({ elements: [] }), resolve })
+  assert.equal(result?.status, 'timeout')
+  assert.deepEqual(result?.metrics, { latency_ms: 320, poll_count: 6, attempts: 2 })
+  assert.deepEqual(delays, [50, 50, 50, 20, 50, 50, 50])
+}
+{
+  const { clock, delays } = fakeClock()
+  let samples = 0
+  const result = await waitForScreenChange({ previousFingerprint: 'old', timeoutMs: 500, pollIntervalMs: 50 }, {
+    clock, fingerprint: async () => ({ fingerprint: samples++ === 0 ? 'old' : 'new' })
+  })
+  assert.equal(result.success, true)
+  assert.equal(result.elapsedMs, 100)
+  assert.deepEqual(delays, [50, 50])
+}
+{
+  const { clock, delays } = fakeClock()
+  const result = await findElement({ query: 'missing', timeoutMs: 200 }, async () => ({ elements: [] }), clock)
+  assert.equal(result.found, false)
+  assert.deepEqual(delays, [100, 100, 100])
+}
+{
+  const { clock, delays } = fakeClock()
+  const result = await expectState({ selector: { text: 'Button' }, property: 'enabled', expected: true }, {
+    clock, observe: async () => present(clock), getHandle: () => undefined,
+    currentHandle: () => null, target: (platform, device, match) => resolve(platform, device, match.el, match.idx)
+  })
+  assert.equal(result.success, true)
+  assert.equal(result.stabilization_window_ms, 150)
+  assert.deepEqual(delays, [150])
+  assert(result.trace.steps.every(step => step.timestamp >= 1000 && step.timestamp <= 1150))
+}
+console.log('PASS injected clocks: wait stability, retry/backoff deadlines, screen confirmation, search expiry and state trace timestamps without global timer replacement')

package/test/unit/interact/element_helpers.test.ts

@@ -0,0 +1,19 @@
+import assert from 'node:assert/strict'
+import { _matchesSelector, _resolveActionableAncestor, _normalizeBounds } from '../../../src/interact/targeting/element-helpers.js'
+import { _readNumericControlRange, _quantizeTargetValue } from '../../../src/interact/adjustment/control-values.js'
+
+assert(_matchesSelector({ text: 'Save', resourceId: 'app:id/save' }, { text: 'save', resource_id: 'app:id/save' }))
+assert(!_matchesSelector({ text: 'Save', resourceId: 'app:id/other' }, { text: 'save', resource_id: 'app:id/save' }), 'all supplied selector fields constrain selection')
+assert(_matchesSelector({ contentDesc: 'Save changes' }, { accessibility_id: 'changes', contains: true }))
+assert(!_matchesSelector({ text: 'Save' }, undefined))
+assert.deepEqual(_normalizeBounds(['1', 2, 3, 4]), [1, 2, 3, 4])
+assert.equal(_normalizeBounds([1, 'invalid', 3, 4]), null)
+const elements = [
+  { id: 'parent', clickable: true, bounds: [0, 0, 100, 100] },
+  { parentId: 'parent', text: 'Save', bounds: [20, 20, 40, 40] }
+]
+assert.deepEqual(_resolveActionableAncestor(elements, { el: elements[1], idx: 1 }), { el: elements[0], idx: 0 })
+assert.deepEqual(_readNumericControlRange({ state: { value: '3 of 10' } }), { min: 0, max: 10 })
+assert.equal(_readNumericControlRange({ state: { value_range: { min: 10, max: 0 } } }), null)
+assert.equal(_quantizeTargetValue(0.26, 0, 1, 0.1), 0.3)
+console.log('PASS injected-free selector, actionable ancestor, numeric range and snapping helpers')

package/test/unit/interact/legacy_wait_service.test.ts

@@ -0,0 +1,17 @@
+import assert from 'node:assert/strict'
+import { waitForUICore } from '../../../src/interact/waits/legacy-wait.js'
+import type { LegacyWaitDependencies } from '../../../src/interact/waits/legacy-wait-state.js'
+
+const calls: string[] = []
+const deps: LegacyWaitDependencies = {
+  fingerprint: async () => { calls.push('fingerprint'); return { fingerprint: 'initial' } },
+  logs: async () => { calls.push('logs'); return { logs: ['before'] } },
+  stream: async () => { calls.push('stream'); return { entries: [{ message: 'operation done' }] } },
+  find: async () => { throw new Error('log waits must not search UI elements') },
+  snapshot: async () => { throw new Error('successful waits must not collect failure snapshots') }
+}
+const result = await waitForUICore({ type: 'log', query: 'done', timeoutMs: 1000 }, deps)
+assert.equal(result.success, true)
+assert.equal(result.observed_state, true)
+assert.deepEqual(calls, ['fingerprint', 'logs', 'stream'])
+console.log('PASS injected legacy wait: baseline collection, stream-first matching and no failure snapshot')

package/test/unit/interact/state_comparison.test.ts

@@ -0,0 +1,20 @@
+import assert from 'node:assert/strict'
+import { compareReadableState } from '../../../src/interact/assertions/state-comparison.js'
+
+assert.equal(compareReadableState('checked', true, { checked: true }).success, true)
+const invalidBoolean = compareReadableState('checked', 'true', { checked: true })
+assert.equal(invalidBoolean.success, false)
+assert.equal(invalidBoolean.reason, 'expected checked must be boolean')
+assert.equal(invalidBoolean.observedValue, true)
+assert.equal(invalidBoolean.rawValue, null)
+assert.equal(compareReadableState('value', 20, { value: '20' }).success, false, 'numeric assertions do not coerce readable strings')
+assert.equal(compareReadableState('value', '20', { value: '20' }).success, true)
+assert.equal(compareReadableState('selected', { id: 'dark' }, { selected: { id: 'dark', label: 'Dark' } }).success, true)
+assert.equal(compareReadableState('selected', false, { selected: false }).success, true)
+assert.equal(compareReadableState('selected', true, { selected: 'true' }).reason, 'selected state is not boolean')
+assert.equal(compareReadableState('text_value', '', { text_value: '' }).reason, 'expected text_value must be string')
+assert.equal(compareReadableState('value', 20, null).reason, 'value state unavailable')
+const range = { min: 0, max: 20 }
+assert.equal(compareReadableState('value_range', range, { value_range: range }).success, true, 'fallback comparison preserves reference equality')
+assert.equal(compareReadableState('value_range', { min: 0, max: 20 }, { value_range: range }).success, false)
+console.log('PASS readable-state comparison compatibility without UI or global mocks')

package/test/unit/interact/target_scope.test.ts

@@ -0,0 +1,35 @@
+import assert from 'node:assert/strict'
+import { ResolvedElements } from '../../../src/interact/targeting/resolved-elements.js'
+import { findScopedElement, resolveUiChangeScope } from '../../../src/interact/targeting/target-scope.js'
+import type { ResolvedUiElementContext } from '../../../src/interact/model.js'
+
+const store = new ResolvedElements(2)
+const context = (id: string): ResolvedUiElementContext => ({
+  elementId: id, platform: 'android', deviceId: 'fixture', bounds: null, index: 0, stable_id: id
+})
+store.remember('one', context('one'))
+store.remember('two', context('two'))
+store.remember('one', context('one'))
+store.remember('three', context('three'))
+assert.equal(store.get('two'), undefined, 'oldest handle is evicted; refresh updates insertion order')
+assert(store.get('one'))
+const tree = { elements: [{ text: 'Root', stable_id: 'one', children: [1] }, { text: 'Child', parentId: 0 }] }
+const match = findScopedElement(tree, 'one', store)
+assert.equal(match?.index, 0)
+assert.equal(match?.reason, 'stable_id_match')
+let calls = 0
+const subtree = resolveUiChangeScope(tree, 'subtree', 'custom-handle', (_tree, id) => {
+  calls++
+  assert.equal(id, 'custom-handle')
+  return { index: 0, stableId: 'one', reason: 'injected_lookup' }
+})
+assert.equal(calls, 1)
+assert.equal(subtree.elements.length, 2)
+assert.equal(subtree.resolution.reason, 'injected_lookup')
+assert.equal(resolveUiChangeScope(tree, 'subtree', '', () => { throw new Error('must not resolve empty targets') }).error?.code, 'INVALID_SCOPE')
+assert.equal(resolveUiChangeScope(tree, 'subtree', 'missing', () => null).error?.code, 'ELEMENT_NOT_FOUND')
+const other = new ResolvedElements(2)
+assert.equal(other.get('one'), undefined, 'resolution stores do not share process-global state')
+store.clear()
+assert.equal(store.get('one'), undefined)
+console.log('PASS bounded handle retention and injected subtree resolution without static replacements')

package/test/unit/network/get_network_activity.test.ts

@@ -5,7 +5,7 @@ import {
   classifyStatus,
   _setTimestampsForTests,
   ToolsNetwork
-} from '../../../src/network/index.js'
+} from '../../../src/observe/network/index.js'
 
 function run() {
 

package/test/unit/observe/screenshot-encoding.test.ts

@@ -0,0 +1,30 @@
+import assert from 'node:assert/strict'
+import sharp from 'sharp'
+import { encodeScreenshot } from '../../../src/observe/screenshot-encoding.js'
+
+async function run() {
+  const alpha = await sharp({ create: { width: 2, height: 2, channels: 4, background: { r: 255, g: 0, b: 0, alpha: 0.5 } } }).png().toBuffer()
+  const opaque = await sharp({ create: { width: 2, height: 2, channels: 3, background: 'red' } }).png().toBuffer()
+  for (const platform of ['android', 'ios'] as const) {
+    const transparent = await encodeScreenshot(alpha, platform)
+    assert.equal(transparent.screenshot_mime, 'image/webp')
+    assert.equal((await sharp(Buffer.from(transparent.screenshot, 'base64')).metadata()).hasAlpha, true)
+    assert.equal(transparent.screenshot_fallback_mime, platform === 'ios' ? 'image/png' : 'image/jpeg')
+    if (platform === 'ios') assert.equal(transparent.screenshot_fallback, alpha.toString('base64'))
+    const solid = await encodeScreenshot(opaque, platform)
+    assert.equal(solid.screenshot_mime, 'image/webp')
+    assert.equal(solid.screenshot_fallback_mime, 'image/jpeg')
+    assert.equal((await sharp(Buffer.from(solid.screenshot_fallback!, 'base64')).metadata()).format, 'jpeg')
+  }
+  // An unreadable capture must survive conversion failures unchanged.
+  const invalid = Buffer.from('unreadable screenshot')
+  const originalError = console.error
+  try {
+    console.error = () => {}
+    for (const platform of ['android', 'ios'] as const) {
+      assert.deepEqual(await encodeScreenshot(invalid, platform), { screenshot: invalid.toString('base64'), screenshot_mime: 'image/png' })
+    }
+  } finally { console.error = originalError }
+  console.log('Screenshot alpha, fallback format and failed conversion tests passed')
+}
+run().catch(error => { console.error(error); process.exit(1) })

package/test/unit/observe/snapshot-logs.test.ts

@@ -0,0 +1,14 @@
+import assert from 'node:assert/strict'
+import { snapshotLog, streamLog } from '../../../src/observe/snapshot-logs.js'
+
+const iso = '2026-10-30T12:00:00Z'
+assert.deepEqual(snapshotLog({ timestamp: 123, message: 'warning', levelName: 'warn' }), { timestamp: 123, message: 'warning', level: 'WARN' })
+assert.equal(streamLog({ timestamp: 123, message: 'warning' }).timestamp, null)
+assert.equal(snapshotLog({ timestamp: 123, _iso: iso, msg: 'hello' }).timestamp, 123)
+assert.equal(streamLog({ timestamp: 123, _iso: iso, msg: 'hello' }).timestamp, Date.parse(iso))
+assert.equal(snapshotLog('FATAL EXCEPTION: crash').level, 'ERROR')
+assert.equal(streamLog('WARN: slow').level, 'WARN')
+assert.equal(snapshotLog({ timestamp: 'invalid', msg: 'hello' }).timestamp, null)
+assert.deepEqual(snapshotLog(null), { timestamp: null, level: 'INFO', message: '' })
+assert.equal(snapshotLog({ context: 'value' }).message, '{"context":"value"}')
+console.log('Snapshot and stream timestamp precedence and log normalization tests passed')

package/test/unit/quality/architecture.test.ts

@@ -0,0 +1,60 @@
+import assert from 'node:assert/strict'
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { architectureGraph } from '../../../scripts/architecture-graph.mjs'
+import { checkArchitecture } from '../../../scripts/check-architecture.mjs'
+
+const root = await mkdtemp(path.join(tmpdir(), 'mcp-architecture-'))
+try {
+  const files: Record<string, string> = {
+    'package.json': JSON.stringify({ type: 'module' }),
+    'tsconfig.json': JSON.stringify({ compilerOptions: {
+      module: 'NodeNext', moduleResolution: 'NodeNext', target: 'ES2022',
+      paths: { '@server/*': ['./src/server/*'] }
+    }, include: ['src/**/*.ts'] }),
+    'src/server/entry.ts': 'export const value = 1',
+    'src/contracts/bad.ts': "export { value } from '@server/entry.js'",
+    'src/interact/entry.ts': "export const load = () => import('../server/entry.js')",
+    'src/interact/adjustment/control-values.ts': "import { spawn } from 'node:child_process'; export const native = spawn",
+    'src/cycle/a.ts': "export { b } from './b.js'; export const a = 1",
+    'src/cycle/b.ts': "export const b = () => import('./a.js')",
+    'src/type-cycle/a.ts': "import type { B } from './b.js'; export interface A { b: B }",
+    'src/type-cycle/b.ts': "import { type A } from './a.js'; export interface B { a: A }",
+    'src/import-equals.ts': "import entry = require('./server/entry.js'); export { entry }",
+    'src/require.ts': "export const load = () => require('./server/entry.js')"
+  }
+  for (const [file, code] of Object.entries(files)) {
+    const target = path.join(root, file)
+    await mkdir(path.dirname(target), { recursive: true })
+    await writeFile(target, code)
+  }
+  const config = path.join(root, 'tsconfig.json')
+  const graph = await architectureGraph(config)
+  const edge = (source: string, target: string) => graph.find(item => item.source === source && item.target === target)
+  assert(edge('src/contracts/bad.ts', 'src/server/entry.ts'), 'Resolve aliased re-exports to .ts sources')
+  assert(edge('src/interact/entry.ts', 'src/server/entry.ts'), 'Resolve literal dynamic .js imports')
+  assert(edge('src/require.ts', 'src/server/entry.ts'), 'Resolve literal require calls')
+  assert(edge('src/interact/adjustment/control-values.ts', 'node:child_process'), 'Include Node builtins')
+  assert.deepEqual(edge('src/type-cycle/b.ts', 'src/type-cycle/a.ts')?.importKinds, ['type'])
+  assert(edge('src/import-equals.ts', 'src/server/entry.ts'), 'Resolve import-equals require syntax')
+  const rejected = spawnSync(process.execPath, ['scripts/check-architecture.mjs', config], { encoding: 'utf8' })
+  assert.equal(rejected.status, 1, rejected.stderr)
+  assert(rejected.stderr.includes('Production runtime dependencies must be cycle-free'))
+  const results = checkArchitecture(graph)
+  assert(results.every(result => result.violations.length > 0), 'Every rule must reject its deliberately broken fixture')
+  const cycles = JSON.stringify(results.at(-1)?.violations)
+  assert(cycles.includes('src/cycle/a.ts'), 'Catch a cycle through a re-export and dynamic import')
+  assert(!cycles.includes('src/type-cycle'), 'Type-only cycles are not runtime cycles')
+  assert(checkArchitecture([]).every(result => result.violations.length > 0), 'An empty graph must fail closed')
+
+  await writeFile(path.join(root, 'src/nonliteral.ts'), 'export const load = (name: string) => import(name)')
+  await assert.rejects(architectureGraph(config), /Nonliteral dependency/)
+  await rm(path.join(root, 'src/nonliteral.ts'))
+  await writeFile(path.join(root, 'src/unresolved.ts'), "import './missing.js'")
+  await assert.rejects(architectureGraph(config), /Unresolved dependency/)
+  console.log('PASS architecture negative controls: NodeNext, aliases, re-exports, dynamic/require imports, pure boundaries, runtime cycles, type-only cycles, empty and unresolved graphs')
+} finally {
+  await rm(root, { recursive: true, force: true })
+}

package/test/unit/quality/code-quality.test.ts

@@ -0,0 +1,58 @@
+import assert from 'node:assert/strict'
+import { measure, compare } from '../../../scripts/code-quality.mjs'
+
+const file = 'src/interact/quality-fixture.ts'
+const inspect = (code: string) => measure(file, code)
+const has = (findings: Awaited<ReturnType<typeof inspect>>, rule: string) => findings.some(f => f.rule === rule)
+const baseline = (findings: Awaited<ReturnType<typeof inspect>>) => findings.map(({ line: _line, ...entry }) => ({ ...entry, reason: 'Test legacy exception' }))
+
+async function main() {
+  assert.deepEqual(await inspect('export const twice = (value: number) => value * 2'), [])
+  const hugeClass = await inspect(`export class Huge {\n${Array.from({ length: 301 }, (_, i) => `field${i} = ${i}`).join('\n')}\n}`)
+  assert(has(hugeClass, 'class-lines'))
+  const hugeFunction = await inspect(`export function work() {\n${Array.from({ length: 81 }, (_, i) => `console.log(${i})`).join('\n')}\n}`)
+  assert(has(hugeFunction, 'max-lines-per-function'))
+  assert(has(await inspect(`export const work = () => {\n${'console.log(1)\n'.repeat(81)}}`), 'max-lines-per-function'))
+  const hugeFile = await inspect(Array.from({ length: 501 }, (_, i) => `export const value${i} = ${i}`).join('\n'))
+  assert(has(hugeFile, 'max-lines'))
+  assert(!has(await inspect(`// A comment\n${'\n// comment\n'.repeat(600)}export const x = 1`), 'max-lines'))
+  const complex = await inspect(`export function decide(value: number) { ${'if(value) console.log(value);'.repeat(21)} }`)
+  assert(has(complex, 'complexity'))
+  assert(has(await inspect('export function nested(x: boolean) { if(x){if(x){if(x){if(x){if(x){console.log(x)}}}}} }'), 'max-depth'))
+  assert(has(await inspect("import { value } from '../server/tool-handlers.js'"), 'import-boundary'))
+  assert(has(await inspect("export { value } from '../server/common.js'"), 'import-boundary'))
+  assert(has(await inspect("type Args = import('../server/common.js').ToolCallArgs"), 'import-boundary'))
+  assert(has(await inspect("const transport = require('../server/common.js')"), 'import-boundary'))
+  assert(has(await inspect('/* eslint complexity: \"off\" */\nexport const value = 1'), 'inline-suppression'))
+  assert(!has(await inspect("import type { Value } from '../contracts/value.js'"), 'import-boundary'))
+  assert(has(await inspect('// eslint-disable\nexport const x = 1'), 'inline-suppression'))
+  assert(has(await inspect('// eslint-disable-next-line complexity\nexport function f() {}'), 'inline-suppression'))
+  const any = await inspect('export function legacy(value: any) { return value }')
+  assert(has(any, 'explicit-any'))
+  assert.deepEqual(compare(any, baseline(any)), [])
+  assert(compare(any, []).some(e => e.includes('explicit-any')))
+  const grown = await inspect('export function legacy(value: any): any { return value }')
+  assert(compare(grown, baseline(any)).some(e => e.includes('explicit-any')))
+  const renamed = await inspect('export function replacement(value: any) { return value }')
+  assert(compare(renamed, baseline(any)).length >= 2, 'renames do not inherit debt')
+  const moved = any.map(f => ({ ...f, file: 'src/interact/moved.ts' }))
+  assert(compare(moved, baseline(any)).length >= 2, 'moves do not inherit debt')
+  assert(compare([], baseline(any)).some(e => e.includes('obsolete')))
+  assert(compare(any, baseline(grown)).some(e => e.includes('Lower baseline')))
+  assert(compare(any, [...baseline(any), ...baseline(any)]).some(e => e.includes('Duplicate')))
+  assert(compare(any, [{ ...baseline(any)[0], reason: '' }]).some(e => e.includes('Invalid')))
+  const collision = await inspect('function same(x: number) {return x} function same(x: number) {return x}')
+  assert(has(collision, 'duplicate-symbol'))
+  assert(compare(collision, baseline(collision)).some(e => e.includes('duplicate-symbol')), 'identity collisions cannot be baseline exceptions')
+  const suppressed = await inspect('// eslint-disable max-lines-per-function\n'+`function huge(){\n${'console.log(1)\n'.repeat(81)}}`)
+  assert(has(suppressed, 'max-lines-per-function'), 'inline directives cannot hide metrics')
+  const typeDebt = await inspect('type First = any; type Second = number')
+  const shiftedTypeDebt = await inspect('type First = number; type Second = any')
+  assert(compare(shiftedTypeDebt, baseline(typeDebt)).length >= 2, 'unrelated type declarations cannot offset each other')
+  const java = await measure('src/debugger/java/Fixture.java', 'int field;\n'.repeat(501))
+  assert(has(java, 'max-lines'))
+  assert.deepEqual(await measure('src/debugger/java/Fixture.java', '// comment\n'.repeat(501)), [])
+  assert(!has(await inspect('class Accessor { get value() { return 1 } set value(value: number) { console.log(value) } }'), 'duplicate-symbol'))
+  console.log('PASS structural metrics, debt ratchet, boundaries and suppression protection')
+}
+main().catch(error => { console.error(error); process.exitCode = 1 })

package/test/unit/quality/interaction_boundaries.test.ts

@@ -0,0 +1,24 @@
+import assert from 'node:assert/strict'
+import { readdir, readFile } from 'node:fs/promises'
+import { measure } from '../../../scripts/code-quality.mjs'
+
+// Refactored interaction services must meet defaults even if someone adds a legacy allowance.
+const legacy = new Set(['android.ts', 'ios.ts', 'conditional-action.ts', 'classify.ts'])
+async function sourceFiles(directory = ''): Promise<string[]> {
+  const entries = await readdir(`src/interact/${directory}`, { withFileTypes: true })
+  const paths: string[] = []
+  for (const entry of entries) {
+    const relative = directory ? `${directory}/${entry.name}` : entry.name
+    if (entry.isDirectory()) paths.push(...await sourceFiles(relative))
+    else if (relative.endsWith('.ts') && !legacy.has(relative)) paths.push(relative)
+  }
+  return paths
+}
+const files = await sourceFiles()
+const baseline = JSON.parse(await readFile('scripts/code-quality-baseline.json', 'utf8')) as Array<{ file: string }>
+for (const file of files) {
+  const path = `src/interact/${file}`
+  assert.deepEqual(await measure(path, await readFile(path, 'utf8')), [], `${path} must meet default structural and typing limits`)
+  assert(!baseline.some(entry => entry.file === path), `${path} cannot inherit legacy exceptions`)
+}
+console.log(`PASS default quality limits and no legacy exceptions across ${files.length} interaction modules`)

package/test/unit/server/conditional_actions.test.ts

@@ -4,7 +4,7 @@ import { tmpdir } from 'node:os'
 import path from 'node:path'
 import { handleToolCall, toolDefinitions } from '../../../src/server-core.js'
 import { ToolsObserve } from '../../../src/observe/index.js'
-import { ToolsNetwork } from '../../../src/network/index.js'
+import { ToolsNetwork } from '../../../src/observe/network/index.js'
 import { deriveSnapshotMetadata, getSnapshotSessionId, resetSnapshotMetadataForTests } from '../../../src/observe/snapshot-metadata.js'
 import { _setDeviceListersForTests, _resetDeviceListersForTests } from '../../../src/utils/resolve-device.js'
 import { runWithBudget } from '../../../src/utils/operation-budget.js'

package/test/unit/server/conditional_schema.test.ts

@@ -1,8 +1,8 @@
 import assert from 'node:assert/strict'
 import { AjvJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/ajv'
 import { toolDefinitions } from '../../../src/server/tool-definitions.js'
-import { conditionalTools, validateExpectedState } from '../../../src/server/condition-schema.js'
-import { journeySchema } from '../../../src/server/journey-schema.js'
+import { conditionalTools, validateExpectedState } from '../../../src/server/schemas/condition-schema.js'
+import { journeySchema } from '../../../src/server/schemas/journey-schema.js'
 
 const provider = new AjvJsonSchemaValidator()
 const expectedState = { snapshotSessionId: 'session-fixture', snapshotRevision: 1 }

package/test/unit/server/debugger-response.test.ts

@@ -0,0 +1,63 @@
+import assert from 'node:assert/strict'
+import { debuggerResponse } from '../../../src/server/handlers/debugger-response.js'
+import { handleDebugger } from '../../../src/server/handlers/debugger-handlers.js'
+import { debuggerContracts, debuggerTools } from '../../../src/server/schemas/debugger-schema.js'
+import { debuggerSessions } from '../../../src/debugger/sessions.js'
+import { DebuggerError } from '../../../src/debugger/worker.js'
+import { diagnostic } from '../../../src/debugger/diagnostics.js'
+
+const baseline = ['capabilities', 'attach', 'state']
+const payload = {
+  success: false, debug_session_id: 'session', device: { id: 'device' }, target: { pid: 42 }, capabilities: { locals: true },
+  state: 'paused', captured_at_ms: 123, reason: null, stop: { stop_id: 'stop', thread_id: 'thread' },
+  limitations: ['SHALLOW_LOCALS'], cleanup: { status: 'failed', remaining_resources: ['forward:tcp:123'] },
+  error: { code: 'DEBUGGER_CLEANUP_FAILED', retryable: false, diagnostic: diagnostic('cleanup', 'operation_failed') },
+  execution_state: 'unknown', result: { frames: [{ frame_id: 'frame' }], truncated: true, availability: 'unknown' },
+  breakpoints: [], events: [], next_cursor: 4, overflow: true, timed_out: false, future_field: { preserve: true }
+}
+const expected = structuredClone(payload) as Record<string, unknown>
+for (const key of ['device', 'target', 'capabilities']) delete expected[key]
+const before = structuredClone(payload)
+for (const tool of debuggerTools) {
+  const contract = debuggerContracts[tool.name]
+  assert.deepEqual(tool.inputSchema.properties.responseMode, { type: 'string', enum: ['compact', 'debug'], default: 'debug' })
+  const shape = contract.schema.shape
+  assert.equal(shape.responseMode.parse(undefined), 'debug')
+  for (const mode of ['compact', 'debug']) assert.equal(shape.responseMode.parse(mode), mode)
+  assert.equal(shape.responseMode.safeParse('full').success, false)
+  assert.deepEqual(debuggerResponse(contract.command, 'debug', payload), payload)
+  assert.deepEqual(debuggerResponse(contract.command, 'compact', payload), baseline.includes(contract.command) ? payload : expected)
+  const success = { ...payload, success: true, error: undefined, cleanup: { status: 'pending', remaining_resources: ['jdi_worker'] } }
+  assert.deepEqual(debuggerResponse(contract.command, 'compact', success), baseline.includes(contract.command) ? success : { ...expected, success: true, error: undefined, cleanup: success.cleanup })
+  const noSession = { ...payload, debug_session_id: null }
+  assert.deepEqual(debuggerResponse(contract.command, 'compact', noSession), noSession)
+}
+assert.deepEqual(payload, before, 'projection must not mutate nested or shared objects')
+
+// This self-running test has its own process; restore the singleton seam in finally.
+const original = debuggerSessions.command
+try {
+  debuggerSessions.command = async (_id, _command, args) => {
+    assert.ok(!Object.hasOwn(args!, 'responseMode'), 'presentation input must not reach worker')
+    return { ...payload, success: true } as unknown as Awaited<ReturnType<typeof original>>
+  }
+  for (const mode of [undefined, 'debug', 'compact']) {
+    const response = await handleDebugger('get_debugger_locals', { debugSessionId: 'session', stopId: 'stop', frameId: 'frame', ...(mode ? { responseMode: mode } : {}) })
+    assert.equal(response.isError, undefined)
+    assert.deepEqual(JSON.parse(response.content[0].text), { ...(mode === 'compact' ? expected : payload), success: true })
+  }
+  for (const code of ['DEBUGGER_STALE_REFERENCE', 'DEBUGGER_NOT_FOUND', 'DEBUGGER_WORKER_FAILED', 'DEBUGGER_TIMEOUT', 'DEBUGGER_CANCELLED']) {
+    debuggerSessions.command = async () => { throw new DebuggerError(code, diagnostic('command', 'unknown')) }
+    for (const responseMode of ['compact', 'debug']) {
+      const response = await handleDebugger('resume_debugger', { debugSessionId: 'absent', stopId: 'old', responseMode })
+      const value = JSON.parse(response.content[0].text)
+      assert.equal(response.isError, true)
+      assert.equal(value.error.code, code)
+      assert.equal(Object.hasOwn(value, 'capabilities'), responseMode === 'debug')
+      assert.equal(value.debug_session_id, 'absent')
+    }
+  }
+  const invalid = await handleDebugger('detach_debugger', { debugSessionId: 'session', responseMode: 'full' })
+  assert.equal(JSON.parse(invalid.content[0].text).error.code, 'INVALID_ARGUMENT')
+} finally { debuggerSessions.command = original }
+console.log('PASS debugger response defaults, exact retention, failures, immutable projection and argument isolation')

package/test/unit/server/tool_definitions_parity.test.ts

@@ -0,0 +1,8 @@
+import assert from 'node:assert/strict'
+import { readFile } from 'node:fs/promises'
+import { toolDefinitions } from '../../../src/server/tool-definitions.js'
+
+// Captured before structural refactoring: changes require an intentional contract review.
+const baseline = JSON.parse(await readFile(new URL('../../fixtures/contracts/tool-definitions.json', import.meta.url), 'utf8'))
+assert.deepEqual(toolDefinitions, baseline, 'Public tool order, schemas, defaults and descriptions must remain compatible')
+console.log('PASS public tool-definition compatibility baseline')