mobile-debug-mcp 0.32.2 → 0.33.0

package/docs/specs/022-correlated-evidence/modul8-selector-fix-evidence.json

@@ -0,0 +1,336 @@
+{
+  "verified_on": "2026-10-30T09:14:34.967Z",
+  "device": {
+    "platform": "android",
+    "deviceId": "emulator-5554"
+  },
+  "package": "com.ideamechanics.modul8.dev",
+  "source": "rebuilt local MCP stdio server",
+  "build_sha256": "ab7f5916468b000b70f445de5a29406adfd141cea89e1298661562e68fbef61d",
+  "steps": [
+    {
+      "selector": {
+        "text": "FAVOURITES"
+      },
+      "waitForCondition": "default",
+      "status": "PASS",
+      "failure_code": null,
+      "evidence": {
+        "session_id": "35528fe5-ba92-4d62-8380-5d977d390b08",
+        "correlation_id": "01a328ba-91a9-4ac6-a768-b06701e71018",
+        "action_id": "01a328ba-91a9-4ac6-a768-b06701e71018",
+        "device": {
+          "platform": "android",
+          "id": "emulator-5554"
+        },
+        "association": "self",
+        "association_reason": null,
+        "operation_started_at_ms": 1793351680409,
+        "operation_completed_at_ms": 1793351683123,
+        "dispatch_started_at_ms": 1793351683067,
+        "dispatch_completed_at_ms": 1793351683123,
+        "verification_completed_at_ms": null,
+        "observations": [
+          {
+            "evidence_id": "1dc56459-d61e-4814-9612-2e3ad6c8782b",
+            "kind": "ui_tree",
+            "status": "captured",
+            "capture_started_at_ms": 1793351680628,
+            "capture_completed_at_ms": 1793351682798,
+            "source_captured_at_ms": 1793351682798,
+            "age_ms": 324.72998046875,
+            "freshness": "stale",
+            "freshness_reasons": [
+              "BEFORE_ACTION"
+            ],
+            "device": {
+              "platform": "android",
+              "id": "emulator-5554"
+            },
+            "snapshot_session_id": "9f2a6439-590e-46a5-9025-d6c828525250",
+            "snapshot_revision": 1,
+            "session_id": "35528fe5-ba92-4d62-8380-5d977d390b08",
+            "correlation_id": "01a328ba-91a9-4ac6-a768-b06701e71018",
+            "action_id": "01a328ba-91a9-4ac6-a768-b06701e71018",
+            "association": "internal"
+          }
+        ],
+        "trace_context": {
+          "supported": false,
+          "trace_id": null,
+          "markers": []
+        }
+      }
+    },
+    {
+      "selector": {
+        "text": "GENER8"
+      },
+      "waitForCondition": "default",
+      "status": "PASS",
+      "failure_code": null,
+      "evidence": {
+        "session_id": "35528fe5-ba92-4d62-8380-5d977d390b08",
+        "correlation_id": "61cdf8f3-3702-4342-ad25-aaa7146f4e85",
+        "action_id": "61cdf8f3-3702-4342-ad25-aaa7146f4e85",
+        "device": {
+          "platform": "android",
+          "id": "emulator-5554"
+        },
+        "association": "self",
+        "association_reason": null,
+        "operation_started_at_ms": 1793351688186,
+        "operation_completed_at_ms": 1793351691068,
+        "dispatch_started_at_ms": 1793351691021,
+        "dispatch_completed_at_ms": 1793351691068,
+        "verification_completed_at_ms": null,
+        "observations": [
+          {
+            "evidence_id": "74bda6d0-fdf1-40d3-92d6-31f61e49316b",
+            "kind": "ui_tree",
+            "status": "captured",
+            "capture_started_at_ms": 1793351688428,
+            "capture_completed_at_ms": 1793351690795,
+            "source_captured_at_ms": 1793351690795,
+            "age_ms": 273.0615234375,
+            "freshness": "stale",
+            "freshness_reasons": [
+              "BEFORE_ACTION"
+            ],
+            "device": {
+              "platform": "android",
+              "id": "emulator-5554"
+            },
+            "snapshot_session_id": "9f2a6439-590e-46a5-9025-d6c828525250",
+            "snapshot_revision": 2,
+            "session_id": "35528fe5-ba92-4d62-8380-5d977d390b08",
+            "correlation_id": "61cdf8f3-3702-4342-ad25-aaa7146f4e85",
+            "action_id": "61cdf8f3-3702-4342-ad25-aaa7146f4e85",
+            "association": "internal"
+          }
+        ],
+        "trace_context": {
+          "supported": false,
+          "trace_id": null,
+          "markers": []
+        }
+      }
+    },
+    {
+      "selector": {
+        "text": "SETTINGS"
+      },
+      "waitForCondition": "exists",
+      "status": "PASS",
+      "failure_code": null,
+      "resolved_target": {
+        "elementId": "el_9b12a59a90203e47349f1943",
+        "text": null,
+        "resource_id": null,
+        "accessibility_id": null,
+        "class": "android.view.View",
+        "bounds": [
+          476,
+          1408,
+          708,
+          1528
+        ],
+        "index": 12,
+        "state": {
+          "checked": false,
+          "selected": true,
+          "focused": false,
+          "enabled": true
+        }
+      },
+      "evidence": {
+        "session_id": "35528fe5-ba92-4d62-8380-5d977d390b08",
+        "correlation_id": "4f52aadc-2249-47f0-8149-781123a3e765",
+        "action_id": "4f52aadc-2249-47f0-8149-781123a3e765",
+        "device": {
+          "platform": "android",
+          "id": "emulator-5554"
+        },
+        "association": "self",
+        "association_reason": null,
+        "operation_started_at_ms": 1793351696337,
+        "operation_completed_at_ms": 1793351699045,
+        "dispatch_started_at_ms": 1793351698985,
+        "dispatch_completed_at_ms": 1793351699045,
+        "verification_completed_at_ms": null,
+        "observations": [
+          {
+            "evidence_id": "35f26191-7b0f-466e-90b0-1cf22f9b03ac",
+            "kind": "ui_tree",
+            "status": "captured",
+            "capture_started_at_ms": 1793351696577,
+            "capture_completed_at_ms": 1793351698724,
+            "source_captured_at_ms": 1793351698724,
+            "age_ms": 321.01416015625,
+            "freshness": "stale",
+            "freshness_reasons": [
+              "BEFORE_ACTION"
+            ],
+            "device": {
+              "platform": "android",
+              "id": "emulator-5554"
+            },
+            "snapshot_session_id": "9f2a6439-590e-46a5-9025-d6c828525250",
+            "snapshot_revision": 3,
+            "session_id": "35528fe5-ba92-4d62-8380-5d977d390b08",
+            "correlation_id": "4f52aadc-2249-47f0-8149-781123a3e765",
+            "action_id": "4f52aadc-2249-47f0-8149-781123a3e765",
+            "association": "internal"
+          }
+        ],
+        "trace_context": {
+          "supported": false,
+          "trace_id": null,
+          "markers": []
+        }
+      }
+    },
+    {
+      "selector": {
+        "text": "FAVOURITES"
+      },
+      "waitForCondition": "visible",
+      "status": "PASS",
+      "failure_code": null,
+      "resolved_target": {
+        "elementId": "el_25faaaa4e20f6ef0b85ab86b",
+        "text": null,
+        "resource_id": null,
+        "accessibility_id": null,
+        "class": "android.view.View",
+        "bounds": [
+          12,
+          1408,
+          244,
+          1528
+        ],
+        "index": 13,
+        "state": {
+          "checked": false,
+          "selected": true,
+          "focused": false,
+          "enabled": true
+        }
+      },
+      "evidence": {
+        "session_id": "35528fe5-ba92-4d62-8380-5d977d390b08",
+        "correlation_id": "fbc19ace-4779-4b92-9677-11852aa6d339",
+        "action_id": "fbc19ace-4779-4b92-9677-11852aa6d339",
+        "device": {
+          "platform": "android",
+          "id": "emulator-5554"
+        },
+        "association": "self",
+        "association_reason": null,
+        "operation_started_at_ms": 1793351704414,
+        "operation_completed_at_ms": 1793351707038,
+        "dispatch_started_at_ms": 1793351706987,
+        "dispatch_completed_at_ms": 1793351707038,
+        "verification_completed_at_ms": null,
+        "observations": [
+          {
+            "evidence_id": "489de2e9-21fe-405d-a680-3d56ece84aae",
+            "kind": "ui_tree",
+            "status": "captured",
+            "capture_started_at_ms": 1793351704599,
+            "capture_completed_at_ms": 1793351706754,
+            "source_captured_at_ms": 1793351706754,
+            "age_ms": 284.26416015625,
+            "freshness": "stale",
+            "freshness_reasons": [
+              "BEFORE_ACTION"
+            ],
+            "device": {
+              "platform": "android",
+              "id": "emulator-5554"
+            },
+            "snapshot_session_id": "9f2a6439-590e-46a5-9025-d6c828525250",
+            "snapshot_revision": 4,
+            "session_id": "35528fe5-ba92-4d62-8380-5d977d390b08",
+            "correlation_id": "fbc19ace-4779-4b92-9677-11852aa6d339",
+            "action_id": "fbc19ace-4779-4b92-9677-11852aa6d339",
+            "association": "internal"
+          }
+        ],
+        "trace_context": {
+          "supported": false,
+          "trace_id": null,
+          "markers": []
+        }
+      }
+    },
+    {
+      "selector": {
+        "text": "SETTINGS"
+      },
+      "waitForCondition": "default",
+      "status": "PASS",
+      "failure_code": null,
+      "evidence": {
+        "session_id": "35528fe5-ba92-4d62-8380-5d977d390b08",
+        "correlation_id": "c49cac9f-dca4-4a94-a4a4-f05119db855e",
+        "action_id": "c49cac9f-dca4-4a94-a4a4-f05119db855e",
+        "device": {
+          "platform": "android",
+          "id": "emulator-5554"
+        },
+        "association": "self",
+        "association_reason": null,
+        "operation_started_at_ms": 1793351712316,
+        "operation_completed_at_ms": 1793351715175,
+        "dispatch_started_at_ms": 1793351715131,
+        "dispatch_completed_at_ms": 1793351715175,
+        "verification_completed_at_ms": null,
+        "observations": [
+          {
+            "evidence_id": "f8c8f253-3e66-456b-94be-318fb94fc868",
+            "kind": "ui_tree",
+            "status": "captured",
+            "capture_started_at_ms": 1793351712552,
+            "capture_completed_at_ms": 1793351714774,
+            "source_captured_at_ms": 1793351714774,
+            "age_ms": 400.86767578125,
+            "freshness": "stale",
+            "freshness_reasons": [
+              "BEFORE_ACTION"
+            ],
+            "device": {
+              "platform": "android",
+              "id": "emulator-5554"
+            },
+            "snapshot_session_id": "9f2a6439-590e-46a5-9025-d6c828525250",
+            "snapshot_revision": 5,
+            "session_id": "35528fe5-ba92-4d62-8380-5d977d390b08",
+            "correlation_id": "c49cac9f-dca4-4a94-a4a4-f05119db855e",
+            "action_id": "c49cac9f-dca4-4a94-a4a4-f05119db855e",
+            "association": "internal"
+          }
+        ],
+        "trace_context": {
+          "supported": false,
+          "trace_id": null,
+          "markers": []
+        }
+      }
+    }
+  ],
+  "status": "PASS",
+  "cleanup": "PASS: restored Subscription; no settings, account data, favourites or sessions changed; no streams or screenshots created",
+  "server": {
+    "name": "mobile-debug-mcp",
+    "version": "0.32.4"
+  },
+  "starting_state": "Subscription",
+  "source_base": "3701f3987940a8abc76ed893b575ed370e3fb673",
+  "interaction_build_sha256": "79cb709c20fe8775571aee92413d01f28e9f8bc97da77476c08310cc555d7c2b",
+  "fixture_version_from_same_session": {
+    "versionName": "0.3.1-dev",
+    "versionCode": 14
+  },
+  "post_suite_cleanup": "PASS: relaunched Modul8 after the general device suite and confirmed Subscription via expect_element_visible"
+}

