Skip to content

Commit 25f501b

Browse files
committed
docs(adr): address cubic review threads
1 parent 207b52d commit 25f501b

4 files changed

Lines changed: 22 additions & 12 deletions

File tree

‎docs/adr/0019-request-bound-platform-runtime.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -951,7 +951,7 @@ The proposed target is ≤ 60.
951951
The target concerns its remaining contents, not directory retirement.
952952

953953
**Entry-to-platform hop count.** The measurement was corrected on 2026-09-03 and repeated for #2278 at `27a97ee619`.
954-
[`0023-end-state-hop-trace.md`](./0023-end-state-hop-trace.md) contains the definition, roles, and measured commit, and links the ordered chains at a pinned commit.
954+
[`0023-end-state-hop-trace.md`](./0023-end-state-hop-trace.md) contains the definition and roles; the [2026-09-03 hop trace evidence](../evidence/entry-to-platform-hop-trace-2026-09-03.md) holds the measured counts and ordered chains.
955955
It supersedes the earlier numbers below.
956956
A file-by-file re-trace at that HEAD measured 41 hops for `press`/Android and 47/49 for `snapshot`/iOS.
957957
The snapshot route shares 30 hops, with 17/19 per arm: in-simulator AX bridge primary and XCTest runner fallback.

‎docs/adr/0023-end-state-hop-trace.md‎

Lines changed: 5 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,11 @@
33
## Status
44

