AirCoding/AirPlan/docs/architecture/cross-platform-matrix-v1.md

AirCoding Cross-Platform Matrix V1

Date: 2026-05-27 Status: Canonical platform support matrix for V1.0.0 Alpha skeleton

This document defines MVP platform targets, feature support levels, toolchain assumptions, and release validation requirements.

1. Support Levels

type PlatformSupportLevel =
  | "tier_1"
  | "tier_2"
  | "experimental"
  | "unsupported"

Level	Meaning
tier_1	release-blocking support; tested before release
tier_2	intended support; best-effort validation; not always release-blocking
experimental	may work; no compatibility promise
unsupported	explicit non-target

2. MVP Platform Targets

Platform	Support level	Notes
Linux x86_64	tier_1	primary development and CI target
Linux arm64	tier_2	important for appliance/VibeBox lineage and embedded-style testing
macOS arm64	experimental	CLI/runtime likely portable; C++/debug tooling varies
macOS x86_64	experimental	lower priority
Windows native	experimental/post-MVP	path/shell/process/debug semantics need dedicated work
WSL2 Linux	tier_2	treated as Linux with Windows filesystem caveats

MVP implementation should be Linux-first and avoid hardcoding Linux-only assumptions where simple abstractions are cheap.

3. Runtime Feature Matrix

Feature	Linux x86_64	Linux arm64	macOS	Windows native	WSL2
Bun runtime	tier_1	tier_2	experimental	experimental	tier_2
CLI	tier_1	tier_2	experimental	experimental	tier_2
OpenTUI/Solid TUI	tier_1	tier_2	experimental	experimental	tier_2
SQLite session DB	tier_1	tier_2	experimental	experimental	tier_2
NDJSON child processes	tier_1	tier_2	experimental	experimental	tier_2
ToolRegistry	tier_1	tier_2	experimental	experimental	tier_2
PermissionEngine path policy	tier_1	tier_2	partial	partial	tier_2
Doctor read-only	tier_1	tier_2	partial	partial	tier_2
Doctor fix	tier_1	tier_2	limited	limited	tier_2

4. Filesystem and Path Matrix

Capability	Linux	macOS	Windows native	WSL2
POSIX paths	yes	yes	no	yes
symlink realpath	yes	yes	different semantics	yes
chmod/exec bits	yes	yes	partial	yes
case sensitivity	usually yes	often no	usually no	depends mount
project-local .air	yes	yes	yes	yes
git worktree	yes	yes	yes with caveats	yes
project-outside backup repo	yes	yes	yes with path handling	yes

V1 path classifier must be platform-aware and must not rely on string prefix checks before realpath normalization.

5. Shell and Command Matrix

Shell behavior	Linux	macOS	Windows native	WSL2
bash/sh commands	tier_1	partial	unsupported by default	tier_2
process signals	POSIX	POSIX-ish	different	POSIX
sudo	yes	yes	no	yes
package manager commands	apt/dnf/pacman/etc	brew optional	winget/choco optional	Linux package mgr
timeout/kill	tier_1	partial	different	tier_2

MVP shell tools target non-interactive POSIX shell. Windows native command support is post-MVP.

6. C++ Toolchain Matrix

Tool	Linux x86_64	Linux arm64	macOS	Windows native	WSL2
CMake	tier_1	tier_2	experimental	experimental	tier_2
Ninja	tier_1	tier_2	experimental	experimental	tier_2
Make fallback	tier_1	tier_2	experimental	partial	tier_2
gcc/clang	tier_1	tier_2	clang-focused	MSVC not MVP	tier_2
clangd CLI	tier_1	tier_2	experimental	experimental	tier_2
cppcheck	tier_1	tier_2	experimental	experimental	tier_2
CTest/GoogleTest	tier_1	tier_2	experimental	experimental	tier_2
core dumps/backtrace	tier_1	partial	different	unsupported MVP	tier_2

Windows MSVC-specific workflows are not MVP.

7. GUI, Debug, and Network Evidence Matrix

Evidence type	Linux	macOS	Windows native	WSL2
screenshots	tier_1 with display backend	experimental	experimental	depends WSLg/X
GUI automation	post-MVP/basic only	post-MVP	post-MVP	depends WSLg/X
pcaps	requires permissions	requires permissions	different tooling	requires permissions
core dumps	Linux-first	different	different	Linux-first
debugger integration	Linux-first	experimental	post-MVP	Linux-first

MVP only requires basic GUI screenshot evidence where display backend is available.

8. Provider/Network Matrix

Provider APIs are platform-independent except for:

TLS/certificate store differences
proxy environment variables
local model runtimes
network firewall/proxy policy

Doctor should validate provider reachability without exposing secrets.

9. Distribution Matrix

MVP distribution:

Platform	Distribution
Linux x86_64	binary tarball
Linux arm64	binary tarball, best-effort
macOS	experimental tarball or manual run
Windows native	no stable MVP distribution
WSL2	use Linux tarball inside WSL

Binary tarball contains:

bin/air
resources/
LICENSE

Resources include templates, prompts, themes, HUD presets, Python scripts, and toolchain resources.

10. Platform Detection Contract

interface PlatformInfo {
  os: "linux" | "darwin" | "windows" | "unknown"
  arch: "x64" | "arm64" | "arm" | "unknown"
  libc?: "glibc" | "musl" | "unknown"
  shell?: string
  is_wsl?: boolean
  display?: {
    wayland?: boolean
    x11?: boolean
    xvfb?: boolean
    wslg?: boolean
  }
  package_managers?: string[]
  path_case_sensitive?: boolean
}

Doctor records platform info in doctor report artifacts and session metadata.

11. Release Gate

Before an AirCoding MVP release:

Tier 1 Linux x86_64 must pass:

unit tests
integration fixture tests
real LLM E2E release test
project init smoke
C++ configure/build/test flow
SQLite recovery smoke
child agent IPC smoke
TUI startup smoke
artifact/event persistence smoke

Linux arm64 best-effort gate:

runtime startup
doctor read-only
SQLite/session creation
basic shell/tool execution
C++ toolchain detection if available

Experimental platforms may have smoke checks but do not block MVP release unless declared for a specific release.

12. VibeBox Relationship

VibeBox targets ARM Linux appliance behavior and has its own downstream baseline. AirCoding mainline should keep Linux arm64 viable, but VibeBox-specific Electron packaging/test requirements do not become AirCoding mainline MVP release blockers.

13. V1.0.0 Alpha Cut Line

V1.0.0 Alpha skeleton must implement:

1. Platform detection.
2. Linux x86_64 tier-1 path/shell/process behavior.
3. Linux arm64 best-effort packaging/runtime checks.
4. WSL detection and warnings.
5. Platform-aware path classifier.
6. Doctor platform report.
7. Release gate script definitions for tier 1.

Post-MVP:

Windows native shell/process support
macOS notarized distribution
containerized test matrix
MSVC toolchain profile
Wayland/X11/Windows/macOS GUI automation adapters
platform-specific sandboxing