System specification

How Mintmark actually works

The complete machine: what runs where, what calls what, what is stored, and where every check stands in the path between a bank feed and a verified commit. Identifiers in the examples below are synthetic.

Topology

Two repositories and three cloud services. The engine is shareable code with zero personal values in it. The book is one person's private data repository — tables, rows, rules, brain memory, the issues docket, and build artifacts. Compute is three serverless pieces that all converge on the book through git.

compute (Cloud Run) records (git + object storage) human surfaces

Three properties fall out of this shape:

• Nothing runs locally. Every job clones the book fresh, works, pushes, and dies. There is no long-lived state outside git and object storage.
• Git is the only write path. Every change to the book — machine or human — is a commit with an author, a diff, and a reason. Provenance is not a feature; it is the transport.
• One writer to main. The pipeline may push main only when the braingate says commit. The ingester and the Remembrancer are structurally incapable of it — their branch namespaces are constants in code, not configuration.

The daily run

Once a day — or on demand — the pipeline job rebuilds the entire book from its inputs and proves the result. Rebuilding from scratch is the point: the ledger is a derivation, so any run can be reproduced, and no stale intermediate state can hide.

pipeline steps records human surfaces ✓ commit ⏸ stage ✕ block

What is stored, and where

Store	Contents	Discipline
Book repo — inputs	Account/asset/anchor/document tables; extraction row files; tag rules; brain memory (working memory, institution quirks, decision journal); the Exchequer docket; tenant config.	The editable surface. Machines and humans change inputs through reviewed commits; every row carries its source.
Book repo — artifacts	The ledger, validation reports, the blocking set, transfer and in-transit views, price/split caches, the rendered dashboard.	Derived, never hand-edited. Rebuilt from inputs every run; fixing an artifact by hand is the cardinal sin. The chat brain is prompt-forbidden from it and the diff would betray it anyway.
Object storage	The document archive (statements, exports, tax forms); the inbox drop zone; raw feed snapshots.	Create-only. Snapshots archive before any code interprets them, so every downstream decision is reproducible from the raw capture. Originals are never deleted by machines.
Engine repo	Pipeline, parsers, validators, braingate, Exchequer, Remembrancer, sync rails, tests, the leak auditor.	Tenant-free by construction: no account id, balance, institution binding, or personal path. An automated audit sweeps source, module constants, and git history against a corpus of real values from the book and fails the build on any hit.

The checks, in order of authority

Layered so that each catches what the previous cannot. The first three are mechanical and blocking; the docket holds what is real but not false; the braingate judges meaning.

1 · Conservation, at parse time

Every document parser must reproduce the document's own printed totals — opening balance plus activity equals closing balance — before its rows are accepted. A parser that reads the right columns of the wrong table fails loudly, at the source, not three stages later.

2 · Balance gates, at the rails

Feed rows book only if the account's rebuilt ledger then matches the feed's stated balance to the cent. No match — that account's rows wait, and the gap is named. One bad account never poisons the rest of the book.

3 · Anchors and integrity, at the book

Anchors: hundreds of balances printed by real documents, reconciled against the rebuilt ledger per account, per date, exactly. Integrity: three invariants over all accounts and all time —

• no unexplained negative cash (money spent that was never there),
• no negative positions (shares sold that were never bought),
• no transfer leg that is both unmatched and unexplained (money from nowhere, money to nowhere).

A violation of any of these means the book is false, and the run cannot commit. There is deliberately no override button — the only exits are fixing the data, or declaring a documented exception in config through the same reviewed-commit path as everything else.

4 · The Exchequer

Everything open but not false: a transfer leg past its pairing window, a staged branch nobody merged, a feed account with no mapping, a question the braingate wants a human to answer. One row per stable fingerprint, a per-class deadline, and a lifecycle the machine drives:

⏱ open (late) ✓ resolved ✕ blocking (false)

Docket class	Deadline	Born from
transit-leg-unpaired	10 days	a transfer leg whose counterpart hasn't posted on its own rail inside the window
stale-staged-branch	3 days	a machine branch nobody merged — age read from the timestamp in its name
unmapped-feed-account	immediate	a feed account with no mapping: invisible money is an issue from day one
brain-flag	—	raised by the braingate's verdict; the one class never closed by machine, because a question is answered by a human

Deadlines are per-class and tenant-tunable. The tag-review backlog is deliberately not docketed — a queue with a thousand rows is a queue nobody opens; categorization has its own surface.

5 · The braingate

The last check reads for meaning. A headless AI session runs inside the rebuilt working tree with the evidence (step results, counts, validator output, error tails of anything that failed), the full diff, its three memory files, and read-only tools to verify anything the evidence leaves open. Its contract:

• Three verdicts. commit — the diff is exactly what the evidence claims. stage — anything unclear: work lands on a branch and a human reviews. block — affirmatively wrong; nothing is written.
• Every failure is stage. Auth failure, quota, timeout, malformed output — the verbatim error travels to the owner, and the gate stays shut. A gate that opens when the reviewer is absent is not a gate.
• Read-only during review. Its only writes are the verdict record, a dated journal entry, and docket flags — applied by the harness after the verdict, as a record of the review.
• Memory with provenance. Working memory, institution quirks, and an append-only decision journal live in the book and travel with every clone. A verdict can cite the decision that authorized the pattern it is looking at.

This layer earns its keep on the failures arithmetic cannot see: it has refused a run whose only defect was silently corrupted reference data — every mechanical validator green — because the diff contained a change the evidence didn't explain.

The Remembrancer

The conversational half. The daily digest threads into Slack; the owner answers in the thread; the Remembrancer turns the answer into a reviewed change:

1. A mention opens a session: fresh clone of the book, an AI with full tools inside that clone, prompted with the thread and the brain's memory files.
2. It applies the decision the owner stated — row edits, rule changes, docket rulings, journal entries — citing the owner's words as authority. Ambiguity means it asks instead of editing; a question with no changes is a valid outcome.
3. Code, not the model, decides what happens next: git status says whether anything changed, and the validators say whether it may be pushed. Green and changed → a chat/<stamp> branch with the diff summary in-thread. Validator failure → the verbatim report, and nothing pushed.
4. The owner merges. The mainline is unreachable from this service by construction — the branch namespace is a compile-time constant, and the refspec is re-checked before every push.

Transport security is the boring kind that works: every request must carry a valid signature inside a five-minute replay window, an unset signing secret refuses all traffic rather than defaulting open, and duplicate event deliveries collapse on an id ring so a retry can never run a second session.

The engine/book boundary

The engine repo can be read by anyone; the book repo can be read by its owner. Holding that line is a build gate, not a promise: a leak auditor builds a corpus of thousands of real values from the book — account numbers, institution strings, document ids, amounts — and sweeps the engine's source, its module-level constants at import time, and its entire git history for any of them. Any hit fails the build. Institution formats are engine code; institution bindings are tenant data reaching the engine as parameters.

---

Why it works this way →