package/docs/specs/022-correlated-evidence/plan.md

@@ -0,0 +1,171 @@
+# Plan: correlated evidence
+
+Authorisation: [intent](intent.md), then [spec](spec.md), explicitly approved by
+“yes” and “approve” respectively in this conversation on 2026-10-29.
+
+## Implementation
+
+- [x] Add per-call evidence context, bounded action history, clocks/freshness/types.
+- [x] Propagate action/journey IDs; instrument dispatch and verification phases.
+- [x] Instrument platform observations, snapshot components, stream device ownership.
+- [x] Register/validate actionRef; preserve compact/debug/image/log responses.
+- [x] Add regression coverage; align tool docs, README, changelog.
+- [x] Review contract, ownership, concurrency, and privacy; complete checks below.
+
+Reuse async-local context, resolution, budget, and trace helpers. Node >=18
+(package/CI requirement); use installed Node/npm/ADB/Xcode tooling. No install,
+publish, commit, push, or device helper APK is required. Retain old response data.
+Risks are missed nested dispatch/capture paths and incorrect stream targeting;
+test adapter boundaries and serialization as well as the metadata helper.
+
+## Verification
+
+| Criteria | Check |
+| --- | --- |
+| 1: matching identifiers | Handler tests: compact/debug actions, screenshot/log references, journey propagation; local-server Android/iOS journeys. |
+| 2: accurate phases | Boundary tests: conditional rejection, no verification, failure/timeout, repeated input; real action before screenshot/log collection. |
+| 3: freshness | Controlled clock/order tests for every specified status/reason and cached source time. |
+| 4: isolation | Concurrent call/device tests; expired/evicted/foreign-session references; stream-owned device. |
+| 5: compatibility/resources | Partial/disabled snapshot and response serialization tests; content-free bounded history. |
+| 6: limitations | Assert unsupported trace context and device-log clock limitations on both providers. |
+
+Commands: focused `npx tsx test/unit/observe/correlated-evidence.test.ts`,
+`npm run verify`, `npm run test:device`. CI uses Node 18 for lint/build/unit;
+Android integration is manual workflow dispatch; local verify additionally checks
+the agent plugin. Device suite coverage must be reported, not assumed.
+
+Device journey: updated local server (record package/build), Android emulator-5554
+and booted iPhone 17 Pro simulator. Starting state: fixture/system Settings app;
+launch it, collect referenced screenshot and bounded logs, verify IDs, dispatch
+and capture intervals, image/log preservation and explicit clock limitations.
+Use fresh device discovery. Exercise disabled/partial snapshot and invalid
+reference without changing app data. Record pass/fail/blocked/unrun plus metadata
+in this directory; avoid saving screenshot/log contents. Restore changed settings,
+stop only owned streams, and remove temporary test data. No settings change is
+needed. Android log healthcheck was degraded: targeted read is the next check;
+if unavailable, record its concrete error and verify metadata failure behaviour.
+iOS physical-device coverage is outside existing simulator support.
+
+## Results
+
+Implementation and focused review completed on 2026-10-30. Review corrected
+journey step completion/verification timestamps, explicit Android stream dispatch
+targeting, stream cleanup ownership, and concurrent iOS screenshot filenames.
+No outstanding findings in correlation implementation. Correlation history
+contains no capture content; later Modul8 testing below records selector limits.
+
+- Local runtime: Node 23.11.0 / npm 10.9.2; CI's Node 18 runtime was not run locally.
+- Focused evidence helper and MCP handler tests: **pass**, including fake-native
+  Android/iOS dispatch, timeout/precondition failures, compact/debug serialization,
+  deferred journey verification, stream ownership, clocks, expiry, eviction,
+  concurrent devices, partial/omitted captures, and reference rejection.
+- `npm run verify`: **pass** after review fixes (lint, build, all automated
+  unit tests, agent-plugin consistency).
+- `npm run test:device`: **pass** on final code. Six existing screenshot/log/tree
+  smokes cover Android and iOS with automatic targeting (their output does not
+  identify each selected device); the new smoke covers rebuilt stdio-server
+  correlation on Android emulator-5554 (Android 16) and iPhone 17 Pro simulator
+  F9243BAF-62A8-4990-8A99-17F527F56FDA (iOS 26.4). This does not exercise physical
+  iOS or all interaction journeys.
+- New real-device journeys: **pass** for Settings launch, referenced screenshot,
+  bounded logs, UI-tree acquisition, disabled snapshot components, pinned device,
+  and foreign-session rejection. Targeted Android logs succeeded despite the
+  earlier healthcheck warning. Phase times/IDs/build hashes are in
+  [device-evidence.json](device-evidence.json); no image/log content is retained.
+- Cleanup: test-owned fake streams/files removed. No device settings or app data
+  changed; system Settings remains foreground on the emulator and simulator.
+- Physical-device correlation, installed/published-package verification: **unrun**.
+  No release or deployment was requested.
+
+Validation logs for this local run: `/tmp/mobile-debug-correlated-verify.log` and
+`/tmp/mobile-debug-correlated-device.log`. The `tsx` CLI requires local IPC blocked
+by the sandbox; required npm checks ran with approved escalation. Focused checks
+also passed via `node --import tsx` without that socket.
+
+## Modul8 follow-up verification — 2026-10-30
+
+User identified the installed Modul8 app as an additional fixture. Tested the
+rebuilt local 0.32.4 server over MCP stdio on emulator-5554 (Android 16), using
+`com.ideamechanics.modul8.dev` version 0.3.1-dev / code 14. Started on Subscription,
+navigated to Favourites and Gener8, and restored Subscription, confirmed by the
+final UI tree. No settings, account/subscription data, favourites, or sessions changed.
+
+- **Pass:** screenshot-confirmed navigation, matching action/session/correlation
+  IDs across referenced screenshots, UI trees and app-scoped logs; distinct
+  capture/dispatch/verification times; pre-action stale and post-action fresh
+  records. Device-log freshness correctly remains unknown.
+- **Pass:** an expectation matching the current screen allowed input. Reusing the
+  Favourites revision after navigating to Gener8 returned `PRECONDITION_FAILED`
+  with null dispatch timestamps. Failed selector calls also retained null
+  dispatch/verification times and could be referenced by subsequent captures.
+- **Fail, existing selector limits:** default `tap_element` lookup exhausted its
+  1,500ms observation budget (baseline 3701f39 has the same default). With a
+  10,000ms lookup/15,000ms action budget, the Gener8 text leaf was found but
+  rejected as `ELEMENT_NOT_INTERACTABLE`; its parent is clickable. Guarded
+  screenshot-based coordinate navigation passed. These are not correlation
+  regressions and were not changed in this follow-up.
+- Fresh screenshots can capture a crossfade: recent acquisition does not prove
+  settled UI. No settled-state or causal-log-emission claim was made.
+
+[modul8-evidence.json](modul8-evidence.json) retains metadata and outcomes, excluding
+screenshots, UI text, and log contents. Temporary screenshots/client were removed.
+Only verification documents changed; link/JSON/whitespace checks passed. Existing
+maintainer/device results above apply to the unchanged implementation.
+
+## Selector repair — 2026-10-30
+
+User explicitly requested fixing the Modul8 selector failures. Lightweight bug-fix
+path: restore existing clickable-ancestor targeting for selector taps after an
+exists/visible wait; use the configured action budget for a single fresh lookup
+(default 5 seconds); preserve `ACTION_TIMEOUT` on failed acquisition. Keep matching,
+ambiguity/index rules, standalone wait results, hidden/disabled-node checks, and
+conditional dispatch guards intact. Preserve unrelated correlated-evidence work.
+
+- Implementation: `executeTapElement` lookup budgeting and internal tap-target
+  resolution in `waitForUIHandler`, reusing the existing ancestor helper.
+- Regression checks: actual resolution/tap pipeline with a Modul8-shaped label
+  and clickable tab parent; default/exists/visible/clickable waits; explicit
+  timeout budget; timeout vs absence; hidden/disabled labels/parents; plain
+  labels; ambiguity; standalone wait behaviour. Focused checks **pass**.
+- Device check: explicit manual fixture helper
+  `node --import tsx test/device/manual/interact/modul8_selector_tap.manual.ts`;
+  rebuilt server, emulator-5554, Modul8 dev. Verify default selector navigation
+  through Favourites/Gener8, exists/visible selector taps, and restored Subscription
+  using semantic assertions. **Pass**: all five selector taps and destination
+  assertions succeeded; no coordinate fallback was used. Metadata is in
+  [modul8-selector-fix-evidence.json](modul8-selector-fix-evidence.json).
+- Final checks: `npm run verify` **pass** (65 unit files, lint/build/plugin check);
+  `npm run test:device` **pass** (7 smoke files, Android/iOS observation and
+  correlation coverage). Native selector repair verified on Android/Modul8;
+  equivalent iOS app selector navigation remains **unrun**.
+- Focused review: matching/index/ambiguity and direct handle behaviour preserved;
+  tap-only ancestor resolution reuses the existing policy and acquisition;
+  hidden/disabled labels cannot route through an enabled parent. No outstanding
+  findings. Documentation links/JSON/whitespace checks passed.
+- Cleanup: after the general device suite reopened system Settings, relaunched
+  Modul8 and semantically confirmed the original Subscription screen. No app data
+  or device settings changed; temporary cleanup client removed.
+- Historical failures in `modul8-evidence.json` are retained as before-fix evidence;
+  this repair supersedes their unresolved-selector status. Validation logs:
+  `/tmp/mobile-debug-selector-fix-verify.log`, `/tmp/mobile-debug-selector-fix-device.log`.
+
+## Remaining readiness test flake — 2026-10-30
+
+After push 0ae7300, [run 41034943919 passed](https://github.com/clivejefferies/mobile-debug-tools/actions/runs/41034943919)
+while [run 41034949793 failed](https://github.com/clivejefferies/mobile-debug-tools/actions/runs/41034949793)
+on the same commit. The failure was `server/readiness.test.ts:51`, expecting four
+reads but observing five. Real timer rounding can leave the fourth sample just
+short of the requested stability interval, legitimately requiring another read.
+
+Test-only repair: the sequential fixture/poll timers now advance wall and
+monotonic clocks by exactly their requested delay. Existing exact read counts,
+late-read/deadline rejection, state transitions, predicate observations, and
+forced second-read timeout assertions remain intact. Clock/timer hooks are
+restored in `finally`. No production timing or readiness behaviour changed.
+
+- Focused check: Node 23 pass; 25 separate Node 18.20.8 test-process runs pass.
+- Full Node 18 maintainer verification with unavailable native defaults: **pass**
+  (65 unit files, lint, build, agent-plugin consistency). Changed whitespace and
+  local document links also pass; log: `/tmp/mobile-debug-readiness-clock-verify.log`.
+- Native device suite not repeated for this test-only change; prior runtime
+  device results remain applicable. GitHub CI requires pushing this local repair.

package/docs/specs/022-correlated-evidence/spec.md

@@ -0,0 +1,123 @@
+# Specification: correlated evidence
+
+Date: 2026-10-29. Status: approved.
+Source: [issue #66](https://github.com/clivejefferies/mobile-debug-tools/issues/66).
+[Intent](intent.md) approved by “yes”; this specification approved by the
+maintainer’s “approve” on 2026-10-29 in this conversation.
+
+## Scope and association
+
+Add metadata to `start_app`, `restart_app`, `tap`, `tap_element`, `swipe`,
+`scroll_to_element`, `type_text`, `press_back`, `adjust_control`, their
+`run_journey` execution, and internal observations. Observation coverage:
+`capture_screenshot`, `get_ui_tree`, `get_screen_fingerprint`,
+`capture_debug_snapshot`, `get_logs`, `read_log_stream`.
+
+Allocate action IDs before execution; reuse them in results, traces, and nested
+observations. Journey steps share one correlation ID but retain individual action
+IDs. Standalone actions use their action ID as correlation ID. Independent
+observations receive a new correlation ID without an associated action.
+
+Observation tools accept optional `actionRef: { sessionId: string, actionId:
+string }`; strings must contain 1–128 characters. Malformed references return
+`INVALID_ARGUMENT` before collection. Associate only known same-session,
+same-device actions; never infer “last action”. Unknown/expired references allow
+independent collection, retaining the requested reference and association reason.
+Restart changes session ID. Retain completed action records for 10 minutes,
+maximum 1,000, evicting oldest first; active records belong to running calls.
+
+## Response contract
+
+Add `evidence` to the first JSON text block in compact/debug responses; snapshots
+place it alongside `raw`/`semantic`. Preserve existing fields, image blocks,
+ordering, IDs, timestamps, and elapsed timings. Log metadata describes the
+following log block.
+
+| Field | Contract |
+| --- | --- |
+| `session_id`, `correlation_id`, `action_id` | Action ID nullable when unassociated. |
+| `device` | Resolved platform/ID, nullable before resolution; app/PID only when resolved. UI scope is device-wide. |
+| `association` | `self`, `explicit`, `internal`, `none`, `unavailable`. |
+| `association_reason` | Null or `ACTION_UNAVAILABLE`, `SESSION_MISMATCH`, `DEVICE_MISMATCH`. Unavailable association has null action ID and independent correlation ID. |
+| Phase timestamps | `operation_started_at_ms`, `operation_completed_at_ms`, `dispatch_started_at_ms`, `dispatch_completed_at_ms`, `verification_completed_at_ms`; unreached/uninstrumented phases null. |
+| `observations` | Component records defined below. |
+| `trace_context` | `{ supported: false, trace_id: null, markers: [] }`; future tracing can reuse these identifiers. |
+
+Each component has unique `evidence_id`, `kind` (screenshot/ui_tree/fingerprint/
+activity/logs), `status` (`captured`, `failed`, `omitted`),
+`capture_started_at_ms`, `capture_completed_at_ms`, nullable
+`source_captured_at_ms`/`age_ms`, `freshness`, and `freshness_reasons`.
+Retain component errors and UI-tree snapshot session/revision references.
+Snapshot components, including fallback logs, have individual acquisition intervals.
+
+## Timing and freshness
+
+New epoch times use server UTC milliseconds; monotonic time governs ordering,
+durations, and retention. Clock reversal yields `CLOCK_DISCONTINUITY`, unknown
+freshness, and null age. Acquisition intervals bound server collection, not exact
+device frame time. Instrument actual dispatch after conditional checks;
+multi-input actions report first start/last completion. Preserve known times on
+failure. Verification completion includes timeout/failure, is null when skipped,
+and never overrides verification status.
+
+Assess freshness at response assembly:
+
+| Evidence | Freshness / reason |
+| --- | --- |
+| New successful visual acquisition, no intervening known dispatch on that device | `fresh`; no guarantee the app stayed unchanged. |
+| Before associated action’s dispatch | `stale` / `BEFORE_ACTION`. |
+| Overlapping dispatch | `unknown` / `OVERLAPPING_ACTION`. |
+| Superseded by later covered dispatch | `stale` / `SUPERSEDED_BY_ACTION`. |
+| Reused observation | Preserve source time; `unknown` / `REUSED_OBSERVATION` unless supersession proves stale. |
+| Missing timing | `unknown` / `CAPTURE_TIME_UNKNOWN`. |
+| Failed or omitted visual component | `unknown`. |
+| Logs / omitted logs | `unknown` / `DEVICE_CLOCK_UNVERIFIED`; omitted logs `not_applicable`. |
+
+Unassociated observations consider known concurrent dispatches. Age uses known
+host source capture time, otherwise null; clients choose age limits. Conditional
+safeguards remain unchanged. Preserve device log timestamps, declaring clock
+`device_or_unknown`, nullable earliest/latest parseable entry times, and
+`event_time_comparable: false`. Never infer emission freshness, causality, or
+an action-window filter from collection time.
+
+## Targeting, resources, and compatibility
+
+Pin snapshot components to one resolved device. References never redirect targets;
+stream reads use their stream’s device. Unknown scope means unknown freshness
+and no matching association. Per-call asynchronous context isolates concurrent
+calls/devices/steps; device dispatch ordering must not serialise independent calls.
+Snapshots remain non-atomic.
+
+Preserve existing errors, partial results, timeouts, and cancellation support;
+attach available metadata on failure. Add no retries, deadline extensions,
+processes, cancellation API, artifact removal, or stream termination. Release
+call context on completion/cancellation; existing owners clean up subprocesses
+and streams. History stores only IDs, scope, timings, and ordering: no captured
+content, arguments, credentials, persistence, or telemetry.
+
+Android ADB and iOS simulators share this contract; physical iOS retains provider
+limitations. Exclude trace capture, clock synchronisation, debugger, recovery,
+heap dumps, and background recording.
+
+## Acceptance and verification
+
+1. Referenced screenshots/logs share action identifiers in compact/debug responses.
+2. Capture, dispatch, verification, skipped phases, precondition failures, timeouts,
+   and multi-input actions have accurate distinguishable timings.
+3. Freshness follows the table, preserving uncertainty and component outcomes.
+4. Concurrent steps/devices, expired/mismatched references, and server restarts
+   cannot falsely associate evidence.
+5. Partial/disabled captures preserve existing responses; history is bounded/content-free.
+6. Platform limitations and unsupported tracing are explicit.
+
+Affected: server schemas/serialization, dispatch hooks, observation adapters,
+shared types/context, journeys, tests, and tool/README/changelog docs. Risks:
+missed dispatch paths, dropped metadata, retimestamped cache, wrong stream device.
+
+Baseline (2026-10-29): checkout 0.32.4; connected build unverified. Discovery:
+Android 16 emulator-5554, Pixel 9 Pro, iOS 26.4 iPhone 17 Pro simulator.
+Android compact tree: revision 1, elapsed timing, no correlation/capture metadata.
+Discovery/Android baseline passed; iOS capture/new behaviour unrun. Android logs
+flagged unavailable by healthcheck; targeted read needed. Post-approval checks:
+updated-server Android/iOS journeys, deterministic failure/concurrency coverage,
+`npm run verify`, `npm run test:device`.