docs(adr): record the #2278 coupling audit and re-trace entry-to-platform hops

[thymikee]

Summary

Audit record for #2278 (companion PR #2354 carries the R76/R75 gates this ADR points at; stacked on top of it):

• New ADR 0022 (docs/adr/0022-daemon-platform-runtime-coupling.md): the three-category classification schema and per-edge outcomes, the per-audit-area decisions, and the child-issue map (refactor(daemon): own Apple runner session observation behind a semantic port #2332 Apple runner session observation port, refactor(daemon): normalize lifecycle participation of platform resource owners #2333 lifecycle participation of platform resource owners, refactor(daemon): separate open-target planning from platform mechanics #2334 open-target planning split, blocked by refactor(daemon): own Apple runner session observation behind a semantic port #2332; the direct-ios-selector seam coordinated under A failed selector query cannot be told apart from a true negative, and it ends the session without saying so #2273/Selector queries have no fallback producer on the iOS Simulator, and any fallback needs producer equivalence #2274).
• Re-traced the ADR 0019 end-state hop trace at 27a97ee with hop roles (policy / orchestration / translation / adapter / pass-through + terminal) and a deletion test per pass-through/translation hop: press/Android 41 hops; snapshot/iOS is now a dual-arm route — shared 30 + in-simulator AX bridge 17 (primary) / XCTest runner fallback 19. Request-spine guards (auth comparison, cancellation gate, idle-reap reset, Android freshness guard/clear) are side-calls, not hops; the deletion test proves a single distinct removable hop (commands/runtime-types). The earlier ≤14 target is superseded as not reachable without folding cross-cutting request-scope wrappers.
• Updated the ADR 0019 end-state paragraph and the ADR index. 4 files. Closes refactor(daemon): audit and retire residual semantic platform coupling #2278.

Validation

Docs-only change; runtime validation does not apply. The hop tables were re-traced file-by-file at 27a97ee under the locked counting method (main call chain, traced request pinned: session-bound agent-surface command, local device, no provider scope, no admitted lease). Spine side-calls were excluded after verifying against the code that none of them is the continuation toward the platform boundary. The newer base (#2331) changed the AX target-discovery failure behavior (single-flight probe, 1.5s bounded wait) without changing the traced file set; the fork line now documents that.

[thymikee]

Before using the 44 / 51 / 53 counts or the three-removable-hop conclusion as audit evidence, reconcile the counting definition’s side-call exclusion with the rows for idle-reap cancellation and token comparison: neither is the call that continues toward the platform boundary. Retrace the tables or revise the definition and conclusion consistently. Keep this companion behind #2354.

[github-actions]

Size Report

Metric	Base	Current	Diff
Installed (including dependencies)	4.51 MB	4.50 MB	-12.0 kB
Package (unpacked)	4.51 MB	4.50 MB	-12.0 kB
Package (download)	1.34 MB	1.33 MB	-3.6 kB

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	26.4 ms	26.2 ms	-0.2 ms
CLI --help	78.1 ms	77.4 ms	-0.7 ms

[thymikee]

Retraced, rather than relaxing the definition. The idle-reap cancel and the token comparison were mis-counted: at the call site each is a sibling statement of the continuation (handleRequest counts in-flight and cancels the reap timer, then dispatchRequest continues; runRequestWithinScope compares the token, then withDeviceInventoryContext continues), so neither is "the first call that continues toward the platform call". Verified in code at the measurement commit. Two more rows fail the same test and were excluded with them: the cancellation gate (throwIfRequestCanceled gates the task() continuation inside runLocked/runAdmitted) and the Android freshness guard/clear (a guard read in deferred-interaction-outcome and a post-capture clear that no-ops on iOS).

The counting definition now states the guard/liveness exclusion explicitly, and every number was recomputed consistently: press/Android 44 → 41; snapshot shared 34 → 30, arms 51/53 → 47/49. The three-removable-hop conclusion changes with it: daemon-idle-reap and session-snapshot-freshness were side-calls, not hops, so the deletion test now proves a single distinct removable hop — commands/runtime-types.ts. ADR 0019's end-state paragraph, ADR 0022's decision 4, and this PR body are all synced to the new numbers.

Per "keep this companion behind #2354", the base is now issue-2278-gates; the branch was rebased onto it and re-pushed (991425d).

[thymikee]

The revised hop trace at 991425d consistently excludes side calls and ties the remaining route counts to the measured source. No remaining documentation findings. Keep this behind #2354; its gate bypass still needs fixing before the pair lands.

[thymikee]

The documentation at e59ee44 remains consistent, with no documentation findings. Keep this behind #2354: its combined named-plus-namespace import bypass still needs fixing before the pair lands. Checks here are green.

[thymikee]

Acknowledged — this stays stacked behind #2354 (base is the gates branch) and unblocks once its fix lands. One note: after rebase onto current main, the new snapshot-assembly gate rule took R74, so the companion gates were renumbered — this PR now references R76 (inventory) / R75 (session authority); no other doc changes.

[thymikee]

The docs are clean at 6b7c189 and now reference the corrected R76 gate consistently. Ready for human review as the companion to #2354; merge that prerequisite first. Documentation checks pass.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-09-08 11:22 UTC