refactor(daemon): implement ADR 0019 through the adoption checkpoint

[thymikee]

Outcome

Implement ADR 0019 so daemon commands consume contracts-owned, request-bound platform runtimes while platform-specific mechanics live in private, implementation-lazy @agent-device/platform-* workspace packages.

This is the canonical implementation tracker and checkpoint record. Do not split later migration slices into worker issues until the pre-substrate baseline has fixed their denominator and dependencies.

Blocked by: #1697

Start condition: ADR 0019 is accepted and merged. Branch every implementation unit from the latest main.

Why now

HarmonyOS makes the shallow PlatformPlugin wrapper insufficient: the daemon no longer merely selects among Apple and Android paths; it owns an expanding platform-to-implementation map across six canonical families (apple, android, harmonyos, vega, linux, web). This resumes the platform-packaging direction deferred at the checkpoint in #1490 and replaces, command by command, the shallow consolidation completed in #972. It also supplies the platform boundary deferred by #1478.

Locked architecture

• Neutral inventory, runtime, operation, lifecycle, result, error, and durable-resource contracts live in @agent-device/contracts.
• Private @agent-device/platform-<family> packages contain only family-specific implementations. They do not import root src/**, daemon-private types, or sibling platform packages.
• src/platform-runtime.ts is the only concrete composition root. Registration is metadata-eager and implementation-lazy; heavy family code loads only for selected discovery or first bind.
• A descriptor has exactly one platform-execution shape: legacy adapter, inventory-backed adapter, or device-runtime-backed adapter. ADR 0003's daemon route and request-policy projection remain unchanged.
• Cutovers are one command across every existing local/provider support cell. Admission and execution migrate together; no dual route, success fallback, or daemon-side tag map remains.
• Process helpers are process-lived, bindings are request-lived, and only explicitly adopted neutral resource handles may become session-lived. Binding disposal must never terminate kept-hot helpers.
• Persisted durable descriptors are versioned, exact-owner, fenced, decoded from unknown, and fail closed. Recovery manifests are authoritative before any new persistence structure; diagnostics/session events are observation-only.
• The substrate and every command unit must be reviewed from a clean committed tree. Structural gates get planted red cases and no migration allowlists.

Checkpoint scope

• Record, before substrate work, the exact command inventory, independent legacy parity matrix, Apple leaf/provider denominator, validation commands and thresholds, cold-start/lazy-load probes, daemon platform import/branch/tag counts, and current R7/R10/R9 baselines.
• Land a behavior-neutral, independently revertible contracts/registry/gate substrate that routes no production descriptor on its own.
• Cut over devices completely through the inventory gateway across all six local family sources and every provider inventory source.
• Cut over logs completely through request-bound runtime contracts.
• Cut over network completely and prove the app-log durable-resource lifecycle: partial-start rollback, pending-transfer guard, adoption, normal finish(), forced idempotent cleanup, exact-owner reattachment/cleanup, fencing, and primary-error precedence.
• Record checkpoint evidence and change ADR 0019 Status to exactly one of continue, revise, or stop.

No further command migration may begin until Status records continue, and continue is legal only when every hard checkpoint item passes. Generic session teardown may call the migrated app-log handle's neutral cleanup contract without migrating close's legacy platform adapter; if another descriptor's platform adapter must change, amend the checkpoint scope before substrate work.

Acceptance evidence

• Zero old capability closures, platform branches, tags/maps, or concrete native imports remain for each migrated descriptor, with a strict net decrease in measured daemon platform coupling.
• Every canonical family/provider cell and applicable Apple leaf is implemented or explicitly unsupported with parity-preserving hints; every formerly supported cell has a contract scenario.
• packages/platform-* build and emit declarations independently, remain lazily evaluated, and have zero prohibited back-edges. Package edits select their contract/provider scenarios through check:affected.
• Runtime requirements narrow handler types without casts, non-null assertions, any, or sibling-operation leakage; planted violations prove the enforcement gates red.
• Request binding disposal preserves process helpers. Partial acquisition and the start-to-adoption cancellation gap cannot leak resources.
• SessionState changes satisfy the ADR's per-unit R7/R10 checklist; equality-pinned baselines do not grow, external daemon/types.ts importers do not grow, and cycle ceilings follow their existing growth-only policy.
• Provider-first behavior, Apple leaf restrictions, startup baselines, and available-command/unsupported-hint parity remain green.

Stop or revise at the checkpoint if satisfying the pilot requires a daemon-side tag map, dual/fallback route, eager native loading, a package back-edge, concrete platform values in daemon live state, an unclassifiable support cell, a second recovery truth, or increased daemon ownership/coupling.

Validation per implementation unit

• pnpm check:affected --run
• pnpm check for the broad substrate/architecture changes
• The descriptor-derived parity, contract, provider, leaf-coverage, lifecycle, lazy-load, and structural planted-red scenarios introduced by that unit

The merge request must state which physical module moves are complete and which legacy consumers intentionally remain in place; shared mechanics move only when all consumers can move or through a neutral injected lower-level port.

[thymikee]

Milestone 0 baseline — locked before substrate

Baseline commit: 44c298d7f (main, ADR 0019 merged). Counts exclude __tests__ and *.test.ts unless stated otherwise.

Authorized units and legacy owners

• devices: descriptor src/core/command-descriptor/registry.ts; unchanged ADR 0003 route session / inventory; handler src/daemon/handlers/session-inventory.ts; provider/local chooser src/core/dispatch-resolve.ts; local family branch owner src/core/platform-inventory.ts; duplicate legacy PlatformPlugin.discoverDevices declarations in src/core/interactors/register-builtins.ts, src/platforms/apple/plugin.ts, and src/platforms/vega/plugin.ts.
• logs: seven normalized plans (path, start, stop, doctor, mark, clear, clear --restart); route session / observability; owner src/daemon/handlers/session-observability.ts; mechanics under src/daemon/app-log*.ts; generic close cleanup in src/daemon/session-teardown.ts; daemon-start stale cleanup in src/daemon/server/daemon-runtime.ts.
• network: two action aliases × four include modes = eight parse/projection cells; route session / observability; handler session-observability.ts; parser src/daemon/network-log.ts; local recovery/orchestration in app-log.ts; web direct path in src/platforms/web/provider.ts.

No ADR Status amendment is required if close remains generic neutral cleanup and the shared discovery transition follows ADR 0019 §6 injection. If another handler must bind a runtime or select platform behavior, amend Status before the substrate lands.

devices discovery is also admission inventory for every legacy command. The command unit must move mechanics once and inject the composed inventory gateway into the legacy selector path; it must not duplicate discovery or migrate other handlers.

Frozen denominator

• Exactly six local family inventory sources: Apple (Apple core plus the macOS host fast path), Android, HarmonyOS, Vega, Linux, and static Web.
• Exactly three production provider inventory runtime IDs: browserstack, aws-device-farm, and limrun; each returns only its admitted leased device. Direct provider runtime leaf cells are each provider × {android, ios}. Deterministic fakes are contract adapters, not production sources.
• Narrow provider modes remain injected dependencies rather than runtime owners: app-log provider, Android ADB, Apple runner/tool, Vega tool, Linux tool, and Web provider.
• Apple coverage has eight required cells: iOS simulator, iOS CoreDevice physical, iOS XCTest physical, iPadOS, tvOS focus-only, macOS desktop, visionOS, and watchOS discovery-absence/unsupported sentinel.
• Current logs: all listed working Apple fixture cells are supported except iOS XCTest; preserve the CoreDevice-only hint. Current network: every listed Apple fixture, including iOS XCTest, is admitted.
• Non-Apple local rows: Android emulator/device supports both; HarmonyOS emulator/device supports logs but not network; Vega VVD supports neither; Linux device supports neither; Web device supports network but not logs.
• Existing independent parity evidence includes a 72-row synthetic family × kind × target matrix, 83 capability sample rows, and 95 AppleOS sample rows. Six generic family fixtures are insufficient.

Provider parity decision

• BrowserStack/AWS WebDriver logs is frozen as unsupported, matching the provider's existing explicit capability declaration. The current daemon's attempt to run local tools on those devices is not retained as a provider fallback.
• WebDriver network has no real provider operation today; preserve the current empty-success result shape through an explicit provider runtime operation for this migration. Changing that semantic result is a separate behavior decision.
• Limrun exposes readLogs through its device session and should implement the real provider facet. It must never fall through to local tools.

Legacy parity oracles

• Registry/route: command-descriptor parity and daemon-command-registry tests.
• Inventory: core platform-inventory tests, platform-plugin parity, session inventory Apple/Harmony tests, family device suites, provider-device-runtimes tests, and provider scenario runtime tests.
• Support/hints: capability-plugin routing parity and AppleOS capability-table parity.
• Logs/network: app-log plugin routing parity, session logs/network, app-log/app-log-android, network-log, web provider, and provider scenarios. iOS live coverage currently owns devices and logs; network remains command-contract evidence.

Numeric coupling baseline

• Direct src/daemon/** -> src/platforms/** imports: 141 = 90 static value + 21 static type + 30 dynamic. By family: Apple 57, Android 56, HarmonyOS 7, Vega 4, Linux 3, Web 10, shared platform modules 4.
• Repro: rg -n "(?:from\\s+|import\\()(['\"])(?:\\.\\./)+platforms/" src/daemon -g '*.ts' -g '!**/__tests__/**' -g '!*.test.ts' | wc -l.
• Daemon target-family decision lines: 161, counting known platform literal comparisons and isApplePlatform|isIosFamily|isMacOs|isTvOsDevice, excluding comment lines.
• Checkpoint-owned logs/network baseline: 11 concrete daemon-to-platform imports and 14 explicit platform decision lines. Both must be zero for migrated command-owned mechanics.
• Inventory has 12 duplicated lazy import sites: six in core/platform-inventory.ts and six equivalent PlatformPlugin.discoverDevices sites. The cutover must leave one package-owned source per family and no legacy discovery facet.
• Legacy behavior-indirection families: 4 (app-log tag, perf sampler tag, recording tag, provider-key list). The checkpoint removes app-log, leaving at most three globally.

Ratchets

• R7/R10: 23 writer-owned SessionState fields / 29 owner claims; 11 store-owned fields; 34 total classified. appLog and appLogFailure are store-owned today. Keep replacement updates through whole-record SessionStore.set so the writer/claim counts stay 23/29 or decrease.
• R9 largest type cycle: 47 = root 3, client 1, commands 14, core 10, daemon-server 17, platforms 2. Total and per-zone ceilings must not grow.
• External production daemon/types.ts importers: exactly two (src/client/client-normalizers.ts, src/remote/daemon-artifacts.ts).
• Every proof is rerun from a clean committed tree; untracked package files do not count as layering evidence.

Laziness and size thresholds

• Hard structural probe: importing composition evaluates zero heavy family implementations; selected discovery/bind evaluates only its family; unrelated-family evaluation count remains zero; helper managers constructed before first use remains zero. Plant an eager import and require the probe to name it.
• Existing Size baseline on main: raw JS 2.04 MB, gzip 659.6 kB, npm tarball 797.0 kB, unpacked 2.78 MB; seven-run medians --version 21.4 ms and --help 52.3 ms. Compare base/head on the same runner rather than treating these host-specific absolutes as portable.
• Add a 15-run median import-only probe for built dist/src/internal/daemon.js.
• Fail when --version, --help, or daemon import regress by more than max(5 ms, 10%) against base; fail bundle/package metrics above +3%; reject emitted chunks that duplicate one platform implementation. Threshold changes require reviewed evidence.

Stack and serialization points

1. Substrate: contracts, selected-operation projection, metadata registry, src/platform-runtime.ts, six metadata-only package façades, layering/laziness/narrowing/affected-selection gates. It routes no descriptor and creates no fake behavior loaders.
2. devices: six honest package inventory implementations, provider inventory adapters, shared legacy-selector injection, descriptor/handler cutover, removal of discoverDevices and parity artifact.
3. logs: package app-log implementations, live handle/descriptor/codec/manifest/fence, SessionState neutral resource, handler/descriptor cutover, generic teardown.
4. network: normalized network operation/parser ownership, platform recoveries, explicit provider operations, handler/descriptor cutover.
5. Checkpoint: clean committed rerun, before/after counts, ADR Status exactly continue, revise, or stop.

Package-local adapters may be developed in parallel after contracts freeze. One integration owner serializes package.json/lockfile, contract façades, src/platform-runtime.ts, descriptor registry, request scope, and session-observability.ts.

[thymikee]

Adversarial preflight resolution

I ran Claude Code 2.1.220 (claude -p, Opus/high, read-only) against ADR 0019, the locked baseline, and the live implementation routes before committing substrate code. It agreed with the metadata-only registry refinement but found four load-bearing traps. They are resolved as follows before the bottom PR may land:

1. Substrate and devices become one bottom PR. A metadata-only composition root is otherwise unreachable to fallow and cannot honestly prove implementation laziness. The bottom review unit introduces the contracts/packages/gates and completes devices; it is independently coherent and revertible.
2. One shared lower-level DeviceInventoryGateway replaces all family branches. The devices unit injects it into the existing legacy target-selection consumers (resolveTargetDevice, doctor device discovery, and replay test sharding) without migrating those commands' platform adapters. There is no second discovery implementation. ADR Status will name this coexistence route before the PR lands.
3. Provider inventory remains authoritative override, not union. When a request-scoped provider inventory exists, its admitted leased device replaces local discovery exactly as today. “Composed” means the gateway selects the authoritative source; it does not concatenate provider and local inventories.
4. logs includes daemon-start exact-owner recovery. The current unconditional PID reaper cannot remain. The logs unit owns its replacement with fenced descriptor recovery and must demonstrate at least one genuinely reattachable cell plus explicit cleanup-only/unreattachable cells. If that cannot be achieved, the checkpoint outcome is revise; it will not be waived as N/A.
5. R7/R10 growth is not authorized. appLog/appLogFailure will be replaced, not supplemented, by immutable neutral resource state installed through an atomic whole-SessionState replacement owned by SessionStore; aliased nested mutation is forbidden. The logs unit adds an ownership gate for that transition and must keep the 23/29 equality pins unchanged or lower.

Claude also found structural-gate defects in the work-in-progress substrate: the git ls-files untracked-file hole, a vacuous planted-red assertion, comment/string false positives in the probe matcher, an exact import allowlist that would reject honest later capabilities, missing sibling-workspace restrictions, a re-enumerated six-family path regex, and missing new projects from the root typecheck. These are now required fixes in the bottom PR, each with focused red/green evidence.

Per-command facts remain distinct: Web provider network support is preserved through an explicit runtime operation rather than the current Android-default fallthrough, while provider logs remains explicitly unsupported where its provider capability already says so.

[thymikee]

Devices stack entry is ready: #1699

This lands the behavior-neutral substrate plus the complete devices inventory cutover: six implementation-lazy platform packages, provider-first composed inventory, removal of legacy discovery routes, command-atomicity/layering gates, and independent parity coverage.

Final local boundary: pnpm check:affected --run passed; 402/402 test files and 3,688/3,688 tests passed, changed-line coverage 79.42%, Node integration 53 passed / 8 skipped, with layering, fallow, package, build, integration-progress, and replay-compat green. Claude Opus adversarial review and focused Sonnet closure found no remaining P0/P1 issues.

The gate also exposed and fixed a pre-existing hermeticity leak: Node integration daemons were scanning the user-global device-claims directory. The wrapper now owns an isolated claims directory, with a planted lifecycle test.

[thymikee]

Milestone update: the second stack layer is ready as #1701, based on #1699.

• refactor: extract platform device inventory runtime #1699 extracts the six-family inventory/runtime substrate and devices cutover.
• refactor: extract platform log runtime #1701 migrates all seven logs plans to typed platform runtimes across the six local families plus Limrun, with exact-owner durable descriptors, fenced recovery, request-scoped binding, fail-closed provider behavior, and deletion of the daemon tag/provider/platform branches.

Validation on the committed logs branch:

• pnpm check:affected --run: all runnable checks passed
• 6,316 tests passed in the affected coverage run
• changed-line coverage: 87.78%
• committed-state layering: 112/112 structural tests plus repository scan green
• package tarball, declarations, clean-install imports, provider scenarios, and replay compatibility green
• final Claude -p adversarial review: no P0/P1 blockers

The final gate initially exposed a real Android fixture regression: the scripted adb logcat child had accidentally replaced every provider subprocess, including snapshot-helper instrumentation. A planted V8 run failed three replay tests at their capture deadline; restricting the real child to logcat restored the legacy subprocess fixture and the exact run passed 14/14 without increasing any timeout.

Next stack layer: the complete network descriptor cutover, followed by the ADR 0019 checkpoint evidence/status decision.

[thymikee]

Network extraction is ready as stack PR 3: #1702 (base: #1701).

Evidence from the final committed tree:

• all 8 network projection cells route through one networkDump runtime operation
• Apple, Android, Web transport, Limrun, WebDriver, HarmonyOS, Vega, and Linux cells are explicitly classified
• provider owners fail closed; no provider-to-local execution fallback
• four legacy daemon network parser/recovery modules are deleted
• R15 planted structural gates are green
• pnpm check:affected --run passed: 3,966 tests, 87.67% changed-line coverage, package/layering/fallow/integration-progress/replay-compat green

Next stack unit is the ADR 0019 decision checkpoint; no broader command migration starts before it records continue, revise, or stop.