refactor: move W6 platform families behind package facades

[thymikee]

Summary

Implements W6 of #2082 for HarmonyOS, Linux, Vega, and Web:

• moves each family implementation and colocated tests from src/platforms into its private platform package;
• exposes named root facades through each package exports map and repoints runtime, interactor, provider, snapshot, daemon, and integration consumers;
• routes moved filesystem and process authority through host-kit, including a separate host-file entry point so existing host-kit/file consumers retain their eager-load baseline;
• completes the W2 desktop snapshot composition seam by injecting Linux/macOS surface loaders into the neutral snapshot host;
• keeps R13 narrow: deferred/type-only platform-package edges are allowed only from the explicit platform-runtime host watchlist, not from every root file;
• adds fail-closed W6 root-shape, R11, eager-closure, and layering enforcement.

Per-family adversarial review:

• HarmonyOS — checked HDC, lifecycle, input, screenshot, snapshot, settings, perf, doctor, inventory, runtime, package closure, and named consumer routes; no stale implementation path remains.
• Linux — checked AT-SPI, input, clipboard, screenshot, snapshot, surface, provider, desktop snapshot injection, package dependencies, and provider-backed scenarios.
• Vega — checked plugin, interactor, toolchain, input, provider, doctor, and lifecycle routes; the old plugin entrypoint is absorbed into the package facade with no compatibility plugin.
• Web — checked managed-browser setup, provider, lifecycle, process, network, audio, snapshot, recording, request-scoped provider behavior, teardown, and test-fixture ownership.
• Combined — checked exports and package closure, lazy facade budgets, old W6 deletion, root/deep import policy, host-file eager closure, snapshot composition, CI path ownership, and W4/W5/W7 scope boundaries.

No W4, W5, or W7 implementation is included. The W6 scope is explicitly authorized by the current implementation task; #2082 remains the coordination umbrella. Refs #2082

Validation

• Planted red was observed before the fixes: the pre-move W6 root-shape scan reported 65 retired-family violations; the old platform-root policy case was 25 passing / 1 failing; exact-head Coverage showed host-kit/file 12→13, provision-kit/install-source 25→26, src/cli.ts 381→382, and session-teardown 68→69.
• Green after the fix: eager-closure budget suite 382/382, focused W6 family/snapshot tests 41/41, pnpm typecheck, pnpm check:layering (159 tests plus the global scan), build, package clean-install closure, and Node integration smoke (90 passed / 9 live tests skipped).
• The final pnpm check:affected --run selected 56 checks and reached the related Vitest lane. 499 files / 3,971 tests passed; two unrelated 5-second tests timed out only under the 501-file concurrent suite. Both passed in isolation: gesture-admission parity 4/4 and scripted-provider iOS lifecycle 3/3. No local check result is being overstated as a full-gate pass.
• ADR-0019 §8 size accounting (source-tree relocation, exact bytes): 37 W6 production files removed from root src/platforms = 154,071 B; 36 relocated production files plus four package facades = 171,259 B in the platform-package targets; source-tree delta = +17,188 B. The follow-up host-authority facade adds 430 B as a separate package-only seam and does not duplicate the implementation. Causes are the four named lazy facades (17,006 B), 828 B of moved-source normalization, and the explicit W2/host-file seam; the 646 B superseded Vega plugin is deleted. The rejected smaller designs were retaining host-file exports in host-kit/file (the measured eager regression) and using a blanket R13 dynamic/type-only allowance (the structural escape); neither is present.
• The exact-head GitHub Size report measures +9.1 kB npm-unpacked / +9.1 kB raw JS / +4.7 kB gzip / +2.9 kB tarball; no eager budget was raised.
• The previous exact-head GitHub checks at b5dd30fdd2 were green, including Coverage, Repo Guards, Integration Tests, Bundle Size, and Android/iOS/macOS/Linux smoke. After the conflict-resolution rebase onto current main, fresh checks for 4eec054598 are running; GitHub remains authoritative for native, device, provider, and live-web lanes. Exact-head live HarmonyOS/Vega/Web provider evidence is not available locally and is not claimed.
• Family landing remains sequenced by the maintainer: land/rebase refactor: move W6 platform families behind package facades #2116 first, then rebase refactor: move Android family behind package exports #2117, then refactor: move Apple platform family into package #2118 against both and validate the combined family tip. This PR does not mutate sibling W4/W5 work or claim combined-family readiness; no merge was performed.

