feat: add governed payment request slice

docs/PAYMENTS_DOMAIN.md

@@ -0,0 +1,67 @@
+# Payments Domain Boundary
+
+## Purpose
+
+Payments records payment obligations and authoritative settlement evidence for
+GovOPlaN procedures. The first vertical slice is deliberately narrow: a Case,
+Workflow, or other owner requests a fixed amount, and an authorized operator
+records a full offline/manual receipt against immutable evidence.
+
+## Ownership and contract
+
+Payments owns:
+
+- the tenant-bound payment ID and human payment reference;
+- requested amount, ISO currency, subject, due time, and lifecycle state;
+- replay-safe request and reconciliation semantics;
+- the external transaction reference and typed evidence reference; and
+- append-only request and reconciliation events.
+
+Procedure modules call Core's `payments.requests` capability. They provide
+their own stable source resource and optional Case/Workflow context references,
+then retain the returned payment ID. They never import Payments models.
+Payments does not own the Case, Workflow, applicant, invoice, journal entry,
+evidence binary, or payment-provider transaction.
+
+## Manual reconciliation
+
+The first path supports exactly one full reconciliation. The supplied amount
+and currency must equal the obligation. Evidence must belong to the same tenant
+and carry a version or checksum so the observation can be reconstructed. The
+operator also records the external transaction reference and received time;
+the API assigns the recorded time from the server clock. All supplied
+timestamps require a timezone.
+
+The request and reconciliation commands are idempotent. Reusing a key with the
+same canonical command returns the existing result; changing any material
+field conflicts. Once paid, another reconciliation under a different key fails
+closed. Corrections, reversals, refunds, chargebacks, partial payments, and
+overpayments require future append-only adjustment types and must never mutate
+the original evidence silently.
+
+## Access, privacy, and audit
+
+Payment readers see obligation and reconciliation metadata. Writers create
+obligations, while the separate reconciliation permission records receipt.
+The contract needs stable procedure references, not applicant names, bank
+account details, or Form values. Evidence bytes remain with Files or another
+owner; Payments stores only `EvidenceReference` metadata.
+
+Each state transition writes a Payment event. API transitions also emit Core
+audit evidence; installations with Audit retain it through the Audit owner.
+Automated capability consumers must retain their own command/effect evidence
+and the returned payment ID in the owning Case or Workflow.
+
+## Recovery and retirement
+
+Restore obligations, reconciliations, and events together. Verify one unique
+payment ID and payment reference per tenant, one matching reconciliation for
+each `paid` obligation, exact amount/currency equality, same-tenant immutable
+evidence, and ordered lifecycle events. Replay the original keys and hashes to
+confirm they return the restored objects.
+
+Destructive retirement is blocked while any of the three tables contain data.
+It requires a verified database snapshot and an explicit records/accounting
+decision for the retained evidence references. Ledger posting, XRechnung,
+online checkout, callbacks, and provider reconciliation are not implied by this
+slice.