Skip to content

SPEC-013: Generic bank connections ​

Amended 2026-10-09 by ADR 0035 (Product Owner, 2026-10-08): slices (b) and (c) and the Finexer source are withdrawn. GetMy Books reads bank lines from statement files only; slice (a) is the whole feature.

Amended 2026-11-09 (Product Owner, DH-8, issue #73): statement content over the deployed route, scenarios S18 to S27 in the section of that name at the end. DH-8a (S18 to S24) is approved; paging, DH-8b (S25 to S27), is specified and not built.

DRAFT for Product Owner and Rob approval. Nothing here is built. It extends SPEC-003, whose check rules stay unchanged.

Business intent ​

SPEC-003 reads two kinds of bank: Starling through its API and American Express through an Amex-specific CSV parser. Other customers (and FEAW's other accounts) bank elsewhere. The Product Owner chose, for issue #225, "Xero feed plus generic CSV/OFX import". This spec establishes what each can really do and slices the work so that any bank works through statement files first, without waiting on an aggregator.

Feasibility, stated honestly ​

Xero bank feed lines through the standard Accounting API: not possible. Xero's Accounting API exposes bank transactions, payments, transfers and the Bank Summary report (SPEC-003 already reads these). Unreconciled statement lines (the feed items waiting for OK in Xero's reconcile screen) are not in it. Xero's bank statement data is reached through the Finance API (bank statement accounting reports) which is restricted: an app needs Xero's approval, and as I understand it that access is for approved partners such as accountancy practice tools. This is from general knowledge of Xero's public developer documentation, not tested against this repo's app, and must be confirmed with Xero (QD-39). Nothing in the repo reads it today (src/xero/ uses the Accounting API scopes in src/xero/session.ts only).

What Xero can give today, and SPEC-003 uses: records already entered on the bank account (reconciled or not) and the Bank Summary movement. That shows what is in Xero, not what the bank says; the point of SPEC-003 (ADR 0013) is to compare with the bank's own data. So a Xero-feed source is not a substitute for statement files unless Finance API access is granted.

Other facts from the repo. ADR 0015 picks Finexer for aggregated bank reading and keeps sources provider-neutral (bank_account.source = starling_token | statement_file | aggregator); QD-12 is open on Finexer's answers. ADR 0032 allows a customer's own statement text passed inline, parsed in memory, never stored. Today src/banks/amex-csv.ts is the only file parser and src/banks/read-lines.ts dispatches by source.

Slices ​

Slice (a): generic statement import (build first). Any bank's statement, read through the bank-source interface, with the same guards as today: the owner confirms the files (filesConfirmedByOwner), checkId flows as now, and statement text is never stored (ADR 0032). Formats and banks (QD-40): OFX and QIF as standard readers first; then CSV presets for Barclays, HSBC, Lloyds, NatWest/RBS, Santander, Revolut Business (WealthTechPros' bank), Tide, Monzo Business, Starling, Wise and Amex (Amex moves onto the generic reader); then a saved per-account column mapping for any other CSV (date, amount or debit/credit pair, description, reference; date format; sign convention; header row). The mapping is configuration, not statement content (QD-42, ADR 0034). PDF is excluded. Built in order:

  • a1 the bank-source interface, with Amex and Starling moved behind it and no behaviour change.
  • a2 OFX and QIF readers.
  • a3 CSV presets for the banks listed above.
  • a4 saved column mapping for unknown CSVs.

Slice (b): Starling API as an optional live source (WITHDRAWN, ADR 0035) behind the bank-source interface (ADR 0034, proposed). No change in behaviour for FEAW; Starling stops being a special case in read-lines.ts.