55
Reference audit for the entry-to-platform hop counts in ADR 0019 and the coupling audit in ADR 0022.
6-
The [ordered traces](https://github.com/callstack/agent-device/blob/0e7df74a1ad724e1deff07ff57f8ec763c883d21/docs/adr/0023-end-state-hop-trace.md) and measurements describe commit `27a97ee619`.
7-
They are not a current file map.
6+
The measured counts and the ordered traces are in [the 2026-09-03 hop trace evidence](../evidence/entry-to-platform-hop-trace-2026-09-03.md).
87

98
## Decision
109

11-
Count each distinct production TypeScript file entered on the main call path once, including both endpoints.
10+
Count each distinct production `.ts` file entered on the main call path once, including both endpoints.
1211
The path runs from the daemon HTTP entry to the file that issues the platform call.
1312
For Android `press`, that call is the serial-scoped `adb shell input tap`.
1413
For iOS `snapshot`, it is the AX bridge socket write on the primary arm, or the XCTest runner `fetch` on the fallback arm.
@@ -19,16 +18,14 @@ Trace the snapshot runner fallback with an existing runner session.
1918
Assign each file exactly one role: policy, orchestration, translation, adapter, or pass-through.
2019
A pass-through hop delegates to exactly one next call on the path without a branch or transformation.
2120
A translation hop maps values or shapes without issuing the platform call.
22-
The pinned trace defines the other roles.
21+
The ordered traces in the evidence define the other roles.
2322

2423
Apply the deletion test to each pass-through or translation hop.
2524
A hop is a collapse candidate if its caller, callee, or both can inline its handoff without losing admission, budget, isolation, a boundary declared in an ADR, or a testability seam.
2625
The test evaluates the hop, not whether the file can be deleted.
2726

2827
The audit supersedes the earlier 38/29 counts and the target of at most 14 hops.
29-
At the measured commit, the Android `press` route had 41 hops, and the iOS `snapshot` primary and fallback routes had 47 and 49.
30-
The audit proved one hop removable: the `bindRuntimeCommands` closure wrapper on the shared snapshot path.
31-
Its collapse would reduce the snapshot counts to 46 and 48.
28+
It proved one hop removable: the `bindRuntimeCommands` closure wrapper on the shared snapshot path.
3229
The audit endorses only that reduction.
3330
Any further target requires a decision to fold cross-cutting request-scope wrappers.
3431
That decision is outside the traced routes' ownership.
@@ -42,9 +39,7 @@ The request spine, runtime bindings, and platform protocols retain responsibilit
4239

4340
## Rejected alternative
4441

45-
Keep the target of at most 14 hops by folding every pass-through hop without kept depth.
46-
Only one hop lacked kept depth.
47-
For Android `press`, at most 14 hops would need the removal of 27 files with cross-cutting daemon responsibilities or necessary bindings.
42+
Keep the target of at most 14 hops by folding every pass-through hop without kept depth: on the `press` route every pass-through hop keeps depth, so the target would remove files with cross-cutting daemon responsibilities.
4843
Treat 14 as a historical discussion reference, not a derived number.
4944

5045
## Consequences

‎docs/adr/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@
2424
| [0020 Composable Recorded Fragments (Proposed)](0020-composable-recorded-fragments.md) | lifecycle-free recorded fragment capture/composition, entry guards, fragment-local addresses/digests, staleness, and native `.ad`/Maestro composition |
2525
| [0021 Simlock-Leased Devices Through Ordinary Local Runtimes](0021-simlock-leased-devices.md) | operation of a Simlock-leased simulator or emulator, and the reason for no agent-device allocator integration |
2626
| [0022 Daemon — Platform Runtime Coupling Audit and Ownership Ratchets](0022-daemon-platform-runtime-coupling.md) | daemon imports of root `platform-runtime-*` modules, the coupling ban that replaces R76 edge classification, the R75 session-authority ratchet, entry-to-platform hop routes and roles |
27-
| [0023 Entry-to-Platform Hop Audit](0023-end-state-hop-trace.md) | the hop counting definition, roles, deletion test, and measured results for numbers in ADR 0019 and ADR 0022; the ordered chains are at a pinned commit |
27+
| [0023 Entry-to-Platform Hop Audit](0023-end-state-hop-trace.md) | the hop counting definition, roles, and deletion test behind the route-depth rule; measured counts are in `docs/evidence/` |
2828
| [0024 Screen Recording — One Coordinator, Two Facts (Proposed)](0024-screen-recording-provable-signal.md) | `record start`/`stop` lifecycle, separate export-exists / recorder-stopped facts, backend stop-and-collect contract, coordinator recovery, the ADR 0019 §5 amendment, and the failed-finish cleanup fix |
2929
| [0025 Foldable Apple Panels — Capture the Lit Panel](0025-foldable-apple-panels.md) | iPhone Duo outer/inner panels, the screen authority (CoreDevice display info in the default set, the guest panel read in a scoped set), black-panel capture from `simctl`'s implicit display default, derived (never asserted) pose, `fold` pose control with guest hinge and scoped-set panel readback, and the Android emulator posture amendment |
3030
| [0026 Scroll Clip Authority — Ownership Is the Parent Edge](0026-scroll-clip-authority.md) | iOS scroll indicators and the visible band, parent-edge ownership instead of ancestor traversal, permitted node removal from interactive snapshots, and ejection dispositions |
Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Entry-to-platform hop trace, 2026-09-03
2+
3+
This trace measured the entry-to-platform route depth at commit `27a97ee619`, with the counting rules in [ADR 0023](../adr/0023-end-state-hop-trace.md). The [ordered per-hop chains](https://github.com/callstack/agent-device/blob/0e7df74a1ad724e1deff07ff57f8ec763c883d21/docs/adr/0023-end-state-hop-trace.md) list every file, its role and the deletion-test result. They describe that commit and are not a current file map.
4+
5+
| Route | Hops | After the one endorsed collapse |
6+
| --- | ---: | ---: |
7+
| Android `press` | 41 | 41 |
8+
| iOS `snapshot`, AX bridge arm | 47 | 46 |
9+
| iOS `snapshot`, XCTest runner fallback arm | 49 | 48 |
10+
11+
The one removable hop is the `bindRuntimeCommands` closure wrapper on the shared snapshot path, so only the snapshot counts change.
12+
13+
These counts supersede the earlier 38 (`press`) and 29 (`snapshot`) figures, which had no ordered chain or counting definition. On the `press` route every pass-through hop kept depth; a target of at most 14 hops would have needed the removal of 27 files with cross-cutting daemon responsibilities or necessary bindings.
14+
15+
The ordered chains state 18 files for the fallback arm's own segment but total the arm at 49 (30 shared + 19). The counts above keep the published totals.

0 commit comments

Comments
 (0)