Personal Finance Ledger.osc

---
osc: osc://personal-finance-ledger/local/0.1.0
version: 0.1.0
license: OSC-Open
sha256: a26650044a3586d874779f73990104ea5aaf79e41d713d6f8b676d36aee9389f
---

## § 1 — Intent

A person wants to understand where their money goes without connecting their bank
account to a third-party app. They import bank statement CSVs, categorise transactions,
set budgets, and generate monthly reports — all stored in plain text on their own
machine. The accounting model is double-entry: every transaction has a source and a
destination account, so the books always balance. No Mint, no Plaid, no one else
touching their financial data.

## § 2 — Behavior Contract

**Inputs**
- CSV import: a bank statement CSV with configurable column mapping
- Manual entry: date, amount, source account, destination account, category, notes
- Budget definition: category, monthly limit, rollover policy
- Report request: date range, account filter, category filter, output format

**Outputs**
- Transaction list: filterable, sortable, with running balance
- Monthly report: income vs expenses, spending by category vs budget, net position
- Account balances: current balance per account
- CSV/PDF export of any report
- On CSV import: a preview of parsed transactions with proposed category assignments
  before committing to the ledger

**Invariants**
- The ledger MUST use double-entry accounting: every transaction affects exactly two
  accounts (debit one, credit one); the sum of all account balances MUST always equal zero
- No transaction MUST be deleted; corrections are made via reversal entries
- The ledger storage format MUST be plain text (CSV or a documented plain-text format
  like Ledger CLI / hledger) — human-readable without the tool
- Financial data MUST NOT be transmitted over any network
- Imported transactions MUST be deduplicated: re-importing the same CSV MUST NOT create
  duplicate entries (deduplication by date + amount + description hash)
- All monetary arithmetic MUST use fixed-point or decimal types, never floating-point

## § 3 — Stack Negotiation

**Preferred:** Python (using the `decimal` module for arithmetic) with a local web UI
  or CLI; storage in plain-text Ledger CLI format for maximum interoperability  
**Acceptable:** Rust, Go, any language with decimal arithmetic; SQLite storage with
  documented schema  
**Prohibited:** any financial API or bank connection service; floating-point arithmetic
  for monetary values; any binary storage format not documented in this contract

## § 4 — Data Shape