AirCoding/AirPlan/docs/architecture/system-overview-design.md

AirCoding V1.0.0 Alpha System Overview Design

Date: 2026-05-29 Status: FROZEN — no further edits permitted. This document is the authoritative overview for detailed design and implementation. Scope: Architecture-level design. No implementation code.

1. Purpose

This document turns the repaired AirCoding V1.0.0 Alpha architecture baseline into a system-level overview design. It is the bridge between the formal architecture baselines and the later detailed design / class diagram freeze.

Frozen source documents:

1. AirPlan/docs/analysis/requirements.md
2. AirPlan/docs/architecture/baselineV1.md
3. AirPlan/docs/architecture/solution-architecture.md
4. AirPlan/docs/architecture/interface-contracts-v1.md
5. AirPlan/docs/architecture/db-schema-v1.md
6. AirPlan/docs/architecture/event-registry-v1.md
7. AirPlan/docs/architecture/runtime-semantics-v1.md
8. AirPlan/docs/architecture/c4/module.md
9. AirPlan/docs/architecture/c4/code-view.md
10. AirPlan/docs/architecture/main-agent-state-machine.md
11. AirPlan/docs/architecture/scheduler-state-machine-v1.md
12. AirPlan/docs/architecture/scope-escalation-v1.md
13. AirPlan/docs/architecture/security-model-v1.md
14. AirPlan/docs/architecture/capability-trust-v1.md
15. AirPlan/docs/architecture/provider-capability-matrix-v1.md
16. AirPlan/docs/architecture/prompt-layering-v1.md
17. AirPlan/docs/architecture/artifact-naming-v1.md
18. AirPlan/docs/architecture/error-taxonomy-v1.md
19. AirPlan/docs/architecture/tool-registry-v1.md
20. AirPlan/docs/architecture/cross-platform-matrix-v1.md
21. AirPlan/docs/architecture/decisions-round-1.md
22. AirPlan/docs/architecture/decisions-round-2.md
23. AirPlan/docs/architecture/decisions-round-3.md
24. idea.md

Current-stage review inputs:

1. AirPlan/docs/architecture/gpt5概要设计审查.md
2. AirPlan/docs/architecture/mimo2.5概要设计审查.md
3. AirPlan/docs/architecture/Opus4.7概要设计审查.md
4. AirPlan/docs/architecture/DeepSeek概要设计审查.md
5. AirPlan/docs/architecture/多模型三视角审查联合评估.md
6. AirPlan/plan.md
7. AirPlan/todo.md

Baseline precedence: frozen source documents are authoritative. This overview may add design-stage alignment decisions and cross-document summaries, but it does not change frozen requirements or baselines.

2. System Goal

AirCoding V1.0.0 Alpha is a self-owned, Linux-first, local AI coding runtime. It is not a Claude Code plugin, wrapper, or thin shell around another coding agent. It owns its runtime state, event log, task scheduler, tool permission layer, artifact/evidence lifecycle, and UI projection.

Canonical V1 coding loop:

requirement
  → architecture/interface design
  → code reading
  → implementation planning
  → scoped implementation
  → build
  → static analysis
  → test
  → run/debug
  → crash/log/network/GUI evidence analysis
  → fix
  → review
  → change summary
  → experience mining

V1.0.0 Alpha must deliver a usable developer loop with:

• global ~/.air user state and project-local .air state;
• stable project_id UUID per initialized project;
• SQLite-backed session persistence and recovery;
• event-driven runtime behavior;
• isolated Bun child-process workers;
• ToolRegistry + PermissionEngine for all side effects;
• Anthropic-canonical provider boundary;
• OpenTUI/Solid terminal UI and HUD;
• complete zero-config-oriented C++ configure/build/test/static-analysis/debug/fix/review workflow;
• capability/plugin foundation;
• evidence-backed completion and release gates.

Core architecture decisions inherited from solution-architecture.md:

1. Event-driven runtime with SQLite recovery.
2. ToolRegistry + PermissionEngine for all side effects.
3. Anthropic canonical internal message format with provider adapter boundary.
4. Bun child-process workers over NDJSON IPC.

Reference influences and reuse boundaries:

Reference	Used for	Not reused for
Claude Code	Execution-layer quality benchmark: read-before-edit, exact conservative edits, small patches, no unrelated refactors, verification-before-completion, evidence-backed closure	Runtime ownership or state model
OpenCode	UI visual patterns and OpenTUI primitives	SDK, sync, session, or business-state logic
Hermes Agent	Experience mining, Nudge triggers, Curator daemon, self-patch ideas, SKILL.md format	Runtime process model
OpenAI Codex	Shell/patch/test loop and tool orchestration ideas	Provider/runtime lock-in
Claude Skills	Skill directory layout and trigger descriptions	Untrusted side-effect bypass
asciinema / Atuin / claude-hud	PTY capture, command history indexing, HUD/statusline layout	Source of truth for runtime recovery

Technology baseline:

