How Mintmark actually works

The book is a list of transactions

One atom: the transaction — a dated, signed quantity of one unit in one account. The book is that list. There are no transaction types: spend, income, transfer, buy, sell and corporate action are readings of structure, computed at read time, never stored kinds. A negative quantity is money out; a positive one is money in; a group ties legs into one event and must balance to the cent.

Every transaction carries its source — a document, a feed record, or your explicit instruction — and a status:

• Pending: work in progress — a one-legged transfer, an uncategorized charge.
• Settled: may violate nothing. The full rule set runs at settle time; any failure refuses. Settled is true state.

The cast

A small cast of officers keeps the book. Each role is enforced by code.

Intake: how a row is admitted

A rail is a live feed — a bank aggregator, a price source — fast and untrusted; it creates pending transactions and quotes but never verifies. A document is evidence: a statement, a form, a receipt, hashed into a content-addressed archive, which creates pending transactions and the anchors the book must reconcile against. Both run the same six-stage sequence; deterministic layers run first so the model handles only the residue.

Documents are parsed in two layers. Format parsers ship with the engine and are institution-blind: bytes to raw structure by file type — PDF to text and tables, CSV to rows, OFX to records, images to OCR text. Extractors live in your book, one per statement layout, turning that raw structure into rows and anchors. When no extractor matches, the agent reads the layout once and drafts one as code you review and settle — from then on, that layout is deterministic. Saved code, never a fresh guess per document.

One derivation path

Actions never touch the read model directly. An action validates, writes the truth files, and the read model re-derives from those files — the same function that runs on a cold start from a fresh clone. The commit that follows is serialization, not logic.

action arrives (settle a batch, edit a tag, move a panel)
  → validate against the current read model
  → write the truth files in the working checkout   ← the ONLY write
  → re-derive the read model from the files          ← the ONLY derivation
  → debounced git commit of the touched files        ← plumbing, no logic

The read model — a SQLite database of closures, running sums, the lots fold, concept outputs — is disposable: delete it and it re-derives identically from the truth files.

The audit, and why it never blocks

Validity is checked in two places. The settlement gate is synchronous and entity-local: tags exist and fit, requirements met, the group balances — any failure refuses the settle. The audit is asynchronous and whole-book:

• Anchor reconciliation — cumulative settled transactions per account and unit, measured against every settled anchor, to the cent.
• Archive integrity — every document hash still resolves to a stored blob that still hashes to it.
• Referential and registry integrity — no dangling references; the tag graph acyclic; every requirement's target real.
• Aging — in-flight transfer legs and pending work past their deadline.

A failed check changes derived state, never truth. It marks the affected span unreconciled — a badge that follows every figure drawn from that span — and raises a fingerprinted docket item. It never undoes a settlement or blocks one.

The docket

Items are snoozable to a date with a reason, and carry a deadline. Resolved items stay: the durable record of point-fact decisions (“these two are not the same money”) that no general rule can encode. The agent reads the docket before it proposes.

The agent

Everything in the system is an action — create, edit, tag, group, settle, resolve. The screens, the MCP connector, and the agent all drive the same actions through the same validation and derivation.

The agent reads the whole book, proposes in plain language, and waits for your reply before executing. Even an approved action lands as pending; settlement still requires its own explicit ask and confirmation. The confirmation is conversational and cannot be self-approved. Tags you settle feed back into the meaning stage as rules — so future charges arrive pre-tagged, and the proposals improve from your decisions.

Analytics

Spend and income are not tags — they are concepts: named, versioned SQL queries over the read model. The engine ships a few (spend, income, net worth, returns); yours are SQL the agent drafts and you settle — saved definitions in your book, not one-off renders.

A panel renders one concept. Pin it to your home screen and it updates itself from the same definition next month. Your home is a composable grid you arrange. Returns report both ways: time-weighted to judge the holdings, money-weighted to judge your timing.

Topology

Two repositories and one running writer. The engine is shareable code, tenant-free. The book is your private data repository — registries, transaction files, the archive, rules, concepts, the docket. One writer owns the book at a time; every screen and the agent are thin clients.

Git is the datastore: every book state is a commit hash, backup is a push, and the record of your rulings is the log — a commit maps to an action, not a keystroke. Any git remote works. The same engine runs on your laptop or your own always-on infrastructure without a single code path branching on which.

What is stored, and where