SPB Git
spboucher.ai

spb/air

Public MIT

AIR — The Language of Accounting.

languageaccountingcompiler

AIR v0.1.0 — Accounting Intermediate Representation

The language of accounting: LLMs produce economic events (AIR), a
deterministic compiler (AIC) produces balanced journal entries under
versioned, source-cited ALSL policies.

All six phases complete:
- Phase 0: 9 cited research reports (GST/QST from official sources,
  LLVM architecture, ledger engines, ERP APIs, camt.053/MT940, ...)
- Phase 1: AIR v0.1 schema, provenance graph (accounting SSA),
  double-entry invariant verified after every pass, 21 golden cases
- Phase 2: incremental compilation (content-fingerprint diff,
  reversal + replacement entries)
- Phase 3: QuickBooks backend (100% offline-tested mock transport),
  managed AIR home (hash-chained ledger, document archive)
- Phase 4: LLM ingestion with confidence routing + human approval inbox
- Phase 5: agent syscalls + hash-chained audit log, closed periods
- Phase 6: fusion/netting/duplicate passes, bank reconciliation
  (camt.053, MT940 with integrity check, CSV)

99 offline tests + 2 opt-in live tests. No floats, no rules in code,
append-only everything.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
simon-pierre boucher committed (Aug 5, 2026) Browse files

98 changed files +11,076 −0

