Oikos Economics Accounting DSL

A typed DSL for stock-flow consistent macroeconomic modelling.

Note	This repository is only the Oikos DSL. OikosBot, the code-analysis GitHub App that used to live beside the DSL, now lives in hyperpolymath/oikosbot.

Oikos provides a surface language for stock-flow consistent (SFC) macroeconomic models in the tradition of Godley & Lavoie (2007). It desugars into Ephapax, inheriting its linear types, Tofte–Talpin regions, and typestate.

The core guarantee:

A model that violates any accounting identity does not compile.

Table of Contents

• Status
• What Oikos gives you
• Quick example
• Building
  • Prerequisites
  • Tasks
• Repository structure
  • Blocked on Ephapax
• Planned ecosystem interoperability
• Specification
• Licence
• References

Status

0.1.0-dev — scaffold only. The AST and type-checking scaffolds are in place. The parser and desugaring pass are in progress; desugaring is blocked on the Ephapax parser milestone.

See DESIGN.adoc for the full architectural decision log and ROADMAP.adoc for the planned milestones.

What Oikos gives you

Guarantee	Mechanism
Stock ≠ Flow	Distinct phantom types; adding them without integration is a type error.
GBP ≠ USD	Currency as a phantom type parameter; FX requires an explicit dated rate.
Period scoping	Fiscal periods are Tofte–Talpin regions; crossing a boundary requires close.
Godley invariant	The column-sum rule is enforced at compile time, not test time.
Instrument lifecycle	Financial contracts progress through typestate; invalid transitions are errors.
Linear transfers	transfer A → B consumes A at the type level; double-counting is impossible.

Quick example

-- Minimal two-sector SFC model (Godley & Lavoie, Model SIM)
model ModelSIM (period: FY2025) {
period FY2025 : FiscalYear from 2025-01-01 to 2025-12-31
account wages : Flow GBP
account taxes : Flow GBP
account deposits : Stock GBP
sector Households { asset deposits }
sector Government { liability deposits }
godley {
| Account | Households | Government |
| wages | + | - |
| taxes | - | + |
| deposits | + | - |
}
transfer wages → deposits { amount: 100.00 GBP }
transfer deposits → taxes { amount: 20.00 GBP }
}

Mismatched Godley columns, currency mixtures, and invalid typestate transitions all produce compiler errors — not runtime panics.

Building

Prerequisites

• Rust ≥ 1.83 (via asdf or rustup)

• just task runner

Tasks

just check # clippy + doc check
just test# full test suite
just fmt # format check (use `just fmt-fix` to apply)
just build # release build
just all # fmt + check + build + test

Repository structure

oikos-economics-accounting-dsl/
├── oikos-syntax/ # AST: stocks, flows, sectors, Godley matrix, instruments
├── oikos-parser/ # Logos lexer + Chumsky parser → oikos-syntax::Model
├── oikos-desugar/ # Desugaring pass → Ephapax IR (blocked: see below)
├── oikos-check/ # Type checker wrapping Ephapax (blocked: see below)
├── spec/SPEC.adoc # Language specification
└── docs/DESIGN.adoc # Architectural decision log

Blocked on Ephapax

The oikos-desugar and oikos-check crates require ephapax-ir and ephapax-typing from the Ephapax project. Those crates are stable; the blocker is Ephapax’s surface-language parser, which is not yet complete. Pre-desugar checks (Godley invariant, instrument typestate reachability) are implemented and runnable today.

Planned ecosystem interoperability

These integrations are design-stage only — nothing is implemented yet. See DESIGN.adoc DR-006, DR-007, DR-008 for rationale and open questions.

Project	Role
Betlang	Stochastic amounts. A MoneyExpr::Stochastic(BetExpr) variant lets transfer amounts be drawn from Betlang distributions. Oikos owns the accounting structure (Godley invariant, linearity); Betlang owns the uncertainty (distributions, Bayesian inference, sampling). The type constraint holds in all branches: Bet[Money[GBP], Money[GBP], Money[GBP]] is still Money[GBP]. Also natural for auction theory: Treasury/gilt auctions extend instrument typestate to Draft → OnAuction → Issued → Settled | Void, with Betlang modelling bid distributions and Oikos recording the balance-sheet effects.
Eclexia	Resource-constrained SFC models. Eclexia’s energy, carbon, and time annotations on transfers answer "what is the carbon cost of this monetary flow?" Eclexia’s LP shadow-price engine supplies marginal resource costs that Oikos can surface as model outputs. Dimensional analysis is shared: both languages treat units as phantom type parameters.
Julia the Viper	Separation of data and control. JtV’s Harvard Architecture (Turing-incomplete data language / Turing-complete control language) maps cleanly onto Oikos’s MoneyExpr layer (total, no effects) vs the model body (Turing-complete expression sequence). JtV purity levels (@total / @pure / @impure) could annotate Oikos expressions and inform the Ephapax linearity checker.

Specification

See spec/SPEC.adoc for:

• Full BNF grammar (draft)

• Type system overview with examples for each of the six semantic requirements

• A complete worked example (Model SIM)

Licence

MPL-2.0. See LICENSE.

(Oikos was originally licensed EUPL-1.2; the estate migrated to MPL-2.0 on 2026-05-22. See [DR-010] in docs/DESIGN.adoc for the rationale.)

References

• Godley, W.A.H. & Lavoie, M. (2007). Monetary Economics. Palgrave Macmillan.

• Godley, W.A.H. & Lavoie, M. (2012). Monetary Economics, 2nd ed.

• Ephapax: https://github.com/hyperpolymath/ephapax