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

```ts
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:

```text
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:

```text
bin/air
resources/
LICENSE
```

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

## 10. Platform Detection Contract

```ts
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:

```text
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:

```text
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:

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