Skip to content

Commit 7ef3490

Browse files
committed
docs(adr): accept 0038 as a one-page decision record
Keep only the decisions, reasons, rejected alternatives, and consequences. Move the source interface, planner mechanics, and per-owner inventory to #4205. Keep the constraints that the code cannot show: unproven is not clear, cancellation is terminal, no circuit without a verified generation, and a served surface owns its identity. Amend the ADR 0004 status to point at 0038.
1 parent fd031ee commit 7ef3490

3 files changed

Lines changed: 66 additions & 117 deletions

File tree

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@
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.
6+
[ADR 0038](0038-snapshot-capture-source-routing.md) owns snapshot source routing for every platform.
7+
Until the router from [#4205](https://github.com/callstack/agent-device/issues/4205) replaces the Apple route, the routing rules here describe the current iOS code.
88
The iOS reader, runner capture plan, presentation, geometry, and in-place system-surface contracts remain here.
99
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.
1010
The public surface remains two modes: regular interactive snapshots and raw diagnostic snapshots.

‎docs/adr/0038-snapshot-capture-source-routing.md‎

Lines changed: 63 additions & 114 deletions
Original file line numberDiff line numberDiff line change
@@ -2,129 +2,78 @@
22

33
## Status
44

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.
109

11-
## Rules at a glance
10+
## Context
1211

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.
1616

17-
## Boundary and channels
17+
## Decision
1818

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).
2424

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.
2628

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 |
7844
| --- | --- |
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. |
11848

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
12062

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.
12367

124-
## Rationale and alternatives
68+
## Rejected alternatives
12569

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
12876

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.

‎docs/adr/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +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 |
42+
| [0038 Snapshot capture source routing](0038-snapshot-capture-source-routing.md) | the source router for multi-source owners, one fallback, refusal scopes, surface proof, and the producer registry |
4343

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

0 commit comments

Comments
 (0)