Slice (c): Xero-feed lines, only if access is confirmed. (WITHDRAWN, ADR 0035: Xero's Finance API is closed to lending partners and no live source is wanted.) Blocked on Finance API access (QD-39); the Product Owner is applying to Xero (owner action). If granted, a xero_feed source returns statement lines for the linked account. If not, this slice is dropped; slice (a) already covers every bank.

Later: Finexer (WITHDRAWN, ADR 0035; QD-12 closed as no longer needed).

Scope (slice a) ​

  • A bank-source interface returning BankLine[] for a period, the same type the rules already consume (src/rules/ is unchanged and never knows the source).
  • Column mapping: setup tool that reads only the first rows of a file the owner supplies, proposes a mapping from the headers, and saves the mapping after the owner confirms it. Sample rows used for the proposal are not kept.
  • Parse CSV (RFC 4180 quoting, as today), OFX 1.x/2.x and QIF in src/banks/ (pure parsing, no I/O beyond reading the text given).
  • Same refusals as ADR 0032: bad date, bad amount (integer pence by construction, ADR 0025), missing column, empty statement, period outside the statement's dates; errors name row and column, never the cell text.
  • Both delivery routes: statementFiles from the statements/ folder and inline statementCsv-style text (name, text) as today.
  • Duplicate-line protection: identical date, amount and description rows in one file are kept (real statements repeat), and a line in two overlapping files is counted once only when the bank's own transaction id (OFX FITID or a mapped id column) is present; otherwise the overlap is reported, not guessed.

Out of scope ​

  • Aggregator and Finexer build (withdrawn, ADR 0035).
  • Payment initiation (docs/not-doing.md).
  • Receiving files ourselves through an upload page or folder (ADR 0031).
  • Non-GBP accounts, PDF statements, screen scraping.
  • Pressing OK or any write change; writes stay as SPEC-003.

Scenarios ​

S1: New bank, mapping proposed and confirmed ​

Given a bank account with source statement_file and no saved mapping And a CSV from a bank GetMy Books has not seen When the owner sets up the account Then a proposed mapping is shown with the sample headers And it is saved only after the owner confirms it

S2: Later checks use the saved mapping ​

Given an account with a confirmed mapping When the reconciliation check runs on a new statement with the same headers Then lines are parsed with the mapping, with no further question

S3: Header change refuses, never guesses ​

Given a saved mapping and a statement whose headers no longer match When the check runs Then it stops, names the missing column, and asks for the mapping to be updated

S4: Amex statements still work ​

Given an Amex export, standard or extended When the check runs on the generic importer Then the lines and totals equal those of the previous Amex parser on the same files

S5: OFX statement ​

Given an OFX file with three transactions and their FITIDs When the check runs Then three lines are read, amounts as integer pence, dates as London dates

S6: Debit and credit in separate columns ​

Given a mapping with a debit column and a credit column When a row has a value in debit Then the line is an outflow of that amount, and a row with both or neither is refused

S7: Owner must confirm the files ​

Given files in the statements folder When statementFiles are passed without filesConfirmedByOwner Then the call is refused, as in SPEC-003

S8: Statement text is not stored ​

Given statement text sent inline When the check finishes, whether it passed or failed Then no statement text, filename content or cell value remains in the database or logs; only the mapping and the existing short-lived structures of ADR 0032 (QD-34) exist

S9: Bad cell refused without echo ​

Given a row with an impossible date or an amount too large for integer pence When parsed Then the refusal names the row and column and does not include the cell text

S10: Missing rows are not detected silently ​

Given a statement with a gap in its date range or a balance that does not reconcile (where the file has a running balance) When the check runs Then the gap or balance difference is reported as a warning, as ADR 0032 section 4 describes

S11: Xero feed lines unavailable ​

Given an account with source xero_feed and no Finance API access When the check runs Then it says the source is not available and checks nothing, instead of falling back silently to Xero's own records

S12: Companies are isolated ​

Given two companies with accounts of the same name When a mapping is saved or used Then it belongs to one entity under row-level security (CLAUDE.md rule 4)

S13: A bank CSV is recognised by its header row ​

Given a CSV export from one of Barclays, HSBC, Lloyds, NatWest, Santander, Revolut Business, Tide, Monzo, Starling or Wise When the check runs Then the bank's preset reads it: UK dates become YYYY-MM-DD, amounts integer pence, with direction, counterparty, reference and a bank-prefixed id And a header that fits no preset is refused, and one that fits two equally is refused naming both

S14: Non-GBP rows are refused ​

Given a CSV whose currency column holds anything other than GBP When parsed Then the refusal names the row and column, not the value (ADR 0025)

S15: A statement is tokenised once (added 2026-11-02, #297) ​

Given a CSV statement of several megabytes When the formats are asked which of them reads it, and the winner parses it Then the CSV is read into its header and rows once, and that one table is handed to every format's match and parse And every fixture reads to the same lines as before

S16: UTF-16 and Windows-1252 statement files are decoded (added 2026-11-02, #297) ​

Given a statement file in the statements folder saved as UTF-16 (with a byte-order mark) or as Windows-1252 (a pound sign as one byte) When it is read Then its text is decoded before parsing, so the lines read as they would from the same file saved as UTF-8, and the file's content is held in memory only (ADR 0032) And a file that cannot be decoded as text (binary, or UTF-16 with no byte-order mark) is refused with a plain error naming the file and not its content

S17: DD MMM YYYY accepts Sept and full month names (added 2026-11-02, #297) ​

Given a mapping whose date format is DD MMM YYYY When a row's date is 3 Sept 2026, 3 September 2026 or 3 SEP 2026 Then it reads as 2026-09-03, and a word that is no month is still refused by row and column

Data model sketch ​

bank_account.source gains statement_import semantics for all statement accounts (existing statement_file is kept as an alias in the first migration; expand then contract, ADR 0029). New bank_account_mapping (id, entity_id, bank_account_id, format = csv | ofx, mapping jsonb, confirmed_at, confirmed_by). No statement content. The pipeline applies the migration (ADR 0014).

Steps to request Xero Finance API access (for QD-39) ​

  1. Check the app's page in the Xero developer portal for Finance API / bank statement access, and what tier it needs (ADR 0024).
  2. Contact Xero developer support or the partner team, stating the use: read unreconciled bank statement lines for the app's own connected organisations to prepare reconciliation, read-only.
  3. Expect to need App Partner status or a security assessment, and a statement of data handling (ADR 0026).
  4. The Product Owner applies and records the answer here. Until it is yes, slice (c) stays blocked.

Decisions (2026-10-08) ​

QD-39 closed: Product Owner applies for Finance API access, slice (c) blocked until granted. QD-40 closed: formats and banks as in slice (a). QD-41 closed: Starling kept as a live source. QD-42 closed: saved column mapping allowed, ADR 0034 accepted.

As built: a3 (CSV presets) ​

One engine, src/banks/formats/csv-core.ts, reads every preset; each bank is a small data module in src/banks/formats/ (barclays, hsbc, lloyds, natwest, santander, revolut, tide, monzo, starling-csv, wise). Detection is by header cells (case-insensitive); the most specific match wins (specificity = number of required headers), so the loose Amex columns never take a bank's file, and an equal tie is refused naming both formats. A row with a non-GBP currency, both or neither of paid in / paid out, or an unreadable Fee is refused by row and column. Revolut: a non-zero Fee becomes its own outflow line, and only COMPLETED rows are read. Ids are <bank>:<bank id> where the export has one, otherwise <bank>-row: plus the row's content and occurrence.

Presets require only the distinctive header cells, so a small header difference still matches. Amex matches only its own column set and never a file with bank-only columns (Currency, Balance, Type, ID...), so a near-miss bank export is refused, not read with inverted signs. Zero-amount rows are skipped and counted in skippedRows; an unterminated quote is a row error. The high-street presets (Barclays, HSBC, Lloyds, NatWest, Santander, Tide, Starling) have no currency column and assume GBP.

None of these headers was checked against a real export (no network). Each must be confirmed against a real file from that bank before it is relied on; the comment in each module says the same. Confidence:

BankConfidenceNote
Lloydsmedium-highdebit / credit columns
Starling CSVmedium-highAmount (GBP) header
BarclaysmediumNumber,Date,Account,Amount,Subcategory,Memo
NatWest / RBSmediumBankline layout not covered
Monzomediumsubset of columns required
Wisemediumsubset; repeated ids keep every line
Revolut Businessmedium-lowsubset; fee emitted as its own line; only COMPLETED rows read, others counted as skipped
HSBClowpersonal export has no header; business header guessed
Santanderlowpersonal download has preamble lines, unsupported
Tidelowheader guessed

As built: a4 (saved column mapping) ​

A CSV that no preset reads, for a statement-file account with no mapping, is refused by the check with its header names only (each cleaned to one line, labelled as data from the file, never a row), and Claude is told to ask the owner which column is which and never guess (S1). bank_statement_mapping_preview takes the owner's answer and the same statement: the date column and its format (allow-list DD/MM/YYYY, DD-MM-YYYY, DD.MM.YYYY, YYYY-MM-DD, MM/DD/YYYY, DD MMM YYYY), the amount as one signed column with positiveAmountIs (in or out) or as paid in and paid out (S6), the counterparty, and optional reference, currency (GBP only, S14) and transaction id columns. It refuses a column not in the header, used twice or named twice, a file a preset already reads, and any row that does not read with the mapping (by row and column, S9); otherwise it shows the mapping and what it read in the approval card. Only Approve saves it (AUDIT C5), as preview kind statement_mapping, and the card tells Claude it was saved in GetMy Books, not Xero. The activity log keeps the preview (account, roles and header names, the owner's reason), the decision and the outcome.

Storage is migration 0012-statement-mapping.sql: table statement_mapping (not bank_account_mapping as sketched above), one row per entity and bank account, holding the header row and the column settings as jsonb, who approved it and when. Row-level security as for vat_treatment, and the approver must be the signed-in person; the app may not delete a row (S8, S12).

Once saved, the account's files and text are read by csv-core with the mapping when their header row has exactly the saved names (any order, case aside). Any other header row is read by a preset if one fits, else refused naming the missing and new header names and asking for a new mapping (S2, S3). Line ids are mapped:<id> with a mapped transaction id, otherwise mapped-row: plus the row's content and occurrence, as for the presets.

A CSV whose first row holds a date or an amount has no header row: it is refused as such, by the check and the mapping preview, and that row is never shown, saved or logged as header names (ADR 0032).

Follow-up: statement_mapping references bank_account (id) alone. A composite key (entity_id, bank_account_id) → bank_account (entity_id, id) would make a cross-company mapping impossible in the schema too, but bank_account has no unique (entity_id, id) key yet; adding one is its own migration. Row-level security already confines both tables to one company.

As built: statement parsing follow-ups (2026-11-02, #297) ​

parseStatement tokenises a CSV once (tokenise in src/banks/statement-format.ts): the header cells and rows are read into one table that every format's matches and parse receive, so a large file is no longer re-read once per preset (S15). Statement files are read as bytes and decoded in src/banks/statement-encoding.ts before parsing: a UTF-16 byte-order mark selects UTF-16 (little- or big-endian), otherwise strict UTF-8, falling back to Windows-1252; a file that still cannot be decoded, or holds NUL bytes, is refused naming only the file (S16). DD MMM YYYY accepts Sept and full month names in any case (S17).

Amendment: statement content over the deployed route (DH-8, #73) ​

Status: DH-8a (S18 to S24) approved 2026-11-09 by the Product Owner; DH-8b (S25 to S27) specified, not built (DH8-Q1). Decision DH-8 (Product Owner, 2026-11-04, docs/plans/deploy-hardening.md): once port 5433 closes (#73), the owner's real FEAW work goes through the deployed endpoint (DH-6), whose server has no statements folder. So a statement tool takes the CSV content from the client, parses it in pure code with the entity from the session only, within the approved 1 MiB request limit (C4, DEFAULT_MAX_BODY_BYTES in src/web/app.ts), and takes the statement in pages rather than the limit being raised if a full statement does not fit. Every existing guard keeps working: the owner confirms the statement is this company's for this account, checkId flows as now, and statement text is never stored (ADR 0032, ADR 0035).

What already exists ​

The content route is mostly built already, for attachments in claude.ai (ADR 0032 and its amendments; SPEC-003 S19 to S28, S36, S39, S41):

  • statementCsv ([{ name, text, bankAccount? }], at most 12 entries, each text at most 1,000,000 characters) on bank_reconciliation_check, vat_prepare_return and bank_entries_preview; one entry on bank_statement_mapping_preview. Parsed by parseStatement (through src/banks/sources/statement-import.ts), the same parser as files.
  • checkId (the parsed lines held in memory for 60 minutes, src/banks/check-lines-store.ts) on bank_outstanding, bank_explain_line, bank_entries_preview, receipts_reconcile and attachments_missing.
  • Over the limit, the web layer answers HTTP 413 {"error":"The request is too large."} before any tool runs (SPEC-003 S25).

Gaps on the deployed route ​

  1. No owner confirmation for content. filesConfirmedByOwner guards statementFiles only (SPEC-003 S43). Attached text needed none, because the owner chose the attachment. Over the deployed route from Claude Code, Claude reads CSVs from a folder on the owner's computer and passes their text: S41's shared-folder risk moved to the laptop (files chosen by date alone, possibly another company's).
  2. vat_corrections_preview reads statement files only. It takes statementFiles and reads the bank lines again; it has neither statementCsv nor checkId. For a statement-file account it cannot run on a server with no folder.
  3. The hosted guidance says "attach the CSV in the chat". Claude Code has no attachment: it reads the file from the owner's disk.
  4. Over the limit there is only a bare 413, which the owner may see as a failed call.
  5. The web route is read-only (xeroWrites: false). Entering lines from statement content over it (bank_entries_preview) waits for DH-7; the read-only checks do not.

Size, measured 2026-11-09 ​

File sizes and line counts only, never content, of the nine real Amex CSV exports in the owner's local statements folder (FEAW, saved there between 28 September and 6 October 2026): the largest is 22,214 bytes (188 lines); the nine together are 123,685 bytes (1,032 lines, headers included), about 120 bytes a row. In the JSON-RPC request each " and line break is escaped, which for the largest file adds about 2%.

So one month's Amex statement uses about 2% of the 1 MiB limit, and all nine files together about 12%. A statement reaches the limit at roughly 8,000 rows of this width, more than a small company's card or bank account has in a year. At that size the check could not hold its lines for a checkId either: a check of more than 5,000 lines in the period is not held (MAX_HELD_LINES, ADR 0032 amendment of 2026-10-06).

The tighter constraint is the model, not the request. Claude has to write the text out as the tool's argument: a 22 KB statement is several thousand output tokens, and the September exit test showed Claude garbling re-typed rows (QD-34). Statement text over the deployed route is therefore sent one statement period at a time, as attached text is today, and the owner compares the "Statements received" table with the real statement before relying on the check (ADR 0032 section 4).

Decided (2026-11-09): build S18 to S24 now (DH-8a). Paging, S25 to S27 (DH-8b), stays specified so the decision is complete, and is built later, only if a real statement period needs it (DH8-Q1). A full statement fits, so under DH-8 the limit stays at 1 MiB.

Scope (DH-8a) ​

  • No new parser and no new statement source: content is statementCsv, parsed by parseStatement in pure code; nothing in src/rules/ changes.
  • statementCsv needs filesConfirmedByOwner: true wherever it is accepted, as statementFiles does (S19).
  • vat_corrections_preview takes checkId, under SPEC-003 S39's rules (S21).
  • Tool descriptions and the server instructions say how to send a statement from Claude Code: read the CSV from the owner's computer and pass its text exactly, one statement period at a time, at most 900,000 bytes of statement text in one call (S20).
  • The /mcp 413 names the remedy (S22).
  • Statement text never reaches a log, at any layer (S23).

Out of scope (DH-8) ​

  • Raising DEFAULT_MAX_BODY_BYTES.
  • Xero writes on the web route (DH-7, its own spec change).
  • statementCsv on bank_outstanding, bank_explain_line and receipts_reconcile: they keep using the check's checkId.
  • A file upload page or folder on the server (ADR 0031, docs/not-doing.md).
  • A local reader that posts lines to the server directly (ADR 0032 Consequences: its own ADR).

S18: An Amex statement on the owner's computer is checked over the deployed route (approved 2026-11-09, DH-8a) ​

Given the owner uses Claude Code connected to the deployed endpoint, which has no statements folder And an Amex statement-file account, and the owner's Amex CSV for September 2026 on their own computer When the owner has confirmed the file is this company's statement for this account, and Claude passes its text exactly as statementCsv with filesConfirmedByOwner: true to bank_reconciliation_check for September 2026 Then the lines are parsed by code and the result equals the same file read through statementFiles on a local server And the reply shows the "Statements received" table (name, lines, dates, charges and payments in pence) for the owner to compare with the statement, and a checkId And the company comes only from the signed-in session, and nothing of the text is stored

S19: Statement text needs the owner's confirmation, as files do (approved 2026-11-09, DH-8a) ​

Given a statement-file account When bank_reconciliation_check, vat_prepare_return, bank_entries_preview or bank_statement_mapping_preview is given statementCsv without filesConfirmedByOwner: true Then the call is refused before anything is parsed or Xero is read And the refusal lists each statement by its name only and asks Claude to show the owner the file names and their dates and confirm they are this company's statements for this account And the refusal carries no line, amount or description from the text

S20: The deployed server says how to send a statement (approved 2026-11-09, DH-8a) ​

Given the deployed server, with no statements folder When bank_statement_files is called Then it says the server has no statements folder, and to send the statement CSV as statementCsv: an attachment in the chat as it is, or a file on the owner's computer read and passed exactly as it is, never re-typed, summarised or edited And it says to send one statement period at a time, with the owner's confirmation first And the descriptions of the tools that take statementCsv say the same in one line each (SPEC-011 S2)

S21: VAT corrections on a statement-file account use the check's checkId (approved 2026-11-09, DH-8a) ​

Given bank_reconciliation_check or vat_prepare_return read a statement-file account from statementCsv and returned a checkId When vat_corrections_preview is called for that account and period with the checkId Then it uses the held lines, as bank_entries_preview does (SPEC-003 S39), and flags and corrects as it does from files And an unknown or expired checkId, or one held for another person, company, account or period, gets the same refusal as elsewhere, before Xero is read And checkId with statementFiles, or for an account not read from statement files, is refused

S22: A request over the limit names the remedy (approved 2026-11-09, DH-8a) ​

Given a call to /mcp whose body is over the request limit (1 MiB) When it reaches the web layer Then it is answered 413 before any tool runs, with the error "The request is too large. Send the statement one period at a time, such as one month." And nothing in the request is parsed, read or logged And the limit is not raised

S23: Statement text reaches no log, at any layer (approved 2026-11-09, DH-8a) ​

Given a /mcp request carrying statementCsv When it succeeds, is refused by a tool, fails with an unexpected error, or is answered 413 Then no request body, statement text or cell value appears in any log line, alert or error reply (ADR 0032 section 6) And a test sends a marker string in the statement text through each of those paths and finds it in no log output

S24: Content for one company is never used for another (approved 2026-11-09, DH-8a) ​

Given a person signed in through the deployed endpoint, authorised for entity A only When they send statementCsv naming an account of entity B, or name entity B Then nothing is read for entity B and the text is not used (CLAUDE.md rule 4, SPEC-003 S26) And the same text for entity A's own account is checked normally

As built: DH-8a (2026-11-09) ​

  • S19. requireConfirmedStatementFiles (src/mcp/reconciliation/open.ts) takes the call's statementCsv too: without filesConfirmedByOwner: true the four tools that take text refuse it after the company is checked and before anything is parsed or Xero is read, naming each statement by its name only (unconfirmedTextRefusal, src/present/statements.ts). The prompts ask the owner to confirm attached files before passing them.
  • S20. The no-folder reply, bank_statement_files' next step, the statementCsv descriptions (SEND_STATEMENT_TEXT, src/mcp/schemas.ts), the one-line pointer (FILES_RULE_POINTER) and the server instructions (CONFIRM_STATEMENT_FILES) say how to send a statement: an attachment as it is, or a file on the owner's computer read and passed exactly as it is, one period at a time, at most 900,000 bytes of text a call, after the owner's confirmation.
  • S21. vat_corrections_preview takes checkId (lines source checkId). The stored request keeps the checkId (a random id, not statement content) so Approve recalls the same held lines; once they have gone, Approve posts nothing and asks for the check again.
  • S22. /mcp's 413 says "The request is too large. Send the statement one period at a time, such as one month." The limit stays 1 MiB.
  • S23, S24. tests/web/statement-content-logs.test.ts sends a marker in statement text through the web route (refused for confirmation, refused later, an unexpected tool error, and 413), captures stdout, stderr, the console and alerts, and finds the marker nowhere, with a negative control that the capture sees the logger. The same file checks that another company named over the web route reads nothing. A fully successful check is covered by the in-memory tests in tests/mcp/bank-tools.test.ts (SPEC-003 S39, SPEC-010 S6), which already assert nothing of the lines is logged.

Paging (DH-8b: specified, not built; built later if a real statement needs it, DH8-Q1) ​

If a statement period's text is over 900,000 bytes, Claude sends it in pages to one tool, bank_statement_pages, which parses each page in pure code as it arrives and holds only the parsed lines (never the text), in memory, under a statementId, as checkId holds a check's lines. Each page is the file cut at row boundaries, in order, unchanged; only page 1 carries the header row, and the server reads pages 2 onwards with page 1's header names (header names are not statement content: ADR 0032, a4).

S25: A statement too large for one request is sent in pages (specified, not built, DH-8b) ​

Given a statement whose text is over 900,000 bytes, and the owner's confirmation that it is this company's statement for this account When Claude sends it to bank_statement_pages as pages 1 to N, in order, each at most 900,000 bytes, page 1 with the header row, each page ending at a row boundary, with filesConfirmedByOwner: true Then each page is parsed by code as it arrives, and only its parsed lines are held, bound to the person, company and bank account, for 60 minutes from the latest page, as long as a checkId (amended 2026-11-17, #433: was 15) And after page N the reply gives a statementId and the "Statements received" table for the whole statement (name, pages, lines, dates, charges and payments in pence) for the owner to compare with the statement And bank_reconciliation_check and vat_prepare_return take that statementId instead of statementCsv or statementFiles, exactly one of the three per statement-file account, and return a checkId as now

S26: A page that does not fit the statement is refused (specified, not built, DH-8b) ​

Given a statement being sent in pages When a page arrives out of order or twice, ends inside a quoted cell, has a row that page 1's header cannot read, or is over 900,000 bytes Then that page is refused naming its page number, and the row and column where there is one, never a cell's value And the pages already held are dropped, and Claude starts again from page 1 And a statementId for which not every page arrived is refused by the checks, which read nothing

S27: Held pages are bounded and never stored (specified, not built, DH-8b) ​

Given parsed pages held under a statementId When 60 minutes pass with no new page, the server restarts, or the person already holds 5 statements or checks Then the oldest are dropped, as for checkId (MAX_HELD_CHECKS_PER_PRINCIPAL, MAX_HELD_CHECKS), and a check that needs them asks for the statement again And a statement over the held-lines cap is refused at the page that crosses it, telling Claude to send a shorter period And no page text, held line or statementId is written to the database, a file or a log, and a statementId held for another person, company or account gets the same refusal as an unknown one

Decisions (DH-8, Product Owner, 2026-11-09) ​

Answered on PR #383. Each question and its recommendation are kept after the answer.

  • DH8-Q1, paging. Decided: paging later; S25 to S27 stay specified, not built. Measured, one month of FEAW's Amex uses about 2% of the limit, and the limit is reached only around 8,000 rows, past the 5,000-line cap a check can hold for a checkId. Recommended: build DH-8a only, and build DH-8b if a real statement period ever exceeds 900,000 bytes. If DH-8b is wanted now, the held-lines cap must rise for paged statements (S27), or paging is unreachable in practice.
  • DH8-Q2, confirmation for attached text. Decided: yes, one rule for files and content. S19 asks the owner to confirm attached text too, which they chose themselves: one more question in claude.ai, for one rule everywhere. Recommended: yes, one rule; the server cannot tell an attachment from a file Claude chose.
  • DH8-Q3, model output. Decided: accepted for the deployed route, relying on the existing parse and gap checks and the owner's comparison with the "Statements received" table. Over the deployed route Claude writes the whole statement out as the tool's argument (several thousand output tokens a month, and rows can be garbled, QD-34). The owner's comparison with the "Statements received" table is the only catch. Accept this for DH-6, or open the "local reader posting lines" ADR that ADR 0032 names as the next step?
  • DH8-Q4, ADR 0032. Decided: a short dated amendment note in ADR 0032 (added 2026-11-09). S19 and S21 change ADR 0032's rules (confirmation of text; VAT corrections no longer files only), and DH-8b would add a held statementId. Recommended: a short amendment to ADR 0032 with this approval, not a new ADR.