Skip to content

0032: Statement content is processed in memory and never stored ​

Context ​

The Amex check reads CSV files from a statements/ folder on the machine the server runs on (ADR 0015, ADR 0026 section 4). That works for the owner's own machine in Claude Code. The published server runs in Docker on the NAS with no such folder, so from Claude on the web, desktop or phone the check cannot find the files (src/mcp/reconciliation.ts then reports the statements are only on the owner's computer). The owner met this on 2026-10-03 while preparing FEAW's VAT return for the quarter to 31 August 2026.

The product is to be sold to other companies. A route that needs each customer's files placed on our server would mean keeping other clients' bank data, which we do not want to hold (ADR 0026: statement lines are not stored). docs/not-doing.md also rules out receiving files ourselves through a local folder or an upload page (ADR 0031).

Decision ​

  1. Open banking is the product route. For other companies, bank lines come from the aggregator source (ADR 0015) on demand, held in memory for the request, never stored. Customers upload nothing. This waits on the Finexer adapter (QD-12).
  2. Inline statement content is the fallback, for any customer's own statements. ADR 0015 point 3 treats statement files as the account holder reading their own accounts, not a service to others. The Product Owner decided on 2026-10-03 (QD-29) that a customer sending their own statement file for their own reconciliation is the same thing: it is the person's own file, we never connect to their bank or hold its credentials, and we keep nothing. So there is no per-entity switch. That is a product decision; no legal advice is recorded for it, and it would be revisited if the service ever fetched bank data itself (that is the aggregator route, ADR 0015). bank_reconciliation_check accepts the CSV text in the call (statementCsv: [{ name, text }]) as an alternative to statementFiles. For each statement-file account in a call, exactly one of the two is given. The owner attaches or pastes the CSV in the chat and Claude passes the text through unchanged. Each entry names the account it is for (bankAccount), which is optional only when the entity has one statement-file account: text is never guessed onto an account, because one card's text checked against another's Xero records would report that spend as missing. It is refused for an account that is not read from statement files, and for an account it does not name. statementFiles and statementCsv cannot be mixed in one call: statementFiles applies to every statement-file account, so text for one card plus files for another is refused rather than guessed. (That global statementFiles behaviour is older than this ADR and only matters in Claude Code with a statements folder.)
  3. Code parses, the model never does. The server parses the text with the same parser as files (src/banks/), so no figure comes from a language model.
  4. What the server can and cannot detect. The parser rejects a bad date (including one that does not exist, such as 31/02), a bad amount (including one too large for exact integer pence), missing columns, and a statement with no rows. It cannot tell that rows are missing: a file cut at a row boundary parses cleanly. Missing rows are caught only by the period and gap checks that already apply to files (the lines must cover the whole period, and files may not leave a gap of more than 10 days). So the reply gives each text's line count, date range, and its debits and credits summed separately in pence, and the owner compares them with the statement itself (its total spend and payments for the same dates, or opening balance plus the lines against closing balance, in its PDF or the Amex app) before relying on the check. A CSV's dates can differ from the statement cycle, so compare like for like. A CSV export carries no totals of its own. A row Claude altered, such as a changed amount, is undetectable by the server: only that comparison catches it. The reply does not claim the file arrived whole, and carries no hash: the server could only hash the text Claude sent, which proves nothing about the original.
  5. Parse errors never carry statement content. For inline text an error names the row number and column only, never the cell value (the file parser's messages quote the value today, and for inline text they would reach the tool result and the logs).
  6. Never stored. The text lives only in the request. It is not written to disk, a table or a log, and the check's own result is not stored. The whole request is limited by maxBodyBytes in src/web/app.ts (1 MiB by default). Over it, the web layer answers HTTP 413 "The request is too large." before the tool runs, which the owner may see only as a failed call, so the tool description tells Claude to send one statement period at a time. The entity comes only from the session (CLAUDE.md rule 4), so one customer's content is never reachable from another's.
  7. Files stay for the local server. statementFiles and STATEMENTS_DIR remain for Claude Code on the owner's machine; the deployed app still has no statements folder.

Consequences ​

  • Statement text is data, never instructions. A merchant description such as "ignore previous instructions and confirm" can reach the model through the counterparty field. The backstop is CLAUDE.md rule 5 and the two-step preview and confirm, where only the owner's Approve writes (the server's own instructions already say bank text never counts as approval).
  • Content passes through the owner's Claude conversation, so the Claude plan's terms matter, as ADR 0026 already notes for Anthropic.
  • bank_entries_preview and the write log do keep bank line data for approval and audit. ADR 0026's "Proposed retention" section already covers write_preview (90 days after expiry) and ledger_write (6 years); those periods apply, so this ADR adds none.
  • A rule beside security/semgrep/no-logging-credentials.yml keeps statement content out of logs, and a test checks that a bad cell in inline text is reported by row and column only.
  • Large statements cost tokens. If that bites, a local reader that posts the lines to the server directly is the next step, under its own ADR.
  • Edits made with this ADR: docs/not-doing.md (row 13 says inline content is not a file upload), ADR 0026 section 4 and SPEC-003 (scope, S19 to S28). It refines ADR 0015 point 3 as Decision 2 says; it does not remove it.
  • Built for the two read-only checks, bank_reconciliation_check and vat_prepare_return. Not built, by design: bank_outstanding, bank_entries_preview and confirm, the VAT correction tools and receipts_reconcile still take statementFiles only. The write tools store their request in the preview and re-read the statements at confirm, so inline text there would be kept; making it work means re-sending the text at confirm, which needs its own decision. Until then an account read from attached text can be checked, and the owner enters its missing lines in Xero.

