Skip to content

Commit fd031ee

Browse files
committed
docs(adr): narrow 0038 routing to multi-channel owners and move the plan to #4205
- Route only owners with more than one channel through the router. Every producer stamps identity through capture-kit and declares a registry row. - Give unknown refusal codes generation scope without a verification condition. - Add the runner-session scope from #4241. - Derive quiet time per capture from the served producer. - Move the migration plan and the guard inventory to #4205.
1 parent cb15409 commit fd031ee

1 file changed

Lines changed: 15 additions & 22 deletions

File tree

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

Lines changed: 15 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,9 @@ Completed migration history stays in git history.
1010

1111
## Rules at a glance
1212

13-
- Route every supported capture through capture-kit channels.
13+
- Route owners with more than one channel through the capture-kit router.
1414
- Permit one fallback; share refusal scope, circuits, and warnings.
15-
- Stamp served identity; derive producer facts from contracts.
15+
- Every producer stamps served identity through capture-kit and declares a contracts registry row.
1616

1717
## Boundary and channels
1818

@@ -78,8 +78,10 @@ Preserve iOS scope:
7878
| --- | --- |
7979
| Capture | Preparation, read-in-flight, tree change, foreground ownership, unresolved coordinates, window placement, surface-host presence or uncertainty. |
8080
| 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. |
8182

82-
Unknown codes have generation scope if verified.
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.
8385
Intercept cancellation before lookup, including `abort-signal`.
8486
Unclassified provider errors remain terminal.
8587

@@ -91,11 +93,13 @@ Residue distinguishes source-measured and provider-derived facts.
9193
Derive provenance pairs, iOS subsets, producer warning dispatch, quiet time, and ref behavior here.
9294
First move provenance-dependent carriers/helpers from `packages/kernel/src/snapshot.ts` to contracts.
9395
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.
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.
9598

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+
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.
99103
Unsupported owners such as Vega declare no channel.
100104
WebDriver keeps `appium-source` on both backend channels.
101105
Rename Revyl Android to `revyl-android-tree`; sharing a parser does not make it Appium.
@@ -112,26 +116,15 @@ Android `systemSurfaceOnly` stays acquisition metadata, not `SurfaceProof`.
112116
This and system-bar labels prove no absence: use `proof: 'none'`, preserving disclosure/recovery.
113117
A future app-only channel needs independent window-ownership evidence tied to its read.
114118

115-
## Migration and enforcement
119+
## Consequences
116120

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

131124
## Rationale and alternatives
132125

133126
Readers, decoding, discovery, process checks, native budgets, geometry, and lifecycle stay platform-specific.
134127
Presentation stays in capture-kit and runner-side Swift.
135128

136-
Rejected: Apple placeholder ports (absent capabilities), provider planners (duplicated policy), and annotations as absence proof (no pre-read evidence).
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).
137130
The cost is provenance migration and explicit channels.

0 commit comments

Comments
 (0)