refactor(platforms): sink the shared src/platforms root files into their substrate homes

[thymikee]

#2082 W3, stacked on #2090. Retires the shared files sitting directly under src/platforms, so the family trees can move behind their exports maps.

What owns what

• @agent-device/provision-kit (new, above capture-kit) owns the provisioning domain — everything that gets a device and app ready to run: install-artifact acquisition (local paths, archives, guarded network downloads), host toolchain probing, device boot-failure classification, and app-resolution caching. It depends on host-kit's ports, never on capture-kit.
• @agent-device/kernel takes the pure numeric helpers (roundPercent, roundOneDecimal).
• @agent-device/contracts keeps vocabulary only.

What deliberately did not move

Settings parsing, command-attempt rendering, and the unsupported-interactor factory are cross-family but not one domain, so pooling them in a substrate package would have recreated platform-common under a new name. They stay with their owners instead:

• src/platforms/android/settings-parsing.ts and src/platforms/apple/core/settings-parsing.ts each own their appearance/state parsing and attempt summarizing.
• src/core/interactors/unsupported-interactor.ts serves the web interactor, with a local copy in src/platforms/vega/.

Each of those now has an owning test over its accepted spellings, its rejections, and the whole interactor surface.

Enforcement

• platforms-root-shape rejects any new shared file or directory appearing directly under src/platforms.
• provision-kit's direction gates are planted red in both directions: no platform package may be imported by it, and capture-kit may not import it.
• provision-kit's exported subpaths and dependency set are pinned in package-boundaries.test.ts; each carries an exact eager-closure row.

Two of those rows drop in this PR rather than leaving headroom, because #2088's capability ports shrank them: install-artifact-archive-context 20 → 10 and toolchain-probe 15 → 8.

🤖 Generated with Claude Code

https://claude.ai/code/session_018VngeKZH6zBuJzNBk5YzUH

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://callstack.github.io/agent-device/pr-preview/pr-2100/
Built to branch gh-pages at 2026-08-27 19:48 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	2.48 MB	2.48 MB	+553 B
JS gzip	834.2 kB	834.0 kB	-282 B
npm tarball	957.4 kB	957.5 kB	+90 B
npm unpacked	3.32 MB	3.32 MB	+639 B

npm unpacked components

Component	Base	Current	Diff
JS / dist source	2.64 MB	2.64 MB	+566 B
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.3 kB	45.4 kB	+73 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	29.0 ms	28.5 ms	-0.5 ms
CLI --help	82.7 ms	81.8 ms	-0.9 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/android.js	+419 B	+106 B

Top changed packed files

Packed file	Base	Current	Diff
dist/src/unsupported-interactor.js	815 B	0 B	-815 B
dist/src/interactor2.js	2.0 kB	2.7 kB	+718 B
dist/src/web.js	1.2 kB	1.9 kB	+718 B
dist/src/app-resolution.js	6.3 kB	6.8 kB	+490 B
dist/src/android.js	26.0 kB	26.4 kB	+419 B
dist/src/setting-state.js	347 B	0 B	-347 B
dist/src/perf-frame.js	7.3 kB	7.0 kB	-296 B
dist/src/appearance.js	264 B	0 B	-264 B
dist/src/numeric.js	0 B	84 B	+84 B
dist/src/perf-utils.js	84 B	0 B	-84 B

[thymikee]

[P1] Keep capture-kit an owning domain, not platform-common. ADR-0019 explicitly limits it to durable-capture mechanics, but this head publishes unrelated app-resolution, boot, command-attempt, install-source/network, perf, and toolchain utilities from it. R18’s hint does not supersede that decision. Split the shared files behind cohesive domain owners/interfaces, or explicitly amend and enforce the architecture before W4–W6 cement this dependency.

[P2] Also gate W3’s claimed closure: current export/budget tests do not reject a new direct production file under src/platforms; add a planted-red root-shape invariant.

Not ready, and still stacked on open #2090 with failing base Coverage; Android/iOS checks on this head are pending.

[thymikee]

Both points addressed on dde8f75, taking the split path rather than an ADR amendment:

P1 — capture-kit is back to its ADR-0019 durable-capture scope (36 exports; undici/ipaddr.js leave its dependencies). The shared files redistribute onto cohesive owners: the pure classification/vocabulary (boot-diagnostics beside its existing boot-failure types, app-resolution-cache, command-attempts, perf-utils) joins contracts, all R18-clean; the provisioning mechanics (the install-source family with its guarded network transport, install-artifact-archive-context, toolchain-probe) form the new private @agent-device/provision-kit package at kernel < contracts < capture-kit < provision-kit < platform/provider/daemon, pinned in the boundary test at exactly five subpaths with install-source-archive/install-source-download package-internal. W4–W6 now cement dependencies on domain owners, not a grab-bag.