• Runtime language: TypeScript on Bun.
• Monorepo: Bun workspaces + Turborepo.
• TUI: @opentui/solid, @opentui/core, @opentui/keymap.
• Storage: SQLite per session, project-local by default.
• IPC: NDJSON over stdio.
• Python: subprocess-only helper layer for existing scripts/libraries, not core runtime.
• Distribution: binary tarball before public package channels.

Non-goals for V1.0.0 Alpha:

• third-party plugin registry/signing;
• container sandboxing;
• multi-machine scheduling;
• Windows-native deep support;
• advanced semantic merge;
• production bitmap image generation provider integration.

3. System Context

Developer
  │
  ▼
AirCoding CLI/TUI
  │
  ├─ global ~/.air user state
  ├─ local project files
  ├─ project-local .air state
  ├─ local shell/toolchains/debug tools
  ├─ configured LLM providers
  └─ optional display/network evidence tools

External dependencies:

External system	Role	Boundary rule
Global ~/.air	User config, provider config, project index, global skills/cache/logs	User-local state; not project source of truth
Local project	Source files, build outputs, tests	All writes go through tools and permissions
.air/shared	Git-shareable project config/rules/plans	May be committed by user/project
.air/local	Private local DBs/artifacts/workspaces/backups	Gitignored by default
LLM providers	Model completions	Provider adapters convert at boundary
OS shell/toolchain	Build/test/debug/static analysis	ToolRegistry + PermissionEngine only
Git	Diff, status, worktree, merge, backup repo	Permissioned tools only
Display/network subsystems	GUI screenshots, pcaps	Explicit evidence tools, no automatic upload

4. Container Overview

packages/contracts
  ▲          ▲          ▲              ▲              ▲
  │          │          │              │              │
packages/cli ───▶ packages/runtime ───▶ packages/llm  │
  │                 │        │                         │
  ▼                 │        └── provider adapters     │
packages/tui        │                                  │
                    ├── packages/toolchain-cpp via capability/tools
                    ├── child worker processes over NDJSON IPC
                    ├── SQLite session/project DBs
                    └── project filesystem/artifacts/backups

Canonical dependency direction from C4 module view:

contracts ← cli
contracts ← runtime
contracts ← llm
contracts ← tui
contracts ← toolchain-cpp
runtime   ← cli
runtime   ← workers over IPC, not direct imports
llm       ← runtime through ProviderManager facade
tui       ← cli bootstrap and ProjectionClient contracts only
toolchain-cpp ← runtime through capability/tool boundary

Container	Responsibility	Key outputs
packages/contracts	Shared TypeScript public contracts	RuntimeEvent, TaskSpec, WorkerResult, ToolDefinition, IPC, provider, UI, DB-facing types
packages/cli	Entry point, command routing, init/open project, Doctor, TUI bootstrap	CLI commands and startup lifecycle
packages/tui	OpenTUI/Solid views and HUD	User conversation, progress, evidence, permission prompts
packages/runtime	Main Agent, Architecture Designer, Scheduler, EventStore, ToolRegistry, PermissionEngine, context, artifacts, projection	Core orchestration and state ownership
packages/llm	Provider config, startup/session selection, adapters, conversion reports	ProviderManager facade and stream events
packages/toolchain-cpp	C++ capability/tools	cpp.* tools, deterministic diagnostics, evidence
worker processes	Executor/Reviewer/Debugger/Compactor/ExperienceMiner roles	WorkerResult, RuntimeEvents, tool calls

Future language packages may add packages/toolchain-python, packages/toolchain-rust, and packages/toolchain-js; V1.0.0 Alpha only requires packages/toolchain-cpp.

Expected packages/contracts/src/ public file set from code view:

index.ts
types.ts
errors.ts
events.ts
storage.ts
project.ts
scheduler.ts
workers.ts
tools.ts
permissions.ts
artifacts.ts
providers.ts
context.ts
projection.ts
capabilities.ts
doctor.ts
knowledge.ts
diagnostics.ts

5. Dependency Rules

contracts → no implementation dependencies
cli → runtime, tui, llm, toolchain-cpp
tui → contracts only for projection/UI contracts
runtime → contracts, llm facade, toolchain-* through capability boundary
llm → contracts
toolchain-cpp → contracts
workers → contracts and WorkerRuntime IPC surface

Forbidden paths:

• TUI → SQLite direct query;
• TUI → runtime private service import;
• worker → SQLite direct write;
• worker → filesystem/shell/network side effect outside tool IPC;
• tool → side effect without PermissionEngine;
• capability → dependency install outside Doctor;
• provider adapter → silent semantic prompt loss;
• repository → scheduling policy;
• EventBus → recovery source of truth;
• runtime → TUI import;
• LLM output → direct file/shell side effect.

6. Runtime Component Overview

