purchases — What You Buy · Area Specification

last conformance run: 9/9 scenarios pass · 30 acts mapped 2026-10-07 20:55 UTC

Spec

Status: 0.5. A spec on the record before a line of module code, so the shape can be argued with. 0.3 makes the statement's own lines the normal path of import_statement. 0.4 adds standing rules: what the person says ahead of time, kept as suggestions, never as bookings. 0.5 adds bills: what vendors say is owed, prepared here, approved by a person, paid in their bank.

1. Calibration: who this is for

One person, a household, or a very small business that wants to know what it buys, what it pays for every month without noticing, and whether it has the receipt. The facts arrive as files: bank and card statements, receipts. Nobody parses them here. The agent reads the file and states what it read; the module keeps the record, checks that the statement adds up, refuses what it cannot reconcile, and remembers where every number came from. Agent first: the import is a batch of rows the agent hands over, never a parser we maintain per bank.

2. Scope

In: statements as sources with control totals, transactions traced to their source row, review and classification, purchases, subscriptions declared and then confirmed by what actually charges, receipts matched to transactions, spend by category and month, per currency.

Out (§9): bank connections and feeds (files only, by design), currency conversion, budgets, forecasts, advice, tax treatment of purchases, paying anything.

3. Entities and lifecycles

• source — one file the agent read: name, a content hash the agent computed, kind (bank | card | other), the account label as printed, period start and end, opening and closing balance, row count, currency. Immutable once accepted. The same hash is never accepted twice.
• transaction — one row of a source: date, signed amount in minor units, description as printed, counterparty if the row names one, source and row index, the raw line as read. Status: unreviewed → purchase | recurring | transfer | income | fee | ignored, set by review with a reason; recurring is spending that repeats, and naming its vendor declares the subscription. Never edited in amount or date: a wrong row is a wrong source, re-imported after the agent re-reads it.
• purchase — a transaction reviewed as spending: vendor, category, note, optional receipt. Category empty until someone sets it; empty beats guessed.
• vendor — a name and its aliases as statements spell it, so the same shop is one vendor.
• subscription — a declared recurring charge: vendor, cadence (weekly | monthly | yearly), expected amount and currency, tolerance, start. Status: active | cancelled | lapsed. Confirmed by matches: each period either has a matching purchase, or shows as missed. Lapsed is derived (two periods missed), never asserted; cancelled is an act with a reason.
• rule — something the person said ahead of time ("the next five days are the Texas conference, book it to travel"): a label, the category and status it suggests, and what it matches (a date window, words the statement line contains, a vendor, a currency; at least one of window, words or vendor). Status: active | ended, ending is an act with a reason. A rule never books a row: it suggests, and the suggestion is computed when rows are read, so ending a rule removes its suggestions and leaves every reviewed row as the person confirmed it.
• bill — what a vendor says the person owes: the vendor, their invoice number, the bill and due dates, the amount and currency as printed, a category in the person's words, the file it came from (name and hash; the file stays with the person). open → approved (a person only, optionally with a pay-by date) → paid (recorded after the fact with the day it went and how, linked to the statement row that shows it) | rejected (with a reason). A bill is a record, never a payment.
• receipt — an attachment the person gave the agent: file name, hash, vendor, date, total, currency. Matched to at most one transaction, by an act with a reason; unmatched is a visible state, not an error.

4. The acts

