homestead-ledger

Homestead · Affairs — module two. The homesteader keeping their own books.

A self-contained desktop module: it ships to a household who double-clicks it, so its store is embedded SQLite — a linked library, not a server (the face's 2026-08-04 "no listening socket" decision holds; SQLite binds no port). The record layer is the engine's: store.py is a thin binding — homestead.keep.store's adapter contract on a SQLite backing, in the ledger database. It pins the engine from PyPI — homestead-affairs>=0.1.0,<1.0 (the distribution name; import homestead is unchanged) — and shares the ~/.homestead root with homestead-law, because a household's affairs are one thing.

Mirror, not judge

The ledger reflects the household's money; it never authors a financial judgment and never edits a transaction. Concretely, that is the engine's record model applied to money:

• Canonical = the household's own books — imported transactions, statements — read-only by type (I-6). The app has no write path to them.
• Sidecar = the household's overlay — categorization, notes, budget envelopes, a confirmed merchant name. This is where the app writes.
• Money amounts tied to an account are L4; account numbers / SSNs are L5; due-dates and schedules are L1/L2 (see the engine's rung model). The engine enforces this at the storage boundary; a corrupt or unclassified row reads L5 on the way out.

The shared Postgres engine on the fleet side is a sync target reached through the egress gate — never a runtime dependency of the shipped app. Sync is an S4 egress: an L5 record never crosses, and what lands in the shared store is only what the household chose to expose.

Status: bite 0 — the seat is bound. The store binding (homestead.keep.store on a SQLite ledger db), a no-egress AST guard over this package (I-17 — a money ledger must never dial out), CI (cold checkout, engine from PyPI, three OSes), and the build plan (docs/build-plan.md). The books, the "what's due" queue, CSV import, and the app land in the bites that follow.

Entering your own information

The demo (--demo) is synthetic. The household's own books go into the household root — $HOMESTEAD_HOME, else ~/.homestead — and nothing below needs the optional entity extra:

pip install -e .

homestead-ledger ui                                              # entry forms, intake, queue and subscriptions, on localhost
homestead-ledger obligation add rent "Sunrise Properties LLC" 1450.00 2026-10-01 monthly
homestead-ledger obligation list                                 # the list pane: payee, due date, cadence; the amount derives
homestead-ledger obligation show rent                            # the detail pane: the amount renders
homestead-ledger queue                                           # what's due
homestead-ledger transaction add 2026-08-01 -84.23 "Whole Foods Market" --account-number 9821
homestead-ledger transaction list                                # the books, through the gate — the account number is never a row
python -m homestead_ledger --import statement.csv --account-number 9821   # a whole statement
python -m homestead_ledger --import card.csv --account-number 4242 --account credit_card \
  --kind credit_card --liability-columns debit,credit                    # a card statement
python -m homestead_ledger --import statement.csv --account-number 9821 --bank chase   # a slashed date column
homestead-ledger transaction list --gaps                        # rows whose stored date predates this fix
python -m homestead_ledger                                       # the window, on these books (the demo only if empty)

Every imported row's date is parsed to ISO before it is ever written. --bank <name> declares which day/month order that statement's date column is written in (wells-fargo, chase, bank-of-america, capital-one, usaa, discover, amex) and is tried first, so the operator's own declaration is never overruled by a guess from somewhere else; a cell that does not fit it still parses if it is unambiguous on its own (2026-08-01, August 1, 2026, …). A slashed, ambiguous date (08/01/2026) with no bank named is a per-row import error, never a guess, and a refusal names the field rather than echoing the cell. This is what lets the same transaction imported once as 08/01/2026 --bank chase and once as 2026-08-01 dedup as the same row. There is no migration for a transaction already on the books from before this fix with an unparsed, slashed date (v1's own books are synthetic-only) — such a row keeps its old date text, will not dedup against a re-import in the new ISO form, and transaction list --gaps is how an operator finds it.

An obligation is one record per field at the pack's rungs (homestead_ledger/obligations.py), under the household's own short id (lowercase letters, digits and hyphens — rent, car-insurance), which is what the queue carries; a second add under an id already on file is refused by the store itself, not by a check that another writer could have raced, and --replace is how you mean it; a transaction is grown onto the read-only canonical books through books.import_transaction, the one writer — entered once, refused on re-entry, never edited ("mirror, not judge"). The browser UI (ui) has a Records tab with both forms and both lists, an Intake tab that extracts amounts, dates, merchants and due dates from a pasted bill or receipt and fills a form with one click, the Queue, and Subscriptions — the recurring-charge pass over the real books. Merchant resolution, reconciliation and the ledger check need pip install 'homestead-ledger[entity]' and say so when it is missing. --account names an account kind the registry knows (checking, savings, credit_card, loan); an unregistered name is refused rather than quietly grown. An amount is signed from the household's own side on every kind — money leaving is negative, money arriving is positive — so on a credit card or a loan a charge is negative and a payment positive, and the running balance is read back as what is owed (balance.running_balance(..., liability=True)). A card or loan statement whose columns are a Debit/Credit split is refused unless --liability-columns CHARGE,PAYMENT says which column means which: an issuer's own column names do not say, and guessing would misstate a debt.

The method

Test-first, as in homestead: every claim is a check somebody can run. From a cold checkout — the engine (homestead.keep) resolves from PyPI as homestead-affairs, no sibling checkout needed:

pip install -e .    # pulls homestead-affairs (homestead.keep) from PyPI
pytest -q

The full build plan — the reuse map, the bite order, the invariants that carry from the engine and the ones new to money — is in docs/build-plan.md.

Apache-2.0.