Component	Owns	Calls	Emits / persists
Main Agent	User interaction, request classification, direct mode	ContextAssembler, ProviderManager, Scheduler, Architecture Designer	messages, requirement.changed, progress summaries
Architecture Designer	Architecture impact and plan/doc sync	ContextAssembler, ProviderManager, document stores	architecture.plan.updated, architecture.impact.completed
Scheduler	TaskGraph, wave planning, retries, workspaces, worker lifecycle	SessionStore, WorkerManager, ContextAssembler, EventIngestor	task.*, agent.*, workspace.*
WorkerManager	Child process spawn/monitor, IPC lifecycle	OS process APIs, WorkerProtocol	agent.started/lost/completed/failed
EventIngestor	Event intake boundary	EventStore, EventBus, EventSchemaRegistry	routes durable/ephemeral events
EventStore	Durable event validation and domain projection transaction	SQLite, EventSchemaRegistry	events + domain table rows
EventBus	Live pub/sub	subscribers only	ephemeral delivery and post-commit durable delivery
SessionStore	Repositories over session DB	SQLite	domain records
ToolRegistry	Tool registration and dispatch	PermissionEngine, ArtifactStore, EventIngestor	tool.*, ToolResultEnvelope
PermissionEngine	Action/risk decisions	PathClassifier, CommandRiskAnalyzer, EventIngestor	permission.*
CapabilityRegistry	Manifest discovery/validation/enable	ToolRegistry, DoctorService	capability config and registered tools
ContextAssembler	Prompt layering and context budget	SessionStore, ArtifactStore, PromptLayerLoader, CompactionPolicy	AssembledContext, compaction requests
ArtifactStore	Artifacts temp-write/rename/hash/read	filesystem, EventIngestor, SessionStore	artifacts table, artifact.created
EvidenceStore	Evidence refs and claim links	ArtifactStore, diagnostics	evidence_refs table
ProjectionStore	TUI/HUD view model	SessionStore, EventBus	derived ProjectionSnapshot
ProviderManager	Startup/session provider/model validation and streaming	provider adapters	ProviderStreamEvent, conversion reports
DoctorService	Environment/capability checks/fixes/bundles	CapabilityRegistry, PermissionEngine, tools	doctor events/artifacts
DebugKnowledgeStore	debug-records.db	project-level DB	DebugRecord rows
LearnedMemoryStore	learned-memory.db	project-level DB	LearnedMemory rows
Logger	user and developer logs	redaction/encryption policy	air.log, encrypted developer log
ProjectScanner	directory tree metadata scan	filesystem metadata only	project scan artifacts/warnings
MigrationManager	schema/version checks and migrations	SQLite, backup repo, PermissionEngine	migration plan/evidence

Main Agent must remain idle-ready and responsive. It never performs long-running background work itself; Scheduler dispatches background tasks to workers.

Scheduler owns TaskGraph loading, dependency resolution, write-area conflict handling, wave planning, retry budgets, child worker dispatch, heartbeat monitoring, workspace merge coordination, and restart recovery.

Capability lifecycle:

discovered
  → validated
  → doctor_checked
  → enabled
  → registered
  → active
  → disabled | failed | updated

Trust levels:

built_in | project_local | user_installed | verified_publisher | untrusted

Built-in and local manifests still pass schema validation and permission checks. Trust affects default enablement and prompt posture; it never bypasses ToolRegistry or PermissionEngine.

7. Runtime Agent Overview

Agent/role	Process model	Writes project code?	Key inputs	Key outputs
Main Agent	in runtime process	only in direct mode	user messages, projections, context	messages, routing decisions, summaries
Architecture Designer	in runtime process / LLM role	planning docs only	requirement changes, current architecture	impact assessment, plan/doc updates
Scheduler	in runtime process	no code writes	TaskGraph, events, worker results	wave plans, worker dispatch, task outcomes
Executor	child process	yes, scoped	TaskSpec, ContextPack, WorkerRuntime	ExecutorResult, diffs, artifacts, evidence
Reviewer	child process	no	diffs, evidence, architecture context	findings, verdict, follow-up tasks
Debugger	child process	yes if assigned	failure evidence, diagnostics, logs	diagnosis, fix/blocker, debug record
Compactor	child process	no project code	message snapshot, compaction rules	summary row/artifact
ExperienceMiner	child process	rules/skills only if assigned	verified patterns/evidence	memory/rule/skill candidates

Worker loops are independent role implementations, not one generic shared loop.

8. State and Data Overview

8.1 Filesystem layout

Global user directory:

~/.air/
  config.yaml
  models.yaml
  permissions.yaml
  compaction-rules.md
  project-index.db
  cache/
    plugins/
    providers/
    lsp/
    downloads/
  resources/versions/<version>/
  skills/
  logs/
    air.log
    air.developer.log

Project-local directory:

<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/

project_id is a stable UUID generated at project initialization and stored in .air/shared/project.json. It is not derived from the absolute path. .air/local/ is gitignored by default.

8.2 Session DB

session.db lives at .air/local/sessions/<session-id>/session.db and owns recoverable per-session state:

• sessions;
• messages;
• message_drafts;
• events;
• tasks;
• task_dependencies;
• task_attempts;
• agents;
• tool_runs;
• command_runs;
• artifacts;
• diagnostics;
• evidence_refs;
• workspaces;
• summaries;
• ui_state.

Rules:

