feat(mcp): already-explained voucher guard at stage and commit for match_batch_allocate (#2294) (#2346)

* feat(mcp): already-explained voucher guard at stage and commit for match_batch_allocate

The dashboard match-batch route refused BATCH_TX_POSSIBLE_DUPLICATE when
posted, unlinked vouchers already summed to the bank row (PR #2300), but the
MCP door (gnubok_match_batch_allocate staging + commitMatchBatchAllocate)
called the RPC with no guard, so an agent could book a Bankgirot aggregate a
second time. The detector existed once; the guard lived in one door.

One shared decision helper, lib/invoices/already-explained-guard.ts, now
sits on top of the existing detectors (no fork) and is called by the
dashboard route, the MCP staging tools and the commit executors:

- gnubok_match_batch_allocate refuses to stage, coded
  BATCH_TX_POSSIBLE_DUPLICATE, naming the vouchers, the reconcile_match /
  link_transaction_to_journal_entry call that resolves the row, and the
  exact force + expected_journal_entry_ids binding.
- commitMatchBatchAllocate runs the same guard before the RPC and
  re-validates a staged force binding against the set detected at commit,
  so a stale approval cannot book a duplicate; 409 auto-rejects with the
  vouchers in result_data.
- force + expected_journal_entry_ids on the tool mirror MatchBatchSchema;
  an honoured override stages with a compliance_warning and, after the
  booking succeeds, writes BankTransactionDuplicateDismissed to
  behandlingshistorik (dashboard route included; it only logged before).
- gnubok_match_transaction_to_invoice and commitMatchTransactionInvoice get
  the dashboard's 1:1 soft-duplicate guard (MATCH_INVOICE_POSSIBLE_DUPLICATE
  / MATCH_INVOICE_FORCE_CANDIDATE_MISMATCH) with force +
  expected_journal_entry_id; at commit it runs before the storno.
- Registry: both duplicate codes gain retryable: false and a remediation.

Catalog payload held under the 60K ceiling by trimming the two tools' own
descriptions (59 988 measured, ledger entry in payload-size.bench.test.ts).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019SaJfqNi4VmsG8FMKq99G6

* docs(decisions): record the 2026-09-06 ten-issue batch's first-principles choices

Carries the DECISIONS.md lines for PRs #2337 #2339 #2340 #2341 #2342 #2343 #2344 #2345 #2346 #2347 in one place so the ten branches do not conflict on this file.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019SaJfqNi4VmsG8FMKq99G6

* fix(mcp): refuse an unverifiable forced override, surface a failed duplicate check, validate the binding (#2294 review)

Review round on PR #2346 (CodeRabbit + compliance):

- guardAlreadyExplained returned 'clear' when the detector threw even with
  force=true, so a forced 1:N override could book without re-validating
  expected_journal_entry_ids and left no behandlingshistorik record. It now
  returns a distinct 'unverifiable' outcome under force (mirrors
  guardDuplicatePaymentVoucher); the dashboard route, the MCP staging tool
  and the commit executor all refuse it with the new registry code
  BATCH_TX_EXPLAINED_CHECK_FAILED (409, retryable, remediation). Regression
  tests on every caller.
- A detector failure without force still fails open at stage time, but no
  longer silently: the tools track onDetectError and stage a
  complianceNote, so preview_data.compliance_warning is set on both
  match_batch_allocate (GenericPreview renders it) and
  match_transaction_invoice (MatchTransactionInvoicePreview now renders
  data.compliance_warning through AttnLine).
- expected_journal_entry_ids / expected_journal_entry_id are validated at
  the MCP boundary (array of 1 to 10 non-empty strings / non-empty string)
  and refused with VALIDATION_ERROR instead of being silently filtered.
  No schema description text added: catalog payload unchanged.
- RoPA: .compliance/ropa.yaml gains bookkeeping.duplicate_dismissal_history
  for the BankTransactionDuplicateDismissed record (Art. 6(1)(c), BFNAR
  2013:2 p. 9.16, retention per BFL 7 kap, stored in processing_history).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

---------

Co-authored-by: Jakob Wennberg <311770904+jakobwennberg-oss@users.noreply.github.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

.compliance/ropa.yaml

@@ -818,6 +818,48 @@ processing_activities:
       - company_name_header_injection_sanitized
       - cron_secret_authenticated_trigger
 
+  - id: bookkeeping.duplicate_dismissal_history
+    name: Behandlingshistorik för åsidosatt dubblettkontroll
+    purpose: >-
+      Bevara en oföränderlig post i behandlingshistoriken (processing_history,
+      händelsetyp BankTransactionDuplicateDismissed) när en användare eller en
+      API-nyckel bokför en banktransaktion trots att dubblettkontrollen visade
+      att bokförda verifikat redan förklarar den (force=true i dashboarden,
+      i MCP-verktyget eller vid godkännande av en väntande operation). Posten
+      gör beslutet rekonstruerbart för revisor och Skatteverket: vilka
+      verifikat som åsidosattes, belopp, konto, datum och vem som fattade
+      beslutet. Innehåller endast interna id:n, verifikationsnummer, belopp
+      och datum; aldrig motpartsnamn, transaktionsbeskrivningar eller
+      personnummer.
+    lawful_basis: art_6_1_c   # BFL 5 kap. 11 § + BFNAR 2013:2 p. 9.16 (behandlingshistorik)
+    special_category_basis: null
+    controller: gnubok-tenant
+    processor: supabase
+    data_subjects:
+      - company_member          # the user (or API-key owner) who honoured the override
+    data_categories:
+      - user.activity_timestamp
+      - user.financial.transaction   # amount + settlement account of the bank row, no counterparty
+    recipients:
+      - name: Supabase
+        country: EU
+        role: processor
+    international_transfers:
+      applicable: false
+      mechanism: null
+    retention:
+      duration: through_seventh_calendar_year_after_fiscal_year_end
+      basis: bfl_7_kap_and_gdpr_storage_limitation
+      stored_in:
+        - processing_history
+    security_measures:
+      - rls_company_scoped
+      - service_role_insert_only_no_update_or_delete_triggers
+      - personnummer_pattern_rejected_at_append
+      - ids_labels_amounts_dates_only_never_descriptions_or_counterparties
+      - actor_recorded_as_pseudonymous_user_or_api_key_id
+      - written_only_after_the_booking_succeeded
+
   - id: documents.own_company_supplier_guard
     name: Egenbolagskontroll vid dokumentextraktion
     purpose: >-