Skip to content

Commit cb15409

Browse files
committed
docs(adr): propose platform-neutral snapshot source routing
1 parent b42c7c2 commit cb15409

3 files changed

Lines changed: 141 additions & 0 deletions

File tree

‎docs/adr/0004-ios-snapshot-backend-strategy.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@
33
## Status
44

55
Accepted.
6+
Source-routing ownership and rules are proposed for replacement by [ADR 0038](0038-snapshot-capture-source-routing.md).
7+
Until that proposal is accepted, this ADR's routing rules remain in force.
8+
The iOS reader, runner capture plan, presentation, geometry, and in-place system-surface contracts remain here.
69
This ADR was amended after local iOS Simulator acquisition moved to the host AX bridge, and again for provider iOS Simulators that the runner serves.
710
The public surface remains two modes: regular interactive snapshots and raw diagnostic snapshots.
811
The host AX bridge is an acquisition route, not a third public mode.
Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
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.

‎docs/adr/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@
3939
| [0035 Host-Scoped Devices](0035-macos-app-devices.md) | native macOS apps as devices of their own, the host/scoped-device overlap and claim rule, concurrent app sessions, and `macos-app` lease claims |
4040
| [0036 Bounded Composite Resource Admission](0036-bounded-composite-resource-admission.md) | resource operations, nested tests, session disposal, and claim recovery inside bounded batch/replay steps |
4141
| [0037 Web Session Devices](0037-web-session-devices.md) | web sessions as devices of their own, the session name rule, the `p_`/`t_` backend key and tenant isolation, and first-open locking for web |
42+
| [0038 Snapshot capture source routing (Proposed)](0038-snapshot-capture-source-routing.md) | platform-neutral source channels, proof, one fallback, generation circuits, refusal scope, and the producer registry |
4243

4344
ADRs record rationale.
4445
The registries and gates they describe are the current source of truth.

0 commit comments

Comments
 (0)