AirCoding/AirPlan/docs/architecture/error-taxonomy-v1.md

# 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
```