# Architecture Decision Records

ADRs capture the architectural decisions behind the Application SDK — what was chosen, what was rejected, and why. Each record is dated and numbered so the context behind a decision is never lost.

| ADR | Decision |
| --- | --- |
| [ADR-0001](0001-per-app-handlers.md) | Per-App Handlers vs Uber-Handler |
| [ADR-0002](0002-per-app-workers.md) | Per-App Workers vs Uber-Worker |
| [ADR-0003](0003-per-app-observability.md) | Per-App Observability with Correlation-Based Tracing |
| [ADR-0004](0004-build-time-type-safety.md) | Build-Time Type Safety Over Runtime Validation |
| [ADR-0005](0005-infrastructure-abstraction.md) | Abstraction of Underlying Infrastructure |
| [ADR-0006](0006-schema-driven-contracts.md) | Schema-Driven Contracts with Additive Evolution |
| [ADR-0007](0007-apps-as-coordination-unit.md) | Apps as the Unit of Inter-App Coordination |
| [ADR-0008](0008-payload-safe-bounded-types.md) | Payload-Safe Bounded Types in Contracts |
| [ADR-0009](0009-separate-handler-worker-deployments.md) | Separate Handler and Worker Deployments |
| [ADR-0010](0010-async-first-blocking-code.md) | Async-First Design and Blocking Code Pitfalls |
| [ADR-0011](0011-logging-level-guidelines.md) | Logging Level Guidelines |
| [ADR-0012](0012-observability-consolidation.md) | Observability Consolidation |
| [ADR-0013](0013-error-hierarchy-and-failure-taxonomy.md) | Error Hierarchy and Failure Taxonomy |
| [ADR-0014](0014-two-store-storage-architecture.md) | Two-Store Storage Architecture (task-to-task vs app-to-app) |
| [ADR-0015](0015-directory-listing-race-fix.md) | Directory Listing Race Fix (safe_list_directory primitive) |
| [ADR-0016](0016-multi-pool-worker-routing.md) | Multi-Pool Worker Routing (N pools per app, @task(pool=...) static affinity) |
| [ADR-0017](0017-native-execution-isolation.md) | Native Execution Isolation (best-effort work in an isolated process; run_fault_isolated / run_best_effort, conformance rule P036) |
| [ADR-0018](0018-progress-aware-heartbeat.md) | Progress-Aware Stall Watchdog and Duration-Backstop Timeouts (in-process no-progress watchdog; heartbeat_timeout unchanged; start_to_close = backstop) |