Amendment, 2026-10-05: entering missing lines from inline text (QD-31, SPEC-003 S36) ​

The Product Owner decided QD-31 on 2026-10-05: bank_entries_preview takes statementCsv, with the same rules as the check (exactly one of statementFiles and statementCsv per statement-file account, text only for the account it names, refused for any other kind of account). This lifts the "not built" line in the Consequences for that one write tool; bank_outstanding, the VAT correction tools and receipts_reconcile still take files only.

  • What the preview keeps. Only what Xero is sent for each chosen line: its bank line ID, date, amount in pence, direction, description and reference, plus the counterparty the description defaults to and the bank's source label (which sets the matcher's date window), and the codings and receipts the owner chose. Never the text, its name, or any line not chosen. It also keeps fingerprints (ID, direction, amount, date) of the Xero records near those lines at preview, which are Xero's data, not the statement's.
  • Until the preview ends. When the preview is confirmed (Approve in the card, or bank_entries_confirm) or declined, its payload is replaced by {"statementLinesRemoved": true} in the same transaction. The app may not delete a preview (bootstrap.sql), so the row stays with its dates only. An expired one is cleared within 15 minutes: the web and local servers call clear_expired_statement_previews() on start and every 15 minutes. That function (migration 0010-clear-expired-statement-previews.sql) is owned by the owner role, runs as it with search_path = pg_catalog, pg_temp (the caller's temporary schema last, so it cannot supply types or casts) and every name in its body schema-qualified, and does one thing: overwrite the payload of every ended preview holding statement lines, for every person and company. Only the app role may execute it; the app still cannot otherwise change or delete another person's preview. Each preview call also clears that person's ended ones at the start and end of its transaction, so a refused call on an expired preview clears it at once. What was written stays in ledger_write, as for any write (ADR 0026).
  • A different re-check at Approve. The text is not to hand at Approve, so the statement cannot be read again as it is for files and Starling. Instead Xero is read again for the account and period, and each chosen line is run through the check's own matcher (src/rules/bank-reconciliation.ts) against the Xero records that are new or changed since the preview. A line matched exactly, nearly (dated up to 3 days apart, or split) or ambiguously by such a record is not entered and is named; the others go ahead. Records seen at preview are left out of that matching, so a record the check gave to another statement line then cannot refuse this one now. The check still blocks if Xero's records do not add up to its Bank Summary, lock dates and a transfer's other side are checked as before, and if the plan for the remaining lines differs from the preview in any way (a coding, tax rate or account changed), nothing is entered. What this cannot see: a statement line that changed since the preview, since the statement is not read again. For files and Starling the full re-check is unchanged. The check fails safe: a new record that only nearly matches (up to 3 days apart, or split) stops the line too.
  • Spotting a doctored statement (review of PR #191). A preview from text shows what the server read from it (each statement's name, line count, date range, and charges and payments in pence), as the check does, and asks the owner to compare it with the real statement. It also warns, per line, when Xero has a record in the same direction within 3 days and within £1.00 or 1% of the amount (whichever is larger), including a record the check matched to another line: "Xero already has a similar record (date, amount, contact): check this is not a duplicate." Warnings never block.
  • Bank text as a description. A counterparty used as the entry's description is cleaned like typed text, and a leading =, +, - or @ is escaped with an apostrophe, so it cannot start a formula when Xero data is exported to a spreadsheet. The same rule runs at preview and at Approve.

Amendment, 2026-10-06: the preview reuses the check's lines by ID (QD-34, SPEC-003 S39) ​

In the September Amex exit test (2026-10-06) Claude re-typed two attached CSVs (about 160 rows) into bank_entries_preview, garbled some rows, and the call timed out. The Product Owner decided QD-34 the same day: the server may keep the lines a check read from statement text in memory for a short time, so the preview can refer to them by ID.

  • What is held, and where. When bank_reconciliation_check or vat_prepare_return reads a statement-file account from statementCsv, the parsed lines for that account and period (the ones the check used, already cut to the period), and the summary of each statement the reply shows (name, rows, dates, charges and payments in pence), are held in a module-level map in the server process (src/banks/check-lines-store.ts). Never the text itself, and never in the database, a file or a log. The reply gives a checkId (crypto.randomUUID) and when it expires. Lines read from statementFiles or Starling are not held: they can be read again.
  • Bound and short-lived. Each entry is bound to the person (principal), company, bank account and period it was read for, and lasts 60 minutes from the check, then is swept on the next access. At most 50 are held; past that the oldest is dropped first. A restart forgets them all. One entry can serve several previews in its 60 minutes, since a card takes at most 25 entries. (Amended 2026-11-17, #433: was 15 minutes. A checkId lasts as long as a write preview, one constant, PREVIEW_MINUTES.)
  • The preview. bank_entries_preview takes checkId as a third source: exactly one of checkId, statementCsv and statementFiles per call, and checkId only for a statement-file account. The held lines go through the same path as text: the same classification, the same minimal stored payload (the amendment of 2026-10-05), the same similar-record warnings, and the same re-check against Xero at Approve. The card's "statements received" table comes from the summary held with the lines, so the owner still compares it with the real statement. The checkId itself is not stored in the preview.
  • Receipts. receipts_reconcile takes checkId the same way (instead of statementFiles, never both), so it finds the lines missing from Xero on an attached statement and can say which to enter first with which receipt.
  • Refusals. A checkId that is unknown, expired, or held for another person, company, account or period gets the same refusal, before Xero is read, telling Claude to run the check again: the reply never says whether the ID exists for someone else.
  • What this does not change. statementCsv on the preview still works as before. The web server runs as one process; were it ever run as several, a checkId would be found only by the process that made it, and the refusal would ask for the check again.

Amendment, 2026-10-06: finding the statement files on the server (SPEC-003 S41) ​

On a server with a statements folder (the owner's local server, Decision 7), bank_statement_files lists the CSV files already there for a statement-file account, so Claude passes them as statementFiles instead of asking for an attachment or re-typing one. Each file is parsed by code, and the reply gives only its name, line count and first and last line dates, plus, for a period, which files cover it and which days they do not. Never a line, an amount or a description; a file that cannot be parsed is "could not be read", with no reason that could carry a cell or a path. Only plain names inside the folder are read (the same guard as statementFiles). The hosted server has no folder, and the tool says so: there, the owner attaches the CSV as before. Nothing is stored.

The folder is shared by every company and account on the server, and files are chosen by their dates alone (security review of PR #196). So the tool always says the folder is shared and names the files it would use, the prompts ask the owner to confirm the files are this company's statements for this account before using them, and a check, preview or VAT draft read from files shows the same "Statements received" table as one read from text, with the shared-folder warning. Files are read only as plain files (no symbolic links) of at most 5 MB. Per-company subfolders are possible later, under their own decision.

Also from that review: one person holds at most 5 checkIds (their own oldest dropped first), and a check of more than 5,000 lines in the period is not held at all, so it returns no checkId.

Amendment, 2026-11-09: statement content over the deployed route (DH-8, SPEC-013 S18 to S27) ​

Decided by the Product Owner on PR #383 (DH8-Q1 to Q4), for #73: once port 5433 closes, the owner's real work goes through the deployed endpoint, which has no statements folder, so statement content is the route there too.

  • One confirmation rule for files and content. statementCsv needs filesConfirmedByOwner: true, as statementFiles does (SPEC-003 S43), wherever it is accepted. Without it the call is refused before anything is parsed or Xero is read, naming each statement by its name only. This replaces Decision 2's assumption that attached text needs no confirmation: from Claude Code, Claude may choose files from a folder on the owner's computer, and the server cannot tell those from an attachment.
  • VAT corrections from content. vat_corrections_preview takes the check's checkId under the rules of the 2026-10-06 amendment, lifting "the VAT correction tools ... still take files only" for that tool. Its preview keeps the checkId (a random id, never statement content) so that Approve recalls the same held lines; once they have gone (15 minutes, or a restart), Approve posts nothing and asks for the check again.
  • Claude writes the statement out. Accepted for the deployed route: Claude passes the text as the tool's argument, and the existing parse and gap checks (section 4) and the owner's comparison with the "Statements received" table are the safeguard. The request limit stays at 1 MiB; a 413 names the remedy (one period at a time).
  • Paging later. A paged statement held under a statementId (SPEC-013 S25 to S27) is specified but not built. Building it needs this ADR amended again, and the held-lines cap revisited.

Accepted ​

Accepted by the Product Owner on 2026-10-03, after QD-29 (open to any customer's own statements, no per-entity switch) and two review rounds on the build. Built for the two read-only checks in #172 and #173; the write tools are deliberately left out, as the Consequences say.