Finfry::Store
The book's store. The truth is an append-only log of commits
(finfry.log, a Keep::Log); the Database held here is the fold of that
log, and finfry.json is a checkpoint of the fold as of some commit —
regenerable at any time. Every mutation is an action: it is applied to
the in-memory state and appended to the log by the same apply, so the
fold and the live state can't disagree.
Mutations made inside changeset become one commit (kind ledger);
made outside, each becomes its own commit (kind bookkeeping). Undo is a
revert mark on the log — nothing is ever deleted.
An older finfry.json (no log beside it) is migrated on first open: its
journal becomes commits, the rest of its state one migrated commit, and
the original is kept as finfry.json.pre-log.
Constants
The visible per-directory book file. finfry discovers it by walking up from the current directory (like git's .git), so a project/folder can hold its own ledger.
Commit kinds. history shows ledger commits; bookkeeping ones (cleared
marks, due staging, rules, metadata) are there with --all.
Constructors
Class methods
Apply one action to a database. Used for the live state and for replay,
so it is the definition of what each action means. For a reverted
commit only the id counters advance (reverted: true), so ids are never
reused even after an undo.
Resolve the active ledger: an explicit FINFRY_DATA override, else the nearest book file walking up from the current directory, else the global per-user ledger.
Instance methods
Net balance of every account (optionally restricted to a subtree, and/or
to transactions on or before up_to). Returns account => signed cents.
Run a block as one commit. Nested calls join the enclosing one, so an AI plan's many operations collapse into one undo unit. Nothing is written if the block changed nothing or raised.
Ledger commits (what history shows), oldest first, as Changeset
views: id = the commit's sequence number. With all, every commit —
bookkeeping (cleared marks, due staging, rules, metadata) and the undo
marks themselves — so the log can be read end to end.
Balance of the staged tier (cleared-but-not-committed).
Transaction ids marked cleared against account's statement.
Declare an account in the chart. Returns false if already declared.
Remove a transaction by id. Returns the deleted record, or nil if absent.
Adjust an entry before posting; it's marked ok.
Materialize every occurrence due up to today into the queue, advancing
each rule's cursor so nothing is generated twice. What was generated —
including a computed interest charge — is what's logged, so replay never
recomputes it. Returns how many were added.
Declared ∪ used — the accounts finfry treats as known. Feeds the AI's
chart context, the accounts listing, and completions.
The most recent finalized reconciliation for an account, if any.
How many occurrences generate_due would materialize as of today,
without touching anything — so a read-only view can say "N new have
come due" and offer the catch-up as a deliberate step.
Finalize a reconciliation: move every staged-cleared transaction into the committed tier and record the statement it was balanced against. The caller verifies the balance matches first. Returns the number locked in.
Balance of the committed tier (locked by past reconciliations).
Every finalized reconciliation for an account, oldest first.
Build, validate, persist, and return a transaction. Raises Error if the
postings don't balance.
Bring back the change undo just removed — only while it is the latest
thing in the log; any new change invalidates it.
Pick up commits another process appended (the CLI or MCP alongside
serve). Returns true if anything new was folded in.
Rewrite every posting on from to to (also updating the chart and any
budget keyed on it). Doubles as a merge when to already exists. Returns
the number of postings rewritten.
Correct an older change the proper accounting way: append a reversing
entry. The original is never removed — transactions it added are negated by
mirror-image postings, budget changes restored. Returns the reversing
changeset, nil if id is unknown, or raises if it's already reversed.
Mark (or unmark) transactions as cleared against account. Returns the
number of ids whose state actually changed.
Net movement into an account subtree within a "YYYY-MM" month. For an Expenses account this is the amount spent.
Remove an account from the chart. Returns false if it wasn't declared. (If postings still reference it, it stays "known" via use.)
Undo the most recent ledger change by marking it reverted — as if it never happened, without erasing it from the log. Returns it, or nil if there's nothing to undo.
Remove a metadata key. Returns false if it wasn't set.