patchr 0.1.0__py3-none-any.whl

picux/domains/pay/engine.py

@@ -0,0 +1,950 @@
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+import os
+from collections.abc import Callable
+from datetime import datetime, timedelta, timezone
+from typing import Any, Mapping
+
+from .adapters import PayRailAdapter, PayRailAdapterContext, defaultAdapters
+from .models import Money, ProofOfValue, SettlementAdapterSpec, SettlementRequest
+
+SignatureVerifier = Callable[[dict[str, Any], str, str], bool]
+
+
+class PayDomain:
+    """Mandate and settlement engine for Picux PAY."""
+
+    def __init__(
+        self,
+        *,
+        verifier: SignatureVerifier | None = None,
+        clock: Callable[[], datetime] | None = None,
+        env: Mapping[str, str] | None = None,
+        adapters: list[PayRailAdapter] | None = None,
+    ) -> None:
+        self.verifier = verifier
+        self.clock = clock or (lambda: datetime.now(timezone.utc))
+        self.env = dict(os.environ if env is None else env)
+        self.adapterRunners = {adapter.adapterId: adapter for adapter in (adapters or defaultAdapters())}
+        self.challenges: dict[str, dict[str, Any]] = {}
+        self.verifiedCredentials: dict[str, dict[str, Any]] = {}
+        self.sessions: dict[str, dict[str, Any]] = {}
+        self.reputationCards: dict[str, dict[str, Any]] = {}
+
+    def validateMandate(self, mandate: dict[str, Any]) -> dict[str, Any]:
+        errors: list[str] = []
+        normalized = self._normalizeMandate(mandate)
+        kind = self.mandateKind(normalized)
+        required = ("mandateId", "issuer", "validUntil", "signature")
+        if kind == "payment":
+            required = (*required, "payer", "payee", "amount", "rail")
+        else:
+            required = (*required, "constraints")
+        for key in required:
+            if not normalized.get(key):
+                errors.append(f"missing:{key}")
+        issuer = normalized.get("issuer", {}) if isinstance(normalized.get("issuer"), dict) else {}
+        if not issuer.get("entityId"):
+            errors.append("missing:issuer.entityId")
+        if not issuer.get("publicKey"):
+            errors.append("missing:issuer.publicKey")
+
+        if kind == "payment":
+            spend = self._paymentAmount(normalized)
+            payerId = self.payerId(normalized)
+            payeeId = self.payeeId(normalized)
+            rail = self.rail(normalized)
+            if not payerId:
+                errors.append("missing:payer.entityId")
+            if not payeeId:
+                errors.append("missing:payee.entityId")
+            if spend.amount <= 0:
+                errors.append("invalid:amount")
+            if not spend.currency:
+                errors.append("missing:amount.currency")
+            if not rail.get("railId"):
+                errors.append("missing:rail.railId")
+            budget = self._constraintMaxSpend(normalized)
+            if budget.amount > 0:
+                if spend.amount > budget.amount:
+                    errors.append("amountOverMaxSpend")
+                if spend.currency != budget.currency:
+                    errors.append("amountCurrencyMismatch")
+        else:
+            spend = self._constraintMaxSpend(normalized)
+            if spend.amount <= 0:
+                errors.append("invalid:maxSpend.amount")
+            if not spend.currency:
+                errors.append("missing:maxSpend.currency")
+
+        validUntil = str(normalized.get("validUntil", "") or "")
+        expiresAt = self._parseTime(validUntil)
+        if expiresAt is None:
+            errors.append("invalid:validUntil")
+        elif expiresAt <= self.clock():
+            errors.append("expired")
+
+        signature = str(normalized.get("signature", "") or "")
+        publicKey = str(issuer.get("publicKey", "") or "")
+        sigOk = False
+        if signature and publicKey and self.verifier is not None:
+            sigOk = bool(self.verifier(self.canonicalPayload(normalized), signature, publicKey))
+        elif signature and publicKey:
+            errors.append("signatureVerifierMissing")
+        if self.verifier is not None and not sigOk:
+            errors.append("signatureInvalid")
+
+        return {
+            "ok": not errors,
+            "errors": errors,
+            "kind": kind,
+            "mandateId": str(normalized.get("mandateId", "") or ""),
+            "maxSpend": spend.toMap(),
+            "allowedVendors": self.allowedVendors(normalized),
+            "resolveRules": self.resolveRules(normalized),
+            "payerId": self.payerId(normalized),
+            "payeeId": self.payeeId(normalized),
+            "rail": self.rail(normalized),
+            "signatureOk": sigOk,
+        }
+
+    def canSettle(self, mandate: dict[str, Any], request: SettlementRequest | dict[str, Any]) -> dict[str, Any]:
+        req = request if isinstance(request, SettlementRequest) else SettlementRequest.fromObj(request)
+        validation = self.validateMandate(mandate)
+        errors = list(validation["errors"])
+        if not req.taskId:
+            errors.append("missing:taskId")
+        if not req.vendorId:
+            errors.append("missing:vendorId")
+        if req.amount.amount <= 0:
+            errors.append("invalid:amount")
+
+        maxSpend = Money.fromObj(validation.get("maxSpend", {}))
+        if req.amount.currency != maxSpend.currency:
+            errors.append("currencyMismatch")
+        if req.amount.amount > maxSpend.amount:
+            errors.append("overBudget")
+
+        allowed = validation.get("allowedVendors", [])
+        if allowed and req.vendorId not in allowed:
+            errors.append("vendorNotAllowed")
+
+        missingRules = [rule for rule in validation.get("resolveRules", []) if rule not in req.pov.rules]
+        if missingRules:
+            errors.append("missingProofRules")
+        if validation.get("resolveRules") and not req.pov.povId:
+            errors.append("missing:povId")
+
+        return {
+            "ok": not errors,
+            "errors": errors,
+            "taskId": req.taskId,
+            "vendorId": req.vendorId,
+            "amount": req.amount.toMap(),
+            "pov": req.pov.toMap(),
+        }
+
+    def settle(
+        self,
+        mandate: dict[str, Any],
+        request: SettlementRequest | dict[str, Any],
+        adapter: SettlementAdapterSpec | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        normalized = self._normalizeMandate(mandate)
+        req = request if isinstance(request, SettlementRequest) else SettlementRequest.fromObj(request)
+        decision = self.canSettle(normalized, req)
+        status = "settled" if decision["ok"] else "rejected"
+        receipt = self.receipt(
+            mandateId=str(normalized.get("mandateId", "") or ""),
+            taskId=req.taskId,
+            status=status,
+            amount=req.amount,
+            pov=req.pov,
+            errors=decision["errors"],
+        )
+        result: dict[str, Any] = {"ok": decision["ok"], "decision": decision, "receipt": receipt}
+        if not decision["ok"]:
+            return result
+        adapterSpec = adapter if isinstance(adapter, SettlementAdapterSpec) else SettlementAdapterSpec.fromObj(adapter)
+        rail = self.rail(normalized)
+        railId = str(rail.get("railId", adapterSpec.rail) or adapterSpec.rail)
+        adapterRunner = self.adapterRunners.get(adapterSpec.adapterId) or self._adapterForRail(railId)
+        if adapterRunner is None:
+            return result
+        prepared = self.prepareSettlement(normalized, request, adapterSpec)
+        instruction = prepared.get("instruction", {}) if isinstance(prepared.get("instruction"), dict) else {}
+        extras = request if isinstance(request, dict) else {}
+        executionPayload = {
+            "instruction": {
+                **instruction,
+                **{key: extras[key] for key in ("signedTransaction", "transaction", "live", "execute", "mission") if key in extras},
+            }
+        }
+        adapterExecution = adapterRunner.invoke("settlement.execute", executionPayload, self._adapterContext())
+        result["prepare"] = prepared
+        result["adapterExecution"] = adapterExecution
+        result["rail"] = railId
+        if not adapterExecution.get("ok") and railId not in {"", "offchain", "picuxLedger"}:
+            result["ok"] = False
+            result["receipt"] = {**receipt, "status": "pendingExternalSettlement", "errors": [*receipt.get("errors", []), str(adapterExecution.get("error", "adapterExecutionFailed") or "adapterExecutionFailed")]}
+            result["decision"] = {**decision, "errors": [*decision.get("errors", []), str(adapterExecution.get("error", "adapterExecutionFailed") or "adapterExecutionFailed")]}
+        return result
+
+    def prepareSettlement(
+        self,
+        mandate: dict[str, Any],
+        request: SettlementRequest | dict[str, Any],
+        adapter: SettlementAdapterSpec | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        normalized = self._normalizeMandate(mandate)
+        req = request if isinstance(request, SettlementRequest) else SettlementRequest.fromObj(request)
+        decision = self.canSettle(normalized, req)
+        status = "ready" if decision["ok"] else "rejected"
+        adapterSpec = adapter if isinstance(adapter, SettlementAdapterSpec) else SettlementAdapterSpec.fromObj(adapter)
+        rail = self.rail(normalized)
+        railId = str(rail.get("railId", adapterSpec.rail) or adapterSpec.rail)
+        payerId = self.payerId(normalized)
+        payeeId = self.payeeId(normalized) or req.vendorId
+        createdAt = self.clock().isoformat().replace("+00:00", "Z")
+        adapterPayload = {
+            "idempotencyKey": self._stableId(
+                "settlement",
+                {
+                    "mandateId": str(normalized.get("mandateId", "") or ""),
+                    "taskId": req.taskId,
+                    "payeeId": payeeId,
+                    "amount": req.amount.toMap(),
+                },
+            ),
+            "mandateId": str(normalized.get("mandateId", "") or ""),
+            "intentMandateId": str(normalized.get("intentMandateId", "") or ""),
+            "taskId": req.taskId,
+            "payerId": payerId,
+            "payeeId": payeeId,
+            "amount": req.amount.toMap(),
+            "povRef": req.pov.povId,
+        }
+        base = {
+            "status": status,
+            "adapterId": adapterSpec.adapterId,
+            "rail": railId,
+            "network": str(rail.get("network", adapterSpec.network) or adapterSpec.network),
+            "mandateId": str(normalized.get("mandateId", "") or ""),
+            "intentMandateId": str(normalized.get("intentMandateId", "") or ""),
+            "taskId": req.taskId,
+            "payerId": payerId,
+            "payeeId": payeeId,
+            "amount": req.amount.toMap(),
+            "povRef": req.pov.povId,
+            "escrowId": str((request if isinstance(request, dict) else {}).get("escrowId", "") or ""),
+            "errors": decision["errors"],
+            "createdAt": createdAt,
+            "adapterPayload": adapterPayload,
+        }
+        settlementId = "setl_" + hashlib.sha256(
+            json.dumps(base, ensure_ascii=True, sort_keys=True, separators=(",", ":")).encode("utf-8")
+        ).hexdigest()[:24]
+        instruction = {"settlementId": settlementId, **base}
+        result = {
+            "ok": decision["ok"],
+            "decision": decision,
+            "instruction": instruction,
+            "adapter": adapterSpec.toMap(),
+            "contract": self.settlementAdapterContract(),
+        }
+        adapterRunner = self.adapterRunners.get(adapterSpec.adapterId) or self._adapterForRail(railId)
+        if adapterRunner is not None:
+            result["adapterExecution"] = adapterRunner.invoke("settlement.prepare", {"instruction": instruction}, self._adapterContext())
+        return result
+
+    @staticmethod
+    def settlementAdapterContract() -> dict[str, Any]:
+        return {
+            "ok": True,
+            "contract": "picuxSettlementAdapter",
+            "version": "2026-05-10",
+            "mode": "prepare|invoke",
+            "routes": {
+                "contract": "GET /v1/pay/adapters/contract",
+                "invoke": "POST /v1/pay/adapters/{adapterId}/invoke",
+            },
+            "input": {
+                "required": ["mandateId", "taskId", "payerId", "payeeId", "amount", "povRef", "idempotencyKey"],
+                "optional": ["intentMandateId", "escrowId", "rail", "network", "meta"],
+            },
+            "output": {
+                "required": ["adapterId", "status", "providerRef", "createdAt"],
+                "statuses": ["accepted", "rejected", "pending", "settled", "failed"],
+            },
+            "rules": [
+                "Adapters receive no issuer private keys.",
+                "Adapters must treat idempotencyKey as replay protection.",
+                "Adapters must return a providerRef before Picux records external execution.",
+            ],
+        }
+
+    def listRails(self) -> dict[str, Any]:
+        rails = self.rails()
+        return {"ok": True, "rails": rails, "count": len(rails)}
+
+    def getRail(self, railId: str) -> dict[str, Any]:
+        requested = str(railId or "")
+        rail = next((item for item in self.rails() if item["railId"] == requested), None)
+        if rail is None:
+            return {"ok": False, "error": "railNotFound", "railId": requested}
+        return {"ok": True, "rail": rail}
+
+    def listAdapters(self) -> dict[str, Any]:
+        adapters = self._adapterCatalog()
+        return {"ok": True, "adapters": adapters, "count": len(adapters)}
+
+    def getAdapter(self, adapterId: str) -> dict[str, Any]:
+        requested = str(adapterId or "")
+        adapter = next((item for item in self._adapterCatalog() if item["adapterId"] == requested), None)
+        if adapter is None:
+            return {"ok": False, "error": "adapterNotFound", "adapterId": requested}
+        return {"ok": True, "adapter": adapter}
+
+    def invokeAdapter(self, adapterId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        requested = str(adapterId or "")
+        adapter = self.adapterRunners.get(requested)
+        if adapter is None:
+            return {"ok": False, "error": "adapterNotFound", "adapterId": requested}
+        action = str(payload.get("action", "") or self._inferAdapterAction(payload))
+        runnerPayload = payload.get("payload", payload) if isinstance(payload.get("payload", payload), dict) else {}
+        result = adapter.invoke(action, runnerPayload, self._adapterContext())
+        return {"ok": bool(result.get("ok")), "adapter": adapter.metadata(self.env), "result": result}
+
+    def listReputationCards(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        filters = filters or {}
+        subjectId = str(filters.get("subjectId", "") or "")
+        context = str(filters.get("context", "") or "")
+        cards = list(self.reputationCards.values())
+        if subjectId:
+            cards = [card for card in cards if card.get("subjectId") == subjectId]
+        if context:
+            cards = [card for card in cards if card.get("context") == context]
+        cards.sort(key=lambda item: (str(item.get("updatedAt", "")), str(item.get("cardId", ""))), reverse=True)
+        return {"ok": True, "cards": [copy.deepcopy(card) for card in cards], "count": len(cards)}
+
+    def getReputationCard(self, cardId: str) -> dict[str, Any]:
+        requested = str(cardId or "")
+        card = self.reputationCards.get(requested)
+        if card is None:
+            return {"ok": False, "error": "reputationCardNotFound", "cardId": requested}
+        return {"ok": True, "card": copy.deepcopy(card)}
+
+    def updateReputationCard(self, payload: dict[str, Any]) -> dict[str, Any]:
+        subjectId = str(payload.get("subjectId", "") or "")
+        subjectKind = str(payload.get("subjectKind", "agent") or "agent")
+        context = str(payload.get("context", "settlementReliability") or "settlementReliability")
+        if not subjectId:
+            return {"ok": False, "error": "missing:subjectId"}
+        cardId = str(payload.get("cardId", "") or self._stableId("rep", {"subjectId": subjectId, "subjectKind": subjectKind, "context": context}))
+        current = self.reputationCards.get(cardId, {})
+        baseScore = float(current.get("score", payload.get("baseScore", 50.0)) or 50.0)
+        delta = float(payload.get("delta", 0.0) or 0.0)
+        score = min(100.0, max(0.0, baseScore + delta))
+        evidenceRefs = current.get("evidenceRefs", []) if isinstance(current.get("evidenceRefs"), list) else []
+        evidenceRef = str(payload.get("evidenceRef", "") or "")
+        if evidenceRef and evidenceRef not in evidenceRefs:
+            evidenceRefs = [*evidenceRefs, evidenceRef]
+        card = {
+            "cardId": cardId,
+            "subjectId": subjectId,
+            "subjectKind": subjectKind,
+            "context": context,
+            "score": round(score, 2),
+            "thresholds": payload.get("thresholds", current.get("thresholds", {}))
+            if isinstance(payload.get("thresholds", current.get("thresholds", {})), dict)
+            else {},
+            "evidenceRefs": evidenceRefs,
+            "chainRef": str(payload.get("chainRef", current.get("chainRef", "")) or ""),
+            "updatedAt": self._now(),
+            "meta": payload.get("meta", current.get("meta", {})) if isinstance(payload.get("meta", current.get("meta", {})), dict) else {},
+        }
+        self.reputationCards[cardId] = copy.deepcopy(card)
+        return {"ok": True, "card": card, "delta": delta}
+
+    def createPaymentChallenge(self, payload: dict[str, Any]) -> dict[str, Any]:
+        now = self._now()
+        ttl = self._positiveInt(payload.get("ttlSeconds"), 300)
+        amount = Money.fromObj(payload.get("amount", {}) if isinstance(payload.get("amount"), dict) else {})
+        if amount.currency == "USD" and payload.get("currency"):
+            amount = Money(amount.amount, str(payload.get("currency", "USD") or "USD"))
+        if amount.amount <= 0 and payload.get("price"):
+            amount = Money.fromObj(payload.get("price", {}) if isinstance(payload.get("price"), dict) else {})
+        railId = str(payload.get("railId", payload.get("rail", "picuxLedger")) or "picuxLedger")
+        resource = payload.get("resource", {}) if isinstance(payload.get("resource"), dict) else {}
+        resourceId = str(
+            resource.get(
+                "resourceId",
+                payload.get("resourceId", payload.get("path", payload.get("connectorId", "resource"))),
+            )
+            or "resource"
+        )
+        challengeBase = {
+            "railId": railId,
+            "resourceId": resourceId,
+            "method": str(resource.get("method", payload.get("method", "POST")) or "POST").upper(),
+            "path": str(resource.get("path", payload.get("path", "")) or ""),
+            "amount": amount.toMap(),
+            "payer": payload.get("payer", {}) if isinstance(payload.get("payer"), dict) else {},
+            "payee": payload.get("payee", {}) if isinstance(payload.get("payee"), dict) else {},
+            "nonce": str(payload.get("nonce", "") or ""),
+        }
+        challengeId = str(payload.get("challengeId", "") or self._stableId("paychal", challengeBase))
+        challenge = {
+            "challengeId": challengeId,
+            "status": "requiresPayment",
+            "railId": railId,
+            "resource": {
+                "resourceId": resourceId,
+                "method": challengeBase["method"],
+                "path": challengeBase["path"],
+            },
+            "amount": amount.toMap(),
+            "payer": challengeBase["payer"],
+            "payee": challengeBase["payee"],
+            "headers": {
+                "WWW-Authenticate": f'Payment realm="picux", rail="{railId}", challenge="{challengeId}"',
+                "X-Picux-Payment-Challenge": challengeId,
+            },
+            "credentialReq": {
+                "required": ["challengeId", "railId", "payer", "signature"],
+                "acceptedRails": [railId],
+                "mode": "paymentAuth",
+            },
+            "retry": {
+                "method": challengeBase["method"],
+                "path": challengeBase["path"],
+                "headers": ["Payment-Signature", "X-Picux-Payment-Credential"],
+            },
+            "createdAt": now,
+            "expiresAt": self._iso(self.clock() + timedelta(seconds=ttl)),
+            "meta": payload.get("meta", {}) if isinstance(payload.get("meta"), dict) else {},
+        }
+        adapterResult = self._invokeRailAdapter(railId, "challenge.create", {"challenge": challenge, **payload})
+        if adapterResult:
+            challenge["adapter"] = adapterResult
+            resultHeaders = adapterResult.get("headers", {}) if isinstance(adapterResult.get("headers"), dict) else {}
+            challenge["headers"] = {**challenge["headers"], **resultHeaders}
+            if payload.get("requireConfiguredRail") and not adapterResult.get("ok"):
+                self.challenges[challengeId] = copy.deepcopy(challenge)
+                return {"ok": False, "challenge": challenge, "status": "adapterNotConfigured", "adapter": adapterResult}
+        self.challenges[challengeId] = copy.deepcopy(challenge)
+        return {"ok": True, "challenge": challenge, "status": "requiresPayment"}
+
+    def verifyPaymentChallenge(self, challengeId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        credential = payload.get("credential", payload) if isinstance(payload, dict) else {}
+        credential = credential if isinstance(credential, dict) else {}
+        challenge = self.challenges.get(str(challengeId or ""), {})
+        challengeRail = str(challenge.get("railId", credential.get("railId", "")) or "") if isinstance(challenge, dict) else str(credential.get("railId", "") or "")
+        if challengeRail and not credential.get("railId"):
+            credential = {**credential, "railId": challengeRail}
+        errors: list[str] = []
+        if str(credential.get("challengeId", challengeId) or "") != str(challengeId or ""):
+            errors.append("challengeMismatch")
+        requiredCredentialKeys = ("railId",) if challengeRail in {"x402", "l402"} else ("railId", "payer")
+        for key in requiredCredentialKeys:
+            if not credential.get(key):
+                errors.append(f"missing:{key}")
+        credentialRail = str(credential.get("railId", "") or "")
+        if credentialRail in {"picuxLedger", "mpp", "stripeSpt", "solanaPay", "baseUsdc"} and not credential.get("signature"):
+            errors.append("missing:signature")
+        adapterResult: dict[str, Any] | None = None
+        if challenge:
+            if str(credential.get("railId", "") or "") != challengeRail:
+                errors.append("railMismatch")
+            adapterResult = self._invokeRailAdapter(
+                challengeRail,
+                "challenge.verify",
+                {
+                    "challenge": challenge,
+                    "credential": credential,
+                    "headers": payload.get("headers", {}) if isinstance(payload.get("headers"), dict) else {},
+                },
+            )
+            if adapterResult is None:
+                errors.append("adapterNotFound")
+            elif not adapterResult.get("ok"):
+                adapterErrors = adapterResult.get("errors", []) if isinstance(adapterResult.get("errors"), list) else []
+                errors.extend(adapterErrors or [str(adapterResult.get("error", "adapterRejected") or "adapterRejected")])
+        else:
+            errors.append("challengeNotFound")
+        status = "verified" if not errors else "rejected"
+        credentialId = str(credential.get("credentialId", "") or self._stableId("paycred", credential))
+        receipt = {
+            "receiptId": self._stableId("payrcpt", {"challengeId": challengeId, "credential": credential}),
+            "challengeId": str(challengeId or ""),
+            "credentialId": credentialId,
+            "status": status,
+            "railId": str(credential.get("railId", "") or ""),
+            "paymentRef": str(credential.get("paymentRef", "") or ""),
+            "amount": challenge.get("amount", credential.get("amount", {})) if isinstance(challenge, dict) else {},
+            "resource": challenge.get("resource", {}) if isinstance(challenge, dict) else {},
+            "adapter": adapterResult if isinstance(adapterResult, dict) else {},
+            "createdAt": self._now(),
+        }
+        if not errors:
+            self.verifiedCredentials[credentialId] = copy.deepcopy(receipt)
+        return {
+            "ok": not errors,
+            "challengeId": str(challengeId or ""),
+            "status": status,
+            "errors": errors,
+            "receipt": receipt,
+        }
+
+    def createPaymentSession(self, payload: dict[str, Any]) -> dict[str, Any]:
+        session = self._session(payload, status="created")
+        self.sessions[session["sessionId"]] = copy.deepcopy(session)
+        return {"ok": True, "session": session}
+
+    def authorizePaymentSession(self, sessionId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        session = self._session({**self.sessions.get(str(sessionId or ""), {}), **payload, "sessionId": sessionId}, status="authorized")
+        self.sessions[session["sessionId"]] = copy.deepcopy(session)
+        return {"ok": True, "session": session, "status": "authorized"}
+
+    def consumePaymentSession(self, sessionId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        existing = self.sessions.get(str(sessionId or ""), {})
+        errors: list[str] = []
+        if not existing:
+            errors.append("sessionNotFound")
+        if existing and str(existing.get("status", "") or "") not in {"authorized", "active"}:
+            errors.append("sessionNotAuthorized")
+        session = self._session({**existing, **payload, "sessionId": sessionId}, status="active")
+        amount = Money.fromObj(payload.get("amount", {}) if isinstance(payload.get("amount"), dict) else {})
+        previous = Money.fromObj(existing.get("spent", {}) if isinstance(existing.get("spent"), dict) else {})
+        spent = Money(previous.amount + amount.amount, amount.currency or previous.currency)
+        limit = Money.fromObj(session.get("sessionLimit", {}) if isinstance(session.get("sessionLimit"), dict) else {})
+        cap = Money.fromObj(session.get("perRequestCap", {}) if isinstance(session.get("perRequestCap"), dict) else {})
+        resourceId = self._resourceId(payload.get("resource", payload.get("resourceId", "")))
+        allowedResources = session.get("allowedResources", []) if isinstance(session.get("allowedResources"), list) else []
+        if amount.amount <= 0:
+            errors.append("invalid:amount")
+        if cap.amount > 0 and (amount.currency != cap.currency or amount.amount > cap.amount):
+            errors.append("perRequestCapExceeded")
+        if allowedResources and resourceId not in allowedResources:
+            errors.append("resourceNotAllowed")
+        if spent.currency != limit.currency or spent.amount > limit.amount:
+            errors.append("sessionLimitExceeded")
+        ok = not errors
+        session["spent"] = spent.toMap() if ok else previous.toMap()
+        if not ok and "sessionLimitExceeded" in errors:
+            session["status"] = "exhausted"
+        elif not ok:
+            session["status"] = "rejected"
+        usage = {
+            "usageId": self._stableId("payuse", {"sessionId": sessionId, "payload": payload}),
+            "sessionId": str(sessionId or ""),
+            "amount": amount.toMap(),
+            "resource": payload.get("resource", {}) if isinstance(payload.get("resource"), dict) else {"resourceId": resourceId},
+            "createdAt": self._now(),
+        }
+        self.sessions[session["sessionId"]] = copy.deepcopy(session)
+        return {"ok": ok, "session": session, "usage": usage, "status": "recorded" if ok else "rejected", "errors": errors}
+
+    def closePaymentSession(self, sessionId: str, payload: dict[str, Any]) -> dict[str, Any]:
+        session = self._session({**self.sessions.get(str(sessionId or ""), {}), **payload, "sessionId": sessionId}, status="closed")
+        self.sessions[session["sessionId"]] = copy.deepcopy(session)
+        return {"ok": True, "session": session, "status": "closed"}
+
+    def localPaymentCredential(self, challenge: dict[str, Any], payer: dict[str, Any] | None = None) -> dict[str, Any]:
+        payerObj = payer if isinstance(payer, dict) else challenge.get("payer", {})
+        payerObj = payerObj if isinstance(payerObj, dict) else {}
+        challengeId = str(challenge.get("challengeId", "") or "")
+        railId = str(challenge.get("railId", "picuxLedger") or "picuxLedger")
+        createdAt = self._now()
+        credential = {
+            "credentialId": self._stableId("paycred", {"challengeId": challengeId, "railId": railId, "payer": payerObj}),
+            "challengeId": challengeId,
+            "railId": railId,
+            "payer": payerObj,
+            "signature": self.localPaymentSignature(challengeId=challengeId, railId=railId, payer=payerObj),
+            "paymentRef": self._stableId("localpay", {"challengeId": challengeId, "payer": payerObj}),
+            "amount": challenge.get("amount", {}) if isinstance(challenge.get("amount"), dict) else {},
+            "createdAt": createdAt,
+            "meta": {"mode": "picuxLedgerLocal"},
+        }
+        return credential
+
+    def authorizePaymentHeaders(self, headers: dict[str, Any]) -> dict[str, Any]:
+        normalized = {str(key).lower(): str(value) for key, value in headers.items()}
+        challengeId = normalized.get("x-picux-payment-challenge", "")
+        credentialId = normalized.get("x-picux-payment-credential", "")
+        signature = normalized.get("payment-signature", "")
+        receipt = self.verifiedCredentials.get(credentialId, {})
+        errors: list[str] = []
+        if not challengeId:
+            errors.append("missing:x-picux-payment-challenge")
+        if not credentialId:
+            errors.append("missing:x-picux-payment-credential")
+        if not signature:
+            errors.append("missing:payment-signature")
+        if not receipt:
+            errors.append("credentialNotVerified")
+        if receipt and str(receipt.get("challengeId", "") or "") != challengeId:
+            errors.append("challengeMismatch")
+        return {
+            "ok": not errors,
+            "errors": errors,
+            "challengeId": challengeId,
+            "credentialId": credentialId,
+            "receipt": receipt,
+            "status": "authorized" if not errors else "paymentRequired",
+        }
+
+    @classmethod
+    def localPaymentSignature(cls, *, challengeId: str, railId: str, payer: dict[str, Any]) -> str:
+        return cls._stableId("paysig", {"challengeId": challengeId, "railId": railId, "payer": payer})
+
+    @staticmethod
+    def rails() -> list[dict[str, Any]]:
+        return [
+            {
+                "railId": "picuxLedger",
+                "kind": "ledger",
+                "status": "local",
+                "network": "local",
+                "asset": "USD",
+                "settlement": {"mode": "adapter"},
+                "auth": {"mode": "payment"},
+                "limits": {"minAmount": 0, "supportsSessions": True},
+                "adapter": {"adapterId": "picuxLedgerAdapter"},
+                "meta": {"desc": "Deterministic local rail for contract tests and sandbox runs."},
+            },
+            {
+                "railId": "x402",
+                "kind": "x402",
+                "status": "contract",
+                "network": "base",
+                "asset": "USDC",
+                "settlement": {"mode": "external"},
+                "auth": {"mode": "payment"},
+                "limits": {"supportsSessions": False},
+                "adapter": {"adapterId": "x402Verifier"},
+                "meta": {"desc": "HTTP 402 challenge/retry payment rail."},
+            },
+            {
+                "railId": "mpp",
+                "kind": "mpp",
+                "status": "contract",
+                "network": "http",
+                "asset": "USD",
+                "settlement": {"mode": "session"},
+                "auth": {"mode": "session"},
+                "limits": {"supportsSessions": True},
+                "adapter": {"adapterId": "mppSessionAdapter"},
+                "meta": {"desc": "Machine-payment session rail for high-frequency calls."},
+            },
+            {
+                "railId": "l402",
+                "kind": "l402",
+                "status": "planned",
+                "network": "lightning",
+                "asset": "BTC",
+                "settlement": {"mode": "external"},
+                "auth": {"mode": "macaroon"},
+                "limits": {"supportsSessions": False},
+                "adapter": {"adapterId": "l402Adapter"},
+                "meta": {"desc": "Macaroon and invoice-based payment authentication."},
+            },
+            {
+                "railId": "stripeSpt",
+                "kind": "stripeSpt",
+                "status": "contract",
+                "network": "stripe",
+                "asset": "fiat",
+                "settlement": {"mode": "external"},
+                "auth": {"mode": "token"},
+                "limits": {"supportsSessions": True},
+                "adapter": {"adapterId": "stripeSptAdapter"},
+                "meta": {"desc": "Fiat/card compatibility for agentic commerce."},
+            },
+            {
+                "railId": "solanaPay",
+                "kind": "solanaPay",
+                "status": "planned",
+                "network": "solana",
+                "asset": "USDC",
+                "settlement": {"mode": "escrow"},
+                "auth": {"mode": "mandate"},
+                "limits": {"supportsSessions": False},
+                "adapter": {"adapterId": "solanaEscrowAdapter"},
+                "meta": {"desc": "Proof-of-utility escrow rail for on-chain settlement."},
+            },
+            {
+                "railId": "baseUsdc",
+                "kind": "baseUsdc",
+                "status": "planned",
+                "network": "base",
+                "asset": "USDC",
+                "settlement": {"mode": "escrow"},
+                "auth": {"mode": "mandate"},
+                "limits": {"supportsSessions": False},
+                "adapter": {"adapterId": "baseEscrowAdapter"},
+                "meta": {"desc": "Base USDC escrow settlement rail."},
+            },
+        ]
+
+    @staticmethod
+    def adapters() -> list[dict[str, Any]]:
+        return [
+            {
+                "adapterId": "picuxLedgerAdapter",
+                "railId": "picuxLedger",
+                "status": "local",
+                "mode": "verify",
+                "capabilities": ["challenge.verify", "session.consume", "escrow.test"],
+                "requiredEnv": [],
+                "liveExecution": False,
+            },
+            {
+                "adapterId": "x402Verifier",
+                "railId": "x402",
+                "status": "contract",
+                "mode": "verify",
+                "capabilities": ["challenge.create", "challenge.verify", "facilitator.prepare"],
+                "requiredEnv": ["PICUX_X402_FACILITATOR_URL"],
+                "liveExecution": False,
+            },
+            {
+                "adapterId": "mppSessionAdapter",
+                "railId": "mpp",
+                "status": "contract",
+                "mode": "session",
+                "capabilities": ["session.authorize", "session.consume", "session.close"],
+                "requiredEnv": ["PICUX_MPP_ISSUER"],
+                "liveExecution": False,
+            },
+            {
+                "adapterId": "stripeSptAdapter",
+                "railId": "stripeSpt",
+                "status": "contract",
+                "mode": "execute",
+                "capabilities": ["token.prepare", "fiat.authorize", "fiat.capture"],
+                "requiredEnv": ["STRIPE_SECRET_KEY"],
+                "liveExecution": False,
+            },
+            {
+                "adapterId": "solanaEscrowAdapter",
+                "railId": "solanaPay",
+                "status": "planned",
+                "mode": "escrow",
+                "capabilities": ["mission.initialize", "mission.settle", "mission.abort"],
+                "requiredEnv": ["PICUX_SOLANA_RPC_URL", "PICUX_SOLANA_PROGRAM_ID"],
+                "liveExecution": False,
+            },
+            {
+                "adapterId": "baseEscrowAdapter",
+                "railId": "baseUsdc",
+                "status": "planned",
+                "mode": "escrow",
+                "capabilities": ["mission.initialize", "mission.settle", "mission.abort"],
+                "requiredEnv": ["PICUX_BASE_RPC_URL", "PICUX_BASE_ESCROW_ADDRESS"],
+                "liveExecution": False,
+            },
+            {
+                "adapterId": "l402Adapter",
+                "railId": "l402",
+                "status": "planned",
+                "mode": "verify",
+                "capabilities": ["macaroon.issue", "invoice.verify", "preimage.redeem"],
+                "requiredEnv": ["PICUX_L402_NODE_URL"],
+                "liveExecution": False,
+            },
+        ]
+
+    def _adapterCatalog(self) -> list[dict[str, Any]]:
+        return [adapter.metadata(self.env) for adapter in self.adapterRunners.values()]
+
+    def _adapterContext(self) -> PayRailAdapterContext:
+        return PayRailAdapterContext(env=self.env, createdAt=self._now())
+
+    def _adapterForRail(self, railId: str) -> PayRailAdapter | None:
+        requested = str(railId or "")
+        return next((adapter for adapter in self.adapterRunners.values() if adapter.railId == requested), None)
+
+    def _invokeRailAdapter(self, railId: str, action: str, payload: dict[str, Any]) -> dict[str, Any] | None:
+        adapter = self._adapterForRail(railId)
+        if adapter is None:
+            return None
+        return adapter.invoke(action, payload, self._adapterContext())
+
+    @staticmethod
+    def _inferAdapterAction(payload: dict[str, Any]) -> str:
+        if isinstance(payload.get("instruction"), dict):
+            return "settlement.prepare"
+        if isinstance(payload.get("challenge"), dict):
+            return "challenge.create"
+        if isinstance(payload.get("session"), dict):
+            return "session.authorize"
+        return "settlement.prepare"
+
+    def freeze(self, *, mandateId: str, taskId: str, reason: str) -> dict[str, Any]:
+        return self.receipt(
+            mandateId=mandateId,
+            taskId=taskId,
+            status="frozen",
+            amount=Money(0.0, "USD"),
+            pov=ProofOfValue(""),
+            errors=[reason],
+        )
+
+    def receipt(
+        self,
+        *,
+        mandateId: str,
+        taskId: str,
+        status: str,
+        amount: Money,
+        pov: ProofOfValue,
+        errors: list[str] | None = None,
+    ) -> dict[str, Any]:
+        createdAt = self.clock().isoformat().replace("+00:00", "Z")
+        base = {
+            "mandateId": mandateId,
+            "taskId": taskId,
+            "status": status,
+            "amount": amount.toMap()["amount"],
+            "currency": amount.currency,
+            "povRef": pov.povId,
+            "errors": errors or [],
+            "createdAt": createdAt,
+        }
+        receiptId = "rcpt_" + hashlib.sha256(
+            json.dumps(base, ensure_ascii=True, sort_keys=True, separators=(",", ":")).encode("utf-8")
+        ).hexdigest()[:24]
+        return {"receiptId": receiptId, **base}
+
+    def canonicalPayload(self, mandate: dict[str, Any]) -> dict[str, Any]:
+        payload = copy.deepcopy(mandate)
+        payload.pop("signature", None)
+        return payload
+
+    @staticmethod
+    def mandateKind(mandate: dict[str, Any]) -> str:
+        kind = str(mandate.get("kind", mandate.get("type", "")) or "").strip().lower()
+        return "payment" if kind == "payment" else "intent"
+
+    @staticmethod
+    def allowedVendors(mandate: dict[str, Any]) -> list[str]:
+        constraints = mandate.get("constraints", {}) if isinstance(mandate.get("constraints"), dict) else {}
+        allowed = list(constraints.get("allowedVendors", [])) + list(constraints.get("allowedPayees", []))
+        payeeId = PayDomain.payeeId(mandate)
+        if payeeId:
+            allowed.append(payeeId)
+        return [str(item) for item in allowed if str(item).strip()]
+
+    @staticmethod
+    def resolveRules(mandate: dict[str, Any]) -> list[str]:
+        constraints = mandate.get("constraints", {}) if isinstance(mandate.get("constraints"), dict) else {}
+        return [str(item) for item in constraints.get("resolveRules", []) if str(item).strip()]
+
+    @staticmethod
+    def payerId(mandate: dict[str, Any]) -> str:
+        payer = mandate.get("payer", {}) if isinstance(mandate.get("payer"), dict) else {}
+        return str(payer.get("entityId", mandate.get("payerId", "")) or "")
+
+    @staticmethod
+    def payeeId(mandate: dict[str, Any]) -> str:
+        payee = mandate.get("payee", {}) if isinstance(mandate.get("payee"), dict) else {}
+        return str(payee.get("entityId", mandate.get("payeeId", "")) or "")
+
+    @staticmethod
+    def rail(mandate: dict[str, Any]) -> dict[str, Any]:
+        rail = mandate.get("rail", {}) if isinstance(mandate.get("rail"), dict) else {}
+        if not rail and mandate.get("rail"):
+            rail = {"railId": str(mandate.get("rail", "") or "")}
+        return {
+            "railId": str(rail.get("railId", rail.get("id", rail.get("type", ""))) or ""),
+            "network": str(rail.get("network", "") or ""),
+            "asset": str(rail.get("asset", rail.get("currency", "")) or ""),
+            "adapterId": str(rail.get("adapterId", "") or ""),
+        }
+
+    @staticmethod
+    def _constraintMaxSpend(mandate: dict[str, Any]) -> Money:
+        constraints = mandate.get("constraints", {}) if isinstance(mandate.get("constraints"), dict) else {}
+        maxSpend = constraints.get("maxSpend", {}) if isinstance(constraints.get("maxSpend"), dict) else {}
+        return Money.fromObj(maxSpend)
+
+    @staticmethod
+    def _paymentAmount(mandate: dict[str, Any]) -> Money:
+        return Money.fromObj(mandate.get("amount", {}) if isinstance(mandate.get("amount"), dict) else {})
+
+    @staticmethod
+    def _normalizeMandate(mandate: dict[str, Any]) -> dict[str, Any]:
+        return mandate if isinstance(mandate, dict) else {}
+
+    @staticmethod
+    def _stableId(prefix: str, payload: dict[str, Any]) -> str:
+        digest = hashlib.sha256(
+            json.dumps(payload, ensure_ascii=True, sort_keys=True, separators=(",", ":")).encode("utf-8")
+        ).hexdigest()[:24]
+        return f"{prefix}_{digest}"
+
+    def _session(self, payload: dict[str, Any], *, status: str) -> dict[str, Any]:
+        now = self._now()
+        ttl = self._positiveInt(payload.get("ttlSeconds"), 3600)
+        limit = Money.fromObj(
+            payload.get("sessionLimit", payload.get("limit", {})) if isinstance(payload.get("sessionLimit", payload.get("limit", {})), dict) else {}
+        )
+        spent = Money.fromObj(payload.get("spent", {}) if isinstance(payload.get("spent"), dict) else {})
+        if spent.currency == "USD" and limit.currency:
+            spent = Money(spent.amount, limit.currency)
+        sessionId = str(payload.get("sessionId", "") or self._stableId("paysess", payload))
+        payer = payload.get("payer", {}) if isinstance(payload.get("payer"), dict) else {}
+        return {
+            "sessionId": sessionId,
+            "status": status,
+            "payer": payer,
+            "railId": str(payload.get("railId", payload.get("rail", "picuxLedger")) or "picuxLedger"),
+            "sessionLimit": limit.toMap(),
+            "perRequestCap": payload.get("perRequestCap", {}) if isinstance(payload.get("perRequestCap"), dict) else {},
+            "spent": spent.toMap(),
+            "allowedResources": [str(item) for item in payload.get("allowedResources", []) if str(item).strip()]
+            if isinstance(payload.get("allowedResources"), list)
+            else [],
+            "createdAt": now,
+            "expiresAt": self._iso(self.clock() + timedelta(seconds=ttl)),
+            "meta": payload.get("meta", {}) if isinstance(payload.get("meta"), dict) else {},
+        }
+
+    @staticmethod
+    def _parseTime(value: str) -> datetime | None:
+        raw = str(value or "").strip()
+        if raw.endswith("Z"):
+            raw = raw[:-1] + "+00:00"
+        try:
+            parsed = datetime.fromisoformat(raw)
+        except Exception:
+            return None
+        if parsed.tzinfo is None:
+            parsed = parsed.replace(tzinfo=timezone.utc)
+        return parsed.astimezone(timezone.utc)
+
+    def _now(self) -> str:
+        return self._iso(self.clock())
+
+    @staticmethod
+    def _iso(value: datetime) -> str:
+        return value.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
+
+    @staticmethod
+    def _positiveInt(value: Any, default: int) -> int:
+        try:
+            parsed = int(value)
+        except Exception:
+            return default
+        return parsed if parsed > 0 else default
+
+    @staticmethod
+    def _resourceId(value: Any) -> str:
+        if isinstance(value, dict):
+            return str(value.get("resourceId", value.get("id", "")) or "")
+        return str(value or "")