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
300
AirPlan/docs/architecture/error-taxonomy-v1.md
Normal file
300
AirPlan/docs/architecture/error-taxonomy-v1.md
Normal file
@@ -0,0 +1,300 @@
|
||||
# AirCoding Error Taxonomy V1
|
||||
|
||||
Date: 2026-05-27
|
||||
Status: Canonical error taxonomy for V1.0.0 Alpha skeleton
|
||||
|
||||
This document defines error kinds, severity, retryability, failure signatures, user-facing presentation, and routing rules.
|
||||
|
||||
## 1. Goals
|
||||
|
||||
The error taxonomy must support:
|
||||
|
||||
1. Consistent ToolResult and WorkerResult failures.
|
||||
2. Scheduler retry/block/skip decisions.
|
||||
3. User-facing concise errors.
|
||||
4. Developer diagnostic detail.
|
||||
5. Stable semantic signatures for repeated failure detection.
|
||||
6. Safe distinction between implementation failure and architecture/product blockers.
|
||||
|
||||
## 2. Core Error Contract
|
||||
|
||||
```ts
|
||||
type ErrorKind =
|
||||
| "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"
|
||||
|
||||
type ErrorSeverity = "info" | "warning" | "error" | "fatal"
|
||||
|
||||
type Retryability = "retryable" | "retryable_after_change" | "not_retryable" | "unknown"
|
||||
|
||||
interface AirError {
|
||||
error_id: string
|
||||
kind: ErrorKind
|
||||
severity: ErrorSeverity
|
||||
message: string
|
||||
detail?: string
|
||||
retryability: Retryability
|
||||
semantic_signature: string
|
||||
cause_ref?: EntityRef
|
||||
cause_refs?: EntityRef[]
|
||||
user_action?: string
|
||||
metadata?: Record<string, unknown>
|
||||
}
|
||||
```
|
||||
|
||||
## 3. Error Kind Semantics
|
||||
|
||||
| Kind | Meaning | Default route |
|
||||
|---|---|---|
|
||||
| `user_error` | invalid/contradictory user input or cancelled decision | Main Agent |
|
||||
| `project_error` | project structure/config issue | Main Agent or Doctor |
|
||||
| `env_error` | local environment missing/broken | Doctor |
|
||||
| `dependency_error` | missing or incompatible dependency | Doctor/PermissionEngine |
|
||||
| `permission_error` | action denied or needs confirmation | PermissionEngine/Main Agent |
|
||||
| `tool_error` | tool implementation or validation failure | Scheduler/Debugger |
|
||||
| `command_error` | shell process failed outside build/test classification | Scheduler/Debugger |
|
||||
| `build_error` | build/configure/compile/link failure | Executor/Debugger |
|
||||
| `test_error` | test command failed or assertion failed | Executor/Debugger |
|
||||
| `static_analysis_error` | static analysis found issue or tool failed | Reviewer/Debugger |
|
||||
| `debug_error` | debugger/instrumentation failed | Debugger/Scheduler |
|
||||
| `provider_error` | provider API/network/auth/rate failure | Provider layer/Main Agent |
|
||||
| `model_capability_error` | selected model lacks required feature | Scheduler/provider selector |
|
||||
| `context_error` | context assembly/compaction/retrieval failure | ContextAssembler/Compactor |
|
||||
| `agent_error` | worker protocol/crash/result validation issue | Scheduler |
|
||||
| `scheduler_error` | graph/dispatch/recovery internal issue | Main Agent/developer log |
|
||||
| `workspace_error` | worktree/copy/workspace setup failure | Scheduler |
|
||||
| `merge_error` | merge/patch conflict or copy-back failure | Scheduler/Debugger/Architecture Designer |
|
||||
| `architecture_error` | design/interface mismatch or invalid plan | Architecture Designer |
|
||||
| `policy_error` | safety/security/policy violation | Main Agent/PermissionEngine |
|
||||
| `system_error` | OS/resource/filesystem unexpected failure | Scheduler/Doctor |
|
||||
| `unknown_error` | insufficient classification evidence | Scheduler/Debugger |
|
||||
|
||||
## 4. Severity Semantics
|
||||
|
||||
| Severity | Meaning | User visibility |
|
||||
|---|---|---|
|
||||
| `info` | non-blocking note | usually hidden or progress detail |
|
||||
| `warning` | degraded path or skipped optional gate | shown in final report |
|
||||
| `error` | task/tool failed but system can continue/retry | shown when relevant |
|
||||
| `fatal` | session/graph cannot safely continue | immediately surfaced |
|
||||
|
||||
Severity does not imply retryability. A fatal provider outage may be retryable after user changes provider; a low-severity policy denial may be not retryable.
|
||||
|
||||
## 5. Retryability Rules
|
||||
|
||||
```text
|
||||
retryable → same strategy may succeed
|
||||
retryable_after_change → retry only after model/context/command/permission/env/workspace change
|
||||
not_retryable → route to block/skip/cancel
|
||||
unknown → first failure can be diagnosed, repeated unknown escalates
|
||||
```
|
||||
|
||||
Default retryability by kind:
|
||||
|
||||
| Kind | Default retryability |
|
||||
|---|---|
|
||||
| provider_error | retryable or retryable_after_change |
|
||||
| env_error | retryable_after_change |
|
||||
| dependency_error | retryable_after_change |
|
||||
| permission_error | retryable_after_change |
|
||||
| build_error | retryable_after_change |
|
||||
| test_error | retryable_after_change |
|
||||
| merge_error | retryable_after_change |
|
||||
| architecture_error | not_retryable until architecture decision |
|
||||
| policy_error | not_retryable unless policy changes |
|
||||
| agent_error | retryable_after_change |
|
||||
| scheduler_error | unknown/fatal depending on invariant |
|
||||
|
||||
## 6. Semantic Failure Signature
|
||||
|
||||
Failure signatures are used for retry-loop detection and debug knowledge.
|
||||
|
||||
Signature inputs:
|
||||
|
||||
```text
|
||||
kind
|
||||
normalized tool/command name
|
||||
normalized exit code or provider status
|
||||
primary diagnostic semantic_signature
|
||||
primary file/module path when relevant
|
||||
normalized error message class
|
||||
architecture/policy blocker class when relevant
|
||||
```
|
||||
|
||||
Signature format:
|
||||
|
||||
```text
|
||||
<kind>:<surface>:<class>:<location-or-none>:<hash>
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
```text
|
||||
build_error:cpp.build:undefined_reference:src/foo.cpp:ab12cd34
|
||||
provider_error:llm.complete:rate_limit:none:91fe2300
|
||||
merge_error:git.merge_workspace:patch_conflict:src/main.cpp:3344aa90
|
||||
permission_error:shell.run:system_sensitive:/usr/bin:bb12cc88
|
||||
```
|
||||
|
||||
Do not include volatile data such as timestamps, temp paths, PIDs, random IDs, full absolute home paths, or secret-like strings.
|
||||
|
||||
## 7. Mapping to Task Outcomes
|
||||
|
||||
| Error kind | Common task outcome |
|
||||
|---|---|
|
||||
| build/test/static_analysis | failed, then retry/debug |
|
||||
| permission | blocked unless policy auto-allows |
|
||||
| architecture | blocked and route to Architecture Designer |
|
||||
| provider/model capability | failed or blocked depending fallback availability |
|
||||
| merge/workspace | failed, retry serial/repair, or blocked |
|
||||
| env/dependency | blocked or doctor fix task |
|
||||
| policy | blocked/cancelled |
|
||||
| agent/scheduler/system | failed or fatal blocked |
|
||||
|
||||
WorkerResult status rules:
|
||||
|
||||
1. Use `failed` when the task goal was not achieved but Scheduler can decide retry/skip.
|
||||
2. Use `blocked` when a higher-level decision or external condition is required.
|
||||
3. Use `cancelled` when explicitly stopped.
|
||||
4. Do not label architecture/product impossibility as ordinary failure.
|
||||
|
||||
## 8. User-Facing Error Presentation
|
||||
|
||||
User-facing messages should include:
|
||||
|
||||
```text
|
||||
what failed
|
||||
why it matters
|
||||
what AirCoding tried or can try next
|
||||
whether user decision/action is needed
|
||||
where evidence/report is stored
|
||||
```
|
||||
|
||||
They should not include:
|
||||
|
||||
```text
|
||||
secrets
|
||||
raw huge logs
|
||||
stack traces unless the user asks
|
||||
irrelevant implementation detail
|
||||
```
|
||||
|
||||
Developer detail goes to `air.developer.log` and artifacts.
|
||||
|
||||
## 9. Tool and Command Error Mapping
|
||||
|
||||
ToolResult errors must map into `AirError`.
|
||||
|
||||
```ts
|
||||
interface ToolErrorOutput {
|
||||
error: AirError
|
||||
partial_output?: unknown
|
||||
artifact_ids?: string[]
|
||||
evidence_ref_ids?: string[]
|
||||
}
|
||||
```
|
||||
|
||||
Command failures are classified by purpose:
|
||||
|
||||
| Command purpose | Non-zero exit maps to |
|
||||
|---|---|
|
||||
| `build` | `build_error` |
|
||||
| `test` | `test_error` |
|
||||
| `doctor` | `env_error` or `dependency_error` |
|
||||
| `debug` | `debug_error` or diagnosed target error |
|
||||
| `general` | `command_error` |
|
||||
|
||||
## 10. Provider Error Mapping
|
||||
|
||||
Provider adapter maps provider-specific failures:
|
||||
|
||||
| Provider condition | Error kind |
|
||||
|---|---|
|
||||
| auth failure | `provider_error`, not retryable until config change |
|
||||
| rate limit | `provider_error`, retryable_after_change or retryable after delay |
|
||||
| model not found | `model_capability_error` or `provider_error` |
|
||||
| context too large | `context_error` or `model_capability_error` |
|
||||
| tool use unsupported | `model_capability_error` |
|
||||
| network timeout | `provider_error`, retryable |
|
||||
| malformed model output | `provider_error` or `agent_error` depending boundary |
|
||||
|
||||
## 11. Policy and Security Errors
|
||||
|
||||
Policy errors are not bypassed by retry. They require one of:
|
||||
|
||||
```text
|
||||
user approval within policy
|
||||
permission/profile change
|
||||
architecture/task redesign
|
||||
request refusal/cancellation
|
||||
```
|
||||
|
||||
Security-sensitive details may be summarized in user-facing text and preserved in encrypted developer logs/artifacts when needed.
|
||||
|
||||
## 12. Error Events and Persistence
|
||||
|
||||
Errors appear in:
|
||||
|
||||
```text
|
||||
tool.failed
|
||||
command.failed
|
||||
task.failed
|
||||
task.blocked
|
||||
agent.failed
|
||||
context.compaction.failed
|
||||
doctor.fix.failed
|
||||
```
|
||||
|
||||
Each failure payload should include canonical `AirError` plus evidence refs:
|
||||
|
||||
```text
|
||||
error.kind
|
||||
error.message
|
||||
error.detail when useful
|
||||
error.retryability
|
||||
error.semantic_signature
|
||||
evidence refs
|
||||
```
|
||||
|
||||
Diagnostics table uses `semantic_signature`; not every error is a diagnostic.
|
||||
|
||||
## 13. V1.0.0 Alpha Cut Line
|
||||
|
||||
V1.0.0 Alpha skeleton must implement:
|
||||
|
||||
1. `AirError`, `ErrorKind`, `ErrorSeverity`, `Retryability` contracts.
|
||||
2. Tool/command/provider error mapping.
|
||||
3. Semantic failure signature generation.
|
||||
4. Scheduler retry/block mapping from error kind.
|
||||
5. User-facing vs developer-detail formatting.
|
||||
6. Event payload integration for all failure events.
|
||||
|
||||
Post-MVP:
|
||||
|
||||
```text
|
||||
learned failure classifier
|
||||
cross-session duplicate failure clustering
|
||||
automatic debug knowledge promotion by signature
|
||||
localized user-facing error text
|
||||
provider-specific deep error parsers
|
||||
```
|
||||
Reference in New Issue
Block a user