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

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

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:

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:

<kind>:<surface>:<class>:<location-or-none>:<hash>

Examples:

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:

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:

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.

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:

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:

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:

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:

learned failure classifier
cross-session duplicate failure clustering
automatic debug knowledge promotion by signature
localized user-facing error text
provider-specific deep error parsers