98 changed files
Load all 98 files Unified Split
added .github/workflows/ci.yml +49 −0
@@ -0,0 +1,49 @@
1+# Projet : AIR — Accounting Intermediate Representation
2+# Auteur : Simon-Pierre Boucher
3+# Contact : contact@spboucher.ai
4+# CI: offline test suite (no API keys) + author-header gate on every push/PR.
5+
6+name: CI
7+
8+on:
9+ push:
10+ branches: [main]
11+ pull_request:
12+
13+jobs:
14+ test:
15+ runs-on: ubuntu-latest
16+ strategy:
17+ fail-fast: false
18+ matrix:
19+ python-version: ["3.11", "3.12", "3.13"]
20+ steps:
21+ - uses: actions/checkout@v4
22+ - uses: actions/setup-python@v5
23+ with:
24+ python-version: ${{ matrix.python-version }}
25+ - name: Install
26+ run: pip install -e ".[dev]"
27+ - name: Author-header gate
28+ run: python scripts/check_headers.py
29+ - name: Offline test suite (99 tests — no network, no API keys)
30+ run: pytest tests/ -q --ignore=tests/test_llm_live.py
31+
32+ golden-determinism:
33+ # compile the demo document twice on a fresh interpreter each time:
34+ # byte-identical CSV output or the build fails
35+ runs-on: ubuntu-latest
36+ steps:
37+ - uses: actions/checkout@v4
38+ - uses: actions/setup-python@v5
39+ with:
40+ python-version: "3.12"
41+ - name: Install
42+ run: pip install -e .
43+ - name: Determinism check
44+ run: |
45+ python -m sdk.cli compile tests/fixtures/demo_document.yaml \
46+ --policies alsl/policies/ca-qc-2026.yaml --backend csv --out out_a
47+ python -m sdk.cli compile tests/fixtures/demo_document.yaml \
48+ --policies alsl/policies/ca-qc-2026.yaml --backend csv --out out_b
49+ diff out_a/*.csv out_b/*.csv && echo "byte-identical: OK"
added .gitignore +17 −0
@@ -0,0 +1,17 @@
1+__pycache__/
2+*.pyc
3+.venv/
4+.pytest_cache/
5+.hypothesis/
6+.mypy_cache/
7+out/
8+books/
9+dist/
10+build/
11+*.egg-info/
12+.DS_Store
13+
14+.env
15+books/
16+out_a/
17+out_b/
added CLAUDE.md +320 −0
@@ -0,0 +1,320 @@
1+# CLAUDE.md — Projet AIR (Accounting Intermediate Representation)
2+
3+> **Auteur du projet : Simon-Pierre Boucher — contact@spboucher.ai**
4+> Ce fichier est la source de vérité pour Claude Code. Lis-le intégralement avant toute action.
5+
6+---
7+
8+## 0. RÈGLE ABSOLUE — En-tête obligatoire de chaque fichier
9+
10+**CHAQUE fichier créé ou modifié dans ce projet DOIT commencer par un en-tête d'auteur.**
11+Aucune exception : code source, tests, docs, scripts, configs, schémas, notebooks.
12+
13+### Formats selon le type de fichier
14+
15+**Python (.py)**
16+```python
17+# =============================================================================
18+# Projet : AIR — Accounting Intermediate Representation
19+# Auteur : Simon-Pierre Boucher
20+# Contact : contact@spboucher.ai
21+# Fichier : <nom_du_fichier>
22+# Description : <une ligne décrivant le rôle du fichier>
23+# =============================================================================
24+```
25+
26+**TypeScript / JavaScript / Rust / Go / C / Zig (.ts, .js, .rs, .go, .c, .zig)**
27+```ts
28+// =============================================================================
29+// Projet : AIR — Accounting Intermediate Representation
30+// Auteur : Simon-Pierre Boucher
31+// Contact : contact@spboucher.ai
32+// Fichier : <nom_du_fichier>
33+// Description : <une ligne>
34+// =============================================================================
35+```
36+
37+**Markdown (.md)**
38+```markdown
39+<!--
40+Projet : AIR — Accounting Intermediate Representation
41+Auteur : Simon-Pierre Boucher
42+Contact : contact@spboucher.ai
43+Fichier : <nom_du_fichier>
44+-->
45+```
46+
47+**YAML / TOML / config (.yaml, .yml, .toml)**
48+```yaml
49+# Projet : AIR — Accounting Intermediate Representation
50+# Auteur : Simon-Pierre Boucher
51+# Contact : contact@spboucher.ai
52+```
53+
54+**JSON** : le format JSON n'accepte pas les commentaires. Ajouter une clé au niveau racine :
55+```json
56+{ "_author": "Simon-Pierre Boucher <contact@spboucher.ai>", ... }
57+```
58+
59+**SQL (.sql)**
60+```sql
61+-- =============================================================================
62+-- Projet : AIR | Auteur : Simon-Pierre Boucher | contact@spboucher.ai
63+-- =============================================================================
64+```
65+
66+✅ Avant de terminer toute tâche, vérifie que tous les fichiers touchés portent l'en-tête.
67+✅ Ajoute un hook / script `scripts/check_headers.py` qui échoue en CI si un fichier n'a pas l'en-tête.
68+
69+---
70+
71+## 1. RÈGLE ABSOLUE — Recherche web intensive AVANT de coder
72+
73+Ce projet touche des domaines où tes connaissances peuvent être incomplètes ou périmées : normes comptables, fiscalité, API des ERP, design de compilateurs. **Tu ne dois JAMAIS deviner.**
74+
75+### Protocole de recherche obligatoire
76+
77+Avant chaque nouveau module ou décision de design importante :
78+
79+1. **Fais au minimum 3 à 5 recherches web ciblées** sur le sujet (spécifications, docs officielles, articles récents, RFC, standards existants).
80+2. **Consulte les sources primaires** : documentation officielle des ERP (SAP, QuickBooks, Xero, Odoo, Oracle NetSuite, Sage, Dynamics), sites gouvernementaux (ARC/Revenu Québec pour TPS/TVQ, IRS pour sales tax US), sites des normalisateurs (IFRS Foundation, FASB pour US GAAP, CPA Canada pour ASPE).
81+3. **Documente tes trouvailles** dans `docs/research/<sujet>.md` (avec en-tête auteur) : sources, dates de consultation, résumé, décisions prises.
82+4. **Vérifie l'existant** : avant d'inventer un format, recherche les standards déjà en place (voir §1.1) pour t'en inspirer ou t'y aligner.
83+5. Si une info fiscale ou normative est incertaine ou pourrait avoir changé : **recherche web obligatoire**, jamais de mémoire seule.
84+
85+### 1.1 Sujets à rechercher intensivement (checklist de démarrage)
86+
87+- [ ] **Standards de données comptables existants** : XBRL / XBRL-GL, ISO 20022, UBL (Universal Business Language), Peppol, OFX, camt.053, EDIFACT, hledger/beancount/ledger-cli (plain text accounting), REA ontology (Resources-Events-Agents), ValueFlows, OpenCorporates schemas.
88+- [ ] **Architecture LLVM** : structure de l'IR, forme SSA, pass manager, backends, tablegen — pour transposer correctement les concepts.
89+- [ ] **API ERP** : SAP OData/BAPI/IDoc, QuickBooks Online API (JournalEntry, Invoice, Payment), Xero Accounting API, Odoo XML-RPC/ORM, NetSuite SuiteTalk, Sage Intacct.
90+- [ ] **Normes comptables** : IFRS (IFRS 15 revenus, IFRS 16 locations, IAS 21 devises), US GAAP (ASC 606, ASC 842), ASPE canadien (chapitres pertinents).
91+- [ ] **Fiscalité** : TPS/TVQ Canada (taux actuels, règles de lieu de fourniture), sales tax US (nexus, taux par État), TVA UE si pertinent.
92+- [ ] **Event sourcing & double-entry engines** : Martin Fowler (Accounting Patterns), TigerBeetle, Formance Ledger, Modern Treasury, Increase, Stripe Ledger — architectures de grands ledgers.
93+- [ ] **Rapprochement bancaire & formats bancaires** : ISO 20022 camt, MT940, Plaid/Flinks API.
94+- [ ] **Structured outputs LLM** : meilleures pratiques actuelles pour extraction structurée (JSON Schema, tool use, validation).
95+
96+⚠️ Les taux de taxes, seuils de capitalisation, et versions d'API **changent**. Toujours vérifier la date des sources et privilégier les documents officiels récents.
97+
98+---
99+
100+## 2. Vision du projet
101+
102+AIR est à la comptabilité ce que LLVM est à la compilation.
103+
104+**Problème** : chaque ERP (SAP, Oracle, QuickBooks, Xero, Sage, Odoo, Dynamics) réinvente le même modèle comptable. Les LLM sont excellents pour comprendre ("cette facture = 3 ordinateurs payés par Visa") mais peu fiables pour appliquer des centaines de règles comptables/fiscales sans erreur.
105+
106+**Solution** : séparer la *compréhension* (LLM) de l'*application des règles* (compilateur déterministe).
107+
108+```
109+Facture / Email / Banque / POS / API
110+ ↓
111+ LLM (extraction)
112+ ↓
113+ AIR (événement économique, PAS une écriture)
114+ ↓
115+ Passes (validation, taxes, FX, fraude, approbation)
116+ ↓
117+ Compilation déterministe (AIC)
118+ ↓
119+ Backends : SAP | QuickBooks | Xero | Odoo | IFRS | US GAAP | ASPE
120+```
121+
122+**Principe fondamental** : le LLM ne produit JAMAIS une écriture comptable finale. Il produit uniquement de l'AIR. Le compilateur applique les politiques, normes et taxes de façon déterministe, traçable et testable.
123+
124+---
125+
126+## 3. Composants de l'écosystème
127+
128+| Composant | Analogie LLVM | Rôle |
129+|---|---|---|
130+| **AIR** | LLVM IR | Format universel décrivant les événements économiques |
131+| **AIC** | clang/llc | Compilateur AIR → écritures comptables |
132+| **ALSL** | TableGen | Langage déclaratif de règles (politiques, taxes, normes) |
133+| **Backends** | x86/ARM backends | Générateurs SAP, QBO, Xero, Odoo, etc. |
134+| **Passes** | Optimization passes | Validation, fusion, netting, doublons, conformité |
135+| **SDK Agents** | libclang | API standard pour agents IA (syscalls comptables) |
136+| **AIR Kernel** | microkernel | Services : Ledger, Tax, FX, Policy, Period, Audit, Approval, Reporting |
137+
138+### 3.1 AIR — le format
139+
140+Un événement économique (`EconomicEvent`), pas un journal. Exemple cible :
141+
142+```yaml
143+EconomicEvent:
144+ id: evt_01H... # ULID
145+ type: Sale
146+ seller: company:acme
147+ buyer: customer:cust_123
148+ items:
149+ - sku: chair-std
150+ qty: 3
151+ unit_price: {amount: 333.33, currency: CAD}
152+ payment:
153+ method: card.visa
154+ gross: {amount: 1150.00, currency: CAD}
155+ delivery: {status: pending, expected: 2026-09-01}
156+ tax:
157+ jurisdiction: CA-QC
158+ codes: [GST, QST]
159+ meta:
160+ source: {kind: invoice_pdf, uri: "s3://...", ocr_score: 0.97}
161+ llm: {model: "...", confidence: 0.93, reasoning_hash: "sha256:..."}
162+ policy_version: "2026.08"
163+ timestamps: {ingested: ..., approved: null}
164+ approver: null
165+```
166+
167+Exigences du format :
168+- **Schéma formel** (JSON Schema + types Pydantic/TypeScript générés).
169+- **Forme SSA comptable** : chaque montant a une origine unique et traçable (Invoice → Tax → Payment → FX → Settlement → Write-off). Implémenter un graphe de provenance immuable.
170+- **Versionné** : `air_version` dans chaque document ; migrations explicites.
171+- **Immutabilité + diff** : compilation incrémentale — si une facture change, on recompile uniquement le delta (comme Git), avec écritures de contrepassation générées automatiquement.
172+
173+### 3.2 AIC — le compilateur
174+
175+Pipeline de passes ordonnées :
176+
177+```
178+OCR pass → Classification pass → Tax pass → FX pass →
179+Fraud pass → Approval pass → Optimization passes → Posting pass
180+```
181+
182+Passes d'optimisation :
183+- **Fusion** : 50 paiements identiques → 1 batch.
184+- **Netting** : 100 remboursements → compensation.
185+- **Reclassement** : Expense → Asset selon politiques (ex. capitalisation > 5000 $).
186+- **Détection doublons** : hachage + similarité.
187+- **Invariant permanent** : `Assets = Liabilities + Equity` vérifié après CHAQUE passe. Toute violation = échec de compilation avec diagnostic précis (comme les erreurs clang : localisation, cause, suggestion).
188+
189+### 3.3 ALSL — le langage de règles
190+
191+Déclaratif, versionné, testable :
192+
193+```
194+policy capitalization_ca:
195+ when event.type == Purchase and event.amount > 5000 CAD
196+ then classify as Asset(class: equipment)
197+
198+policy tax_quebec:
199+ when event.jurisdiction == CA-QC
200+ then apply GST(5%), QST(9.975%)
201+```
202+
203+⚠️ Les taux ci-dessus sont des exemples — **vérifie les taux actuels par recherche web** avant de les coder, et ne les code JAMAIS en dur dans le moteur : ils vivent dans les policies ALSL versionnées.
204+
205+### 3.4 Backends
206+
207+Chaque backend implémente une interface commune `Backend`:
208+- `capabilities()` — ce que la cible supporte
209+- `compile(journal: CompiledJournal) -> TargetPayload`
210+- `post(payload) -> PostingReceipt`
211+- `reverse(receipt) -> ReversalReceipt`
212+
213+Ordre de développement : **1) Backend générique CSV/journal**, 2) QuickBooks Online (API la plus accessible), 3) Xero, 4) Odoo, 5) SAP (le plus complexe — recherche approfondie requise sur OData/BAPI).
214+
215+### 3.5 SDK Agents — les "syscalls"
216+
217+Les agents IA n'accèdent JAMAIS au grand livre directement. API exclusive :
218+
219+```
220+CreateEconomicEvent() | Validate() | Compile() | Post() | Reverse()
221+Merge() | ClosePeriod() | Reconcile() | GenerateReport()
222+```
223+
224+Chaque appel est journalisé (audit log append-only, hash-chaîné).
225+
226+---
227+
228+## 4. Architecture technique
229+
230+### Stack recommandée (à valider par recherche)
231+- **Cœur (AIR + AIC + passes)** : Rust (fiabilité, typage fort) OU Python typé strict (vitesse de dev). Décision à documenter dans `docs/adr/0001-language.md` après recherche comparative.
232+- **Schémas** : JSON Schema comme source de vérité → génération de types Rust/Python/TS.
233+- **Montants** : JAMAIS de float. Décimal fixe (rust_decimal / Python Decimal), arrondi banker's rounding documenté par juridiction (à vérifier par recherche : règles d'arrondi TPS/TVQ).
234+- **Stockage** : event store append-only (PostgreSQL) + projections.
235+- **ALSL** : parser dédié (pest/lark) ; commencer par un sous-ensemble YAML avant le DSL complet.
236+
237+### Structure du dépôt
238+
239+```
240+air/
241+├── CLAUDE.md
242+├── README.md
243+├── docs/
244+│ ├── adr/ # Architecture Decision Records
245+│ ├── research/ # Résultats de recherches web (OBLIGATOIRE)
246+│ └── spec/ # Spécification formelle AIR / ALSL
247+├── schemas/ # JSON Schemas versionnés
248+├── core/ # AIR types + graphe de provenance
249+├── aic/ # Compilateur + pass manager
250+│ └── passes/
251+├── alsl/ # Parser + évaluateur de règles
252+├── backends/
253+│ ├── generic_csv/
254+│ ├── quickbooks/
255+│ ├── xero/
256+│ └── odoo/
257+├── kernel/ # Services (ledger, tax, fx, policy, audit...)
258+├── sdk/ # SDK agents (syscalls)
259+├── ingestion/ # OCR + extraction LLM → AIR
260+├── tests/
261+│ ├── golden/ # Cas dorés : AIR → écritures attendues
262+│ ├── property/ # Property-based (invariant bilan)
263+│ └── fixtures/ # Factures réelles anonymisées
264+└── scripts/
265+ └── check_headers.py # Vérifie les en-têtes auteur
266+```
267+
268+---
269+
270+## 5. Exigences de qualité non négociables
271+
272+1. **Déterminisme** : même AIR + mêmes policies = mêmes écritures, toujours. Aucun appel LLM dans le compilateur.
273+2. **Invariant comptable** : partie double vérifiée à chaque étape ; property-based testing (hypothesis/proptest) sur `Assets = Liabilities + Equity`.
274+3. **Traçabilité totale** : de chaque ligne d'écriture, on remonte à l'événement source, au document, au score OCR/LLM, à la version de policy, à l'approbateur.
275+4. **Golden tests** : chaque fonctionnalité comptable = cas dorés validés contre des exemples de la littérature comptable (trouvés par recherche web, sources citées).
276+5. **Diagnostics de qualité compilateur** : erreurs précises, localisées, avec suggestions.
277+6. **Aucun taux/seuil en dur** : tout paramètre fiscal ou de politique vit dans ALSL.
278+7. **En-têtes auteur** partout (voir §0), vérifiés en CI.
279+
280+---
281+
282+## 6. Plan de développement par phases
283+
284+**Phase 0 — Recherche (docs/research/)** : compléter la checklist §1.1, produire un rapport par sujet, rédiger les ADR fondateurs (langage, alignement ou non avec XBRL-GL/UBL/REA, modèle de montants).
285+
286+**Phase 1 — Cœur** : schéma AIR v0.1, types, graphe de provenance, invariant bilan, backend CSV générique, 20 golden tests (vente simple, achat, taxes QC, FX, remboursement).
287+
288+**Phase 2 — Compilateur** : pass manager, passes Tax (CA-QC d'abord) / FX / Validation, ALSL v0.1 (YAML), compilation incrémentale (diff + reversal).
289+
290+**Phase 3 — Backend réel** : QuickBooks Online (sandbox), OAuth, idempotence, Post/Reverse.
291+
292+**Phase 4 — Ingestion** : PDF → extraction structurée LLM → AIR, avec scores de confiance et file d'approbation humaine sous seuil.
293+
294+**Phase 5 — Kernel + SDK** : services, syscalls, audit log hash-chaîné, agent de démonstration.
295+
296+**Phase 6 — Optimisations** : fusion, netting, doublons, rapprochement bancaire (camt.053/MT940).
297+
298+---
299+
300+## 7. Workflow de travail attendu de Claude
301+
302+À chaque session :
303+1. Relire ce CLAUDE.md.
304+2. Identifier la tâche → **recherche web d'abord** si le sujet touche normes, taxes, API externes, ou standards.
305+3. Consigner la recherche dans `docs/research/`.
306+4. Écrire les tests avant/avec le code (golden + property).
307+5. Coder avec en-têtes auteur.
308+6. Lancer `scripts/check_headers.py` + suite de tests.
309+7. Mettre à jour la doc/ADR si une décision de design a été prise.
310+
311+### Interdits
312+- ❌ Coder une règle fiscale de mémoire sans source web vérifiée et citée.
313+- ❌ Utiliser des floats pour des montants.
314+- ❌ Laisser le LLM produire des écritures finales.
315+- ❌ Créer un fichier sans l'en-tête Simon-Pierre Boucher / contact@spboucher.ai.
316+- ❌ Casser l'invariant de la partie double, même temporairement.
317+
318+---
319+
320+*Fin du CLAUDE.md — Projet AIR — Simon-Pierre Boucher — contact@spboucher.ai*
added CONTRIBUTING.md +57 −0
@@ -0,0 +1,57 @@
1+<!--
2+Projet : AIR — Accounting Intermediate Representation
3+Auteur : Simon-Pierre Boucher
4+Contact : contact@spboucher.ai
5+Fichier : CONTRIBUTING.md
6+-->
7+
8+# Contributing to AIR
9+
10+Thank you for considering a contribution! AIR has a few **non-negotiable
11+rules** that CI enforces — read them before opening a PR.
12+
13+## The rules (enforced)
14+
15+1. **Author header on every file.** Every source/doc/config file starts with
16+ the project header (see any file for the format). `python scripts/check_headers.py`
17+ must pass — CI fails otherwise.
18+2. **No floats for money — ever.** Amounts, quantities, rates are `Decimal`
19+ in code and strings in JSON/YAML. Floats are rejected at every boundary.
20+3. **No tax rate, threshold, or rounding mode in code.** All fiscal and policy
21+ parameters live in versioned ALSL policy sets with a mandatory source
22+ citation. The loader rejects uncited rates.
23+4. **Research before rules.** Anything touching tax law, accounting standards,
24+ external APIs, or data formats needs a cited report in `docs/research/`
25+ (official sources, consultation dates). Never from memory.
26+5. **The compiler stays deterministic.** No LLM, network, or clock inside AIC.
27+ Same document + same policies = byte-identical journal.
28+6. **The invariant is sacred.** `Assets = Liabilities + Equity` is verified
29+ after every compiler pass. New passes must keep entries balanced.
30+7. **Append-only history.** Corrections are reversal entries; nothing posted
31+ is ever edited or deleted.
32+
33+## Workflow
34+
35+```bash
36+python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
37+.venv/bin/python -m pytest tests/ -q --ignore=tests/test_llm_live.py # offline suite
38+python3 scripts/check_headers.py
39+```
40+
41+- Write tests with the code: golden cases for accounting behavior
42+ (`tests/golden/cases/*.yaml`), property tests for invariants, unit tests
43+ for mechanics.
44+- New event types need: posting rules, golden cases, and a spec update.
45+- New backends implement `backends/base.py` (`capabilities/compile/post/reverse`)
46+ and must be fully testable offline (mock transport pattern —
47+ see `backends/quickbooks/`).
48+- Architecture decisions get an ADR in `docs/adr/`.
49+
50+## What makes a good first contribution
51+
52+- A new ALSL policy set for another jurisdiction (with cited research)
53+- The beancount/hledger export backend (near-free per the research)
54+- Reference-first matching (`EndToEndId`) in reconciliation
55+- A Xero or Odoo backend with an offline mock transport
56+
57+*Author: Simon-Pierre Boucher — contact@spboucher.ai*
added LICENSE +21 −0
@@ -0,0 +1,21 @@
1+MIT License
2+
3+Copyright (c) 2026 Simon-Pierre Boucher <contact@spboucher.ai>
4+
5+Permission is hereby granted, free of charge, to any person obtaining a copy
6+of this software and associated documentation files (the "Software"), to deal
7+in the Software without restriction, including without limitation the rights
8+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+copies of the Software, and to permit persons to whom the Software is
10+furnished to do so, subject to the following conditions:
11+
12+The above copyright notice and this permission notice shall be included in all
13+copies or substantial portions of the Software.
14+
15+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+SOFTWARE.
added README.md +233 −0
@@ -0,0 +1,233 @@
1+<!--
2+Projet : AIR — Accounting Intermediate Representation
3+Auteur : Simon-Pierre Boucher
4+Contact : contact@spboucher.ai
5+Fichier : README.md
6+-->
7+
8+<div align="center">
9+
10+# ⚙️ AIR
11+
12+### The Language of Accounting
13+
14+**LLVM for the ledger** — LLMs understand your documents, a deterministic compiler keeps your books.
15+
16+[![CI](https://github.com/spboucher-ai/air/actions/workflows/ci.yml/badge.svg)](https://github.com/spboucher-ai/air/actions/workflows/ci.yml)
17+[![Python](https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white)](pyproject.toml)
18+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
19+[![Tests](https://img.shields.io/badge/tests-99%20offline%20%2B%202%20live-brightgreen)](tests/)
20+[![Golden cases](https://img.shields.io/badge/golden%20cases-21-gold)](tests/golden/cases/)
21+[![Amounts](https://img.shields.io/badge/floats-forbidden-red)](docs/adr/0003-monetary-amounts.md)
22+[![Double entry](https://img.shields.io/badge/A%20%3D%20L%20%2B%20E-verified%20after%20every%20pass-blueviolet)](core/invariant.py)
23+[![Ledger](https://img.shields.io/badge/ledger-append--only%20%7C%20hash--chained-orange)](kernel/ledger.py)
24+[![Offline first](https://img.shields.io/badge/works%20offline-no%20ERP%2C%20no%20API%20key%20required-informational)](docs/cli-reference.md)
25+
26+*by [Simon-Pierre Boucher](mailto:contact@spboucher.ai)*
27+
28+</div>
29+
30+---
31+
32+## The idea
33+
34+Every ERP reinvents the same accounting model. LLMs are brilliant at *understanding*
35+("this invoice = 3 chairs paid by Visa") and unreliable at *applying* hundreds of
36+tax and accounting rules. **AIR separates the two** — exactly like LLVM separated
37+language frontends from machine backends:
38+
39+```mermaid
40+flowchart LR
41+ A[📄 Invoice / Email<br/>Bank / POS / API] --> B["🧠 LLM<br/><i>understanding</i>"]
42+ B -->|"AIR events<br/>(never journal entries)"| C["⚙️ AIC Compiler<br/><i>deterministic rules</i>"]
43+ P["📜 ALSL Policies<br/>taxes · thresholds · rounding<br/><i>versioned & cited</i>"] --> C
44+ C -->|"balanced entries<br/>+ full provenance"| D["📗 Native Ledger<br/>hash-chained, standalone"]
45+ C --> E["📤 CSV · QuickBooks<br/>Xero · Odoo · SAP*"]
46+ D --> F["📊 Trial balance · Balance sheet<br/>Income statement · GL"]
47+ style B fill:#f9e79f,stroke:#b7950b
48+ style C fill:#aed6f1,stroke:#2471a3
49+ style D fill:#a9dfbf,stroke:#1e8449
50+ style P fill:#f5b7b1,stroke:#c0392b
51+```
52+
53+> **The one rule that never bends:** an LLM (or any frontend) only ever produces
54+> **AIR** — a description of *what happened economically*. It never writes a journal
55+> entry, an account code, or a debit. The compiler does that, deterministically,
56+> with the double-entry invariant `Assets = Liabilities + Equity` verified after
57+> **every** pass and clang-style diagnostics when anything is wrong.
58+
59+## What you get
60+
61+| | |
62+|---|---|
63+| 🗣️ **A universal language** | `EconomicEvent` (REA-based): sales, purchases, refunds, payments, FX — perspective-neutral, schema-validated, no debits anywhere |
64+| ⚙️ **A real compiler** | Pass pipeline (validation → classification → tax → FX → posting), pass manager with verify-after-every-pass, diagnostics with location + cause + `help:` fix |
65+| 📜 **Rules as data (ALSL)** | GST 5%, QST 9.975%, HST, capitalization thresholds, rounding modes — all in versioned YAML policy sets with **mandatory source citations** (the loader rejects uncited rates) |
66+| 🏠 **Standalone books** | No ERP required: managed AIR home with an append-only, tamper-evident ledger, content-addressed document archive, and all financial statements in text/markdown/CSV/JSON |
67+| 🔁 **Git-style corrections** | Changed invoice? `air recompile` diffs by content fingerprint and posts reversal + replacement entries — history is never edited |
68+| 🤖 **An agent SDK** | AI agents get syscalls (`CreateEconomicEvent`, `Post`, `Reverse`, `ClosePeriod`, `Merge`, `Reconcile`…) — never the ledger. Every call, including refusals, lands in a hash-chained audit log |
69+| 🧾 **LLM ingestion** | Invoice text → Claude (structured outputs) → schema-validated AIR → confidence routing → human approval inbox. Fully offline mock for tests |
70+| 🚀 **Optimizations** | 50 identical payments → 1 batch entry (fusion), refund↔sale netting, duplicate detection — provenance preserved through every transformation |
71+| 🏦 **Bank reconciliation** | camt.053 + MT940 (with statement integrity check) + CSV → matched against the books, differences reported on both sides |
72+| 🔍 **Total traceability** | Every posted cent walks back through the provenance graph (accounting SSA) to its source event, document, OCR/LLM confidence, policy version, and rounding mode |
73+
74+## Quickstart
75+
76+```bash
77+git clone https://github.com/spboucher-ai/air && cd air
78+python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
79+source .venv/bin/activate
80+
81+# 1) Your books live in a managed AIR home — one command
82+air init --home books --policies alsl/policies/ca-qc-2026.yaml
83+
84+# 2) Compile economic events into the books (document archived, ledger chained)
85+air compile tests/fixtures/demo_document.yaml --home books \
86+ --report trial-balance --report balance-sheet
87+
88+# 3) A source invoice was corrected? Post only the delta (reversal + replacement)
89+air recompile old.yaml corrected.yaml --home books
90+
91+# 4) Statements any time, any format
92+air report income-statement --home books --format markdown
93+
94+# 5) Ingest a real document (offline extractor; add --llm for Claude)
95+air ingest tests/fixtures/invoice_high_confidence.txt --home books
96+air inbox --home books
97+
98+# 6) Month end
99+air reconcile statement.mt940 --home books
100+air audit --home books
101+```
102+
103+Full command reference: **[docs/cli-reference.md](docs/cli-reference.md)**
104+
105+## Sixty seconds of AIR
106+
107+An economic event — *what happened*, nothing else:
108+
109+```yaml
110+events:
111+ - id: evt_01H8XGJWBW
112+ type: Sale
113+ date: 2026-07-20
114+ parties: {seller: "company:acme", buyer: "customer:cust_123"}
115+ items:
116+ - {sku: chair-std, qty: "3", unit_price: {amount: "333.33", currency: CAD}}
117+ payment: {method: card.visa, immediate: true}
118+ tax: {jurisdiction: CA-QC} # ← where. Rates live in policies, never here
119+```
120+
121+The compiler applies the cited CA-QC policy set (GST 5%, QST 9.975% on the
122+pre-GST price, half-up per Excise Tax Act s.165.2(2)) and emits a balanced entry:
123+
124+```
125+DR 1000 Cash 1149.74
126+ CR 4000 Sales revenue 999.99
127+ CR 2310 GST payable 50.00 tax:GST@0.05~half_up
128+ CR 2320 QST payable 99.75 tax:QST@0.09975~half_up
129+```
130+
131+Same input + same policies = **byte-identical output, always** (property-tested,
132+and CI compiles the demo twice and `diff`s the results). When something is wrong,
133+you get a compiler error, not a wrong number:
134+
135+```
136+error[AIR-E400]: no tax policy in set 'ca-qc' matches jurisdiction 'CA-BC'
137+ --> event evt_x, field tax.jurisdiction
138+ pass: tax
139+ help: add an ALSL tax policy for this jurisdiction or mark the event tax.exempt: true
140+```
141+
142+## Agents keep books through syscalls — and only syscalls
143+
144+```python
145+from sdk.syscalls import AirKernel
146+
147+k = AirKernel("books", actor="agent:alice")
148+k.create_economic_event({...}) # schema-validated draft
149+k.post() # deterministic compile → books (idempotent)
150+k.reverse("je_evt_x") # corrections are contra entries, never edits
151+k.close_period("2026-01") # posting into it now fails with AIR-E700
152+k.merge() # post with netting + payment fusion
153+k.reconcile("statement.mt940") # bank matching
154+```
155+
156+```
157+$ air audit --home books
158+#0000 OK agent:alice CreateEconomicEvent {"event_id": "evt_x", "type": "Sale"}
159+#0001 OK agent:alice Post {"drafts": 1}
160+#0008 ERR agent:alice Post {"drafts": 1} <- error[AIR-E700]: period 2026-01 is closed
161+10 syscalls, hash chain VALID
162+```
163+
164+Refused actions are audited like successful ones. Editing any record breaks the chain.
165+
166+## The seven guarantees
167+
168+1. **Determinism** — no LLM, network, or clock inside the compiler.
169+2. **Double entry** — the invariant is verified after *every* pass; violations abort compilation.
170+3. **Traceability** — provenance graph from every posted line to its source (accounting SSA).
171+4. **No floats** — exact decimals end to end; floats rejected at every boundary.
172+5. **No rules in code** — every rate/threshold lives in cited, versioned ALSL policies.
173+6. **Append-only** — reversals, never edits; ledger and audit log are hash-chained.
174+7. **Human in the loop** — low-confidence or schema-invalid extractions always route to a person.
175+
176+## Repository map
177+
178+| Path | Role | LLVM analogy |
179+|---|---|---|
180+| [`schemas/`](schemas/) | AIR JSON Schema | the IR definition |
181+| [`core/`](core/) | events, Money, provenance, invariants | IR + verifier |
182+| [`aic/`](aic/) | pass manager, passes, diagnostics, incremental | opt/llc |
183+| [`alsl/`](alsl/) | rule language + cited policy sets | TableGen |
184+| [`backends/`](backends/) | native, CSV, QuickBooks (offline-tested) | targets |
185+| [`kernel/`](kernel/) | ledger, reporting, workspace, audit, reconciliation | runtime |
186+| [`sdk/`](sdk/) | CLI, agent syscalls, demo agent | libclang |
187+| [`ingestion/`](ingestion/) | extractors, confidence routing, approval queue | frontend |
188+| [`docs/spec/`](docs/spec/) | **the AIR/ALSL specification** | LangRef |
189+| [`docs/adr/`](docs/adr/) | architecture decision records | — |
190+| [`docs/research/`](docs/research/) | 9 cited research reports (tax law, formats, APIs) | — |
191+| [`tests/`](tests/) | golden cases, property tests, unit + live tests | lit |
192+
193+## Documentation
194+
195+- 📖 **[The AIR Specification](docs/spec/air-spec-v0.1.md)** — the language, the compiler, diagnostics, syscalls, reconciliation
196+- 🧭 **[CLI Reference](docs/cli-reference.md)** — every command with examples
197+- 🏛️ **[ADRs](docs/adr/)** — why Python, why REA events, why rounding is policy
198+- 🔬 **[Research](docs/research/)** — GST/QST from official sources, camt.053/MT940 specs, ERP API surveys, LLVM architecture lessons
199+- 🤝 **[Contributing](CONTRIBUTING.md)** — the non-negotiable rules CI enforces
200+
201+## Development
202+
203+```bash
204+.venv/bin/python -m pytest tests/ -q --ignore=tests/test_llm_live.py # 99 tests, fully offline
205+python3 scripts/check_headers.py # author-header gate
206+
207+# opt-in live LLM tests (cost a few cents)
208+ANTHROPIC_API_KEY=sk-ant-... .venv/bin/python -m pytest tests/test_llm_live.py -v
209+```
210+
211+Everything — including the QuickBooks backend and the LLM ingestion — develops
212+and tests **fully offline**: mock transports simulate the real APIs' documented
213+behaviors (idempotency replay, duplicate errors), so no account or key is ever
214+required to work on AIR.
215+
216+## Roadmap
217+
218+- [x] Phases 0–6: research → core → compiler → backends → ingestion → agent SDK → optimizations & reconciliation *(complete)*
219+- [ ] beancount/hledger export backend
220+- [ ] Xero & Odoo backends (offline mock pattern)
221+- [ ] Reference-first bank matching (`EndToEndId`)
222+- [ ] More jurisdictions as cited ALSL policy sets (US sales tax, EU VAT)
223+- [ ] AIR v0.2: REA commitments (pending deliveries, IFRS 15 performance obligations)
224+
225+---
226+
227+<div align="center">
228+
229+**AIR** — *because your books deserve a compiler.*
230+
231+MIT © 2026 [Simon-Pierre Boucher](mailto:contact@spboucher.ai)
232+
233+</div>
added aic/__init__.py +7 −0
@@ -0,0 +1,7 @@
1+# =============================================================================
2+# Projet : AIR — Accounting Intermediate Representation
3+# Auteur : Simon-Pierre Boucher
4+# Contact : contact@spboucher.ai
5+# Fichier : __init__.py
6+# Description : Package marker.
7+# =============================================================================
added aic/compiler.py +76 −0
@@ -0,0 +1,76 @@
1+# =============================================================================
2+# Projet : AIR — Accounting Intermediate Representation
3+# Auteur : Simon-Pierre Boucher
4+# Contact : contact@spboucher.ai
5+# Fichier : compiler.py
6+# Description : Top-level AIC entry point — AIR document + ALSL policies -> CompiledJournal.
7+# =============================================================================
8+"""compile_document(): the deterministic core of AIR.
9+
10+Same AIR document + same policy set => byte-identical journal, always.
11+No LLM, no network, no clock inside this function.
12+"""
13+from __future__ import annotations
14+
15+from aic.diagnostics import Diagnostic
16+from aic.pass_manager import PassManager
17+from aic.passes.classification import ClassificationPass
18+from aic.passes.fx import FxPass
19+from aic.passes.posting import PostingPass
20+from aic.passes.tax import TaxPass
21+from aic.passes.validation import ValidationPass
22+from aic.unit import CompilationUnit
23+from alsl.model import PolicySet
24+from core.events import AirDocument
25+from core.journal import CompiledJournal
26+
27+DEFAULT_PIPELINE = [
28+ ValidationPass(),
29+ ClassificationPass(),
30+ TaxPass(),
31+ FxPass(),
32+ PostingPass(),
33+]
34+
35+
36+def _optimized_pipeline() -> list:
37+ from aic.passes.optimize import (
38+ DuplicateDetectionPass,
39+ FusionPass,
40+ NettingPass,
41+ )
42+ return [
43+ ValidationPass(),
44+ DuplicateDetectionPass(),
45+ ClassificationPass(),
46+ TaxPass(),
47+ FxPass(),
48+ PostingPass(),
49+ NettingPass(),
50+ FusionPass(),
51+ ]
52+
53+
54+def compile_document(
55+ document: AirDocument,
56+ policies: PolicySet,
57+ pipeline: list | None = None,
58+ optimize: bool = False,
59+) -> tuple[CompiledJournal, list[Diagnostic]]:
60+ """Compile an AIR document into a journal. Raises CompilationError on errors.
61+
62+ optimize=True adds the Phase 6 passes (duplicate detection, netting,
63+ fusion); the invariant is still verified after every pass.
64+ """
65+ if pipeline is None:
66+ pipeline = _optimized_pipeline() if optimize else DEFAULT_PIPELINE
67+ unit = CompilationUnit(document=document, policies=policies)
68+ manager = PassManager(pipeline)
69+ manager.run(unit)
70+ journal = CompiledJournal(
71+ entries=list(unit.entries),
72+ provenance=unit.provenance,
73+ policy_set=policies.name,
74+ policy_version=policies.version,
75+ )
76+ return journal, unit.diagnostics
added aic/diagnostics.py +53 −0
@@ -0,0 +1,53 @@
1+# =============================================================================
2+# Projet : AIR — Accounting Intermediate Representation
3+# Auteur : Simon-Pierre Boucher
4+# Contact : contact@spboucher.ai
5+# Fichier : diagnostics.py
6+# Description : Clang-style diagnostics — precise location, cause, suggestion.
7+# =============================================================================
8+"""Compiler-quality diagnostics for AIC.
9+
10+Modeled on clang: every diagnostic names WHERE (event id / field path),
11+WHAT (computed cause, e.g. the exact imbalance), and HOW TO FIX (suggestion).
12+Errors abort compilation; warnings and notes ride along in the result.
13+"""
14+from __future__ import annotations
15+
16+import enum
17+from dataclasses import dataclass
18+
19+
20+class Severity(enum.Enum):
21+ ERROR = "error"
22+ WARNING = "warning"
23+ NOTE = "note"
24+
25+
26+@dataclass(frozen=True, slots=True)
27+class Diagnostic:
28+ code: str # e.g. "AIR-E101"
29+ severity: Severity
30+ message: str
31+ location: str # e.g. "event evt_01H..., field items[0].unit_price"
32+ suggestion: str | None = None
33+ origin_pass: str | None = None
34+
35+ def render(self) -> str:
36+ head = f"{self.severity.value}[{self.code}]: {self.message}"
37+ lines = [head, f" --> {self.location}"]
38+ if self.origin_pass:
39+ lines.append(f" pass: {self.origin_pass}")
40+ if self.suggestion:
41+ lines.append(f" help: {self.suggestion}")
42+ return "\n".join(lines)
43+
44+
45+class CompilationError(Exception):
46+ """Raised when any ERROR diagnostic is produced; carries all diagnostics."""
47+
48+ def __init__(self, diagnostics: list[Diagnostic]):
49+ self.diagnostics = diagnostics
50+ errors = [d for d in diagnostics if d.severity is Severity.ERROR]
51+ super().__init__(
52+ f"{len(errors)} error(s):\n" + "\n".join(d.render() for d in errors)
53+ )
added aic/incremental.py +154 −0
@@ -0,0 +1,154 @@
1+# =============================================================================
2+# Projet : AIR — Accounting Intermediate Representation
3+# Auteur : Simon-Pierre Boucher
4+# Contact : contact@spboucher.ai
5+# Fichier : incremental.py
6+# Description : Incremental compilation — diff two AIR documents, emit reversal + replacement entries.
7+# =============================================================================
8+"""Incremental compilation (Phase 2).
9+
10+When a source document changes (a corrected invoice, a removed duplicate, a
11+new event), AIR never mutates posted history. Instead, like Git, we diff the
12+old and new documents by event fingerprint and emit:
13+
14+- a REVERSAL entry (exact contra) for every changed or removed event;
15+- a replacement entry (with a revision-suffixed id) for every changed event;
16+- a normal entry for every added event;
17+- nothing for unchanged events.
18+
19+Determinism holds: same (old, new, policies) triple => identical delta.
20+
21+Provenance scoping: reversal lines keep the provenance ids of the prior
22+compilation (they describe the amounts being reversed); the `reverses` field
23+links each contra entry to the original. Replacement/added entries carry the
24+new compilation's provenance graph.
25+"""
26+from __future__ import annotations
27+
28+import hashlib
29+from dataclasses import dataclass, field, replace
30+
31+from aic.compiler import compile_document
32+from aic.diagnostics import CompilationError, Diagnostic, Severity
33+from alsl.model import PolicySet
34+from core.events import AirDocument, EconomicEvent
35+from core.invariant import verify_entries, verify_equation
36+from core.journal import CompiledJournal, JournalEntry, JournalLine, Side
37+
38+
39+def event_fingerprint(event: EconomicEvent) -> str:
40+ """Content hash of an event (canonical JSON, field order fixed by the schema)."""
41+ return hashlib.sha256(event.model_dump_json().encode("utf-8")).hexdigest()
42+
43+
44+@dataclass(frozen=True, slots=True)
45+class DocumentDiff:
46+ added: tuple[str, ...]
47+ removed: tuple[str, ...]
48+ changed: tuple[str, ...]
49+ unchanged: tuple[str, ...]
50+
51+ def is_empty(self) -> bool:
52+ return not (self.added or self.removed or self.changed)
53+
54+
55+def diff_documents(old: AirDocument, new: AirDocument) -> DocumentDiff:
56+ old_fp = {e.id: event_fingerprint(e) for e in old.events}
57+ new_fp = {e.id: event_fingerprint(e) for e in new.events}
58+ added = tuple(i for i in new_fp if i not in old_fp)
59+ removed = tuple(i for i in old_fp if i not in new_fp)
60+ changed = tuple(i for i in new_fp if i in old_fp and new_fp[i] != old_fp[i])
61+ unchanged = tuple(i for i in new_fp if i in old_fp and new_fp[i] == old_fp[i])
62+ return DocumentDiff(added=added, removed=removed, changed=changed,
63+ unchanged=unchanged)
64+
65+
66+def make_reversal(entry: JournalEntry) -> JournalEntry:
67+ """Exact contra of a posted entry (sides swapped, amounts identical)."""
68+ return JournalEntry(
69+ id=f"rev_{entry.id}",
70+ date=entry.date,
71+ description=f"REVERSAL: {entry.description}",
72+ lines=tuple(
73+ JournalLine(
74+ account=line.account,
75+ side=Side.CREDIT if line.side is Side.DEBIT else Side.DEBIT,
76+ amount=line.amount,
77+ memo=f"reversal of {entry.id}: {line.memo}",
78+ provenance_id=line.provenance_id,
79+ )
80+ for line in entry.lines
81+ ),
82+ source_event_id=entry.source_event_id,
83+ policy_set=entry.policy_set,
84+ policy_version=entry.policy_version,
85+ reverses=entry.id,
86+ )
87+
88+
89+@dataclass
90+class IncrementalResult:
91+ """The delta between two compilations: what must be posted on top."""
92+
93+ diff: DocumentDiff
94+ reversals: list[JournalEntry] = field(default_factory=list)
95+ new_entries: list[JournalEntry] = field(default_factory=list)
96+ journal: CompiledJournal = field(default_factory=CompiledJournal) # reversals + new
97+ diagnostics: list[Diagnostic] = field(default_factory=list)
98+
99+
100+def recompile(
101+ old: AirDocument,
102+ new: AirDocument,
103+ policies: PolicySet,
104+) -> IncrementalResult:
105+ """Compile only the delta between two AIR documents.
106+
107+ Both documents are compiled (compilation is cheap and deterministic; the
108+ OLD compile reconstructs exactly what was posted, so no external state is
109+ needed), but the returned journal contains ONLY the delta entries.
110+ """
111+ old_journal, _ = compile_document(old, policies)
112+ new_journal, new_diags = compile_document(new, policies)
113+ diff = diff_documents(old, new)
114+
115+ old_by_event = {e.source_event_id: e for e in old_journal.entries}
116+ new_by_event = {e.source_event_id: e for e in new_journal.entries}
117+ new_fp = {e.id: event_fingerprint(e) for e in new.events}
118+
119+ result = IncrementalResult(diff=diff, diagnostics=list(new_diags))
120+
121+ for event_id in diff.removed + diff.changed:
122+ original = old_by_event.get(event_id)
123+ if original is not None:
124+ result.reversals.append(make_reversal(original))
125+
126+ for event_id in diff.added:
127+ entry = new_by_event.get(event_id)
128+ if entry is not None:
129+ result.new_entries.append(entry)
130+
131+ for event_id in diff.changed:
132+ entry = new_by_event.get(event_id)
133+ if entry is not None:
134+ # revision-suffixed id: deterministic, unique per content revision
135+ revision = new_fp[event_id][:8]
136+ result.new_entries.append(replace(entry, id=f"{entry.id}_r{revision}"))
137+
138+ delta_entries = result.reversals + result.new_entries
139+ result.journal = CompiledJournal(
140+ entries=delta_entries,
141+ provenance=new_journal.provenance,
142+ policy_set=policies.name,
143+ policy_version=policies.version,
144+ )
145+
146+ # the permanent invariant applies to the delta as well
147+ invariant = (
148+ verify_entries(delta_entries, "incremental")
149+ + verify_equation(delta_entries, "incremental")
150+ )
151+ result.diagnostics.extend(invariant)
152+ if any(d.severity is Severity.ERROR for d in result.diagnostics):
153+ raise CompilationError(result.diagnostics)
154+ return result
added aic/pass_manager.py +35 −0
@@ -0,0 +1,35 @@
1+# =============================================================================
2+# Projet : AIR — Accounting Intermediate Representation
3+# Auteur : Simon-Pierre Boucher
4+# Contact : contact@spboucher.ai
5+# Fichier : pass_manager.py
6+# Description : Pass manager — ordered passes, invariant verified after every pass.
7+# =============================================================================
8+"""AIC pass manager.
9+
10+Runs the pass pipeline in order. After EVERY pass, the double-entry invariant
11+(per-entry balance + accounting equation) is verified — the accounting
12+analogue of `opt -verify-each`. Any ERROR diagnostic aborts compilation with
13+a CompilationError carrying clang-style diagnostics.
14+"""
15+from __future__ import annotations
16+
17+from aic.diagnostics import CompilationError, Severity
18+from aic.passes.base import Pass
19+from aic.unit import CompilationUnit
20+from core.invariant import verify_entries, verify_equation
21+
22+
23+class PassManager:
24+ def __init__(self, passes: list[Pass]):
25+ self.passes = passes
26+
27+ def run(self, unit: CompilationUnit) -> CompilationUnit:
28+ for p in self.passes:
29+ unit.diagnostics.extend(p.run(unit))
30+ # the permanent invariant: checked after every pass, no exceptions
31+ unit.diagnostics.extend(verify_entries(unit.entries, p.name))
32+ unit.diagnostics.extend(verify_equation(unit.entries, p.name))
33+ if any(d.severity is Severity.ERROR for d in unit.diagnostics):
34+ raise CompilationError(unit.diagnostics)
35+ return unit
added aic/passes/__init__.py +7 −0
@@ -0,0 +1,7 @@
1+# =============================================================================
2+# Projet : AIR — Accounting Intermediate Representation
3+# Auteur : Simon-Pierre Boucher
4+# Contact : contact@spboucher.ai
5+# Fichier : __init__.py
6+# Description : Package marker.
7+# =============================================================================
added aic/passes/base.py +29 −0
@@ -0,0 +1,29 @@
1+# =============================================================================
2+# Projet : AIR — Accounting Intermediate Representation
3+# Auteur : Simon-Pierre Boucher
4+# Contact : contact@spboucher.ai
5+# Fichier : base.py
6+# Description : Pass interface — every AIC transformation implements this.
7+# =============================================================================
8+"""Base class for AIC passes (LLVM-pass analogue).
9+
10+A pass is a deterministic transformation over the CompilationUnit. It returns
11+diagnostics; it never calls an LLM, the network, or a clock. The pass manager
12+re-verifies the double-entry invariant after every pass.
13+"""
14+from __future__ import annotations
15+
16+import abc
17+
18+from aic.diagnostics import Diagnostic
19+from aic.unit import CompilationUnit
20+
21+
22+class Pass(abc.ABC):
23+ """One deterministic compilation step."""
24+
25+ name: str = "pass"
26+
27+ @abc.abstractmethod
28+ def run(self, unit: CompilationUnit) -> list[Diagnostic]:
29+ """Transform the unit in place; return any diagnostics produced."""
added aic/passes/classification.py +55 −0
@@ -0,0 +1,55 @@
1+# =============================================================================
2+# Projet : AIR — Accounting Intermediate Representation
3+# Auteur : Simon-Pierre Boucher
4+# Contact : contact@spboucher.ai
5+# Fichier : classification.py
6+# Description : Classification pass — applies ALSL classification policies (e.g. capitalization).
7+# =============================================================================
8+"""Classification pass.
9+
10+Decides which account role receives the debit side of a Purchase
11+(expense vs capitalized asset) by evaluating ALSL classification policies —
12+e.g. "capitalize equipment purchases at or above the policy threshold".
13+Thresholds live in ALSL, never here.
14+"""
15+from __future__ import annotations
16+
17+from aic.diagnostics import Diagnostic, Severity
18+from aic.passes.base import Pass
19+from aic.unit import CompilationUnit
20+from alsl.evaluator import applicable_classifications
21+from core.events import EventType
22+
23+
24+class ClassificationPass(Pass):
25+ name = "classification"
26+
27+ def run(self, unit: CompilationUnit) -> list[Diagnostic]:
28+ diags: list[Diagnostic] = []
29+ for event in unit.document.events:
30+ if event.type is not EventType.PURCHASE:
31+ continue
32+ state = unit.event_state(event.id)
33+ if state.subtotal is None:
34+ continue # validation already failed this event
35+
36+ hits = applicable_classifications(unit.policies, event, state.subtotal)
37+ if not hits:
38+ continue
39+ if len(hits) > 1:
40+ diags.append(Diagnostic(
41+ code="AIR-W300", severity=Severity.WARNING,
42+ message=(
43+ "multiple classification policies match: "
44+ + ", ".join(p.name for p in hits)
45+ + f"; applying '{hits[0].name}'"
46+ ),
47+ location=f"event {event.id}",
48+ suggestion="tighten the policies' when-clauses so at most one matches",
49+ origin_pass=self.name,
50+ ))
51+ policy = hits[0]
52+ state.classify_as = policy.classify_as
53+ state.classification_role = policy.account_role
54+ state.classification_policy = policy.name
55+ return diags
added aic/passes/fx.py +148 −0
@@ -0,0 +1,148 @@
1+# =============================================================================
2+# Projet : AIR — Accounting Intermediate Representation
3+# Auteur : Simon-Pierre Boucher
4+# Contact : contact@spboucher.ai
5+# Fichier : fx.py
6+# Description : FX pass — converts to the functional currency; computes settlement gains/losses.
7+# =============================================================================
8+"""FX pass (IAS 21 semantics — see docs/research/accounting-standards.md and
9+docs/research/fx-handling.md).
10+
11+- Transactions in the functional currency pass through (quantized for posting).
12+- Foreign-currency transactions are converted at the event's observed rate
13+ (a fact provided by ingestion, e.g. a Bank of Canada Valet daily rate —
14+ never a constant in code).
15+- Foreign-currency settlements (payments) compare the settlement rate to the
16+ booking rate of the related event and realize an FX gain or loss.
17+Every conversion is a provenance node: "fx:USD->CAD@1.3500".
18+"""
19+from __future__ import annotations
20+
21+from aic.diagnostics import Diagnostic, Severity
22+from aic.passes.base import Pass
23+from aic.unit import CompilationUnit, TaxLineState
24+from core.events import EconomicEvent, EventType
25+from core.money import Money
26+
27+SETTLEMENT_TYPES = (EventType.PAYMENT_RECEIVED, EventType.PAYMENT_SENT)
28+
29+
30+class FxPass(Pass):
31+ name = "fx"
32+
33+ def run(self, unit: CompilationUnit) -> list[Diagnostic]:
34+ diags: list[Diagnostic] = []
35+ functional = unit.policies.functional_currency
36+ rounding = unit.policies.rounding.mode
37+
38+ for event in unit.document.events:
39+ state = unit.event_state(event.id)
40+ if state.subtotal is None or state.subtotal_node is None:
41+ continue
42+ ccy = state.subtotal.currency
43+
44+ if ccy == functional:
45+ state.post_subtotal = state.subtotal.quantized(rounding)
46+ state.post_subtotal_node = state.subtotal_node
47+ state.post_taxes = list(state.taxes)
48+ continue
49+
50+ if event.fx is None:
51+ diags.append(Diagnostic(
52+ code="AIR-E500", severity=Severity.ERROR,
53+ message=(
54+ f"event is in {ccy} but functional currency is {functional} "
55+ "and no fx rate is provided"
56+ ),
57+ location=f"event {event.id}, field fx",
58+ suggestion="attach fx: {rate, source, rate_date} observed on the "
59+ "transaction date (e.g. Bank of Canada Valet)",
60+ origin_pass=self.name,
61+ ))
62+ continue
63+
64+ rate = event.fx.rate
65+ op = f"fx:{ccy}->{functional}@{rate}"
66+
67+ converted = Money(
68+ state.subtotal.amount * rate, functional
69+ ).quantized(rounding)
70+ node = unit.provenance.define(
71+ kind="fx", operation=op, amount=converted,
72+ inputs=(state.subtotal_node,), source_ref=event.fx.source,
73+ )
74+ state.post_subtotal = converted
75+ state.post_subtotal_node = node.id
76+
77+ for tax in state.taxes:
78+ tax_converted = Money(
79+ tax.amount.amount * rate, functional
80+ ).quantized(rounding)
81+ tax_node = unit.provenance.define(
82+ kind="fx", operation=op, amount=tax_converted,
83+ inputs=(tax.node_id,), source_ref=event.fx.source,
84+ )
85+ state.post_taxes.append(TaxLineState(
86+ code=tax.code, amount=tax_converted, node_id=tax_node.id,
87+ payable_role=tax.payable_role,
88+ receivable_role=tax.receivable_role,
89+ recoverable=tax.recoverable, policy=tax.policy,
90+ ))
91+
92+ if event.type in SETTLEMENT_TYPES:
93+ diags.extend(self._settlement_diff(unit, event, rate, functional))
94+ return diags
95+
96+ def _settlement_diff(
97+ self, unit: CompilationUnit, event: EconomicEvent,
98+ settle_rate: object, functional: str,
99+ ) -> list[Diagnostic]:
100+ """Realized FX gain/loss: settlement rate vs the related event's booking rate."""
101+ state = unit.event_state(event.id)
102+ rounding = unit.policies.rounding.mode
103+
104+ if event.related_event is None:
105+ return [Diagnostic(
106+ code="AIR-E501", severity=Severity.ERROR,
107+ message="foreign-currency settlement without related_event: "
108+ "the booking rate cannot be determined",
109+ location=f"event {event.id}, field related_event",
110+ suggestion="reference the Sale/Purchase this payment settles",
111+ origin_pass=self.name,
112+ )]
113+ origin = unit.find_event(event.related_event)
114+ if origin is None or origin.fx is None:
115+ return [Diagnostic(
116+ code="AIR-E502", severity=Severity.ERROR,
117+ message=(
118+ f"related event '{event.related_event}' not found in this "
119+ "document or carries no fx rate"
120+ ),
121+ location=f"event {event.id}, field related_event",
122+ suggestion="compile the settlement together with its origin event, "
123+ "or attach the origin's booking rate",
124+ origin_pass=self.name,
125+ )]
126+
127+ assert state.subtotal is not None and state.subtotal_node is not None
128+ booked = Money(
129+ state.subtotal.amount * origin.fx.rate, functional
130+ ).quantized(rounding)
131+ settled = state.post_subtotal
132+ assert settled is not None and state.post_subtotal_node is not None
133+ diff = settled - booked
134+ state.booked_amount = booked
135+ state.fx_diff = diff
136+ if not diff.is_zero():
137+ node = unit.provenance.define(
138+ kind="fx_realized",
139+ operation=(
140+ f"fx_realized:{state.subtotal.currency}->{functional}"
141+ f"@{settle_rate}-vs-@{origin.fx.rate}"
142+ ),
143+ amount=diff,
144+ inputs=(state.post_subtotal_node,),
145+ source_ref=event.related_event,
146+ )
147+ state.fx_diff_node = node.id
148+ return []
added aic/passes/optimize.py +222 −0
@@ -0,0 +1,222 @@
1+# =============================================================================
2+# Projet : AIR — Accounting Intermediate Representation
3+# Auteur : Simon-Pierre Boucher
4+# Contact : contact@spboucher.ai
5+# Fichier : optimize.py
6+# Description : Optimization passes — duplicate detection, netting, fusion (Phase 6).
7+# =============================================================================
8+"""Optimization passes (the LLVM optimization-pass analogue).
9+
10+Opt-in (compile with optimize=True); the default pipeline is untouched.
11+All three preserve the double-entry invariant, which the pass manager
12+re-verifies after each of them, and full provenance: every optimized line's
13+provenance node points back to the lines it absorbed.
14+
15+- DuplicateDetectionPass — events with identical economic content but
16+ different ids get a warning (AIR-W800); a human decides, nothing is dropped.
17+- NettingPass — a Refund referencing a Sale compiled in the same batch is
18+ netted against it: one net entry (or none, when fully offset) replaces both.
19+- FusionPass — N same-day payments with the same posting shape become one
20+ batch entry (50 identical payouts -> 1 entry, amounts summed per line).
21+"""
22+from __future__ import annotations
23+
24+import hashlib
25+import json
26+from collections import defaultdict
27+from decimal import Decimal
28+
29+from aic.diagnostics import Diagnostic, Severity
30+from aic.passes.base import Pass
31+from aic.unit import CompilationUnit
32+from core.events import EconomicEvent, EventType
33+from core.journal import JournalEntry, JournalLine, Side
34+from core.money import Money
35+
36+
37+def _event_fingerprint(event: EconomicEvent) -> str:
38+ """Economic-content hash: identical business facts, ignoring id and meta."""
39+ payload = json.loads(event.model_dump_json(exclude_none=True))
40+ payload.pop("id", None)
41+ payload.pop("meta", None)
42+ return hashlib.sha256(
43+ json.dumps(payload, sort_keys=True).encode("utf-8")).hexdigest()
44+
45+
46+class DuplicateDetectionPass(Pass):
47+ name = "duplicate-detection"
48+
49+ def run(self, unit: CompilationUnit) -> list[Diagnostic]:
50+ diags: list[Diagnostic] = []
51+ by_content: dict[str, list[str]] = defaultdict(list)
52+ for event in unit.document.events:
53+ by_content[_event_fingerprint(event)].append(event.id)
54+ for ids in by_content.values():
55+ if len(ids) > 1:
56+ diags.append(Diagnostic(
57+ code="AIR-W800", severity=Severity.WARNING,
58+ message=(
59+ f"{len(ids)} events carry identical economic content: "
60+ + ", ".join(ids)
61+ ),
62+ location=f"events {ids[0]} .. {ids[-1]}",
63+ suggestion="if these are duplicates, remove all but one and "
64+ "recompile; if legitimate repeats, add a "
65+ "distinguishing description",
66+ origin_pass=self.name,
67+ ))
68+ return diags
69+
70+
71+class NettingPass(Pass):
72+ """Net Refund entries against the Sale they reverse (same compilation)."""
73+
74+ name = "netting"
75+
76+ def run(self, unit: CompilationUnit) -> list[Diagnostic]:
77+ diags: list[Diagnostic] = []
78+ by_event = {e.source_event_id: e for e in unit.entries}
79+
80+ for event in unit.document.events:
81+ if event.type is not EventType.REFUND or not event.related_event:
82+ continue
83+ refund_entry = by_event.get(event.id)
84+ sale_entry = by_event.get(event.related_event)
85+ if refund_entry is None or sale_entry is None:
86+ continue
87+
88+ # per-(account, sale side): refund lines mirror sale lines, so a
89+ # refund debit offsets the sale's credit on the same account
90+ sale_amts: dict[tuple[str, Side], Money] = {
91+ (l.account.code, l.side): l.amount for l in sale_entry.lines}
92+ refund_amts: dict[tuple[str, Side], Money] = {}
93+ refund_prov: dict[tuple[str, Side], str | None] = {}
94+ for l in refund_entry.lines:
95+ mirrored = Side.CREDIT if l.side is Side.DEBIT else Side.DEBIT
96+ refund_amts[(l.account.code, mirrored)] = l.amount
97+ refund_prov[(l.account.code, mirrored)] = l.provenance_id
98+ if set(refund_amts) - set(sale_amts):
99+ continue # shapes differ; not safely nettable
100+ if any((sale_amts[k] - refund_amts[k]).is_negative()
101+ for k in refund_amts):
102+ continue # refund exceeds sale; leave both entries alone
103+
104+ net_lines: list[JournalLine] = []
105+ for sale_line in sale_entry.lines:
106+ key = (sale_line.account.code, sale_line.side)
107+ refunded = refund_amts.get(key)
108+ net = (sale_line.amount - refunded) if refunded else sale_line.amount
109+ if net.is_zero():
110+ continue
111+ inputs = tuple(p for p in (sale_line.provenance_id,
112+ refund_prov.get(key)) if p)
113+ node = unit.provenance.define(
114+ kind="netting",
115+ operation=f"net:{event.related_event}-{event.id}",
116+ amount=net,
117+ inputs=inputs,
118+ )
119+ net_lines.append(JournalLine(
120+ account=sale_line.account, side=sale_line.side, amount=net,
121+ memo=f"net of {sale_entry.id} minus {refund_entry.id}",
122+ provenance_id=node.id,
123+ ))
124+
125+ unit.entries.remove(sale_entry)
126+ unit.entries.remove(refund_entry)
127+ if net_lines:
128+ unit.entries.append(JournalEntry(
129+ id=f"je_net_{event.related_event}",
130+ date=refund_entry.date,
131+ description=(f"Netting: {sale_entry.description} "
132+ f"minus {refund_entry.description}"),
133+ lines=tuple(net_lines),
134+ source_event_id=f"net({event.related_event},{event.id})",
135+ policy_set=sale_entry.policy_set,
136+ policy_version=sale_entry.policy_version,
137+ ))
138+ detail = "netted into one entry"
139+ else:
140+ detail = "fully offset: no entry posted"
141+ diags.append(Diagnostic(
142+ code="AIR-N801", severity=Severity.NOTE,
143+ message=(f"refund '{event.id}' netted against sale "
144+ f"'{event.related_event}' ({detail})"),
145+ location=f"events {event.related_event}, {event.id}",
146+ origin_pass=self.name,
147+ ))
148+ return diags
149+
150+
151+class FusionPass(Pass):
152+ """Fuse same-day payments with identical posting shape into one batch."""
153+
154+ name = "fusion"
155+ FUSABLE = (EventType.PAYMENT_RECEIVED, EventType.PAYMENT_SENT)
156+
157+ def run(self, unit: CompilationUnit) -> list[Diagnostic]:
158+ diags: list[Diagnostic] = []
159+ events_by_id = {e.id: e for e in unit.document.events}
160+
161+ groups: dict[tuple, list[JournalEntry]] = defaultdict(list)
162+ for entry in unit.entries:
163+ event = events_by_id.get(entry.source_event_id)
164+ if event is None or event.type not in self.FUSABLE:
165+ continue
166+ shape = tuple(sorted(
167+ (l.account.code, l.side.value, l.amount.currency)
168+ for l in entry.lines))
169+ groups[(event.type, entry.date, shape)].append(entry)
170+
171+ for (etype, date, shape), entries in groups.items():
172+ if len(entries) < 2:
173+ continue
174+ summed: dict[tuple[str, str, str], Decimal] = defaultdict(Decimal)
175+ accounts = {}
176+ inputs: dict[tuple[str, str, str], list[str]] = defaultdict(list)
177+ for entry in entries:
178+ for line in entry.lines:
179+ key = (line.account.code, line.side.value,
180+ line.amount.currency)
181+ summed[key] += line.amount.amount
182+ accounts[line.account.code] = line.account
183+ if line.provenance_id:
184+ inputs[key].append(line.provenance_id)
185+
186+ batch_hash = hashlib.sha256(
187+ ",".join(sorted(e.id for e in entries)).encode("utf-8")
188+ ).hexdigest()[:8]
189+ lines = []
190+ for (code, side, ccy), amount in sorted(summed.items()):
191+ money = Money(amount, ccy)
192+ node = unit.provenance.define(
193+ kind="fusion",
194+ operation=f"fuse:{len(entries)}x{etype.value}",
195+ amount=money,
196+ inputs=tuple(inputs[(code, side, ccy)]),
197+ )
198+ lines.append(JournalLine(
199+ account=accounts[code], side=Side(side), amount=money,
200+ memo=f"batch of {len(entries)} {etype.value} entries",
201+ provenance_id=node.id,
202+ ))
203+ for entry in entries:
204+ unit.entries.remove(entry)
205+ unit.entries.append(JournalEntry(
206+ id=f"je_batch_{batch_hash}",
207+ date=date,
208+ description=f"Batch: {len(entries)} x {etype.value}",
209+ lines=tuple(lines),
210+ source_event_id=(
211+ "batch(" + ",".join(e.source_event_id for e in entries) + ")"),
212+ policy_set=entries[0].policy_set,
213+ policy_version=entries[0].policy_version,
214+ ))
215+ diags.append(Diagnostic(
216+ code="AIR-N800", severity=Severity.NOTE,
217+ message=(f"fused {len(entries)} {etype.value} entries dated "
218+ f"{date} into one batch entry (je_batch_{batch_hash})"),
219+ location=f"entries {', '.join(e.id for e in entries)}",
220+ origin_pass=self.name,
221+ ))
222+ return diags
added aic/passes/posting.py +241 −0
@@ -0,0 +1,241 @@
1+# =============================================================================
2+# Projet : AIR — Accounting Intermediate Representation
3+# Auteur : Simon-Pierre Boucher
4+# Contact : contact@spboucher.ai
5+# Fichier : posting.py
6+# Description : Posting pass — lowers economic events into balanced journal entries.
7+# =============================================================================
8+"""Posting pass: the lowering stage (AIR -> journal entries).
9+
10+Maps each economic event to a balanced double-entry journal entry using the
11+account roles defined in the ALSL policy set. Every line carries a provenance
12+node so any posted figure traces back to its origin.
13+
14+Posting rules (v0.1):
15+- Sale DR cash/AR (total) CR revenue, CR tax payables
16+- Refund DR revenue, DR taxes CR cash/AR (mirror of Sale)
17+- Purchase DR expense/asset (+non-recoverable tax), DR recoverable taxes
18+ CR cash/AP
19+- PaymentReceived DR cash (settled) CR AR (booked) [± realized FX]
20+- PaymentSent DR AP (booked) CR cash (settled) [± realized FX]
21+- OwnerContribution DR cash CR owner capital
22+- LoanReceived DR cash CR loan payable
23+"""
24+from __future__ import annotations
25+
26+from aic.diagnostics import Diagnostic, Severity
27+from aic.passes.base import Pass
28+from aic.unit import CompilationUnit, EventState
29+from core.events import EconomicEvent, EventType
30+from core.journal import Account, JournalEntry, JournalLine, Side
31+from core.money import Money
32+
33+
34+class PostingPass(Pass):
35+ name = "posting"
36+
37+ def run(self, unit: CompilationUnit) -> list[Diagnostic]:
38+ diags: list[Diagnostic] = []
39+ for event in unit.document.events:
40+ state = unit.event_state(event.id)
41+ if state.post_subtotal is None:
42+ continue # a previous pass already rejected this event
43+ try:
44+ lines = self._lower(unit, event, state, diags)
45+ except KeyError as exc:
46+ diags.append(Diagnostic(
47+ code="AIR-E600", severity=Severity.ERROR,
48+ message=str(exc.args[0]),
49+ location=f"event {event.id}",
50+ suggestion="add the missing account role to the policy set's "
51+ "accounts section",
52+ origin_pass=self.name,
53+ ))
54+ continue
55+ if not lines:
56+ continue
57+ unit.entries.append(JournalEntry(
58+ id=f"je_{event.id}",
59+ date=event.date,
60+ description=event.description or event.type.value,
61+ lines=tuple(lines),
62+ source_event_id=event.id,
63+ policy_set=unit.policies.name,
64+ policy_version=unit.policies.version,
65+ reverses=(
66+ f"je_{event.related_event}"
67+ if event.type is EventType.REFUND and event.related_event
68+ else None
69+ ),
70+ ))
71+ return diags
72+
73+ # -- helpers ---------------------------------------------------------------
74+ def _line(
75+ self, unit: CompilationUnit, account: Account, side: Side,
76+ amount: Money, memo: str, parent_node: str | None,
77+ ) -> JournalLine:
78+ node = unit.provenance.define(
79+ kind="journal_line",
80+ operation=f"post:{side.value}:{account.code}",
81+ amount=amount,
82+ inputs=(parent_node,) if parent_node else (),
83+ )
84+ return JournalLine(
85+ account=account, side=side, amount=amount,
86+ memo=memo, provenance_id=node.id,
87+ )
88+
89+ def _settlement_account(self, unit: CompilationUnit, event: EconomicEvent,
90+ counterparty_role: str) -> Account:
91+ immediate = bool(event.payment and event.payment.immediate)
92+ return unit.policies.account("cash" if immediate else counterparty_role)
93+
94+ def _check_gross(self, event: EconomicEvent, computed_total: Money,
95+ diags: list[Diagnostic], pass_name: str) -> None:
96+ """Warn when the document's stated gross disagrees with the computed total."""
97+ if event.payment is None or event.payment.gross is None:
98+ return
99+ gross = event.payment.gross.to_money()
100+ if gross.currency != computed_total.currency:
101+ return # gross stated in transaction currency, total in functional
102+ if gross.amount != computed_total.amount:
103+ diags.append(Diagnostic(
104+ code="AIR-W600", severity=Severity.WARNING,
105+ message=(
106+ f"stated gross {gross} differs from computed total "
107+ f"{computed_total}; the computed total is authoritative"
108+ ),
109+ location=f"event {event.id}, field payment.gross",
110+ suggestion="check the source document; a small delta usually means "
111+ "the issuer rounded differently",
112+ origin_pass=pass_name,
113+ ))
114+
115+ # -- lowering per event type -------------------------------------------------
116+ def _lower(
117+ self, unit: CompilationUnit, event: EconomicEvent,
118+ state: EventState, diags: list[Diagnostic],
119+ ) -> list[JournalLine]:
120+ pol = unit.policies
121+ assert state.post_subtotal is not None
122+ subtotal = state.post_subtotal
123+ sub_node = state.post_subtotal_node
124+ taxes = state.post_taxes
125+ total = subtotal
126+ for t in taxes:
127+ total = total + t.amount
128+
129+ if event.type is EventType.SALE:
130+ self._check_gross(event, total, diags, self.name)
131+ counter = self._settlement_account(unit, event, "accounts_receivable")
132+ lines = [self._line(unit, counter, Side.DEBIT, total,
133+ "sale: consideration incl. taxes", sub_node)]
134+ lines.append(self._line(unit, pol.account("revenue"), Side.CREDIT,
135+ subtotal, "sale: revenue", sub_node))
136+ for t in taxes:
137+ lines.append(self._line(
138+ unit, pol.account(t.payable_role), Side.CREDIT, t.amount,
139+ f"{t.code} collected ({t.policy})", t.node_id))
140+ return lines
141+
142+ if event.type is EventType.REFUND:
143+ counter = self._settlement_account(unit, event, "accounts_receivable")
144+ lines = [self._line(unit, pol.account("revenue"), Side.DEBIT,
145+ subtotal, "refund: revenue reversal", sub_node)]
146+ for t in taxes:
147+ lines.append(self._line(
148+ unit, pol.account(t.payable_role), Side.DEBIT, t.amount,
149+ f"{t.code} refunded ({t.policy})", t.node_id))
150+ lines.append(self._line(unit, counter, Side.CREDIT, total,
151+ "refund: consideration incl. taxes", sub_node))
152+ return lines
153+
154+ if event.type is EventType.PURCHASE:
155+ debit_role = state.classification_role or "expense_default"
156+ debit_base = subtotal
157+ recoverable = [t for t in taxes if t.recoverable]
158+ for t in taxes:
159+ if not t.recoverable:
160+ debit_base = debit_base + t.amount # non-recoverable tax is a cost
161+ memo = (
162+ f"purchase: capitalized ({state.classification_policy})"
163+ if state.classify_as == "asset" else "purchase: cost"
164+ )
165+ lines = [self._line(unit, pol.account(debit_role), Side.DEBIT,
166+ debit_base, memo, sub_node)]
167+ for t in recoverable:
168+ lines.append(self._line(
169+ unit, pol.account(t.receivable_role), Side.DEBIT, t.amount,
170+ f"{t.code} recoverable ({t.policy})", t.node_id))
171+ counter = self._settlement_account(unit, event, "accounts_payable")
172+ lines.append(self._line(unit, counter, Side.CREDIT, total,
173+ "purchase: consideration incl. taxes", sub_node))
174+ self._check_gross(event, total, diags, self.name)
175+ return lines
176+
177+ if event.type is EventType.PAYMENT_RECEIVED:
178+ settled = subtotal
179+ booked = state.booked_amount or settled
180+ lines = [self._line(unit, pol.account("cash"), Side.DEBIT, settled,
181+ "payment received", sub_node)]
182+ lines.append(self._line(
183+ unit, pol.account("accounts_receivable"), Side.CREDIT, booked,
184+ f"settles {event.related_event or 'receivable'}", sub_node))
185+ diff = state.fx_diff
186+ if diff is not None and not diff.is_zero():
187+ if diff.is_negative():
188+ lines.append(self._line(unit, pol.account("fx_loss"),
189+ Side.DEBIT, -diff,
190+ "realized FX loss", state.fx_diff_node))
191+ else:
192+ lines.append(self._line(unit, pol.account("fx_gain"),
193+ Side.CREDIT, diff,
194+ "realized FX gain", state.fx_diff_node))
195+ return lines
196+
197+ if event.type is EventType.PAYMENT_SENT:
198+ settled = subtotal
199+ booked = state.booked_amount or settled
200+ lines = [self._line(
201+ unit, pol.account("accounts_payable"), Side.DEBIT, booked,
202+ f"settles {event.related_event or 'payable'}", sub_node)]
203+ diff = state.fx_diff
204+ if diff is not None and not diff.is_zero():
205+ if diff.is_negative():
206+ # paying fewer functional units than booked -> gain
207+ lines.append(self._line(unit, pol.account("fx_gain"),
208+ Side.CREDIT, -diff,
209+ "realized FX gain", state.fx_diff_node))
210+ else:
211+ lines.append(self._line(unit, pol.account("fx_loss"),
212+ Side.DEBIT, diff,
213+ "realized FX loss", state.fx_diff_node))
214+ lines.append(self._line(unit, pol.account("cash"), Side.CREDIT, settled,
215+ "payment sent", sub_node))
216+ return lines
217+
218+ if event.type is EventType.OWNER_CONTRIBUTION:
219+ return [
220+ self._line(unit, pol.account("cash"), Side.DEBIT, subtotal,
221+ "owner contribution", sub_node),
222+ self._line(unit, pol.account("owner_capital"), Side.CREDIT, subtotal,
223+ "owner contribution", sub_node),
224+ ]
225+
226+ if event.type is EventType.LOAN_RECEIVED:
227+ return [
228+ self._line(unit, pol.account("cash"), Side.DEBIT, subtotal,
229+ "loan proceeds", sub_node),
230+ self._line(unit, pol.account("loan_payable"), Side.CREDIT, subtotal,
231+ "loan principal", sub_node),
232+ ]
233+
234+ diags.append(Diagnostic(
235+ code="AIR-E601", severity=Severity.ERROR,
236+ message=f"no posting rule for event type '{event.type.value}'",
237+ location=f"event {event.id}",
238+ suggestion="extend the posting pass or use a supported event type",
239+ origin_pass=self.name,
240+ ))
241+ return []
added aic/passes/tax.py +105 −0
Large diff (105 lines) is not loaded by default to keep the page fast.Load diff
added aic/passes/validation.py +109 −0
Large diff (109 lines) is not loaded by default to keep the page fast.Load diff
added aic/unit.py +81 −0
Large diff (81 lines) is not loaded by default to keep the page fast.Load diff
added alsl/__init__.py +7 −0
Large diff (7 lines) is not loaded by default to keep the page fast.Load diff
added alsl/evaluator.py +46 −0
Large diff (46 lines) is not loaded by default to keep the page fast.Load diff
added alsl/loader.py +144 −0
Large diff (144 lines) is not loaded by default to keep the page fast.Load diff
added alsl/model.py +101 −0
Large diff (101 lines) is not loaded by default to keep the page fast.Load diff
added alsl/policies/ca-qc-2026.yaml +100 −0
Large diff (100 lines) is not loaded by default to keep the page fast.Load diff
added backends/__init__.py +7 −0
Large diff (7 lines) is not loaded by default to keep the page fast.Load diff
added backends/base.py +75 −0
Large diff (75 lines) is not loaded by default to keep the page fast.Load diff
added backends/generic_csv/__init__.py +7 −0
Large diff (7 lines) is not loaded by default to keep the page fast.Load diff
added backends/generic_csv/backend.py +121 −0
Large diff (121 lines) is not loaded by default to keep the page fast.Load diff
added backends/native/__init__.py +7 −0
Large diff (7 lines) is not loaded by default to keep the page fast.Load diff
added backends/native/backend.py +73 −0
Large diff (73 lines) is not loaded by default to keep the page fast.Load diff
added backends/quickbooks/__init__.py +7 −0
Large diff (7 lines) is not loaded by default to keep the page fast.Load diff
added backends/quickbooks/backend.py +94 −0
Large diff (94 lines) is not loaded by default to keep the page fast.Load diff
added backends/quickbooks/mapper.py +114 −0
Large diff (114 lines) is not loaded by default to keep the page fast.Load diff
added backends/quickbooks/transport.py +147 −0
Large diff (147 lines) is not loaded by default to keep the page fast.Load diff
added core/__init__.py +7 −0
Large diff (7 lines) is not loaded by default to keep the page fast.Load diff
added core/document_io.py +43 −0
Large diff (43 lines) is not loaded by default to keep the page fast.Load diff
added core/events.py +178 −0
Large diff (178 lines) is not loaded by default to keep the page fast.Load diff
added core/invariant.py +116 −0
Large diff (116 lines) is not loaded by default to keep the page fast.Load diff
added core/journal.py +90 −0
Large diff (90 lines) is not loaded by default to keep the page fast.Load diff
added core/money.py +121 −0
Large diff (121 lines) is not loaded by default to keep the page fast.Load diff
added core/provenance.py +117 −0
Large diff (117 lines) is not loaded by default to keep the page fast.Load diff
added docs/adr/0001-implementation-language.md +44 −0
Large diff (44 lines) is not loaded by default to keep the page fast.Load diff
added docs/adr/0002-economic-event-model.md +43 −0
Large diff (43 lines) is not loaded by default to keep the page fast.Load diff
added docs/adr/0003-monetary-amounts.md +40 −0
Large diff (40 lines) is not loaded by default to keep the page fast.Load diff
added docs/cli-reference.md +87 −0
Large diff (87 lines) is not loaded by default to keep the page fast.Load diff
added docs/research/accounting-data-standards.md +164 −0
Large diff (164 lines) is not loaded by default to keep the page fast.Load diff
added docs/research/accounting-standards.md +132 −0
Large diff (132 lines) is not loaded by default to keep the page fast.Load diff
added docs/research/bank-statement-formats.md +447 −0
Large diff (447 lines) is not loaded by default to keep the page fast.Load diff
added docs/research/canada-gst-qst.md +240 −0
Large diff (240 lines) is not loaded by default to keep the page fast.Load diff
added docs/research/erp-apis.md +194 −0
Large diff (194 lines) is not loaded by default to keep the page fast.Load diff
added docs/research/fx-handling.md +96 −0
Large diff (96 lines) is not loaded by default to keep the page fast.Load diff
added docs/research/ledger-engines.md +216 −0
Large diff (216 lines) is not loaded by default to keep the page fast.Load diff
added docs/research/llm-structured-extraction.md +116 −0
Large diff (116 lines) is not loaded by default to keep the page fast.Load diff
added docs/research/llvm-architecture.md +204 −0
Large diff (204 lines) is not loaded by default to keep the page fast.Load diff
added docs/spec/air-spec-v0.1.md +240 −0
Large diff (240 lines) is not loaded by default to keep the page fast.Load diff
added ingestion/__init__.py +7 −0
Large diff (7 lines) is not loaded by default to keep the page fast.Load diff
added ingestion/approval.py +134 −0
Large diff (134 lines) is not loaded by default to keep the page fast.Load diff
added ingestion/extractor.py +233 −0
Large diff (233 lines) is not loaded by default to keep the page fast.Load diff
added ingestion/pipeline.py +102 −0
Large diff (102 lines) is not loaded by default to keep the page fast.Load diff
added kernel/__init__.py +7 −0
Large diff (7 lines) is not loaded by default to keep the page fast.Load diff
added kernel/audit.py +88 −0
Large diff (88 lines) is not loaded by default to keep the page fast.Load diff
added kernel/bank_formats.py +222 −0
Large diff (222 lines) is not loaded by default to keep the page fast.Load diff
added kernel/ledger.py +203 −0
Large diff (203 lines) is not loaded by default to keep the page fast.Load diff
added kernel/reconcile.py +139 −0
Large diff (139 lines) is not loaded by default to keep the page fast.Load diff
added kernel/reporting.py +187 −0
Large diff (187 lines) is not loaded by default to keep the page fast.Load diff
added kernel/workspace.py +126 −0
Large diff (126 lines) is not loaded by default to keep the page fast.Load diff
added pyproject.toml +66 −0
Large diff (66 lines) is not loaded by default to keep the page fast.Load diff
added schemas/air-0.1.schema.json +565 −0
Large diff (566 lines) is not loaded by default to keep the page fast.Load diff
added scripts/check_headers.py +74 −0
Large diff (74 lines) is not loaded by default to keep the page fast.Load diff
added sdk/__init__.py +7 −0
Large diff (7 lines) is not loaded by default to keep the page fast.Load diff
added sdk/cli.py +453 −0
Large diff (453 lines) is not loaded by default to keep the page fast.Load diff
added sdk/demo_agent.py +92 −0
Large diff (92 lines) is not loaded by default to keep the page fast.Load diff
added sdk/syscalls.py +230 −0
Large diff (230 lines) is not loaded by default to keep the page fast.Load diff
added tests/__init__.py +7 −0
Large diff (7 lines) is not loaded by default to keep the page fast.Load diff
added tests/fixtures/bank_statement.csv +4 −0
Large diff (4 lines) is not loaded by default to keep the page fast.Load diff
added tests/fixtures/bank_statement.mt940 +9 −0
Large diff (9 lines) is not loaded by default to keep the page fast.Load diff
added tests/fixtures/bank_statement.xml +64 −0
Large diff (64 lines) is not loaded by default to keep the page fast.Load diff
added tests/fixtures/demo_document.yaml +72 −0
Large diff (72 lines) is not loaded by default to keep the page fast.Load diff
added tests/fixtures/invoice_high_confidence.txt +12 −0
Large diff (12 lines) is not loaded by default to keep the page fast.Load diff
added tests/fixtures/invoice_low_confidence.txt +11 −0
Large diff (11 lines) is not loaded by default to keep the page fast.Load diff
added tests/fixtures/invoice_realistic.txt +24 −0
Large diff (24 lines) is not loaded by default to keep the page fast.Load diff
added tests/golden/__init__.py +7 −0
Large diff (7 lines) is not loaded by default to keep the page fast.Load diff
added tests/golden/cases/fx_payments_equity.yaml +181 −0
Large diff (181 lines) is not loaded by default to keep the page fast.Load diff
added tests/golden/cases/purchases.yaml +78 −0
Large diff (78 lines) is not loaded by default to keep the page fast.Load diff
added tests/golden/cases/sales_and_refunds.yaml +148 −0
Large diff (148 lines) is not loaded by default to keep the page fast.Load diff
added tests/golden/test_golden.py +93 −0
Large diff (93 lines) is not loaded by default to keep the page fast.Load diff
added tests/property/__init__.py +7 −0
Large diff (7 lines) is not loaded by default to keep the page fast.Load diff
added tests/property/test_balance_invariant.py +118 −0
Large diff (118 lines) is not loaded by default to keep the page fast.Load diff
added tests/test_core.py +221 −0
Large diff (221 lines) is not loaded by default to keep the page fast.Load diff
added tests/test_incremental.py +128 −0
Large diff (128 lines) is not loaded by default to keep the page fast.Load diff
added tests/test_ingestion.py +152 −0
Large diff (152 lines) is not loaded by default to keep the page fast.Load diff
added tests/test_llm_live.py +74 −0
Large diff (74 lines) is not loaded by default to keep the page fast.Load diff
added tests/test_optimize.py +130 −0
Large diff (130 lines) is not loaded by default to keep the page fast.Load diff
added tests/test_quickbooks.py +140 −0
Large diff (140 lines) is not loaded by default to keep the page fast.Load diff
added tests/test_reconcile.py +164 −0
Large diff (164 lines) is not loaded by default to keep the page fast.Load diff
added tests/test_syscalls.py +188 −0
Large diff (188 lines) is not loaded by default to keep the page fast.Load diff
added tests/test_workspace.py +105 −0
Large diff (106 lines) is not loaded by default to keep the page fast.Load diff
Menu

Theme
↑↓ navigate ↵ open esc close / or ⌘K anywhere