Writes (19): import_statement, split_transaction (one row broken into legs that add to it exactly), rename_category (one word changed on every row that carries it), discard_source (a wrong read thrown out whole, with a reason, its hash freed), review_transaction, review_batch (many rows, one reasoned act, validated whole), set_vendor, add_receipt, match_receipt, declare_subscription, cancel_subscription, unmatch_receipt, add_rule (a standing rule, with its window, words or vendor), end_rule (with a reason), accept_suggestions (confirm what rules suggest, one reasoned act, rows the person rejects left out), add_bill, approve_bill (a person only), record_bill_payment, reject_bill. Reads (11): vocabulary (the statuses with their meaning, the person's categories, vendors and active rules — what an agent proposes from), sources, transactions (each unreviewed row with the suggestion a rule makes for it), purchases, subscriptions, receipts, spend, source, rules, bills, payables (open bills by when they fall due, set against the cash on the latest bank statements).

5. Invariants

• P-1 Money is integer minor units, signed; every source and every transaction carries a currency; sums are per currency and never cross.
• P-2 Every transaction traces to a source: source id, row index, and the raw line as the agent read it. A transaction without provenance cannot exist.
• P-3 A statement is accepted whole or not at all. The agent hands over the statement's lines as it was given them and states the control totals the statement prints: the opening and closing balance always, the row count when one is printed. The batch is refused when the rows do not reconcile to them, naming the gap. That is where a transcription error is caught. (0.3: the lines as text are the normal path and the hash is computed from them; typed rows remain for a statement with no text, and then carry the hash. Five runs out of five, a 26B model retyped forty-seven rows into fields when the schema listed fields first.)
• P-4 The same source (by hash) is refused a second time. Rows already present from an overlapping source (same date, amount, description) are skipped and listed in the result, never silently merged and never silently duplicated.
• P-5 Nothing is invented: category, vendor and status are empty or unreviewed until an act with a reason sets them. Review is an act, and the reason is part of the record.
• P-10 One row may break into several categories, and the legs must add to the row exactly or the split is refused with the gap named. The row's own amount, date and provenance never move: the statement said what it said, and a breakdown is an annotation on top of it.
• P-11 A standing rule suggests and never books. A row a rule matches stays unreviewed and carries the suggestion, the rule's name and id, until a review act confirms it; accepting is a review, so it carries a reason and follows the person's confirmation. A rule suggesting spending never suggests it for money in, nor income for money out. The most specific rule wins (words, then vendor, then the narrowest window), and other matching rules that say something different are listed with the suggestion. Ending a rule removes its suggestions and changes no reviewed row. A rule must narrow something: one that would match every row is refused, as is a window that ends before it starts.
• P-12 A bill is a record, never a payment: nothing here pays anything. Approving payment is a person's act, refused to an agent whatever its role. A payment is recorded only after it happened, with the day it went (never in the future), and an agent records one only for an approved bill; a person recording it approves it in the same act. A linked statement row must be money out, in the bill's currency, for the bill's amount, and pays one bill only; an unreviewed row is reviewed as the bill says. The same vendor and invoice number is refused a second time, as is a bill with no number that matches another's vendor, amount and date. A bill due before its own date is refused. Bills count on a cash basis: the statement row that paid one reaches the books, and bills unpaid at a date are named beside the statements.
• P-6 A subscription is declared, then confirmed by the record: a period with no matching purchase is shown as missed — but only once a statement covering that period has been read; before that it is "no statement yet". Two missed periods make it lapsed. A vendor may carry several subscriptions (different cadence or amount). The module never assumes a charge happened.
• P-7 A receipt matches at most one transaction and a transaction at most one receipt; matching is an act with a reason, refused when amounts differ beyond the receipt's stated total or dates differ by more than seven days, unless the reason says why.
• P-8 Every write is a logged act with an actor; refusals are logged too.
• P-9 Files never live here. A source is its hash, its metadata and its rows; the file stays with the person. The record can prove what was read, not re-show the page.

6. Required read models

sources (what was imported, when, by whom, reconciled), transactions (by period, status, source), purchases (by vendor, category, month), subscriptions (with next expected charge, missed periods, derived status), receipts (matched and unmatched), spend (by category and by month, per currency), source (one source with its rows and the reconciliation).

7. Contract vs freedom

Contract: batch-or-nothing with control totals, provenance on every row, per-currency sums, declared-then-confirmed subscriptions, matching as a reasoned act, hash-refused re-imports. Freedom: category vocabulary (the person's words), vendor alias rules, tolerances, how the agent reads a given bank's layout, which files count as receipts.

8. Conformance (scenarios)

01 a card statement imported whole: control totals reconcile; a second import of the same hash refused; a transposed amount refused with the gap named · 02 overlapping statements: rows already present skipped and listed, new rows in · 03 subscriptions: declared from a purchase, confirmed by the next month's charge, missed when it does not come, lapsed after two · 04 receipts: added, matched with a reason, a mismatched total refused, unmatched shown · 05 splitting: a payroll line broken into wages, employer taxes and the processor's fee; legs that do not add up refused with the gap named; the row itself unchanged · 08 standing rules: a conference rule recorded before the statement, the statement's rows in the window suggested as travel (a refund in the same window not), the suggestions accepted in one act, a second accept refused, a rule that narrows nothing refused, the rule ended · 09 bills: a vendor's bill recorded, the same one forwarded twice refused, one due before its date refused, one with no due date and no terms refused; approval refused to the agent; a payment refused before approval; what is coming due set against the latest statement; a bill rejected with a reason.

9. Deferred — with reasons

---

Change log: 0.5 (2026-10-07) — bills prepared for approval, from Aryeh Munk's phase 1 list ("Enable AI to make payments, process invoices"), reshaped so nothing pays: the agent prepares, a person approves, the bank pays, the record follows. 0.4 (2026-10-07) — standing rules, from Aryeh Munk's phase 1 list ("I am traveling these next 5 days for conference, book to Texas conference"), kept as suggestions so P-5 still holds. 0.2 (2026-09-10) — splitting one row into legs that add to it exactly, for payroll runs and mixed receipts, prompted by a demo session pointing out that one lump to one account would annoy a bookkeeper. 0.1-draft (2026-09-06) — drafted from Peter's and Pavan's "my purchases" idea, with the agent-first import discipline agreed the same day: no parsers, batch-or-nothing, control totals, provenance, refusals.

Acts

Invariants

Scenarios

Each scenario is a file of acts with expected outcomes. ok means the act must succeed with the listed fields; refused means the act must be refused with a sentence containing the listed text. Refusals are contract.

These pages are generated from the files in specs/ in the repository; scenarios are executed by src/conformance.js on every build. Written and maintained by Peter Varga, who also runs Portland AI Works. github.com/alviso/saybooks, AGPL-3.0.