1. Durable event insert and corresponding domain update occur in one SQLite transaction.
2. EventBus is never recovery source of truth.
3. foreign_keys = OFF is compensated by repository-level invariant checks and startup orphan scans.
4. Artifact files use temp-write → hash/size → atomic rename → DB record.
5. ui_state is not source of truth for runtime state.
6. Messages store Anthropic canonical JSON in content_json with canonical_format = "anthropic".
7. assistant.message.started writes/updates message_drafts; assistant.message.created inserts the final messages row and deletes the draft.
8. V1 does not use a separate message_parts source-of-truth table.
9. Closed enum values are controlled by db-schema-v1.md and require migration review when changed.

FK-off application invariants:

1. tasks.session_id must reference an existing sessions.id.
2. task_attempts.task_id must reference an existing tasks.id.
3. agents.task_id must reference an existing tasks.id when not null.
4. tool_runs.task_id and tool_runs.agent_id must reference existing rows when not null.
5. command_runs.task_id, command_runs.agent_id, and command_runs.tool_run_id must reference existing rows when not null.
6. workspaces.task_id and workspaces.agent_id must reference existing rows when not null.
7. diagnostics.command_run_id and diagnostics.artifact_id must reference existing rows when not null.
8. evidence_refs foreign columns must reference existing rows when not null.

command_runs status is derived, not stored as a physical V1 status column:

Row state	Derived status
completed_at is null	running
exit_code = 0	ok
exit_code non-zero	error
cancellation metadata present	cancelled
inconsistent row	unknown

8.3 Project-level DBs

DB	Purpose	Owner
.air/local/debug-records.db	verified failure/debug knowledge records	DebugKnowledgeStore
.air/local/learned-memory.db	candidates, promoted memories, archived/rejected entries	LearnedMemoryStore

Cross-DB and file writes use outbox/compensation semantics:

1. Insert durable session event recording intent/request.
2. Insert or update session domain row with pending/external status where applicable.
3. Perform external DB/file operation through owning service.
4. Emit durable completed/failed event with evidence.
5. On restart, recovery scans pending external intents and reconciles.

8.4 Artifact and evidence naming

Artifacts use the canonical naming model from artifact-naming-v1.md:

artifact://project/<project-id>/session/<session-id>/<artifact-id>
art_<ulid>
<timestamp>-<artifact-id>-<slug><extension>

Artifact type maps to a session artifact subdirectory. Evidence refs link claims to artifacts, diagnostics, command runs, tool runs, messages, agents, or tasks. Worker results embed full EvidenceRef[] when evidence is part of the conclusion; lightweight events may carry evidence IDs.

9. Event, Error, and Projection Overview

9.1 Event flow

Producer
  → EventIngestor
  → validate envelope, schema, and version
  → durable? EventStore transaction + domain projection + EventBus post-commit publish
  → ephemeral? EventBus publish/coalescing only
  → ProjectionStore applies event
  → TUI/HUD renders ProjectionSnapshot

RuntimeEvent envelope:

id
type
version
timestamp
session_id
project_id?
source
route[]
payload

Rules:

1. route is append-only. Forwarders append their segment and never rewrite earlier entries.
2. route_text in SQLite is derived from route.join("/") for indexing.
3. EventStore decides durable vs ephemeral persistence by event type; producers do not decide ad hoc.
4. Payload schema changes require incrementing the event version for that event type.
5. Durable event insert and same-session domain projection happen in one SQLite transaction.
6. Durable events are published to EventBus only after commit.
7. EventBus handler errors are caught, logged to developer log, and do not propagate to the publisher; the subscription remains active.

Durable events include session/message/task/agent/tool/command/artifact/diagnostic/evidence/context/summary/permission/doctor/requirement/architecture/workspace/memory/debug events.

Ephemeral events include heartbeat, task progress, assistant delta, tool progress, command stdout/stderr deltas, HUD frame rendered.

9.2 Error taxonomy

All tool, event, worker, provider, and command failures use AirError rather than parallel ad hoc error shapes.

AirError carries:

error_id
kind
severity
message
detail?
retryability
semantic_signature
cause_ref?
cause_refs?
user_action?
metadata?

Error kinds:

user_error
project_error
env_error
dependency_error
permission_error
tool_error
command_error
build_error
test_error
static_analysis_error
debug_error
provider_error
model_capability_error
context_error
agent_error
scheduler_error
workspace_error
merge_error
architecture_error
policy_error
system_error
unknown_error

Severity:

info | warning | error | fatal

Retryability:

retryable | retryable_after_change | not_retryable | unknown

semantic_signature is the stable grouping key for repeated failure detection, debug knowledge lookup, and Scheduler retry/debug/escalation routing. Scheduler decisions use error kind, retryability, severity, task scope, permission result, architecture impact, verification evidence, and repetition count.

9.3 ProjectionStore

ProjectionStore rules:

• hydrate from DB on startup/resume;
• apply durable and key ephemeral events;
• coalesce noisy deltas;
• ignore unknown event types;
• never become scheduling/recovery source of truth.

10. Execution Flow Overview

10.1 Startup / open session

CLI
  → load global config/resources
  → locate or initialize project
  → Doctor self-bootstrap and read-only startup check
  → open session.db
  → run schema/recovery checks
  → hydrate ProjectionStore
  → start TUI/HUD
  → Main Agent ready

