Initial commit: AirCoding V1.0.0 Alpha architecture baseline
Complete architecture document set with multi-model review remediation: - Frozen interface contracts, runtime semantics, DB schemas - Event/tool/error/provider registries - Scheduler and main agent state machines - C4 module/code views, solution architecture, baseline V1 - Multi-model review reports and joint assessment - Phase-gate remediation complete (P0/P1/P2/UX resolved) - Implementation plan with T-000A through T-045 - Reference folders kept as placeholders only
This commit is contained in:
AirCoding
217
AirPlan/docs/architecture/cross-platform-matrix-v1.md
Normal file
217
AirPlan/docs/architecture/cross-platform-matrix-v1.md
Normal file
@@ -0,0 +1,217 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user