P2 — a platforms-root-shape rule is wired into check:layering's runtime gate: any tracked file under src/platforms/ outside the six family directories and __tests__ (a new direct file or a new sibling directory alike) is a violation. Planted red for real — a committed src/platforms/planted-root-file.ts fails the live gate with this rule's message — plus unit planted-red cases beside the policy tests; the clean tree passes.

Validation on the new head: layering (152/152, R11 now 18 packages / 201 subpaths), boundary pins, budgets (411, rows re-homed and measured), depgraph/mutation/gate-manifest suites, fallow clean vs both W2 and main, pnpm build + packed-tarball closure (publint/attw, dependency closure with the relocated deps, all 13 entry points, CLI run), and 1,004 targeted tests. On the stacked-base note: #2090's Coverage failure is a single flaky provider-scenario test with evidence posted there; iOS/Android smoke on this head were green before this push and rerun now.

---

Generated by Claude Code

[thymikee]

The original capture-kit/root-shape findings are improved, but this head is still not ready.

• P1 — ADR-0019’s contracts boundary is still violated. Contracts is limited to pure vocabulary and plan models. app-resolution-cache.ts owns mutable Date.now/TTL/invalidation lifecycle, boot-diagnostics.ts parses messages and selects operational behavior/hints, command-attempts.ts truncates/render command output, and unsupported-interactor.ts constructs throwing runtime behavior; the appearance/setting parsers and perf rounding are executable policy too. R18 merely not detecting these mechanics does not make them vocabulary. Keep the types/reason unions in contracts and move each implementation to its actual owner instead of solving platform-common by smearing behavior below the seam.
• P1 — the claimed provision-kit dependency direction is not enforced and is contradicted by R13. The PR says capture-kit < provision-kit < platform/..., but platform-package-policy.ts currently allows platform packages to import only capture-kit/contracts/kernel/xml, so W4-W6 platform imports from provision-kit will fail. Encode the intended platform→provision edge and reject reverse/sibling edges with planted-red tests now. Also either make host toolchain readiness an explicit, coherent part of the provisioning domain or give generic toolchain-probe its focused owner.

Remove the remaining touched W3/history/control-flow comments and unused sync tmp helper under current main’s comment rule. Exact-head CI is still in progress, and stacked base #2090 remains open with confirmed review/CI blockers, so no readiness label.

[thymikee]