Doctor fix mode on first startup always asks before applying fixes, even in high-permission mode.

10.2 Main Agent state machine

Main Agent lifecycle:

IDLE
  → CLASSIFYING
  → ANSWERING | DELEGATING | DIRECT_MODE
  → SCHEDULING | ARCHITECTURE_DESIGNING
  → CONFIRMING when user confirmation is needed
  → EXECUTING
  → INTERRUPTING when requirements change mid-execution
  → ARCHITECTURE_REVISING when design-level changes are required
  → SUMMARIZING
  → IDLE

Main Agent state rules:

• IDLE/CLASSIFYING/ANSWERING/CONFIRMING/SUMMARIZING perform no task execution.
• DIRECT_MODE uses permission_template = "main_direct" and writes only to the main workspace.
• EXECUTING is Scheduler-owned; Main Agent reports progress and decisions.
• Requirement changes emit requirement.changed and route to Scheduler/Architecture Designer according to impact.

10.3 Scheduler state machine

Scheduler states:

IDLE
  → LOADING_GRAPH
  → PLANNING_WAVE
  → DISPATCHING
  → MONITORING
  → MERGING
  → REVIEWING
  → RETRYING | DEBUGGING | ESCALATING | BLOCKED | COMPLETED | CANCELLED
  → RECOVERING on restart/lost worker

Scheduler owns:

• runnable task discovery;
• dependency and write-area serialization;
• wave planning;
• workspace assignment;
• model assignment according to constraints;
• worker dispatch;
• heartbeat timeout and lost-worker recovery;
• retry budget enforcement;
• review/debug routing;
• workspace merge and conflict handling;
• architecture/user escalation routing;
• recovery after restart.

10.4 Normal user request

TUI/CLI user message
  → Main Agent records message
  → classify intent
  → answer directly OR route work
  → Architecture Designer if architecture/interface/product impact
  → Scheduler creates TaskSpec records
  → Scheduler computes runnable wave
  → ContextAssembler builds ContextPack
  → WorkerManager starts child worker
  → worker uses WorkerRuntime for events/tools/checkpoints
  → Scheduler collects WorkerResult
  → review/debug/merge/retry/escalate as needed
  → Main Agent reports result with evidence

10.5 Direct mode

/direct
  → Main Agent enters DIRECT_MODE
  → permission_template = main_direct
  → direct ToolRegistry calls, main workspace only
  → events recorded with source.kind = main
/done
  → evidence collection
  → summary
  → IDLE

10.6 Tool call

Agent/worker
  → ToolRegistry.call or IPC tool.call
  → schema validation
  → PermissionEngine.evaluate
  → permission prompt if needed
  → tool.started
  → side effect / command / artifact
  → tool.completed | tool.failed | tool.cancelled
  → ToolResultEnvelope

Tool rules:

• ToolDefinition includes input/output schemas, category, permissions, and streaming flag.
• shell.run is the AirCoding runtime equivalent of a controlled Bash execution primitive.
• call() consumes streaming internally and returns the final ToolResultEnvelope.
• call_streaming() exposes progress events and ends with exactly one final result envelope.

10.7 Review and architecture gate

Ordinary implementation tasks use the normal review path:

WorkerResult
  → Reviewer
  → Scheduler completes/retries/blocks based on ReviewerResult and evidence

Architecture-sensitive work adds an Architecture Designer gate:

WorkerResult
  → Reviewer
  → if architecture-sensitive: Architecture Designer impact/review gate
  → Scheduler combines gates
  → complete | retry | block | replan | ask user

Architecture Designer does not replace Reviewer. Reviewer owns implementation quality, correctness, security, tests, and evidence sufficiency. Architecture Designer owns interface/schema/event/package-boundary/security/runtime-semantics/ADR/C4/plan consistency.

Trigger Architecture Designer gate when any are true:

1. public function/class/module interface changes;
2. DB schema or persisted data shape changes;
3. IPC/event/tool/provider contract changes;
4. package dependency direction or component responsibility changes;
5. runtime semantics, security model, capability trust, or permission boundary changes;
6. ADR/C4/plan/todo architecture artifacts must change;
7. Reviewer emits category = "architecture";
8. worker returns architecture/interface blocker;
9. phase completion requires architecture consistency review;
10. release/final completion requires full architecture consistency review.

Scope impact levels:

implementation
interface
architecture
product
permission
environment
policy

Gate result rule:

Reviewer approved + Architecture gate approved/not_required = may complete
Reviewer changes_requested = retry/debug
Architecture requires_replan = route to Architecture Designer planning
Architecture requires_user_confirmation = Main Agent asks user
Architecture reject_or_escalate = block until explicit decision

10.8 C++ workflow

cpp.detect
  → cpp.cmake.configure
  → cpp.build
  → deterministic DiagnosticParser
  → cpp.test
  → cpp.static.cppcheck
  → cpp.clangd.query when needed
  → Debugger for build/test/debug failures
  → scoped fix loop
  → Reviewer
  → Architecture Designer gate if contracts/schema/events/boundaries changed
  → evidence-backed verification