Evidence status: addressed fixes are pushed and the PR remains open for review; the pre-rebase exact-head checks were green and the rebased exact-head run is pending, while combined-family and live provider/device proof remain outstanding. Do not merge from local evidence alone.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-08-28 10:47 UTC

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	2.49 MB	2.50 MB	+9.1 kB
JS gzip	836.1 kB	840.8 kB	+4.7 kB
npm tarball	959.6 kB	962.6 kB	+2.9 kB
npm unpacked	3.32 MB	3.33 MB	+9.1 kB

npm unpacked components

Component	Base	Current	Diff
JS / dist source	2.64 MB	2.65 MB	+9.1 kB
Apple runner source/project	581.1 kB	581.1 kB	0 B
macOS helper source	54.8 kB	54.8 kB	0 B
Android helper artifacts	0 B	0 B	0 B
Other package files	45.6 kB	45.6 kB	0 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	31.6 ms	31.1 ms	-0.5 ms
CLI --help	83.8 ms	83.0 ms	-0.8 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/src6.js	+47.5 kB	+14.1 kB
dist/src/platform-runtime-operation-host.js	+54 B	+18 B
dist/src/internal/daemon.js	-6 B	+6 B
dist/src/runner-client.js	0 B	+1 B
dist/src/perf-runtime-plan.js	0 B	+1 B

Top changed packed files

Packed file	Base	Current	Diff
dist/src/src6.js	0 B	47.5 kB	+47.5 kB
dist/src/src2.js	47.5 kB	2.9 kB	-44.6 kB
dist/src/src7.js	0 B	25.4 kB	+25.4 kB
dist/src/src3.js	25.4 kB	916 B	-24.5 kB
dist/src/src8.js	0 B	23.2 kB	+23.2 kB
dist/src/src4.js	23.2 kB	2.4 kB	-20.9 kB
dist/src/perf3.js	1.4 kB	20.9 kB	+19.4 kB
dist/src/perf2.js	20.9 kB	4.8 kB	-16.0 kB
dist/src/interactor.js	13.3 kB	2.7 kB	-10.6 kB
dist/src/interactor2.js	2.7 kB	13.3 kB	+10.6 kB

[thymikee]

Re-reviewed 1ffd3bb8. Not ready.

P1: exact-head Coverage proves four real eager-load regressions: host-kit/file 12→13, provision-kit/install-source 25→26, cli 381→382, and session-teardown 68→69. The blanket exports from packages/host-kit/src/file.ts eagerly load the new host-file module for every existing consumer; split or narrow that host-authority surface rather than raising pins.

P1 architecture: #2082 assigns src/snapshot/snapshot-desktop-surface.ts dispatch inversion to prerequisite W2, but this PR retains the root device.platform branch and changes it to import @agent-device/platform-linux, then broadens R13 to permit all dynamic/type-only concrete-package edges. Complete the W2 composition/injection seam instead of encoding the escape.

Scope: #2082’s maintainer triage says the umbrella is not executable and each wave needs a child issue; none is linked, so W6 needs that child or explicit authorization.

Size CI is +9.1 kB npm unpacked; add ADR 0019 §8 root-bytes-removed/package-bytes-added accounting, each growth cause, and the rejected smaller design. iOS Smoke’s zero-readable-capture wait looks unrelated but needs a green rerun; exact-head live HarmonyOS/Vega/Web evidence is also still absent.

