Skip to content

Commit d160201

Browse files
committed
docs: restore ADR 0022 review constraints
1 parent c9f171e commit d160201

2 files changed

Lines changed: 8 additions & 6 deletions

File tree

‎docs/adr/0022-daemon-platform-runtime-coupling.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,26 +2,28 @@
22

33
## Status
44

5-
Accepted. R76 enforces the daemon coupling ban. R75 ratchets handler authority.
5+
Accepted (2026-09-06). R76 enforces the daemon coupling ban. R75 ratchets handler authority.
66

77
## Context
88

99
The daemon must not depend on concrete platform code. This boundary alone does not establish whether each platform-aware responsibility belongs in the daemon. Session state and store authority also need a boundary for handlers. Route depth needs a deletion test, not a numerical budget that would fold necessary request-scope wrappers.
1010

1111
## Decision
1212

13-
R76 prohibits every production daemon import of the root platform-runtime family or a root hub that reaches it. The family consists of the root platform-runtime module and root modules whose names start with platform-runtime-. The ban includes static and dynamic imports. Process-root composition is outside the daemon zone. Composition-essential edges assemble neutral implementations there. Daemon-policy-essential edges own request admission, session ownership, conflicts, locking, cancellation, teardown ordering, artifact publication, or response and event semantics. Platform mechanics and state belong behind a deeper interface or adapter.
13+
R76 prohibits every production daemon import of the root platform-runtime family or a root hub that reaches it. The family is `src/platform-runtime.ts` and the src/platform-runtime-*.ts glob. The ban includes static and dynamic imports. Process-root composition is outside the daemon zone.
1414

1515
Apple session observation uses the neutral `AppleSessionObservation`. It supplies runner liveness, session identity, and sole-foreground-app observation. Recording health, device refresh, and open-hint policy consume it. Root composition supplies request-local inventory and its error classifier. The Apple platform package owns the probes. Selector production and lifecycle participation remain separate.
1616

17-
Platform owners participate through the existing lifecycle phases. Do not introduce a generic hook bag. Open-target plans and results remain separate from platform mechanics. The resolver remains the single construction path for an open plan. Selector reads use the `querySelector` operation on the request-bound runtime owner. Its declaration is conditional on the captured touch and gesture uses. Off-screen rescue uses the command's admitted binding. Do not add a second selector producer.
17+
The daemon receives only the typed `PlatformOwnerLifecycle`. `src/platform-runtime-daemon-lifecycle.ts` alone composes it and imports the platform owners' cleanup and recovery mechanics. Platform owners participate through the existing lifecycle phases. Do not introduce a generic hook bag. Open-target plans and results remain separate from platform mechanics. The resolver remains the single construction path for an open plan. The live selector read uses the `querySelector` operation on the request-bound runtime owner. Its declaration is conditional on the captured touch and gesture uses. Off-screen rescue uses the command's admitted binding. Do not add a second selector producer.
1818

19-
R75 measures `SessionState` shape and `SessionStore` authority by symbol. It fails when a handler file enters either set and the merge-base set does not contain that file. Handler files may leave either set. R75 does not ratchet reads outside the handler path. R7 and R10 own cross-module reads outside that path.
19+
R75 `session-authority-overlay` measures `SessionState` shape and `SessionStore` authority by symbol. It fails when a handler file enters either set and the merge-base set does not contain that file. The handler scope is the packages/daemon/src/{sessions,execution}/handlers/** glob. Handler files may leave either set. R75 does not ratchet reads outside the handler path. R7 and R10 own cross-module reads outside that path.
2020

21-
The route trace assigns each hop a role and tests each pass-through or translation hop for deletion. Collapse only pass-through or translation hops that the deletion test proves removable. The audited runtime-types hop is the only endorsed collapse. The earlier ≤14 target is superseded. The request-spine guards are side-calls, not hops. [ADR 0023](0023-end-state-hop-trace.md) owns the trace and deletion tests.
21+
The route trace assigns each hop a role and tests each pass-through or translation hop for deletion. A route may collapse only pass-through or translation hops that the deletion test proves removable. The `bindRuntimeCommands` closure wrapper on the shared snapshot path is the only proven removable hop and the only endorsed collapse. The earlier ≤14 target is superseded. The request-spine guards are side-calls, not hops: auth comparison, cancellation gate, idle-reap timer reset, and Android freshness guard/clear. [ADR 0023](0023-end-state-hop-trace.md) owns the trace and deletion tests.
2222

2323
## Rationale and rejected alternatives
2424

25+
The #2278 audit sorted edges into three categories: composition-essential edges assemble neutral implementations at the process root; daemon-policy-essential edges own request admission, session ownership, conflicts, locking, cancellation, teardown ordering, artifact publication, or response and event semantics; platform mechanics and state belong behind a deeper interface or adapter.
26+
2527
Root composition and daemon policy can own neutral interfaces without exposing platform mechanics to the daemon. A generic lifecycle hook bag would bypass the existing phases. A second selector producer would duplicate snapshot-producer policy.
2628

2729
A repository-wide authority ratchet would prevent legitimate movement of reads that belong to their modules. The handler ratchet targets growth in handler state shape and store authority.

‎docs/adr/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@
2323
| [0019 Request-Bound Platform Runtime](0019-request-bound-platform-runtime.md) | platform-package boundaries/composition, device discovery, runtime facts/facets, request binding, provider ownership, platform-shaped session resources, durable reattachment, daemon-handler migration |
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 |
26-
| [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 |
26+
| [0022 Daemon platform runtime coupling and ownership](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, the route-depth rule |
2727
| [0023 End-State Entry-to-Platform Hop Trace](0023-end-state-hop-trace.md) | the definition of hop counts, ordered `press`/Android and dual-arm `snapshot`/iOS chains, per-hop roles, and the deletion test for numbers in ADR 0019 and ADR 0022 |
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 |

0 commit comments

Comments
 (0)