Source code for pain001_mcp._clearing

# SPDX-FileCopyrightText: 2023-2026 Sebastien Rousseau <sebastian.rousseau@gmail.com>
# SPDX-License-Identifier: Apache-2.0 OR MIT

"""The clearing simulation over a staged batch.

Each clearing system is one row of :data:`_CLEARING`: its settlement
window and the function that returns its checks. A check passes or
fails; the batch is accepted only when every check passes.
"""

from collections.abc import Callable
from typing import Annotated, Any, Literal

from pain001 import canonicalize_payment_record
from pydantic import Field

from pain001_mcp._schemes import _upper
from pain001_mcp._shapes import ClearingCheck, SimulateClearingResult
from pain001_mcp._staging import _open_order, _StageId

_Records = list[dict[str, Any]]

_SEPA_COUNTRY_CODES: frozenset[str] = frozenset(
    {
        "AD",
        "AT",
        "BE",
        "BG",
        "CH",
        "CY",
        "CZ",
        "DE",
        "DK",
        "EE",
        "ES",
        "FI",
        "FR",
        "GB",
        "GI",
        "GR",
        "HR",
        "HU",
        "IE",
        "IS",
        "IT",
        "LI",
        "LT",
        "LU",
        "LV",
        "MC",
        "MT",
        "NL",
        "NO",
        "PL",
        "PT",
        "RO",
        "SE",
        "SI",
        "SK",
        "SM",
        "VA",
    }
)

_ClearingSystem = Annotated[
    Literal["EPC-SEPA", "FedNow", "US-ACH", "SWIFT-MX", "CHAPS", "BACS"],
    Field(
        description=(
            "Target clearing system simulation profile to evaluate "
            "settlement eligibility, cut-off windows, and routing constraints."
        )
    ),
]


def _check(name: str, ok: bool, passed: str, failed: str) -> ClearingCheck:
    """Return one check, with the detail that matches its outcome."""
    return {
        "check": name,
        "status": "PASS" if ok else "FAIL",
        "detail": passed if ok else failed,
    }


def _currency_check(
    records: _Records, name: str, currency: str, failed: str
) -> ClearingCheck:
    """Check that every payment is denominated in ``currency``."""
    ok = all(_upper(r, "currency") == currency for r in records)
    return _check(name, ok, f"All payments denominated in {currency}", failed)


def _in_sepa(record: dict[str, Any]) -> bool:
    """Whether both IBANs of ``record`` carry a SEPA country prefix."""
    debtor = _upper(record, "debtor_account_IBAN")[:2]
    creditor = _upper(record, "creditor_account_IBAN")[:2]
    return debtor in _SEPA_COUNTRY_CODES and creditor in _SEPA_COUNTRY_CODES


def _sepa_checks(records: _Records) -> list[ClearingCheck]:
    """EUR only, SEPA-zone accounts, and the SLEV charge bearer."""
    all_slev = all(
        str(r.get("charge_bearer", "SLEV")).strip().upper() == "SLEV"
        for r in records
    )
    return [
        _currency_check(
            records,
            "EPC-SEPA Currency Rule (EUR)",
            "EUR",
            "All SEPA transfers must be denominated in EUR",
        ),
        _check(
            "SEPA-Zone Routing Eligibility",
            all(_in_sepa(r) for r in records),
            "Debtor and creditor accounts reside in SEPA member jurisdictions",
            "IBAN country prefix outside SEPA clearing jurisdiction",
        ),
        _check(
            "EPC Charge Bearer Standard (SLEV)",
            all_slev,
            "Charge bearer set to SLEV as mandated by EPC",
            "Charge bearer must be SLEV for standard SEPA credit transfers",
        ),
    ]


def _fednow_checks(records: _Records) -> list[ClearingCheck]:
    """USD only; real-time settlement is always available."""
    return [
        _currency_check(
            records,
            "FedNow Currency Rule (USD)",
            "USD",
            "FedNow instant payments must be denominated in USD",
        ),
        {
            "check": "FedNow 24/7/365 Real-Time Settlement",
            "status": "PASS",
            "detail": (
                "Participating FI connectivity active for immediate gross settlement"
            ),
        },
    ]


def _swift_checks(records: _Records) -> list[ClearingCheck]:
    """Both agent BICs present for correspondent routing."""
    has_bics = all(
        bool(str(r.get("debtor_agent_BIC", "")).strip())
        and bool(str(r.get("creditor_agent_BIC", "")).strip())
        for r in records
    )
    return [
        _check(
            "SWIFT CBPR+ BIC Routing",
            has_bics,
            "Valid debtor and creditor agent BICs present for cross-border routing",
            "Missing debtor or creditor agent BIC required for SWIFT network",
        )
    ]


def _currency_only(
    name: str, currency: str, failed: str
) -> Callable[[_Records], list[ClearingCheck]]:
    """Return the checks function of a system that only checks currency."""
    return lambda records: [_currency_check(records, name, currency, failed)]


#: Settlement window and checks of every simulated clearing system.
_CLEARING: dict[str, tuple[str, Callable[[_Records], list[ClearingCheck]]]] = {
    "EPC-SEPA": ("Next SEPA Cycle (Same Day / D+1)", _sepa_checks),
    "FedNow": ("Instant (< 20 seconds)", _fednow_checks),
    "US-ACH": (
        "Next Business Day ACH Window",
        _currency_only(
            "NACHA ACH Currency Rule (USD)",
            "USD",
            "Domestic US ACH requires USD denomination",
        ),
    ),
    "SWIFT-MX": ("Correspondent Banking Network (D+1 to D+2)", _swift_checks),
    "CHAPS": (
        "Same Day (pre-16:00 UK cut-off)",
        _currency_only(
            "CHAPS Currency Rule (GBP)",
            "GBP",
            "CHAPS high-value RTGS requires GBP denomination",
        ),
    ),
    "BACS": (
        "Three-Day Clearing Cycle",
        _currency_only(
            "BACS Currency Rule (GBP)",
            "GBP",
            "BACS direct credits require GBP denomination",
        ),
    ),
}


[docs] def simulate_clearing( stage_id: _StageId, clearing_system: _ClearingSystem = "EPC-SEPA", ) -> SimulateClearingResult: """Simulate settlement and clearing network execution for a staged batch. Evaluates network-specific rulebooks and clearing constraints: - EPC-SEPA: EUR currency mandate, SEPA-zone IBAN prefixes, SLEV charge bearer. - FedNow: USD instant gross settlement eligibility. - US-ACH: USD next-day clearing cycle routing. - SWIFT-MX: Cross-border correspondent banking BIC routing. - CHAPS: Same-day RTGS high-value GBP clearing. - BACS: Three-day GBP direct credit clearing. Args: stage_id: Staging identifier from stage_payment_batch. clearing_system: Clearing rail profile to simulate. Returns: SimulateClearingResult with verdict (ACCEPTED / REJECTED), detailed checks, and estimated settlement window, or {"error": ...}. """ order, problem = _open_order(stage_id) if order is None: return {"error": problem} if clearing_system not in _CLEARING: return {"error": f"Unsupported clearing system: {clearing_system}"} settlement_window, run_checks = _CLEARING[clearing_system] records = [canonicalize_payment_record(r) for r in order.records] checks = run_checks(records) accepted = all(c["status"] == "PASS" for c in checks) return { "stage_id": stage_id, "clearing_system": clearing_system, "clearing_status": "ACCEPTED" if accepted else "REJECTED", "settlement_window": settlement_window, "checks": checks, }