docs(android): investigate ADB transport addressing apart from the command payload (#2617)

[thymikee]

What this is

The investigation deliverable for #2617: a route trace of ADB transport addressing versus the
device-command payload, measured against origin/main 2cafab3ad0, plus a continue/stop
recommendation and an implementation cut set. Docs-only — 226 lines in one new file.

Per the issue, this is explicitly not a completed implementation, and the prototype is disposable
scaffolding kept off this branch.

Measured answer

Separating typed addressing from the payload is worth doing, with a smaller cut than the spike:

• 11 independently authored addressing/refusal decisions today; 5 collapse into one 241-line module,
  and 2 more are ready to follow once addressing has a shared home.
• Production cost outside that module: +41 lines. src/platform-runtime-android-adb-host.ts
  nets −53. One signature widening makes the adb payload readonly across the platform (96 type
  errors in 24 files, exactly 1 in production source).
• Payload identity survives on the device, managed and host-port routes; it is lost exactly where
  addressing arrives inside flat argv — provider forwarding and the nine host.commands.run /
  runCmdBackground adb sites, which also copy argv ([...request.args]).
• Enforcement did not weaken, but the spike's first guard disagreed with the shared rule on nine
  selector cases (host globals and wait-for-*-prefixed forbidden commands). The existing 21-selector
  loop in src/platform-runtime-android-adb-host.test.ts is what caught it; it is the oracle and
  should become a golden table under contracts/fixtures/.
• Recommendation: continue, cut set ordered in the doc, starting with where addressing should live
  (a tiny shared package vs. a provider-limrun → platform-android edge), because the spike's
  structural duplicate in provider-limrun is not shippable.

Honest limits

• fix(device-shell): one typed device-shell boundary for adb, exec-out, and hdc #2611 is still open, so every device-shell relay claim describes a branch shape, not merged
  transport reality (packages/kernel/src/device-shell.ts does not exist on main).
• No device-backed verification: this is docs-only. exec-out binary results and background logcat
  spawn stay on the device lane named in the doc.
• Ambient routes keep argv authority, so target is advisory there. The doc flags that rawArgv is a
  heuristic and a production shape needs explicit caller-vs-lease provenance.
• One deliberate residual exception: -P <not-a-number> under a lease now refuses where main
  silently replaced it.
• Adversarial review caught two ambient behavior changes in the spike (a caller-typed -P starting to
  lower ANDROID_ADB_SERVER_*, and the non-numeric case above). Both were closed in 5dc8ced575 and
  the corrected claims now match the code.

Side findings, unrelated to this change

• pnpm typecheck is broken on main: snapshot-helper-install.test.ts:29 still sets installArgs,
  dropped from the manifest type by refactor(android): drop the snapshot helper manifest installArgs #2618. Because the script chains with &&, root and
  examples/sdk typecheck never run. One-line fixture fix, separate change.
• pnpm check:production-exports exits 0 only because unused-exports is warn-level; it currently
  reports 68 unused exports across 40 files.

Validation

• pnpm check:affected --run on 2a5b67c124: passes (docs-only, no checks selected).
• Prototype lanes at spike/2617-typed-adb-addressing 3280a0ddbc: 118 files / 846 tests green, plus
  the 12-file / 59-test released-surface and provider-routing lane, root tsc 0 errors, pnpm lint,
  pnpm check:layering green. Exact commands are in the doc.

Prototype branch for inspection (do not merge): spike/2617-typed-adb-addressing.

Delivers the #2617 investigation deliverable; leaves the continue/stop decision to the maintainers.

[thymikee]

Reviewed at 2a5b67c. This is a docs-only investigation, and the analysis and the continue/stop call look sound. CI is green, and no runtime validation applies.

One count does not match. adb-transport-addressing-experiment.md#L161 says Finding 4 covers nine sites but lists eight, the Numbers table says "eight route-level -s stitches", and cut-set step 4 says nine commands.run calls. The ninth -s site in code is packages/platform-android/src/emulator-lifecycle.ts:157, which calls runAndroidHostAdb directly and does not go through host.commands.run. Can you make the count match the list, either eight everywhere or nine with a note that emulator-lifecycle.ts:157 already goes through runAndroidHostAdb? Otherwise whoever implements step 4 may look for a commands.run call that does not exist, or miss that file.

The test-lane counts and line deltas for the spike branch are author-reported.

[thymikee]

Superseded by #2632, which completes the migration. The investigation write-up was experiment scaffolding, not a document this repo should carry, so both this branch and spike/2617-typed-adb-addressing are being deleted; the findings that matter are in #2632.

[github-actions]

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