C++ toolchain rules:

• CMake + Ninja is preferred when available.
• Make fallback is supported.
• compile_commands.json is generated or located when clangd/static analysis requires it.
• clangd is used in CLI/query mode for V1, not hidden inside a language-server UI integration.
• DiagnosticParser in toolchain-cpp performs deterministic extraction and semantic signature generation only.
• LLM-based diagnostic interpretation happens in runtime Debugger/Reviewer context, not inside toolchain-cpp.
• The user experience target is zero-config C++ onboarding where feasible: detect existing project shape before requiring manual .air configuration.

10.9 Claude Code execution discipline

All code-changing execution paths must preserve these runtime-level constraints:

1. Read before edit: fs.edit/fs.patch require a recent read observation or expected file hash.
2. Exact edit: old_string must match exactly; non-unique matches fail unless replace-all is explicit.
3. Conservative patching: changes stay inside TaskSpec scope and write area.
4. No unrelated refactors: workers must not broaden scope to improve nearby code opportunistically.
5. Verification before completion: code-changing WorkerResult cannot be completed unless required verification passed, or skipped verification is explicitly allowed with evidence/risk.
6. Evidence-backed closure: diffs, command outputs, diagnostics, artifacts, or screenshots are linked through evidence refs.
7. Block instead of improvising when product, interface, architecture, permission, environment, or policy decisions are missing.

10.10 TaskSpec and WorkerResult overview

TaskSpec field families:

identity: id, type, title, description
acceptance: acceptance_criteria
scope: write_area, expected_files, allowed_paths, denied_paths
dependencies: hard, soft, conflict, serialization
verification: commands, required, fallback_allowed
constraints: max_turns, soft_timeout_ms, hard_timeout_ms, retry_budget, model_policy, model ids
context_refs: plan_ref, arc_ref, parent results, artifacts
output_contract: ExecutorResult | ReviewerResult | DebuggerResult | CompactorResult | ExperienceMinerResult

WorkerResult field families:

identity: task_id, agent_id, agent_type
status: completed | failed | blocked | cancelled
summary
changed_files
diff_ref
artifacts
verification
risks
follow_up_tasks
evidence_refs
result

Status semantics:

Status	Meaning	Scheduler behavior
completed	Acceptance met and verification policy satisfied	review/merge/complete
failed	Attempt failed due to error and may be retried/debugged according to retryability	retry/debug/fail
blocked	Cannot safely proceed without decision, environment fix, permission, dependency, or architecture assessment	escalate/block
cancelled	Task intentionally stopped	preserve evidence/workspace state

summary is user-facing and scheduler-readable; it must not hide unresolved risks or skipped verification.

11. IPC and Worker Overview

V1 uses NDJSON over stdio between runtime parent and child workers.

IPC envelope fields:

id
direction
kind
timestamp
session_id
agent_id
correlation_id?
protocol_version
payload

Handshake:

1. parent spawns worker process;
2. parent sends agent.start after spawn;
3. worker responds with worker.ready including protocol_version;
4. parent validates protocol version;
5. worker executes role loop;
6. worker returns worker.result, checkpoints, logs, events, and tool calls.

Message categories:

Direction	Kinds
parent → worker	control, tool.result, tool.stream
worker → parent	event, log, tool.call, worker.result, worker.checkpoint, protocol.error

Stdout is NDJSON protocol only. Stderr is for fatal fallback/logging and must not carry protocol messages.

Worker exit codes:

Code	Meaning
0	success
1	task failed
2	worker crashed
3	protocol error
4	cancelled
5	permission/policy blocked

Workers never write SQLite directly and never perform side effects outside parent-mediated tools.

12. Permission and Security Overview

Permission evaluation order:

1. tool capability declaration;
2. permission profile;
3. TaskSpec scope allowed/denied paths;
4. path/command/network risk classification;
5. credential/system-sensitive override;
6. user prompt workflow.

Permission actions:

allow | deny | ask_user | block | refuse | announce_then_run

Grant scopes:

none | once | session | project | global

Path risk categories:

project_source
project_build_output
project_air_shared
project_air_local
project_git_internal
outside_project
credential_or_secret
system_sensitive

Command risk categories:

read_only
build
test
static_analysis
git_read
git_write
destructive
network
system_sensitive
credential_sensitive

Boundary rules:

1. Path policy uses realpath normalization before allow/deny checks; symlink escapes are not allowed by string-prefix checks.
2. .git/ internals are protected from arbitrary write tools; Git operations go through git tools.
3. Build output directories are lower risk than source but still remain scoped by TaskSpec and destructive-command analysis.
4. Runtime-owned writes inside .air/local/ are internal service operations, but user-visible or destructive access still follows permission policy.
5. sudo does not automatically become high risk by string alone; command intent, target path, and system sensitivity determine risk, with safe prompts when uncertain.
6. Static high-risk command patterns are deny/ask by default, with LLM escape hatch only through explicit PermissionEngine reasoning and prompt flow.
7. Project-outside writes require backup where policy says backup_required, usually through .air/local/backups/.
8. Credentials and system-sensitive actions override broad session/project/global allows.
9. Project-level allow does not override TaskSpec scope.
10. Migration, destructive, shared-state, credential, and policy-sensitive operations require explicit user confirmation or block/refuse.