[thymikee]

Addressed in b5dd30fdd2:

• Split @agent-device/host-kit/host-file from host-kit/file; the original four eager-closure pins are back at 12/25/381/68, with a measured 2-module budget for the new facade.
• Completed the W2 snapshot seam: snapshot-desktop-surface.ts is loader-injected and neutral; the macOS loader is kept behind the lazy operation-host seam. R13 now permits deferred/type-only concrete-package edges only in the explicit platform-runtime host watchlist.
• Scope remains W6 only. The implementation was explicitly authorized by the current task request; no W4/W5/W7 or issue edit was added.
• Added ADR-0019 §8 source accounting and rejected-design rationale to the PR description: 154,071 B root W6 production source removed vs 171,259 B in package targets, +17,188 B source delta; the 430 B host-file facade is separately called out.
• Local structural/build/package checks are green. The full affected run reached 499/501 related files and hit two unrelated 5-second suite-load timeouts; both tests pass in isolation (4/4 and 3/3). The previous iOS Smoke readableCaptures: 0 / wait_capture_stalled failure was runner/device evidence; the new commit is triggering a fresh authoritative run.
• Exact-head HarmonyOS/Vega/Web provider/device evidence is still not available locally, so it is not claimed. No merge performed.

[thymikee]

Reviewed b5dd30f as the W6 foundation for the #2082 W4-W6 family. Standalone code review and all exact-head checks are clean after the host-file/snapshot-seam fixes, but I am not marking it ready independently because the current sibling heads are not cohesively landable.

Required family landing plan:

1. Land/rebase refactor: move W6 platform families behind package facades #2116 first as the shared foundation.
2. Rebase refactor: move Android family behind package exports #2117 onto it.
3. Rebase refactor: move Apple platform family into package #2118 last onto both, preserving the injected Apple/Linux desktop snapshot loaders from refactor: move W6 platform families behind package facades #2116 and reusing the focused host-file authority rather than unioning refactor: move Apple platform family into package #2118 competing environment/filesystem facades.
4. Validate the combined family tip before readiness.

Exact live HarmonyOS/Vega/Web provider evidence is still unclaimed, so that remains required family validation. No code finding is outstanding on this head itself; this is a family sequencing/evidence blocker.

[thymikee]

Thanks — acknowledged.

There is no outstanding code finding on b5dd30fdd2. The exact-head #2116 checks are now green, including Coverage, Repo Guards, Integration Tests, Bundle Size, and Android/iOS/macOS/Linux smoke.

I updated the PR description with the family landing/evidence state. I’m keeping this task narrowly on W6: I will not mutate #2117/#2118 or absorb their W4/W5 code. The required order is therefore #2116 first, then #2117 rebased onto it, then #2118 rebased onto both, followed by combined-family validation by the owning work.

Exact-head live HarmonyOS/Vega/Web provider evidence remains unclaimed and is a family readiness blocker. No merge was performed.

[thymikee]

Update: GitHub reported this PR as conflicting with main, so I rebased the W6 branch onto the current base and pushed 4eec054598 with --force-with-lease.

The post-rebase local pnpm check:affected --run completed with all runnable checks passing, including 501 related test files / 3,973 tests, layering, build, package closure, and integration checks. The PR is mergeable again, and a fresh exact-head GitHub run is in progress. I corrected the validation section to distinguish the pre-rebase green run from the fresh run.

No W4/W5 sibling work was changed, no live HarmonyOS/Vega/Web evidence is being claimed, and no merge was performed.

[thymikee]

Re-reviewed exact head 4eec054: it is a pure rebase of previously reviewed b5dd30f with no logical code delta; completed checks are green and one smoke lane remains pending. No code finding on this head, but do not mark independently ready: current main is two commits ahead, #2117 must be truly restacked onto this published head, #2118 remains conflicting and lands last, and combined-family plus live HarmonyOS/Vega/Web evidence is still required.