# Financial import parser, deduplication, and transfer-pairing inventory

Use this reference for a read-only pre-implementation inventory of household bank, card, receipt, or wallet imports before changing parser or reconciliation code.

## Scope and safety

- Pin the exact commit and verify a clean worktree before inspecting code.
- Read source, migrations, API routes, and synthetic tests only. Do not open productive databases, reports, raw imports, archives, or secrets.
- Trace the complete path: raw input → decoding/profile detection → row normalization → semantic identity/fingerprint → candidate insert → duplicate classification → review/confirm → canonical ledger → transfer relation/audit.
- Run focused synthetic tests and disposable in-memory probes. Recheck the worktree afterward.

## Parser inventory matrix

For every source profile, record:

- detection columns and filename fallback;
- actual delimiter/encoding behavior, not merely declarative profile metadata;
- booking date versus value date precedence;
- original signed amount preservation;
- original currency preservation;
- provider transaction ID and account/card identity mapping;
- description/merchant composition;
- receipt grouping and line-item semantics;
- malformed-row behavior and error visibility.

Treat declared fields such as `fingerprint_columns`, `encoding`, `currency_columns`, and `account_columns` as unproven until their consumers are traced. A profile constant is not evidence that the import path uses it.

## Duplicate-protection layers

Inventory each layer separately:

1. **Original-file identity:** hash unchanged bytes where possible; distinguish content identity from decoded/re-encoded text identity.
2. **Semantic document identity:** provider, account, export period, statement/document ID, and source revision.
3. **Row/event identity:** prefer stable provider transaction IDs; otherwise canonical source/account/date/signed amount/currency/reference identity.
4. **Candidate uniqueness:** confirm whether fingerprints have database uniqueness constraints or are informational only.
5. **Candidate-to-candidate overlap:** test renamed files, shifted row numbers, reordered exports, overlapping monthly ranges, and later richer exports.
6. **Candidate-to-confirmed matching:** include account, sign/direction, currency, date policy, transaction type, and merchant/reference evidence.
7. **Source precedence:** receipt versus card, bank transfer versus card settlement, and other intentional coverage rules.

A deterministic candidate ID containing filename or row number proves only same-file replay safety. It does not prove overlap safety. Likewise, a whole-file hash prevents identical-file replay but not overlapping exports with different bytes.

## Required synthetic probes

Use synthetic identifiers and in-memory storage to verify:

- identical bytes, same filename;
- identical bytes, renamed file;
- same event in a changed/overlapping export;
- same date/amount/merchant on different own accounts;
- same magnitude with opposite signs or different transaction types;
- non-CHF and negative card rows;
- discount/refund/return line items in receipt aggregation;
- same receipt repeated under another filename;
- later receipt export containing extra line items;
- manual confirmed transaction versus imported candidate;
- duplicate override requiring an audited reason.

Report observed persisted fields, not assumptions: signed amount, currency, account identity, raw fingerprint, candidate count, duplicate status, and canonical transaction link.

## Transfer-pairing trace

Confirm that the matcher:

- maps both candidates to known active own accounts;
- rejects same-account, same-sign, amount mismatch, currency mismatch, date-window violations, and ambiguous counterparts;
- searches across source types, files, and import runs;
- uses text only as supporting evidence;
- creates proposals only, never auto-confirms;
- revalidates all matching invariants inside the write transaction, including the date window;
- excludes a candidate already confirmed in either source or target role;
- writes exactly two signed transfer ledger rows plus one relation atomically;
- remains idempotent under repeat and competing confirms;
- leaves no income/expense budget effect;
- redacts raw account references, filenames, paths, and diagnostics from API/UI/audit surfaces.

Record both pair quality and candidate confidence. A hard-coded candidate confidence is not a substitute for explicit pair-quality evidence.

## Account mapping checks

- Trace exact matching against canonical account ID, linked account ID, safe source alias, and account name.
- Verify ambiguous name hints fail closed.
- Do not require storage or exposure of full IBAN/card numbers merely to make matching work; use stable redacted aliases or explicit mapping records.
- Test every source, including card accounts. Bank-to-card settlement cannot pair if the card import drops card identity or signed direction.

## Manual-entry compatibility

Do not stop after proving imported pair confirmation. Compare the legacy/manual transaction and transfer paths:

- signed direction of both ledger sides;
- transaction type and budget aggregation semantics;
- atomicity across both rows, relation, and audit;
- idempotency and deterministic IDs;
- account and currency validation;
- duplicate matching against manual rows.

If manual and imported transfers use different sign or commit semantics, report this as a compatibility boundary rather than calling the transfer model unified.

## Preview/confirm contract

Preview should be side-effect free apart from explicitly allowed quarantined evidence storage, and should preflight the same collisions as Confirm. Confirm should re-read immutable evidence, recompute its hash and semantic identity, reparse it, verify the Preview identity/database revision, and then write candidates atomically. Clearly separate “candidate creation” from “ledger confirmation.”

## Reporting shape

Return:

1. exact baseline and read-only status;
2. reusable files, symbols, schema, and tests;
3. a per-source parser matrix;
4. duplicate layers and overlap behavior;
5. transfer matcher/account mapping/confirm behavior;
6. manual-entry compatibility;
7. tested evidence and gaps, prioritized by double-counting or ledger-corruption risk;
8. explicit statement that no productive data was accessed and no files were changed.