|
| 1 | +# ADR 0038: Snapshot capture source routing |
| 2 | + |
| 3 | +## Status |
| 4 | + |
| 5 | +Proposed for [#4205](https://github.com/callstack/agent-device/issues/4205). |
| 6 | +No production migration precedes acceptance. |
| 7 | +On acceptance, this replaces ADR 0004's source-routing rules and ownership. |
| 8 | +ADR 0004 retains iOS acquisition, presentation, geometry, and system-surface contracts. |
| 9 | +Completed migration history stays in git history. |
| 10 | + |
| 11 | +## Rules at a glance |
| 12 | + |
| 13 | +- Route every supported capture through capture-kit channels. |
| 14 | +- Permit one fallback; share refusal scope, circuits, and warnings. |
| 15 | +- Stamp served identity; derive producer facts from contracts. |
| 16 | + |
| 17 | +## Boundary and channels |
| 18 | + |
| 19 | +`@agent-device/capture-kit` owns the router: planning, proof, fallback, circuits, identity, warnings. |
| 20 | +Allow neutral contracts, kernel primitives, host-kit capabilities, and capture-kit policy imports. |
| 21 | +Forbid direct, transitive, and dynamic dependencies on platform/provider code. |
| 22 | +Bound runtime owners retain channels across requests and close only owned resources. |
| 23 | +Keep lease/lock authority ([ADR 0007](0007-remote-device-leases.md)). |
| 24 | + |
| 25 | +Contracts defines `SourceChannel<T>`: |
| 26 | + |
| 27 | +| Member | Contract | |
| 28 | +| --- | --- | |
| 29 | +| `id`, `producer` | Separate transport from producer; both bridge transports emit `simulator-ax-bridge`. | |
| 30 | +| `acquire({ target, hint, proof, signal })` | Return acquired/presented evidence, served identity, residue, proof; or typed refusal. | |
| 31 | +| `resolveTarget(device, app, signal)` | Return real target `T`, device key, target id, optional verified generation; or typed discovery-pending. | |
| 32 | +| `refreshTarget?(device, app, signal)` | Verify cached identity; omit when resolution already verifies identity. | |
| 33 | +| `awaitDiscovery?(device, signal)` | Await detached discovery; omit when none exists. | |
| 34 | +| `proof` | `'none'` or `SurfaceProof`. | |
| 35 | +| `supports` | Declare `customActions`, `observeOnly`, and supported `pinnedBackend` values. | |
| 36 | + |
| 37 | +Operations share remaining budget and cancellation. |
| 38 | +Hints separate raw and presented depth; presentation owns scope. |
| 39 | +Discovery-pending requires `awaitDiscovery` or an available alternate. |
| 40 | +No constant callbacks, `targetFreshness`, or fabricated pids/generations are allowed. |
| 41 | + |
| 42 | +`SurfaceProof(device, signal)` returns `'clear'`, `{ occluded: surfaceId }`, or `'unproven'`. |
| 43 | +`'none'` requires no separate absence proof and asserts none. |
| 44 | +Occlusion selects a surface-capable channel; unproven acquisition must refuse occluded/unverified reads through integrated checks. |
| 45 | +Never cache absence across captures. |
| 46 | + |
| 47 | +Both bridges probe registered hosts through runner foreground state. |
| 48 | +Only provider probes may prepare their required runner. |
| 49 | +If unproven, pass host executables into the bridge's pre/post-read process checks. |
| 50 | +Forbid host-side process probes. |
| 51 | +Serve registered hosts in place without activation or rebinding, per ADR 0004. |
| 52 | + |
| 53 | +## Planning, fallback, and refusals |
| 54 | + |
| 55 | +Pure `plan(input)` takes ordered owner channels, options, target/proof evidence, circuits, and a current-loop backend pin. |
| 56 | +It returns selected channel, typed reason, and at most one eligible alternate. |
| 57 | +It owns eligibility, observe-only, and pins; unsupported requests fail before acquisition. |
| 58 | +Never relax pins or activate for observe-only. |
| 59 | +Stable capture supplies its current-loop private-AX backend pin; previous snapshots cannot pin its first read. |
| 60 | + |
| 61 | +One settlement path handles resolution, acquisition, presentation, and alternates. |
| 62 | +Attempt one alternate at most; its failure retains the first reason. |
| 63 | +Cancellation neither falls back nor changes circuits. |
| 64 | +Channels/presenters cannot route recursively. |
| 65 | +XCTest tiers and Android helper recovery stay internal and cannot select another channel. |
| 66 | + |
| 67 | +Key circuits by owner, device key, channel id, target id, and verified generation. |
| 68 | +Generation refusals disable that channel; new generations clear old circuits. |
| 69 | +Refresh cached targets before honoring disabled circuits and after stale-target evidence. |
| 70 | +If refresh fails, retain only circuit bookkeeping; publish no cached generation. |
| 71 | +Without verified generation, create no generation circuit. |
| 72 | + |
| 73 | +Generalize `contracts/fixtures/ios-snapshot-bridge-refusals.json` into router input for all typed-refusal channels. |
| 74 | +Entries key on producer/code and declare scope plus warning consequence; bridge transports share entries. |
| 75 | +Preserve iOS scope: |
| 76 | + |
| 77 | +| Scope | Evidence | |
| 78 | +| --- | --- | |
| 79 | +| Capture | Preparation, read-in-flight, tree change, foreground ownership, unresolved coordinates, window placement, surface-host presence or uncertainty. | |
| 80 | +| Generation | Remote-content boundary, abandoned read, malformed tree, presentation invariant failure. | |
| 81 | + |
| 82 | +Unknown codes have generation scope if verified. |
| 83 | +Intercept cancellation before lookup, including `abort-signal`. |
| 84 | +Unclassified provider errors remain terminal. |
| 85 | + |
| 86 | +## Producers and publication |
| 87 | + |
| 88 | +Define platform-neutral `SnapshotProducer` and one contracts registry with `satisfies Record<SnapshotProducer, ProducerFacts>`. |
| 89 | +Rows declare backend channels, truncation, residue policy, quiet time, and ref-namespace owner. |
| 90 | +Residue distinguishes source-measured and provider-derived facts. |
| 91 | +Derive provenance pairs, iOS subsets, producer warning dispatch, quiet time, and ref behavior here. |
| 92 | +First move provenance-dependent carriers/helpers from `packages/kernel/src/snapshot.ts` to contracts. |
| 93 | +Keep node/geometry primitives in kernel; forbid kernel-to-contracts cycles. |
| 94 | +Keep bridge quiet time at 300 ms, others at 500 ms; preserve agent-browser refs. |
| 95 | + |
| 96 | +One-channel owners have no alternate: Android, macOS helper/XCTest, web, WebDriver, Revyl, HarmonyOS, Linux, TV CDP, and composing providers. |
| 97 | +Local and Limrun iOS Simulators offer bridge first, then `apple-runner`. |
| 98 | +Physical iOS, tvOS, and visionOS retain one runner channel. |
| 99 | +Unsupported owners such as Vega declare no channel. |
| 100 | +WebDriver keeps `appium-source` on both backend channels. |
| 101 | +Rename Revyl Android to `revyl-android-tree`; sharing a parser does not make it Appium. |
| 102 | + |
| 103 | +Stamp identity once after presentation: actual producer, intent, served target/generation, presentation key, residue. |
| 104 | +Served surfaces override planned app lineage and discard app-generation residue. |
| 105 | +Failed generation resolution carries per-capture unknown-generation residue. |
| 106 | +Channels without generation support declare it unavailable; surfaces carry no app generation. |
| 107 | +Preserve iOS producer names and fallback wording. |
| 108 | +One-channel success adds no fallback warning; assembly retains quality/freshness disclosures. |
| 109 | + |
| 110 | +Android `systemSurfaceOnly` stays acquisition metadata, not `SurfaceProof`. |
| 111 | +`packages/platform-android/src/snapshot-content-recovery.ts` accepts usable system-only trees. |
| 112 | +This and system-bar labels prove no absence: use `proof: 'none'`, preserving disclosure/recovery. |
| 113 | +A future app-only channel needs independent window-ownership evidence tied to its read. |
| 114 | + |
| 115 | +## Migration and enforcement |
| 116 | + |
| 117 | +After acceptance, each small PR must merge alone: |
| 118 | + |
| 119 | +1. Move provenance carriers to contracts; migrate registry consumers atomically. |
| 120 | +2. Add router/refusal input and layering enforcement; port guest/runner tests with unchanged behavior assertions. |
| 121 | +3. Bind both iOS channels; remove old routing, placeholder ports, duplicate eligibility, and fallback settlers. |
| 122 | +4. Bind single-source owners separately; rename Revyl Android with its emitter/consumers. |
| 123 | +5. Slim ADR 0004 below about 15 KB after relocating unique contracts; retain iOS rules. |
| 124 | + |
| 125 | +Add router layering enforcement with a failing dependency control. |
| 126 | +Producer-emitter/refusal guards in `test/repo-guards/` reject missing reachable production emitters, unlisted codes, and scope disagreement. |
| 127 | +Add an ADR-citation guard for nonexistent cited paths/test names. |
| 128 | +Select guards through affected checks with docs-prose, docs-links, and agent-guidance. |
| 129 | +Require live producer/fallback parity on local iOS Simulator, Limrun iOS, and local Android. |
| 130 | + |
| 131 | +## Rationale and alternatives |
| 132 | + |
| 133 | +Readers, decoding, discovery, process checks, native budgets, geometry, and lifecycle stay platform-specific. |
| 134 | +Presentation stays in capture-kit and runner-side Swift. |
| 135 | + |
| 136 | +Rejected: Apple placeholder ports (absent capabilities), provider planners (duplicated policy), and annotations as absence proof (no pre-read evidence). |
| 137 | +The cost is provenance migration and explicit channels. |
0 commit comments