logistiki

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.1.0] — 2026-07-08

### Added

- **Business event API**: `Logistiki.process/1` as the primary public API.
  Applications publish business events; Logistiki decides whether and how those
  events become accounting entries.
- **Datalog knowledge layer**: `ex_datalog`-backed business rules, accounting
  policies, posting templates, account mappings, and constraints. Datalog
  decides facts; Elixir materializes structs.
- **Accounting policy selection**: policies derived from event properties
  (type, fee type, entity type) — not hard-coded.
- **Template resolution**: posting templates resolve symbolic account roles to
  concrete account codes via Datalog rules with static fallbacks.
- **Hierarchical business entities**: closure-table hierarchy with insert, move,
  cycle prevention, and O(rows) subtree/ancestor queries.
- **Hierarchical virtual accounts**: closure-table hierarchy with leaf-only
  posting, currency requirements, and posting-account validation.
- **Entity-account relationships**: many-to-many with effective dating and
  nine relationship types (`:owner`, `:beneficiary`, `:controller`, etc.).
- **Journals and postings**: internal accounting artifacts generated by the
  runtime, immutable once posted, with idempotency keys and reversals.
- **Ledger invariant validator**: pure Elixir enforcement of debits=credits per
  currency, positive amounts, leaf-only posting accounts, idempotency uniqueness,
  and exact reversal — never depends on Datalog.
- **Simulation ledger backend**: fast, deterministic, DB-backed baseline.
- **Beancount ledger backend**: the accounting oracle via `beancount_ex`.
  Verifies each journal with `Beancount.check/1` before persisting. Uses the
  pure-Elixir engine so no Python installation is required.
- **Projections**: balance (leaf, parent aggregation, entity, entity subtree),
  statement with running balances, trial balance, general ledger, balance sheet,
  income statement — all derived, never stored as truth.
- **Audit evidence**: every pipeline stage recorded as an audit event so
  postings are fully explainable after the fact.
- **Business event persistence**: events stored with raw payload and normalized
  form for replay and audit.
- **Telemetry**: events emitted at each pipeline stage.
- **Structured error model**: `%Logistiki.Error{}` with `code`, `message`,
  `details`, and `stage` for every `{:error, _}` path.
- **Built-in events**: `DepositReceived`, `TransferSettled`, `FeeAssessed`,
  `InterestAccrued`, `RefundIssued`, `InvoicePaid`, `AccountOpened`
  (no-accounting-impact).
- **Demo scenario**: `Logistiki.Demo.run_demo/0` runs all 15 spec steps
  end-to-end.
- **Interactive Livebook**: `docs/livebooks/logistiki_demo.livemd` — a 22-step
  walkthrough using SQLite in-memory (no PostgreSQL required).
- **SQLite support**: optional `ecto_sqlite3` adapter for tests and Livebooks
  via `LOGISTIKI_DB_ADAPTER=sqlite`.
- **CI/CD**: GitHub Actions with Elixir 1.20.2/1.19.5/1.18.4 test matrix,
  Coveralls coverage publishing, and tag-triggered Hex.pm release.
- **Documentation**: 15 guides under `docs/`, full `@doc` and `@typedoc`
  on every public function and type, organized module groups in HexDocs.
- **Property tests**: StreamData-based tests for balanced/unbalanced journals,
  reversal restoration, parent=descendants, posting order invariance, and
  simulation/Beancount agreement.
- **Test coverage**: 92.1% across 318 tests and 6 property tests.

### Dependencies

- `ecto_sql` ~> 3.0
- `postgrex` >= 0.0.0
- `ecto_sqlite3` ~> 0.18 (optional)
- `ex_datalog` ~> 0.5
- `beancount_ex` ~> 0.6
- `decimal` ~> 3.1
- `telemetry` ~> 1.0

### Non-goals for v0.1.0

Payment rails, SWIFT/ISO 20022/ACH, card processing, KYC/AML/sanctions/PEP,
onboarding workflows, a workflow engine, regulatory reporting, PDF statements,
invoicing, tax filing, ERP modules, a blockchain ledger, distributed consensus,
a Phoenix dashboard, and a standalone accountant app.