Finance reconciliation: vendor parsers + deterministic matcher (closes unimatrix27/ideas#22)

[unimatrix27]

Summary

Implements the matching half of the Mode-B reconcile agent. Two deliverables, scope-locked to unimatrix27/ideas#22:

1. Vendor parsers (finance/parsers/) — pure functions returning extracted_json for Sipgate, Notion, Lucky Penny, and Vodafone (PDF + portal notification). Single dispatch via finance.parsers.parse(candidate). Failed parses emit parse_status='failed' | 'portal_required' with a parse_error, never silently wrong fields (per fix: align threading docstring with implementation NousResearch/hermes-agent#27's honest-tool-boundaries rule).
2. Deterministic matcher (finance/matcher.py) — walks open bank.transactions, scores every receipt_candidates row, writes decision_status='proposed' (or manual_needed for portal-only) to bank.receipt_matches with stable JSON reason codes.

Closes unimatrix27/ideas#22. Do not merge — needs review per the issue's acceptance criteria. Depends on PR #1 (schema, currently open) and PR #2 (fixture pack, currently open); both branches are merged into this one so the working tree has both prerequisites.

DB strategy: (A) — pure-function tests, adapter mocked

Per the implementing-agent brief, two strategies were viable. I picked (A):

Parsers are already pure (text → dict | None). For the matcher, write a thin DB adapter and mock it in tests. Fast, simple, no Postgres setup.

Rationale:

• Strategy (A) keeps the entire test suite offline and second-fast — no Docker, no fixture-DB seeding, no Postgres on CI.
• The matcher's logic is fully exercised by InMemoryMatcherAdapter loaded from the Endless Terminals Environment Integration NousResearch/hermes-agent#24 fixture JSONL. State transitions are unit-testable.
• A thin PostgresMatcherAdapter ships alongside the in-memory one for the cron entrypoint — it mirrors PR Finance reconciliation: schema + backfill (closes unimatrix27/ideas#20) #1's psycopg2/RealDictCursor style and writes only to bank.receipt_matches (reads-only against bank.transactions and bank.receipt_candidates). Terminal backend fanout pr2 - PENDING NousResearch/hermes-agent#23's toolbox can call run_matcher(PostgresMatcherAdapter(conn)) directly.
• No new migration was needed; the existing schema from PR Finance reconciliation: schema + backfill (closes unimatrix27/ideas#20) #1 already allows receipt_candidate_id IS NULL and the legacy_meta lookup pattern.

Files

Path	Purpose
finance/parsers/__init__.py	parse(candidate) dispatch + vendor detection cascade
finance/parsers/sipgate.py	Rechnungsnummer / Rechnungsdatum / Rechnungsbetrag label parser
finance/parsers/notion.py	Invoice number ZWLWGPDN-… + English date + Amount due €…
finance/parsers/lucky_penny.py	Tax invoice + credit-note variants, Refunded invoice reference: for credit notes
finance/parsers/vodafone.py	PDF parse with Höhe von …,… EUR anchor, plus parse_status='portal_required' for MeinVodafone notifications
finance/matcher.py	Transaction / Candidate / ProposedMatch dataclasses, MatcherAdapter Protocol, InMemoryMatcherAdapter, PostgresMatcherAdapter, vendor cascade, scoring, idempotent upsert
finance/tests/test_parsers.py	Per-vendor parser tests against NousResearch#24 fixtures (11 tests)
finance/tests/test_matcher.py	Per-named-TX acceptance tests + invariants + idempotency (16 tests)

Per-acceptance-criterion checklist

Every named TX outcome from NousResearch#22's acceptance section is covered by a dedicated test:

• Sipgate B4373121 → TX 56 — very_high / exact_invoice_number, reason_codes include invoice_no:B4373121, amount_eq:40.00, date_within:1d, mcc:4814. test_sipgate_b4373121_proposes_very_high_on_tx56.
• Sipgate B4411208 → TX 31 — very_high / exact_invoice_number, reason_codes include invoice_no:B4411208, amount_eq:55.00. test_sipgate_b4411208_proposes_very_high_on_tx31.
• Sipgate B4459838 → TX 5 already sent — matcher writes zero code-decided rows for TX 5. test_sipgate_b4459838_skipped_because_tx5_already_sent.
• Lucky Penny 6945-10683 → TX 39 — high / exact_amount_date, reason_codes include invoice_no:6945-10683, amount_eq:59.50, mcc:5817. test_lucky_penny_6945_10683_proposes_high_on_tx39.
• Lucky Penny credit note → TX 20 — high / refund_to_invoice, reason_codes include refund_ref:6945-10683, direction:refund, amount_eq:9.50. test_lucky_penny_credit_note_proposes_high_on_tx20.
• Notion ZWLWGPDN-0002 → TX 66 already sent — zero code-decided rows for TX 66. test_notion_tx66_skipped_already_sent.
• Notion TX 88 → no candidate exists — zero proposed rows (no Notion candidate matches by amount/period). test_notion_tx88_no_proposal_because_no_candidate_exists.
• Vodafone TX 53 already sent — zero code-decided rows. test_vodafone_tx53_skipped_already_sent.
• Vodafone TX 1 → BOTH manual_needed / portal_only AND very_high / exact_invoice_number on remittance — both rows verified, invoice_no_in_remittance:122064713086, portal_required:vodafone. test_vodafone_tx1_writes_portal_only_AND_invoice_in_remittance.
• TX 27 (Vodafone, ignored=true) — matcher skips entirely despite remittance invoice number. test_vodafone_ignored_tx27_skipped.

Matcher invariants (per NousResearch#27)

Verified by dedicated tests:

• Never writes approved / sent / rejected / ignored. test_matcher_never_writes_approved_or_sent_or_rejected.
• decided_by='code' for everything matcher-written. test_matcher_decided_by_is_always_code.
• Idempotent: re-running with no new state produces zero new rows. test_matcher_is_idempotent.
• Updates existing reason_codes in place when signals change (no duplicate rows). test_matcher_updates_reason_codes_when_signals_change.
• Ignored transactions skipped at iteration boundary, including those with remittance invoice numbers (TX 27).
• Read-only against bank.transactions and bank.belege_sent — PostgresMatcherAdapter only writes to bank.receipt_matches.

Vendor cascade + reason codes

The matcher emits vendor:<key> and mcc:NNNN (when present) on every proposal. Vendor identification cascade per NousResearch#22:

1. counterparty_name substring (e.g. SIPGATE, NOTION LABS, PADDLE.NET* LUCKYPENNY, Vodafone GmbH)
2. MCC from transactions.raw.merchant_category_code or remittance_information (MCC: 4814)
3. Vendor-specific remittance regex (Vodafone Rechnungsnr:)

Reason-code tokens are stable strings, no prose, JSON-array-shaped — both humans and the LLM agent (NousResearch#25) consume them directly.

Scoring rules

Signal	Confidence	match_type
Vodafone invoice number in transactions.remittance_information	very_high	exact_invoice_number (candidate_id NULL)
Candidate invoice number found in tx remittance	very_high	exact_invoice_number
Candidate has invoice_date + exact amount + date within ±3 days	very_high	exact_invoice_number
Exact amount + date within ±3 days (no specific invoice_date; e.g. Lucky Penny period_end)	high	exact_amount_date
Exact amount + billing period covers tx date	high	vendor_period
Billing period covers tx date (no amount match)	medium	vendor_period
Credit-note refund amount + tx is credit	high	refund_to_invoice
Portal-required candidate + non-ignored vendor tx with no sent match	n/a	portal_only → manual_needed

The wide-vendor-only fallback was deliberately dropped — it produced too much cross-month noise (every Sipgate candidate against every Sipgate tx) and the spec's "over-proposes deliberately" still holds via the medium period band.

Test run

$ python -m pytest finance/tests/ -q -o addopts=''
................................................                         [100%]
48 passed in 0.05s

Out of scope (intentionally not in this PR)

• Indexer logic (Gateway interrupt loop: get_pending_message never clears, causing infinite recursion NousResearch/hermes-agent#21).
• Toolbox / CLI verbs / send_match / approve_match / flag_anomaly (Terminal backend fanout pr2 - PENDING NousResearch/hermes-agent#23).
• Agent skill / hunter / cron registration (Nous Portal subscription integration NousResearch/hermes-agent#25, Receiving API errors when messaging through Telegram and using Nous Portal auth NousResearch/hermes-agent#28).
• New vendors beyond Sipgate / Notion / Lucky Penny / Vodafone.
• Anything that approves, sends, rejects, or ignores. The matcher only proposes.

Notes for reviewers

• Both PR Finance reconciliation: schema + backfill (closes unimatrix27/ideas#20) #1 (schema) and PR Finance reconciliation: fixture pack (closes unimatrix27/ideas#24) #2 (fixtures) are merged into this branch. Once they land on main, those merge commits can be dropped in a rebase.
• finance/scripts/build_fixtures.py (from PR Finance reconciliation: fixture pack (closes unimatrix27/ideas#24) #2) is unchanged.
• The Vodafone TX 27 case (ignored) was added as an explicit test even though it wasn't in Env robustness: context-safe prompting + tool arg normalization NousResearch/hermes-agent#22's acceptance list — the issue mentions the ignored-skip invariant and Vodafone is the easiest vendor to verify it against.

🤖 Generated with Claude Code

[github-actions]

🔎 Lint report: feat/finance-parsers-and-matcher vs origin/main

ruff

Total: 1 on HEAD, 0 on base (🆕 +1)

🆕 New issues (1):

Rule	Count
PLW1514	1

First entries

finance/scripts/build_fixtures.py:138: [PLW1514] `pathlib.Path(...).read_text` without explicit `encoding` argument

✅ Fixed issues: none

Unchanged: 0 pre-existing issues carried over.

ty (type checker)

Total: 7982 on HEAD, 7967 on base (🆕 +15)

🆕 New issues (15):

Rule	Count
unresolved-import	12
invalid-argument-type	1
possibly-missing-submodule	1
invalid-assignment	1

First entries

finance/verify_backfill.py:12: [unresolved-import] unresolved-import: Cannot resolve imported module `psycopg2`
finance/verify_backfill.py:13: [unresolved-import] unresolved-import: Cannot resolve imported module `psycopg2.extras`
finance/tests/test_matcher.py:12: [unresolved-import] unresolved-import: Cannot resolve imported module `pytest`
finance/scripts/build_fixtures.py:52: [unresolved-import] unresolved-import: Cannot resolve imported module `pymupdf`
finance/tests/test_fixture_pack.py:11: [unresolved-import] unresolved-import: Cannot resolve imported module `pytest`
finance/tests/test_parsers.py:12: [unresolved-import] unresolved-import: Cannot resolve imported module `pytest`
finance/scripts/build_fixtures.py:51: [unresolved-import] unresolved-import: Cannot resolve imported module `psycopg2.extras`
finance/backfill_receipts.py:29: [unresolved-import] unresolved-import: Cannot resolve imported module `psycopg2`
finance/matcher.py:88: [invalid-argument-type] invalid-argument-type: Argument is incorrect: Expected `date`, found `(Any & ~str & ~datetime) | None | date`
finance/scripts/build_fixtures.py:50: [unresolved-import] unresolved-import: Cannot resolve imported module `psycopg2`
finance/matcher.py:597: [unresolved-import] unresolved-import: Cannot resolve imported module `psycopg2.extras`
finance/backfill_receipts.py:30: [unresolved-import] unresolved-import: Cannot resolve imported module `psycopg2.extras`
finance/migrate.py:18: [unresolved-import] unresolved-import: Cannot resolve imported module `psycopg2`
finance/scripts/build_fixtures.py:218: [possibly-missing-submodule] possibly-missing-submodule: Submodule `error` might not have been imported
finance/parsers/vodafone.py:124: [invalid-assignment] invalid-assignment: Invalid subscript assignment with key of type `Literal["gross_amount"]` and value of type `int | float` on object of type `dict[str, str]`

✅ Fixed issues: none

Unchanged: 4210 pre-existing issues carried over.

Diagnostics are surfaced as warnings — this check never fails the build.