Security invariants:

• LLM output is untrusted until validated by runtime/tool schemas and PermissionEngine;
• provider output cannot directly modify files or run commands;
• credentials are referenced by auth_ref and not copied into events/artifacts;
• no automatic upload of source, logs, screenshots, bundles, pcaps, or artifacts;
• destructive/system-sensitive actions require confirmation or policy block.

13. Context, Memory, and Compaction Overview

Context assembly uses ordered PromptLayers L0-L9 (per prompt-layering-v1.md):

Layer	Name
L0	Runtime invariant
L1	Role / agent mode
L2	Safety and permission policy
L3	Project rules and user preferences
L4	Architecture baseline and current plan
L5	Task specification and acceptance criteria
L6	Relevant code / artifacts / evidence
L7	Recent conversation and decision context
L8	Tool result history / diagnostics
L9	Immediate instruction

Compaction rules:

1. ContextAssembler may request compaction but does not compact itself.
2. Scheduler creates compact task.
3. Compactor snapshots immutable message range.
4. summary.created inserts the summaries row.
5. context.compaction.completed references the created summary.
6. Original messages are preserved for backtracking.

ExperienceMiner triggers:

• debug record created;
• session end;
• N-turn/tool-call interval (default 10);
• stale rule/skill discovered during execution.

Scheduler owns trigger creation. ExperienceMiner never self-triggers. Curator dedup/archive runs as a scheduled mine_experience task.

Experience lifecycle:

candidate.created
  → evidence threshold check
  → user/project policy approval
  → promotion write through owning store
  → memory.promoted or promotion failed
  → rollback/archive if stale or harmful

14. UI/HUD and Provider Overview

TUI is in-process with runtime for V1.0.0 Alpha.

Rules:

• TUI consumes only ProjectionClient and projection contracts;
• UI commands flow through a narrow UiCommandChannel;
• TUI never imports runtime private services;
• TUI never queries SQLite/EventBus directly;
• permission prompts, blockers, evidence, artifacts, and HUD are rendered from ProjectionSnapshot/evidence refs.

OpenCode reuse boundary:

• Reuse visual/component patterns: theme, dialog, modal, toast, keymap, layout, spinner, border, error, markdown, code, diff.
• Do not reuse SDK, sync, session, or business-state logic.

V1.0.0 Alpha UI surfaces:

• conversation;
• task/agent/tool/command progress;
• permission prompt UX with announce_then_run visualization;
• blocker reports;
• evidence display;
• HUD presets: Full / Essential / Minimal;
• read-only provider/model status display;
• CLI command catalog: resume, compact, history, session list, read-only provider list/current, restore.

UI design evidence capability:

• ASCII/wireframe layout sketches for terminal UI planning;
• SVG/textual diagram artifacts where useful;
• screenshot capture and analysis for GUI evidence;
• no automatic upload of screenshots or generated design artifacts.

Provider capability matrix concepts:

provider_kind
quality_tier: frontier | strong | standard | cheap | local | unknown
cost_tier: high | medium | low | free | unknown
context_window_tokens
max_output_tokens
supports
conversion

Provider adapters expose list_models(), validate_model(), optional count_tokens(), and streaming complete(). Provider adapters convert external formats to/from AirCoding's Anthropic canonical internal format and must not silently drop semantic prompt/tool information.

Model/provider rule: runtime provider/model selection is fixed for a running session and must not be changed through TUI shortcuts or CLI commands. Users may inspect current provider/model state, but switching requires starting a new session or editing config before startup. This is a design-stage decision accepted during overview review and should be captured in ADR/detailed design when provider UI is specified.

15. Doctor, Restore, Recovery, and Operations Overview

Doctor self-bootstrap:

1. verify Bun runtime;
2. verify SQLite availability;
3. verify basic shell access;
4. verify .air/ writability;
5. run platform/provider/toolchain/capability/display/network checks.

Doctor modes:

• read-only startup/manual check;
• fix mode under PermissionEngine;
• bundle export with local artifact, no automatic upload.

Restore:

• air restore file <path>;
• air restore time <timestamp>;
• air restore session <session-id>.

Restore uses the git-backed backup repository under .air/local/backups/ and preserves history with a restore commit.

Recovery:

• DB recovery rebuilds scheduler queues from tasks/agents/task_attempts/workspaces;
• lost worker detection emits durable agent.lost;
• orphan artifact scan registers or quarantines files;
• FK-off orphan scan logs and repairs/archive references;
• workspace GC preserves active/conflicted states and cleans merged/abandoned states by retention policy.

Workspace GC policy:

Workspace status	Retention
active	preserve until merge or explicit cancel
merged	preserve 7 days after merged_at, then clean
conflicted	preserve until decision, then move to abandoned
abandoned	preserve 3 days, then clean
cleaned	filesystem artifacts removed; DB row retained

Logging:

