spb/air Public MIT

1<!--2Projet : AIR — Accounting Intermediate Representation3Auteur : Simon-Pierre Boucher4Contact : contact@spboucher.ai5Fichier : 0001-implementation-language.md6-->78# ADR 0001 — Implementation language: strictly-typed Python first, Rust later if needed910- **Status**: Accepted — 2026-08-0511- **Context**: CLAUDE.md §4 requires choosing between Rust and strictly-typed12  Python after comparative research (see docs/research/ledger-engines.md and13  llvm-architecture.md).1415## Decision1617Phase 1–4 are implemented in **Python 3.11+ with strict typing** (Pydantic v218models, `mypy --strict`-compatible code, frozen dataclasses). A Rust port of19the hot core (AIC passes + invariant verifier) remains an explicit later20option once the spec stabilizes.2122## Rationale23241. **Correctness needs here are logical, not mechanical.** The invariants that25   matter (double-entry balance, exact decimals, determinism) are enforced by26   design (Decimal everywhere, floats rejected at every boundary, verifier27   after every pass) — not by the borrow checker. TigerBeetle-class problems28   (throughput, crash-safety under a million TPS) are not Phase 1 problems.292. **Iteration speed on a moving spec.** AIR/ALSL formats will churn during30   Phases 1–3; Python + Pydantic gives schema evolution, JSON Schema31   generation (`model_json_schema()`), and golden-test iteration far faster.323. **Ecosystem adjacency.** Ingestion (Phase 4) is LLM/OCR tooling, which is33   Python-native; the property-testing story (hypothesis) is mature.344. **Exactness parity.** Python's `decimal.Decimal` provides the same35   fixed-point guarantees as `rust_decimal`; both round via explicit modes.3637## Consequences3839- JSON Schema is generated from the Pydantic types today; when the schema40  stabilizes, the direction flips (schema-first, generated types) per41  CLAUDE.md §3.1.42- Performance-critical kernels (batch compilation, reconciliation) may move43  to Rust behind the same AIR/ALSL contracts; the format, not the code, is44  the interface (see docs/research/llvm-architecture.md, lesson 1).45