|
2 | 2 |
|
3 | 3 | ## Status |
4 | 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. |
| 5 | +Accepted. |
| 6 | +This record owns snapshot source routing for every platform and provider. |
| 7 | +It amends [ADR 0004](0004-ios-snapshot-backend-strategy.md), which keeps the iOS acquisition, presentation, geometry, and system-surface contracts. |
| 8 | +The router does not exist yet. [#4205](https://github.com/callstack/agent-device/issues/4205) holds the migration plan and its guards. |
10 | 9 |
|
11 | | -## Rules at a glance |
| 10 | +## Context |
12 | 11 |
|
13 | | -- Route owners with more than one channel through the capture-kit router. |
14 | | -- Permit one fallback; share refusal scope, circuits, and warnings. |
15 | | -- Every producer stamps served identity through capture-kit and declares a contracts registry row. |
| 12 | +Only iOS has a source-selection rule, in the Apple platform runtime. |
| 13 | +Its runner source fills the route's ports with constants. |
| 14 | +Eligibility has three owners, fallback has three settlers, and producer facts have about six tables. |
| 15 | +Each other platform has one hard-wired source with its own refusal and identity vocabulary. |
16 | 16 |
|
17 | | -## Boundary and channels |
| 17 | +## Decision |
18 | 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)). |
| 19 | +**Router.** One platform-neutral router in `@agent-device/capture-kit` owns planning, fallback, refusal scope, circuits, surface proof, and warnings. |
| 20 | +Owners with more than one source use the router. |
| 21 | +Today these owners are the local and Limrun iOS Simulators: the simulator AX bridge first, then the XCTest runner. |
| 22 | +The router depends on no platform or provider code. |
| 23 | +Lease and lock authority stays with [ADR 0007](0007-remote-device-leases.md). |
24 | 24 |
|
25 | | -Contracts defines `SourceChannel<T>`: |
| 25 | +**One-source owners.** An owner with one source does not use the router. |
| 26 | +It stamps identity through the capture-kit helper. |
| 27 | +When an owner gets a second source, it moves to the router. |
26 | 28 |
|
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 | |
| 29 | +**Producers.** One contracts registry keys every producer with a platform-neutral name. |
| 30 | +All other producer facts derive from that registry. |
| 31 | + |
| 32 | +**Identity.** Stamp identity once, after presentation, from the source that served the capture. |
| 33 | +When a system surface serves the capture, the surface owns the published identity, not the app generation below it. |
| 34 | + |
| 35 | +**Fallback.** A capture tries one alternate source at most. |
| 36 | +If the alternate fails, the capture keeps the first reason. |
| 37 | +Cancellation is terminal: it neither falls back nor changes a circuit. |
| 38 | +Never relax a backend pin or an observe-only request to make a fallback possible. |
| 39 | +A source never routes to another source. |
| 40 | + |
| 41 | +**Refusal scope.** Each typed refusal has one scope: |
| 42 | + |
| 43 | +| Scope | Effect | |
78 | 44 | | --- | --- | |
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 | | -| Runner session | Wedged runner-side bridge reader; a new runner session id starts a fresh circuit. | |
82 | | - |
83 | | -Unknown codes have generation scope. |
84 | | -Without a verified generation, an unknown code disables the channel for the current capture and creates no circuit. |
85 | | -Intercept cancellation before lookup, including `abort-signal`. |
86 | | -Unclassified provider errors remain terminal. |
87 | | - |
88 | | -## Producers and publication |
89 | | - |
90 | | -Define platform-neutral `SnapshotProducer` and one contracts registry with `satisfies Record<SnapshotProducer, ProducerFacts>`. |
91 | | -Rows declare backend channels, truncation, residue policy, quiet time, and ref-namespace owner. |
92 | | -Residue distinguishes source-measured and provider-derived facts. |
93 | | -Derive provenance pairs, iOS subsets, producer warning dispatch, quiet time, and ref behavior here. |
94 | | -First move provenance-dependent carriers/helpers from `packages/kernel/src/snapshot.ts` to contracts. |
95 | | -Keep node/geometry primitives in kernel; forbid kernel-to-contracts cycles. |
96 | | -Keep bridge quiet time at 300 ms, others at 500 ms; derive it per capture from the served producer. |
97 | | -Preserve agent-browser refs. |
98 | | - |
99 | | -Local and Limrun iOS Simulators offer bridge first, then `apple-runner`, and route through the router. |
100 | | -Every other owner has one channel and does not route through the router: Android, macOS helper/XCTest, web, WebDriver, Revyl, HarmonyOS, Linux, TV CDP, composing providers, and physical iOS, tvOS, and visionOS. |
101 | | -A one-channel owner calls the capture-kit identity-stamp helper and declares its registry row. |
102 | | -An owner that gains a second channel moves to the router. |
103 | | -Unsupported owners such as Vega declare no channel. |
104 | | -WebDriver keeps `appium-source` on both backend channels. |
105 | | -Rename Revyl Android to `revyl-android-tree`; sharing a parser does not make it Appium. |
106 | | - |
107 | | -Stamp identity once after presentation: actual producer, intent, served target/generation, presentation key, residue. |
108 | | -Served surfaces override planned app lineage and discard app-generation residue. |
109 | | -Failed generation resolution carries per-capture unknown-generation residue. |
110 | | -Channels without generation support declare it unavailable; surfaces carry no app generation. |
111 | | -Preserve iOS producer names and fallback wording. |
112 | | -One-channel success adds no fallback warning; assembly retains quality/freshness disclosures. |
113 | | - |
114 | | -Android `systemSurfaceOnly` stays acquisition metadata, not `SurfaceProof`. |
115 | | -`packages/platform-android/src/snapshot-content-recovery.ts` accepts usable system-only trees. |
116 | | -This and system-bar labels prove no absence: use `proof: 'none'`, preserving disclosure/recovery. |
117 | | -A future app-only channel needs independent window-ownership evidence tied to its read. |
| 45 | +| Capture | The source stays eligible for the next capture. | |
| 46 | +| App generation | The source stays disabled until the app has a new generation. | |
| 47 | +| Runner session | The source stays disabled until the runner has a new session id. | |
118 | 48 |
|
119 | | -## Consequences |
| 49 | +An unknown refusal code has app-generation scope. |
| 50 | +Without a verified generation, the refusal disables the source for the current capture only and creates no circuit. |
| 51 | +The refusal fixture is the one table of codes and scopes. |
| 52 | +The router handles cancellation before it classifies a refusal. |
| 53 | + |
| 54 | +**Surface proof.** Prove surface absence for each capture. Never cache it. |
| 55 | +An unproven state is not a clear state: an app-only read must prove absence or refuse. |
| 56 | +An occluded read selects a source that can read the surface. |
| 57 | +A source that declares no proof asserts no absence. |
| 58 | +Acquisition metadata, such as an Android system-only tree, is not a proof. |
| 59 | +A future app-only source needs window-ownership evidence that is tied to its read. |
| 60 | + |
| 61 | +## Rationale |
120 | 62 |
|
121 | | -The migration plan, its guard inventory, and the live parity checks live in [#4205](https://github.com/callstack/agent-device/issues/4205). |
122 | | -Repo guards enforce the router's layering, the producer emitters, and the refusal table scope. |
| 63 | +- One rule makes fallback, refusals, and warnings the same on every platform. A new provider declares its sources and does not copy policy. |
| 64 | +- The router applies only where a choice exists. A planner that never chooses adds migration cost and no value. |
| 65 | +- An unknown refusal fails closed, so a failed source cannot stay eligible. |
| 66 | +- A surface can appear between captures. A cached absence would publish an occluded read as app content. |
123 | 67 |
|
124 | | -## Rationale and alternatives |
| 68 | +## Rejected alternatives |
125 | 69 |
|
126 | | -Readers, decoding, discovery, process checks, native budgets, geometry, and lifecycle stay platform-specific. |
127 | | -Presentation stays in capture-kit and runner-side Swift. |
| 70 | +- Placeholder ports on the Apple route: they claim capabilities that a source does not have. |
| 71 | +- A planner for each provider: it duplicates policy, and the copies drift. |
| 72 | +- Annotations as absence proof: they give no evidence from before the read. |
| 73 | +- The router for one-source owners: the planner never chooses for them. |
| 74 | + |
| 75 | +## Consequences |
128 | 76 |
|
129 | | -Rejected: Apple placeholder ports (absent capabilities), provider planners (duplicated policy), annotations as absence proof (no pre-read evidence), and routing one-channel owners through the router (the planner never chooses for them). |
130 | | -The cost is provenance migration and explicit channels. |
| 77 | +- Provenance types move from kernel to contracts, and both iOS sources bind to the router. |
| 78 | +- Readers, decoding, discovery, process checks, native budgets, geometry, and lifecycle stay platform-specific. |
| 79 | +- Open gaps: the router and the producer registry do not exist yet. The runner-session scope arrives with [#4256](https://github.com/callstack/agent-device/pull/4256). ADR 0004 must shrink below about 15 KB. |
0 commit comments