• air.log is user-facing and contains redacted operational errors and recovery summaries.
• air.developer.log is encrypted, more detailed, and retained according to policy.
• Logs must redact secrets, auth refs, provider keys, and credential-like values.
• Tool/command failures link log artifacts through evidence refs rather than copying sensitive content into user summaries.

Migration:

1. Detect schema_meta.schema_version on session/project DB open.
2. If migration is needed, build a migration plan and risk summary.
3. Create backup through .air/local/backups/ before migration when required.
4. Ask user for destructive or non-trivial migration confirmation.
5. Apply migration transactionally when SQLite scope allows.
6. Emit migration evidence and recovery instructions.
7. On failure, restore or leave explicit repair state.

Project scanner:

• collects full directory tree metadata with no directory exclusion and no depth limit;
• does not recurse through symlinks by default;
• records permission errors as entries with error metadata;
• does not read file contents during tree scan;
• records special file types without opening them;
• provides progress and cancellation hooks;
• records cycle/mount anomalies as scanner warnings.

Distribution:

binary tarball
  bin/air
  resources/
  LICENSE

Tier-1 Linux x86_64 is release-blocking. Linux arm64 and WSL2 are best-effort/tier-2 according to the cross-platform matrix. Windows-native deep support is not V1.0.0 Alpha release-blocking.

16. Implementation Phase Mapping

Phase	System overview scope
Phase 0	Monorepo skeleton + packages/contracts
Phase 1	.air project/session storage, SQLite, EventStore, ArtifactStore
Phase 2	ToolRegistry, PermissionEngine, built-in tools, CapabilityRegistry
Phase 3	Provider layer, ContextAssembler, prompt resources
Phase 4	Worker IPC, WorkerManager, Scheduler
Phase 5	Complete C++ workflow
Phase 6	ProjectionStore, TUI/HUD, UX surfaces
Phase 7	Main Agent / Architecture Designer / worker role integration
Phase 8	Release gates, Doctor bundle, packaging

Critical serialization:

1. packages/contracts before implementation packages.
2. DB schema before storage/EventStore tests.
3. ToolRegistry + PermissionEngine before side-effect tools/workers.
4. Provider/context contracts before agent prompts.
5. IPC before real worker E2E.
6. Projection contracts before TUI implementation.

ADR alignment checkpoints:

• Monorepo/package boundaries align with the package and C4 decisions.
• IPC/worker process choices align with NDJSON child-process ADRs.
• Permission template and tool trust decisions align with security/capability ADRs.
• Doctor fix/bundle and restore behavior align with decisions-round-2/3.

17. Validation Overview

Minimum release-level validation:

bun install
bun run typecheck
bun test
bun run lint
bun run air -- doctor --read-only
bun run air -- e2e worker-fixture
bun run air -- fixture cpp-build-test
bun run air -- e2e cpp-fix-fixture
bun run air -- e2e cpp-debug-review-fixture
bun run air -- capability validate --all
bun run release:check

Validation categories:

Category	Purpose	Examples
Unit	contract/schema/repository/tool logic	contracts, EventSchemaRegistry, PermissionEngine, path classifier
Integration fixture	deterministic local runtime flows	storage, EventStore, Scheduler graph, IPC fixture, C++ fixture
E2E real LLM	release-level agent behavior	simple edit, C++ debug/fix/review, architecture review gate
UI smoke	TUI/HUD responsiveness and projection rendering	tui startup, permission prompt, evidence view, HUD presets
Release gate	combined Linux tier-1 release readiness	bun run release:check

Additional Alpha UX gates:

bun run air -- e2e direct-mode-fixture
bun test packages/runtime --filter restore
bun run air -- doctor --fix --dry-run
bun run air -- doctor --bundle
bun run air -- tui-smoke --project <fixture>

Skipped gates must record:

• why skipped;
• evidence available;
• risk;
• follow-up task.

18. Open Items for Detailed Design

The following are intentionally left for detailed design and class diagram freeze:

1. exact TypeScript file/module layout per package;
2. final class method signatures beyond public contracts;
3. repository implementation classes and query helpers;
4. EventStore domain projection handler table;
5. WorkerProtocol implementation state machine;
6. CLI command parser structure;
7. TUI component tree and state subscriptions;
8. fixture definitions and test harness layout;
9. release package resource manifest;
10. concrete ProviderAdapter implementation sequence;
11. ADR numbering for design-stage provider/model immutability;
12. exact UI mockups for permission, blocker, evidence, and HUD surfaces.

19. Readiness Decision

The system overview design is complete enough to proceed to detailed design / class diagram freeze after this multi-model audit repair.

Readiness basis:

• P0/P1/P2 overview audit gaps that do not require user decisions are resolved in this document;
• architecture source precedence is stable and all 24 frozen baselines are listed;
• contracts/schema/runtime semantics/error taxonomy/security/capability/artifact models are aligned at overview level;
• system containers and runtime components have clear responsibilities and dependency rules;
• Main Agent, Scheduler, worker, IPC, tool, permission, event, context, and recovery flows have implementation-facing overview semantics;
• implementation phases and serialization points are identified;
• validation gates are explicit.