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
commit 82f3140847
366 changed files with 123826 additions and 0 deletions
--- a/AirPlan/docs/architecture/solution-architecture.md
+++ b/AirPlan/docs/architecture/solution-architecture.md
@@ -0,0 +1,479 @@
+# Solution Architecture
+
+Date: 2026-05-27
+Status: Formal V1 architecture derived from AirCoding Architecture Baseline V1
+
+## 1. Overview
+
+AirCoding is a self-owned local AI coding agent/runtime. It is not a Claude Code plugin wrapper. The product provides a Claude Code-quality execution layer, OpenCode/OpenTUI-inspired terminal UI, project-local session persistence, multi-agent orchestration, and language/toolchain capability packages.
+
+The V1 architecture is Linux-first, TypeScript/Bun-based, event-driven, and project-local by default. C++ is the first deep language profile, while the runtime remains language-agnostic through `toolchain-*` capability packages.
+
+Core value path:
+
+```text
+User requirement
+  → Main Agent clarification and routing
+  → Architecture Designer for design/interface decisions
+  → Scheduler task graph and wave planning
+  → Executor/Reviewer/Debugger/Compactor/ExperienceMiner workers
+  → ToolRegistry + PermissionEngine + EventStore
+  → project-local DB/artifacts/evidence
+  → TUI/HUD ProjectionStore
+```
+
+## 2. Architecture Sources of Truth
+
+This document summarizes the formal architecture. Detailed V1 baselines remain authoritative for implementation contracts.
+
+Precedence rule:
+
+1. `interface-contracts-v1.md` wins for TypeScript public interface shape.
+2. `db-schema-v1.md` wins for SQLite persistence shape.
+3. `event-registry-v1.md` wins for event names and payloads.
+4. `tool-registry-v1.md` wins for tool names and tool I/O schemas.
+5. `runtime-semantics-v1.md` wins for cross-cutting runtime behavior.
+6. `c4/module.md` and `c4/code-view.md` win for package/component boundaries.
+7. ADR files win for accepted design decisions they explicitly cover.
+8. `baselineV1.md` remains the narrative baseline and decision index.
+
+| Area | Source |
+|---|---|
+| Overall baseline | `AirPlan/docs/architecture/baselineV1.md` |
+| Interface contracts | `AirPlan/docs/architecture/interface-contracts-v1.md` |
+| Runtime semantics | `AirPlan/docs/architecture/runtime-semantics-v1.md` |
+| C4/module/code view | `AirPlan/docs/architecture/c4/module.md`, `AirPlan/docs/architecture/c4/code-view.md` |
+| DB schema | `AirPlan/docs/architecture/db-schema-v1.md` |
+| Event registry | `AirPlan/docs/architecture/event-registry-v1.md` |
+| Tool registry | `AirPlan/docs/architecture/tool-registry-v1.md` |
+| Scheduler state machine | `AirPlan/docs/architecture/scheduler-state-machine-v1.md` |
+| Prompt layering | `AirPlan/docs/architecture/prompt-layering-v1.md` |
+| Provider matrix | `AirPlan/docs/architecture/provider-capability-matrix-v1.md` |
+| Error taxonomy | `AirPlan/docs/architecture/error-taxonomy-v1.md` |
+| Artifact naming | `AirPlan/docs/architecture/artifact-naming-v1.md` |
+| Scope escalation | `AirPlan/docs/architecture/scope-escalation-v1.md` |
+| Security model | `AirPlan/docs/architecture/security-model-v1.md` |
+| Capability trust | `AirPlan/docs/architecture/capability-trust-v1.md` |
+| Platform matrix | `AirPlan/docs/architecture/cross-platform-matrix-v1.md` |
+
+## 3. Architectural Principles
+
+1. **Execution quality follows Claude Code.** File edits are read-before-edit, exact, conservative, small, and verified before completion.
+2. **OpenCode is a UI/runtime reference, not a business-state dependency.** Reuse visual patterns and OpenTUI/Solid primitives, not OpenCode's session/sync state model.
+3. **Project-local source of truth.** Session state, artifacts, backups, and project rules live under project `.air/`.
+4. **Events drive live behavior; SQLite drives recovery.** EventBus is live transport; domain tables and durable events are the source of truth.
+5. **Workers are isolated child processes.** Executor, Reviewer, Debugger, Compactor, and ExperienceMiner run as independent Bun processes over NDJSON IPC.
+6. **Main Agent remains responsive.** Long-running background work is delegated to Scheduler/workers.
+7. **Architecture changes are explicit.** Implementation-only changes may continue silently; interface/architecture/product changes route through Architecture Designer and/or user confirmation.
+8. **Tool/capability boundaries are permissioned.** Built-in and future plugin tools all pass through ToolRegistry and PermissionEngine.
+9. **Provider boundary is isolated.** Internal messages are Anthropic canonical; adapters convert at provider boundary.
+10. **Evidence is first-class.** Build/test/debug/review outputs become artifacts and evidence refs before completion claims.
+
+## 4. Major Containers
+
+### CLI Container
+
+Package: `packages/cli`
+
+Responsibilities:
+
+- command entrypoint
+- startup and first-run initialization
+- Doctor invocation
+- project discovery and `.air` initialization
+- resource loading
+- TUI/runtime bootstrap
+
+Interfaces:
+
+- CLI commands
+- local filesystem
+- runtime service initialization
+
+### TUI/HUD Container
+
+Package: `packages/tui`
+
+Responsibilities:
+
+- OpenTUI/Solid user interface
+- Main Agent conversation surface
+- progress, task, agent, diff, and evidence display
+- permission prompts and blocker reports
+- HUD/statusline projection
+
+Interfaces:
+
+- ProjectionStore read API
+- Main Agent UI channel
+- Permission prompt UI
+
+Constraints:
+
+- TUI consumes ProjectionStore only.
+- TUI does not query SQLite or EventBus directly.
+- TUI does not own scheduling state.
+
+### Runtime Container
+
+Package: `packages/runtime`
+
+Responsibilities:
+
+- Main Agent orchestration shell
+- Architecture Designer integration
+- Scheduler
+- child process management
+- EventBus and EventStore
+- SessionStore/domain repositories
+- ToolRegistry
+- PermissionEngine
+- CapabilityRegistry
+- ContextAssembler
+- ArtifactStore and EvidenceStore
+- ProjectionStore producer side
+
+Interfaces:
+
+- `packages/contracts`
+- `packages/llm`
+- `packages/toolchain-*`
+- SQLite
+- project filesystem
+- child process stdio IPC
+
+### LLM Container
+
+Package: `packages/llm`
+
+Responsibilities:
+
+- provider configuration
+- provider adapters
+- Anthropic canonical message handling
+- OpenAI/OpenRouter/ollama/custom endpoint conversion
+- capability matrix validation
+- streaming/tool-use conversion
+- token counting hooks where available
+
+Interfaces:
+
+- ProviderAdapter API
+- ProviderCapabilityMatrix
+- runtime LLM request API
+
+### Toolchain C++ Container
+
+Package: `packages/toolchain-cpp`
+
+Responsibilities:
+
+- C++ project detection
+- CMake configure/build orchestration
+- Ninja-first, Make fallback strategy
+- CTest/GoogleTest execution
+- cppcheck static analysis
+- clangd CLI queries
+- compiler/linker diagnostic parsing
+- build/test/debug evidence production
+
+Interfaces:
+
+- Capability manifest
+- ToolRegistry tools under `cpp.*`
+- shell command runner
+- diagnostics/artifacts/evidence stores
+
+### Contracts Container
+
+Package: `packages/contracts`
+
+Responsibilities:
+
+- compileable shared TypeScript interfaces
+- RuntimeEvent, TaskSpec, WorkerResult, ToolDefinition, ArtifactRef, EvidenceRef
+- error, provider, project, IPC, UI types
+
+Dependency rule:
+
+- All packages may depend on `contracts`.
+- `contracts` must not depend on domain implementation packages.
+
+## 5. Runtime Agents
+
+### Main Agent
+
+User-facing coordinator. It handles conversation, progress summaries, requirement changes, direct foreground tasks, and escalation presentation. It does not perform long-running background work.
+
+### Architecture Designer
+
+Owns architecture planning, impact assessment, ADR/C4/plan/todo alignment, and design/interface change review. It may edit planning/architecture documents, not implementation code.
+
+### Scheduler
+
+Owns TaskGraph loading, wave planning, dependency handling, write-area conflict handling, retry strategy, child worker dispatch, heartbeat monitoring, merge coordination, and restart recovery.
+
+### Executor
+
+Performs scoped implementation/build/test tasks with Claude Code-style execution discipline and structured WorkerResult output.
+
+### Reviewer
+
+Read-only reviewer for correctness, security, scope control, architecture compliance, and evidence sufficiency. It produces review reports and follow-up tasks.
+
+### Debugger
+
+Diagnoses failures using logs, diagnostics, artifacts, command output, GUI/network evidence, and may fix only within assigned write scope.
+
+### Compactor
+
+Performs copy-on-write context compaction. It produces summaries while preserving original messages for explicit backtracking.
+
+### ExperienceMiner
+
+Extracts project rules, skill candidates, and debug knowledge from verified repeated patterns and evidence.
+
+## 6. Data Architecture
+
+Project layout:
+
+```text
+<project>/.air/
+  shared/
+    project.json
+    permissions.yaml
+    compaction-rules.md
+    rules/
+    plan/
+  local/
+    sessions/<session-id>/
+      session.db
+      artifacts/
+    backups/
+    debug-records.db
+    learned-memory.db
+    workspaces/
+    tmp/
+    locks/
+```
+
+Session DB path:
+
+```text
+<project>/.air/local/sessions/<session-id>/session.db
+```
+
+Core data groups:
+
+| Group | Tables |
+|---|---|
+| session/conversation | `sessions`, `messages`, `message_drafts`, `summaries` |
+| orchestration | `events`, `tasks`, `task_dependencies`, `task_attempts`, `agents`, `workspaces` |
+| execution evidence | `tool_runs`, `command_runs`, `artifacts`, `diagnostics`, `evidence_refs` |
+| UI recovery | `ui_state` |
+| schema | `schema_meta` |
+
+SQLite V1 settings:
+
+```sql
+PRAGMA journal_mode = WAL;
+PRAGMA synchronous = NORMAL;
+PRAGMA foreign_keys = OFF;
+```
+
+Durable event insert and corresponding domain table update must be in the same transaction.
+
+## 7. Control Flow Architecture
+
+### Startup Flow
+
+```text
+CLI starts
+  → detect platform and config
+  → load resources/prompts/capabilities
+  → open or initialize project .air
+  → run read-only Doctor
+  → open session DB
+  → hydrate ProjectionStore from DB
+  → start TUI/Main Agent/runtime services
+```
+
+### Normal Execution Flow
+
+```text
+User request
+  → Main Agent classifies intent
+  → direct answer or architecture/task planning
+  → Scheduler creates/loads TaskGraph
+  → ContextAssembler builds agent context
+  → Scheduler dispatches child worker over NDJSON IPC
+  → worker uses ToolRegistry
+  → ToolRegistry enforces PermissionEngine
+  → tools emit events/artifacts/evidence
+  → worker returns WorkerResult
+  → Scheduler retries/merges/reviews/continues
+  → Main Agent reports outcome
+```
+
+### Requirement Change Flow
+
+```text
+User changes requirement
+  → requirement.changed event
+  → Scheduler pauses affected work
+  → Architecture Designer assesses if needed
+  → implementation-level change continues silently
+  → architecture/product-level change routes to user confirmation/replan
+```
+
+### Recovery Flow
+
+```text
+Process/session restarts
+  → open session DB
+  → load running/interrupted tasks and agents
+  → inspect child process liveness when possible
+  → emit agent.lost/task.failed or reconnect/resume
+  → preserve unmerged workspaces
+  → rebuild Scheduler queues
+  → hydrate ProjectionStore
+```
+
+## 8. Tool and Capability Architecture
+
+ToolRegistry provides stable schema-validated built-ins:
+
+```text
+fs.*, shell.*, git.*, project.*, cpp.*, debug.*,
+gui.*, network.*, artifact.*, context.*, permission.*, doctor.*
+```
+
+CapabilityRegistry adds built-in and future plugin capabilities through manifests. Capability dependencies are declared in manifests but installed/fixed by Doctor, never by arbitrary plugin scripts.
+
+Every tool call follows:
+
+```text
+model/agent request
+  → schema validation
+  → PermissionEngine evaluation
+  → tool execution
+  → tool/command/artifact/evidence events
+  → structured ToolResult
+```
+
+## 9. Prompt and Provider Architecture
+
+ContextAssembler emits Anthropic canonical messages with L0-L9 layers:
+
+```text
+runtime invariant
+role/mode
+safety and permission policy
+project rules/user preferences
+architecture baseline/current plan
+task spec/acceptance criteria
+relevant code/artifacts/evidence
+recent conversation/decision context
+tool result history/diagnostics
+immediate instruction
+```
+
+Provider adapters convert canonical messages at the LLM boundary. Conversion omissions are recorded. Required unsupported capabilities block before model call.
+
+Model selection is capability-based and can be Scheduler-forced or agent-selected within allowed constraints.
+
+## 10. Security Architecture
+
+Security boundary summary:
+
+- LLM output is untrusted until validated.
+- Tools are the only path to filesystem/shell/network effects.
+- PermissionEngine evaluates all writes, execution, network, system-sensitive, and credential access.
+- Symlinks are resolved by realpath before risk classification.
+- `.git/` is protected by default.
+- Build directories are allowed project write areas.
+- Project-outside writes require backup.
+- Credentials and system-sensitive operations require explicit confirmation.
+- No automatic upload of logs, artifacts, debug knowledge, or doctor bundles.
+
+## 11. Platform Architecture
+
+V1.0.0 Alpha is Linux-first:
+
+| Platform | Support |
+|---|---|
+| Linux x86_64 | tier 1 |
+| Linux arm64 | tier 2 |
+| WSL2 | tier 2 |
+| macOS | experimental |
+| Windows native | experimental/post-MVP |
+
+Shell/process/C++ tooling in V1.0.0 Alpha targets POSIX-like Linux behavior.
+
+## 12. Quality and Validation Architecture
+
+Validation layers:
+
+```text
+unit tests → integration fixture replay → real LLM E2E release gate
+```
+
+Execution completion requires evidence appropriate to the task:
+
+- build command result
+- test command result
+- static analysis result where configured
+- debug evidence where failures occur
+- review report for significant changes
+- artifact/evidence refs for claims
+
+Release gate for tier-1 Linux must cover startup, project init, child IPC, session DB, artifacts/events, C++ configure/build/test, TUI startup, and real LLM E2E behavior.
+
+## 13. Key Risks and Mitigations
+
+| Risk | Mitigation |
+|---|---|
+| Execution quality below Claude Code | Align edit primitives, tool lifecycle, read-before-edit, verification discipline |
+| Context explosion | copy-on-write compaction, ContextAssembler budgets, artifact refs |
+| Scheduler complexity | V1 state machine and V1.0.0 Alpha cut line; advanced optimization deferred |
+| Tool/plugin safety | ToolRegistry + PermissionEngine + capability trust model |
+| Provider feature mismatch | Provider capability matrix and conversion report |
+| Lost worker/process | heartbeat, task attempts, restart recovery |
+| Merge conflicts across parallel workers | write-area planning, worktrees, merge events, repair/escalation |
+| Debug evidence too large/noisy | artifact naming/layout, evidence refs, summaries |
+| Platform drift | Linux tier-1 release matrix and Doctor platform report |
+
+## 14. V1.0.0 Alpha Architecture Boundaries
+
+In scope for V1.0.0 Alpha:
+
+```text
+Bun monorepo
+contracts package
+runtime services
+project-local SQLite/artifacts
+EventStore/EventBus/ProjectionStore
+Main Agent shell
+Scheduler/worker IPC
+ToolRegistry/PermissionEngine
+complete C++ development workflow
+local/built-in plugin and capability foundation
+TUI/HUD startup and projections
+provider adapters
+Doctor read-only/fix framework
+GUI/network evidence tools
+release gate and binary tarball packaging
+```
+
+Deferred beyond V1.0.0 Alpha:
+
+```text
+third-party plugin registry/signing
+container sandboxing
+advanced semantic merge
+multi-machine scheduling
+Windows-native deep support
+production-grade bitmap image generation providers
+browser/computer-use automation
+learned retry optimizer
+```