Both P1s addressed on the new head (stacked on the reworked #2088/#2090, which carry the ADR-0019 substrate amendment and the capture-kit snapshot-behavior move):

Contracts is vocabulary-only now. The executable policy left for its owners: app-resolution-cache (TTL lifecycle) and boot-diagnostics (classification + hint selection) join @agent-device/provision-kit — the amendment now defines the provisioning domain as everything that gets a device and app ready to run: artifact acquisition, host toolchain readiness, boot-failure classification, app-resolution caching, which also answers the toolchain-probe coherence question. The appearance/setting-state parsers, summarizeCommandAttemptFailures, and createUnsupportedInteractor join capture-kit; perf rounding becomes the pure @agent-device/kernel/numeric primitive beside collections. The reason unions stay in contracts (boot-failure untouched; provision-kit re-exports its guard beside the classifier).

The provision-kit direction is enforced, both ways, planted red. platform-package-policy names provision-kit in the platform allow-list, with a passing planted case (platform-apple importing provision-kit/install-source) and a failing one (a provision-kit file importing @agent-device/platform-android trips the composition rule). The boundary suite pins provisionKitPackage.workspaceDependencies to exactly capture-kit/contracts/kernel, so a reverse capture-kit→provision-kit or sibling edge cannot even be declared; capture-kit's own dependency pin already excludes provision-kit from the other side.

Also removed: the unused sync tmp helper in the provision-kit fixture and the touched W3/history comments (budgets section markers, the root-shape docblock narration, the gate message's issue reference).

Validated: layering 154/154 (including the two new planted-red cases), boundary pins, budgets 413 with re-homed measured rows, fallow clean vs both W2 and main, typecheck/lint/format, depgraph + mutation model suites, 1,481 targeted tests, and pnpm build + the packed-tarball closure. The Coverage failure on the previous head dde8f75 was superseded by this push; if it recurs on this head I'll treat it as this PR's.

---

Generated by Claude Code

[thymikee]

The contracts and provision-kit direction findings are fixed, but this head is still not ready.

• P1 — capture-kit remains a generic platform-common bucket. ADR-0019 limits capture-kit to host-process and durable-capture mechanics. The settings parsers, generic command-attempt rendering, and throwing unsupported-interactor factory are not capture behavior; their consumers are Android/Apple settings and Web/Vega interaction. Move them to cohesive settings/interaction/family owners rather than relocating the ownership smear below the platform seam.
• Remove the remaining touched #2082 W3 history in package-boundaries.test.ts and the lifecycle/control-flow narration in tmp-dir.fixtures.ts; the assertions, helper name, and tool directive already express those contracts.

The platform→provision-kit dependency direction and reverse-edge gates are now coherent and planted-red. Exact-head iOS smoke is still pending, and this remains stacked on open #2090, whose current Android and iOS smokes fail. No readiness label.

[thymikee]

The comment trims are pushed (baf9c86: the pin narration and the fixture lifecycle block are gone).

On the remaining P1 — the three helpers have now been rejected in contracts and in capture-kit, and every candidate left has a real cost, so before pushing a third relocation I want to name the design I'd implement and the trade each alternative carries:

1. Hoist above the seam with typed interfaces (my recommendation, but the widest change). Argument admission parses once at the root settings/interaction layer: the settings runtime passes enabled: boolean / AppearanceAction (type stays in contracts) down instead of raw strings, and command-attempt summarizing moves to the root error-presentation path. This retires all three helpers below the seam entirely — but it changes the settings runtime/interactor signatures in contracts and touches every family's settings implementation, plus their W4/W5 interfaces. createUnsupportedInteractor splits: src/core/interactors/unsupported.ts for the root web interactor, and Vega receives the base through its plugin registration (the same injection shape as the accepted createAndroidAppStateReader), which means widening the plugin interface.

2. Family owners. Each consumer family keeps a private copy (android + apple settings each own their 6-line state parse and attempt summary; Vega owns a local unsupported stub; web's stays in root core). Smallest diff and matches "family owners" literally — the cost is two near-identical 6-line parse bodies, which is exactly the shape the clone gate flags, so it ships with attributed duplication suppressions until W4/W5 lets each family's copy drift.

3. Kernel primitives. parseSettingState/parseAppearanceAction as argument-vocabulary validation and CommandAttemptFailure+summarize as error-details shaping beside kernel's own errors/keyed-lock/collections — pure, dependency-free, one implementation. Doesn't cover createUnsupportedInteractor (interaction behavior), which would still need option 1's split or 2's copies.

Given the round-trips on these exact files I'd rather burn one reply than a fourth speculative push: which shape should W3 carry? If no preference, I'll implement option 1 in full.

---

Generated by Claude Code

[thymikee]

Exact-head iOS smoke on 15ec144 failed in the gesture-pan-duration.ad replay, and the log shows it is the load flake plus a retry artifact, not this diff's: attempt-1 hit the known 60s pan timeout, then attempt-2 failed at step 1 with ios device … is owned by session "…:1-gesture-pan-duration:attempt-1" — the retry could not claim the simulator because the timed-out attempt's session still held the lease. Nothing in this PR touches gesture, replay retry, or device-claim code (it moves provisioning/settings/numeric modules), and the identical lane ran green on #2088's d6442d7 at 15:58 under the same runner image. I have no job-rerun permission from this session; the next push (the pending helper-placement decision) reruns it. The stale-lease-blocks-retry shape itself may deserve its own issue if it recurs — a timed-out attempt leaving the device owned makes every retry a guaranteed failure.

---

Generated by Claude Code

[thymikee]

Not ready. W3 still moves non-capture settings parsing, generic command-attempt rendering, and unsupported-interactor behavior into capture-kit solely because they are cross-family. Their consumers show separate settings and interaction domains; put them behind named owning seams (or retain family ownership) instead of recreating platform-common in a substrate package. Remove the R13 control-flow narration in src/sdk/android-adb.ts. Base #2090 remains open, and exact-head iOS is red after the gesture timeout/retry could not reacquire its simulator; require rerun or same-load base comparison.

[thymikee]

Addressed on 8a9c835, rebased onto the new stack (#2088 fccf8c1 → #2090 c350a07).

Family ownership for the four modules you named. None of them is in capture-kit any more:

• Settings parsing and command-attempt rendering are each family-owned: src/platforms/android/settings-parsing.ts and src/platforms/apple/core/settings-parsing.ts hold their own parseAppearanceAction / parseSettingState / summarizeCommandAttemptFailures, with the apple copy carrying the duplication suppressions. Two settings domains that happen to parse similar words are not one shared module.
• The unsupported-interactor factory lives in root core (src/core/interactors/unsupported-interactor.ts) for the web interactor, with a local copy in src/platforms/vega/, so no family reaches through a substrate package for it.
• packages/capture-kit/src/{appearance,setting-state,command-attempts,unsupported-interactor}.ts and their four export subpaths are deleted; the capture-kit pin in package-boundaries.test.ts shrinks accordingly.

provision-kit sits on host-kit now, not capture-kit: its archive, exec, path and stream imports resolve to the host-kit/fs and host-kit/exec seams, its manifest declares host-kit, and the boundary test pins that dependency set. The direction gates (no platform import in, no capture-kit importer) stay planted red. The R13 message and its test regex both name the widened allow-list.

The R13 control-flow narration in src/sdk/android-adb.ts is gone (removed on #2090's head, carried here).

Three provision-kit budget rows moved to their measured values because those modules now close over whole host-kit seams — same deliberate cost as the seam split itself, updated in this PR rather than left as headroom.

Green on this head: typecheck, lint, check:layering (1505 files, R11 at 19 packages), fallow vs the base, the boundary/policy/budget/ratchet gates, and unit-core at 8199 tests — the only two failures are the chmod-based daemon tests that assert unwritable-directory behavior, which does not bind under uid 0 in this container and is untouched by this diff.

---

Generated by Claude Code

[thymikee]

The prior settings/interaction ownership blocker is resolved: behavior stays with family/root owners instead of capture-kit. Still not ready. Changed-line Coverage is red at 65.31%; add focused colocated tests for Android/Apple settings and Vega unsupported-interactor error/rejection paths with planted proof. Android smoke is red on native-alert cancellation, base #2090 remains DIRTY/open, and this PR is UNSTABLE. Remove the duplicated ./snapshot-desktop-projection export key, update the stale PR summary, and remove inherited R13/control-flow narration in the touched stack.

[thymikee]

Not ready. [P1] Rebase onto current stacked base #2090 (37f146f): this head's merge-base is the obsolete ea1d6b8 chain, so its 641-file compare and CI do not validate the current narrow host-kit stack. Preserve #2090's current capability seams. [P1] Changed-line coverage is owner-action red at 65.31%: add owning branch tests for the new Android/Apple settings parsers and Vega unsupported-interactor. [P2] Remove the duplicate ./snapshot-desktop-projection export key in packages/capture-kit/package.json; JSON silently masks it. [P2] Remove the new root-shape implementation narration in scripts/layering/platform-package-policy.ts under current comment policy. The provision-kit ownership and planted direction/root-shape gates are otherwise sound. After rebase, rerun or same-load base-compare the red Android and iOS native lanes.

[thymikee]

Rebased onto the restructured stack; this branch is now ca88f7c.

The five conflicts were all the same shape — W3's destinations meeting #2088's new capability ports — and resolve to: roundPercent from kernel/numeric beside splitNonEmptyTrimmedLines from kernel/record, requireLocationCoordinates from kernel/location-coordinates, resolveIosSimulatorDeviceSetPath from kernel/device-isolation, createTtlMemo from kernel/ttl-memo, requireExecSuccess from host-kit/command, and boot-failure classification from provision-kit/boot-diagnostics. The family-ownership work from the previous round (android and apple each owning their settings parsing, the unsupported-interactor factory in root core with a vega-local copy) is unchanged.

The port split also shrank two provision-kit closures, so their rows drop in this PR rather than leaving headroom: install-artifact-archive-context 20 → 10 and toolchain-probe 15 → 8.

Green on this head: typecheck, lint, check:layering (1506 files, R11 across 19 packages), fallow, the boundary/policy/budget/ratchet gates, and unit-core at 8227 tests — the only two failures are the chmod 0o500 daemon tests that cannot bind under uid 0 in this container and are untouched by the diff.

Android Smoke is red here for the same cause as the rest of the stack; the write-up is on #2088 — it reproduces identically on unrelated PRs while main is green, so it is not this diff's.

---

Generated by Claude Code

[thymikee]

Re-review after rebase: the stack blocker is fixed — this head is now directly based on current #2090, and the W3 delta is only ~+192 net production lines, so no size escalation. Still not ready: the prior coverage remedy is absent (no owning tests were added for Android/Apple settings-parsing or Vega unsupported-interactor), so the prior 65.31% changed-line failure remains unaddressed until new exact-head Coverage proves otherwise. Remove the still-duplicated ./snapshot-desktop-projection export in packages/capture-kit/package.json. Remove remaining narration in scripts/layering/platform-package-policy.ts, packages/provision-kit/src/tmp-dir.fixtures.ts, and scripts/layering/package-boundaries.test.ts. Provision-kit ownership/root-shape gates are otherwise sound; exact-head coverage/integration/guards/native lanes must finish green.

[thymikee]

Still not ready at unchanged ca88f7c0a7. The newly advanced #2090 base makes this branch DIRTY/CONFLICTING; rebase/resolve and rerun exact-head evidence.

Prior code blockers remain: packages/capture-kit/package.json still declares ./snapshot-desktop-projection twice, and there are no direct colocated tests for Android/Apple settings parsing or Vega unsupported-interactor branches. The SDK app-state test topology is now correct. Android/Linux/macOS smoke are green, but Coverage is red in the Android Settings provider scenario; classify it as unroot-caused until compared against the current #2090 base (whose coverage is still running), not as a flake. iOS is incomplete. Remove inherited touched R13/control narration as the stack is rebased.

[thymikee]

All four addressed on e1207ca, rebased onto #2090's current head (dbbe26b), so the compare is against the narrow-port stack rather than the obsolete chain.

[P1] Rebased. The one conflict was the kernel budget rows meeting kernel/numeric; #2090's capability seams are preserved unchanged.

[P1] Coverage. The three moved-out modules arrived without owning tests, so their branches rode on callers. Each has one now:

• src/platforms/android/__tests__/settings-parsing.test.ts and the Apple sibling — every accepted appearance action and setting-state spelling, both rejection paths, and the attempt summarizer over its arg join and its 400-byte stderr budget.
• src/platforms/vega/__tests__/unsupported-interactor.test.ts — all 24 operations rejecting with UNSUPPORTED_OPERATION and their own name, the per-instance label, and the surface completeness assertion.
• src/core/interactors/__tests__/unsupported-interactor.test.ts — the same guarantee for the root-core factory the web interactor spreads, driven off Object.entries so it cannot go stale against a new operation.

[P2] Duplicate export key removed. ./snapshot-desktop-projection appeared twice in capture-kit's manifest — a rebase artifact, and exactly the silent kind: JSON keeps the last and the pin test compares a Map's keys, so neither noticed. Gone, with the key list now unique.

[P2] Root-shape narration removed from checkPlatformsRootShape; the violation message already states the rule.

Green on this head: typecheck, lint, check:layering (1506 files), fallow, the boundary/policy/budget/ratchet gates, and unit-core at 8244 tests — the only two failures are the chmod 0o500 daemon tests that cannot bind under uid 0 in this container and are untouched by the diff.

The Android and iOS native lanes re-run on this push. The write-up on #2088 has the same-load comparison: the smoke:automation-system native-alert step reproduces identically on unrelated PRs while main is green.

---

Generated by Claude Code

[thymikee]

Now on 39d5c1a, rebased onto #2090's dc23f7d.

Three of the four items were already fixed on e1207ca, which landed just after that review read ca88f7c — the duplicate ./snapshot-desktop-projection key is gone (the manifest's export keys are unique; I re-verified on this head), the root-shape narration is gone, and the colocated tests exist: src/platforms/android/__tests__/settings-parsing.test.ts, the Apple sibling, src/platforms/vega/__tests__/unsupported-interactor.test.ts, and src/core/interactors/__tests__/unsupported-interactor.test.ts. Between them they cover every accepted appearance/state spelling, both rejection paths, the attempt summarizer's arg join and 400-byte stderr budget, and all 24 interactor operations plus the per-instance label. packages/provision-kit/src/tmp-dir.fixtures.ts narration is trimmed here.

On the Coverage failure, taking your instruction not to call it a flake without the base comparison: I ran the comparison locally rather than waiting on CI. test/integration/provider-scenarios/android-lifecycle.test.ts — including "Android Settings flow uses scripted ADB provider" — passes 12/12 on this head three times running, and 12/12 on the #2090 base twice. Identical on both sides, so the settings-parsing split is not the cause; it is the same fail-closed IME-recovery-persistence fence under load that this lane hit on #2090 earlier. I'll re-check the CI base comparison when it finishes and treat a base-green/head-red result as a real finding.

Android, Linux and macOS smoke were green here; iOS and Coverage re-run on this push.

---

Generated by Claude Code