Michał Pierzchała
b6128c0088
* docs: retire plans/perfect-shape.md — roadmap complete The perfect-shape roadmap (two-registry thesis: CommandDescriptor + PlatformPlugin, typed-result spine, folder DAG + layering lint, agent-cost, and the Apple apple+appleOs platform model with a non-breaking leaf wire) is substantively complete and merged. Per its own §5 retirement note, the durable decisions now live in ADR-0008 (command descriptor) and ADR-0009 (Apple/AppleOS), and current-state terms in CONTEXT.md; this removes the last plan file. - Delete plans/perfect-shape.md (plans/ is now empty and gone). - CONTEXT.md: add "Architecture (perfect-shape refactor, completed 2026-07)" end-state summary plus a "Deferred / next-minor" note (Phase 2c client-types narrowing, b.3 recording/providers facets, strict DAG back-edge inversion, legacy alias drops) so nothing is lost. - Repoint every remaining perfect-shape.md/§ reference (ADRs 0003/0008/0009, ci.yml, scripts/layering/check.ts, and the platform-plugin/apple comments) to ADR-0008/0009 or CONTEXT.md. No dangling references remain. Docs/comment-only; tsc, oxlint, oxfmt, and the layering DAG check all pass. * docs: repoint dangling perfect-shape section refs before retiring the roadmap Removing plans/perfect-shape.md left three comments citing bare section numbers with no surviving target. The rationales are already inlined, so drop the numbers (and point the do-not-flatten note at the durable ADR): - src/platforms/apple/plugin.ts: `(§7)` -> "do-not-flatten; see docs/adr/0009". - src/core/interactors/register-builtins.ts: "the §5.1 ... sketch" -> "an ... sketch". - scripts/layering/check.ts: drop `(§5.5 ...)`, keep the inline "re-export barrels only".
4.3 KiB
ADR 0009: Apple Platform Consolidation (AppleOS leaf axis)
Status
Accepted
Context
Apple support is modeled asymmetrically and is physically smeared across an ios directory that is really
the shared Apple engine. Platform carries ios and macos as separate literals, but tvOS is not a
platform at all — it is platform: 'ios' + target: 'tv', with the OS name reconstructed late and lossily by
resolveApplePlatformName (src/kernel/device.ts). Meanwhile ~697 LOC of macOS code lives inside
src/platforms/ios/, src/platforms/macos/devices.ts is a 19-line stub that the iOS discovery imports (the
dependency arrow points backwards), and the Apple interactor in src/core/interactors/apple.ts reaches into
platforms/ios. A four-investigator survey found that ~85% of platforms/ios (the runner stack,
tool-provider, discovery, snapshot, screenshot, perf, debug-symbols) is already OS-agnostic, and the XCTest
runner already builds ios | macos | tvos from one Xcode project. Distinguishing or adding an Apple OS today
is therefore costly out of proportion to the actual work, and iPadOS/visionOS/watchOS are unmodeled.
Decision
Model Apple OSes with an AppleOS discriminant (ios | ipados | tvos | watchos | visionos | macos)
under a single apple Platform — not six Platform literals. The OS-agnostic Apple engine consolidates
under src/platforms/apple/core/, with genuinely per-OS code in src/platforms/apple/os/<os>/ leaves;
the Apple plugin is the first instance of the platform-plugin registry (the platform axis of the
completed perfect-shape refactor; see CONTEXT.md Architecture). Per-OS capability
differences become data keyed by AppleOS. The additive,
non-breaking appleOs discriminant — the groundwork for this — shipped in #896.
Alternatives Considered
- Promote each Apple OS to its own
Platformliteral: rejected.DeviceTarget(mobile | tv | desktop) is already cross-platform (Android TV usestarget: 'tv'), so atvosliteral collides with the form-factor axis; it would also force the ~15isApplePlatformand ~52macosbranch sites to enumerate six literals and break the single-bucketapplecapability/selector model that already works. - Keep the status quo: rejected — the tvOS/macOS asymmetry, the mislabeled macOS code, and the lossy target→OS inference persist, with no path to iPadOS/visionOS.
- Exclude macOS from the consolidation: rejected. macOS is already entangled — it builds via the same XCUITest
project and ~697 LOC of its code already lives inside
platforms/ios. Excluding it would leave the mislabel in place; including it as a distinct AppKit leaf normalizes it without homogenizing it.
Consequences
Adding a first-class Apple OS becomes cheap: a leaf module plus a runner-profile row. iOS/iPadOS/tvOS/macOS
are mostly relocate-and-rename (the engine never needed to know which Apple OS it drives); visionOS is scoped
net-new work (XCUITest supports it — a profile row, a build case, #if os(visionOS), a widened discovery
filter, plus real spatial-input QA); watchOS is an explicit unsupported sentinel because XCUITest cannot
drive watchOS UI. macOS stays a distinct AppKit leaf (its helper binary and menubar/desktop surface model are
preserved). The tvOS focus-only interaction contract (no coordinate tap) must not be flattened across OSes,
and snapshot fidelity is uneven (the deep-RN AX-server fallback is iOS-simulator-only). The final
Platform collapse of ios+macos into apple is the last, highest-diff step.
This composes with ADR 0008 (the descriptor's capability facet) and ADR 0003.
Implementation status as of 2026-06:
- Shipped: additive
appleOsgroundwork, the shared Apple engine undersrc/platforms/apple/core, macOS leaf files undersrc/platforms/apple/os/macos, direct internal imports to the Apple modules, and visionOS profile/build/discovery groundwork. - Deferred: the public
Platformcollapse fromios/macostoapple, a dedicated tvOS leaf, per-AppleOScapability tables, and any watchOS unsupported sentinel. watchOS remains out of scope for the current consolidation.
This ADR owns the architectural decision; implementation progress for the remaining platform-plugin work is tracked in GitHub issues under the Phase 3 umbrella (#972).