admin/AirCoding
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
b668b185e1d34dc785ccaa68e59bada9def68278
AirCoding/AirPlan/docs/architecture/cross-platform-matrix-v1.md
AirCoding 82f3140847 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
2026-05-28 18:45:01 +08:00

218 lines
7.1 KiB
Markdown
Raw Blame History

# 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 View Git Blame Copy Permalink