q-runtime-core 0.9.0__py3-none-any.whl

qruntime/rails/x402_fullcycle.py

@@ -0,0 +1,4651 @@
+"""Q Runtime v0.6 full-cycle verifier and Base-Sepolia test harness.
+
+The deterministic verifier models the x402 v2 ``authorization`` payment flow:
+PAYMENT-REQUIRED -> PAYMENT-SIGNATURE -> verify -> resource -> settle -> response.
+
+The live harness is deliberately testnet-only and localhost-only. It uses the
+installed official x402 Python SDK to exercise a locally controlled resource
+server against the public Base-Sepolia facilitator. It never accepts a mainnet
+network and never writes private keys to reports.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+import json
+import os
+from pathlib import Path
+from typing import Any, Mapping
+from urllib.parse import urlparse
+
+from qruntime.core.invariants import Violation
+from qruntime.rails.x402 import (
+    X402DecodeError,
+    parse_payment_payload,
+    parse_payment_required,
+    parse_settlement_response,
+    requirement_equal,
+)
+from qruntime.rails.x402_capture import X402CaptureError, capture_payment_required
+from qruntime.exceptions import (
+    DuplicateIntentError,
+    IntentInFlightError,
+    IntentResourceMismatchError,
+    SettlementPendingError,
+    PaidResourceError,
+    PaymentRequirementMismatchError,
+    PaymentRequirementRejectedError,
+    PolicyDeniedError,
+    SettlementFailedError,
+    SettlementReceiptError,
+    ReconciliationError,
+    SettlementStoreError,
+)
+from qruntime.policy import Policy, evaluate_policy
+
+
+BASE_SEPOLIA = "eip155:84532"
+DEFAULT_KEY_ENV = "Q_RUNTIME_TESTNET_PRIVATE_KEY"
+
+
+@dataclass(frozen=True)
+class FullCycleResult:
+    passed: bool
+    processed_events: int
+    violation: Violation | None = None
+    trace: tuple[str, ...] = ()
+    pending_transactions: tuple[str, ...] = ()
+
+
+def _wire(event: Mapping[str, Any]) -> Any:
+    if "header" in event:
+        return event["header"]
+    if "data" in event:
+        return event["data"]
+    raise X402DecodeError("full-cycle event requires data or header")
+
+
+def verify_fullcycle_obj(raw: Mapping[str, Any]) -> FullCycleResult:
+    events = raw.get("events")
+    if not isinstance(events, list):
+        return FullCycleResult(False, 0, Violation("InvalidTrace", "events must be an array"))
+
+    flow = str(raw.get("payment_flow", "authorization"))
+    if flow != "authorization":
+        return FullCycleResult(
+            False,
+            0,
+            Violation("UnsupportedPaymentFlow", "v0.6 gate models authorization flow only"),
+        )
+
+    states: dict[str, dict[str, Any]] = {}
+    trace: list[str] = []
+    pending: dict[str, str] = {}
+
+    def state(url: str) -> dict[str, Any]:
+        return states.setdefault(
+            url,
+            {
+                "required": None,
+                "accepted": None,
+                "authorized": False,
+                "verified": False,
+                "resource_executed": False,
+                "resource_failed": False,
+                "settled": False,
+            },
+        )
+
+    def fail(i: int, invariant: str, message: str) -> FullCycleResult:
+        return FullCycleResult(
+            False,
+            i,
+            Violation(invariant, message),
+            tuple(trace),
+            tuple(sorted(pending.values())),
+        )
+
+    for i, event in enumerate(events, start=1):
+        if not isinstance(event, Mapping):
+            trace.append(f"{i}:invalid")
+            return fail(i, "InvalidTrace", "each event must be an object")
+        kind = str(event.get("kind", ""))
+        url = str(event.get("request_url", ""))
+        trace.append(f"{i}:{kind}" + (f" {url}" if url else ""))
+
+        try:
+            if kind == "payment_required":
+                required = parse_payment_required(_wire(event))
+                target = url or required.resource_url
+                if not target:
+                    return fail(i, "InvalidTrace", "payment_required requires request_url or resource.url")
+                st = state(target)
+                st["required"] = required
+                st["authorized"] = False
+                st["verified"] = False
+                st["resource_executed"] = False
+                st["resource_failed"] = False
+                st["settled"] = False
+                continue
+
+            if not url:
+                return fail(i, "InvalidTrace", f"{kind} requires request_url")
+            st = state(url)
+
+            if kind == "payment_signature":
+                if url in pending:
+                    return fail(
+                        i,
+                        "PaymentStateReconciledBeforeRetry",
+                        f"new authorization for {url} while prior settlement is unresolved",
+                    )
+                if st["settled"]:
+                    return fail(i, "NoDuplicateEconomicEffect", f"new payment attempted after {url} already settled")
+                offered = st["required"]
+                if offered is None:
+                    return fail(
+                        i,
+                        "PaymentRequirementKnownBeforeAuthorization",
+                        f"no current PAYMENT-REQUIRED observed for {url}",
+                    )
+                payload = parse_payment_payload(_wire(event))
+                if payload.resource_url and payload.resource_url != url:
+                    return fail(
+                        i,
+                        "PaymentPayloadBoundToResource",
+                        f"payload resource {payload.resource_url} != actual request {url}",
+                    )
+                if not any(requirement_equal(payload.accepted, req) for req in offered.accepts):
+                    return fail(
+                        i,
+                        "PaymentRequirementStableForIntent",
+                        "signed payment does not match any currently advertised payment requirement",
+                    )
+                st["accepted"] = payload.accepted
+                st["authorized"] = True
+                st["verified"] = False
+                continue
+
+            if kind == "verify_response":
+                if not st["authorized"]:
+                    return fail(i, "AuthorizationBeforeVerification", "facilitator verify occurred before authorization")
+                data = _wire(event)
+                if not isinstance(data, Mapping) or not isinstance(data.get("isValid"), bool):
+                    return fail(i, "InvalidVerifyResponse", "verify_response requires boolean isValid")
+                st["verified"] = bool(data["isValid"])
+                if not st["verified"]:
+                    st["authorized"] = False
+                continue
+
+            if kind == "resource_executed":
+                if not st["verified"]:
+                    return fail(
+                        i,
+                        "VerificationBeforeResourceExecution",
+                        f"protected resource {url} executed before successful verify",
+                    )
+                if st["resource_executed"]:
+                    return fail(i, "SingleResourceExecution", f"protected resource {url} executed more than once")
+                st["resource_executed"] = True
+                continue
+
+            if kind == "resource_failed":
+                if not st["verified"]:
+                    return fail(
+                        i,
+                        "VerificationBeforeResourceExecution",
+                        f"protected resource {url} failed before successful verify",
+                    )
+                st["resource_failed"] = True
+                continue
+
+            if kind in {"settle_response", "payment_response"}:
+                if st["resource_failed"]:
+                    return fail(
+                        i,
+                        "NoSettlementAfterResourceFailure",
+                        f"authorization flow attempted settlement after protected resource {url} failed",
+                    )
+                if not st["resource_executed"]:
+                    return fail(
+                        i,
+                        "ResourceExecutionBeforeSettlement",
+                        f"authorization flow settled {url} before protected resource execution",
+                    )
+                response = parse_settlement_response(_wire(event))
+                accepted = st.get("accepted")
+                if accepted is not None and response.network != accepted.network:
+                    return fail(
+                        i,
+                        "SettlementReceiptConsistent",
+                        f"settlement network {response.network} != authorized network {accepted.network}",
+                    )
+                if response.reconciliation_required:
+                    pending[url] = response.transaction
+                    st["settled"] = False
+                elif response.success:
+                    if not response.transaction:
+                        return fail(
+                            i,
+                            "SettlementReceiptConsistent",
+                            "successful settlement requires a non-empty transaction hash",
+                        )
+                    pending.pop(url, None)
+                    st["settled"] = True
+                else:
+                    pending.pop(url, None)
+                    st["settled"] = False
+                continue
+
+            if kind == "transport_timeout":
+                phase = str(event.get("phase", ""))
+                if phase in {"after_payment_submission", "during_settlement"}:
+                    pending[url] = str(event.get("transaction", "unknown"))
+                continue
+
+            if kind == "reconcile":
+                outcome = str(event.get("outcome", ""))
+                if outcome not in {"confirmed", "failed", "not_found_terminal"}:
+                    return fail(i, "InvalidTrace", "invalid reconcile outcome")
+                pending.pop(url, None)
+                st["settled"] = outcome == "confirmed"
+                continue
+
+            if kind == "retry":
+                if url in pending:
+                    return fail(
+                        i,
+                        "PaymentStateReconciledBeforeRetry",
+                        f"retry attempted for {url} before ambiguous settlement was reconciled",
+                    )
+                if st["settled"]:
+                    return fail(i, "NoDuplicateEconomicEffect", f"retry attempted after {url} already settled")
+                continue
+
+            return fail(i, "InvalidTrace", f"unsupported full-cycle event kind: {kind}")
+
+        except X402DecodeError as exc:
+            return fail(i, "InvalidX402WireData", str(exc))
+
+    return FullCycleResult(True, len(events), None, tuple(trace), tuple(sorted(pending.values())))
+
+
+def verify_fullcycle(path: str | Path) -> FullCycleResult:
+    raw = json.loads(Path(path).read_text(encoding="utf-8"))
+    if not isinstance(raw, Mapping):
+        return FullCycleResult(False, 0, Violation("InvalidTrace", "trace root must be an object"))
+    return verify_fullcycle_obj(raw)
+
+
+def fullcycle_result_dict(result: FullCycleResult) -> dict[str, Any]:
+    return {
+        "passed": result.passed,
+        "processed_events": result.processed_events,
+        "violation": None if result.violation is None else {
+            "invariant": result.violation.invariant,
+            "message": result.violation.message,
+        },
+        "trace": list(result.trace),
+        "pending_transactions": list(result.pending_transactions),
+    }
+
+
+def fullcycle_result_text(result: FullCycleResult) -> str:
+    if result.passed:
+        pending_text = ", ".join(result.pending_transactions) if result.pending_transactions else "none"
+        return (
+            "PASS — X402 FULL-CYCLE INVARIANTS\n"
+            f"events processed: {result.processed_events}\n"
+            f"pending reconciliation: {pending_text}\n"
+            "economic invariant violations: 0"
+        )
+    return (
+        "FAIL — X402_FULLCYCLE_COUNTEREXAMPLE\n"
+        f"invariant: {result.violation.invariant if result.violation else 'unknown'}\n"
+        f"reason: {result.violation.message if result.violation else 'unknown'}\n"
+        "trace:\n  " + "\n  ".join(result.trace)
+    )
+
+
+def create_testnet_wallet(path: str | Path) -> dict[str, str]:
+    """Create a disposable EVM wallet file for testnet use only."""
+    try:
+        from eth_account import Account
+    except ImportError as exc:  # pragma: no cover - user's optional integration env
+        raise RuntimeError(
+            "eth-account is missing. Install Q Runtime with: "
+            'python -m pip install -e ".[official-x402]"'
+        ) from exc
+
+    destination = Path(path)
+    if destination.exists():
+        raise FileExistsError(f"refusing to overwrite existing wallet file: {destination}")
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    account = Account.create()
+    private_key = account.key.hex()
+    if not private_key.startswith("0x"):
+        private_key = "0x" + private_key
+    data = {
+        "purpose": "Q Runtime Base Sepolia disposable testnet wallet",
+        "network": BASE_SEPOLIA,
+        "address": account.address,
+        "private_key": private_key,
+        "warning": "TESTNET ONLY. Never fund this address with mainnet assets or reuse this key on mainnet.",
+    }
+    destination.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    return {"address": account.address, "path": str(destination)}
+
+
+def _header_ci(headers: Mapping[str, str], *names: str) -> str | None:
+    lowered = {str(k).lower(): str(v) for k, v in headers.items()}
+    for name in names:
+        if name.lower() in lowered:
+            return lowered[name.lower()]
+    return None
+
+
+
+def _live_requirement_matches_preflight(preflight: Any, current: Any) -> bool:
+    """Require the SDK-selected requirement to equal the preflight-approved quote."""
+    try:
+        current_canonical = {
+            "scheme": current.scheme,
+            "network": current.network,
+            "amount": str(current.amount),
+            "asset": current.asset,
+            "payTo": current.pay_to,
+            "maxTimeoutSeconds": current.max_timeout_seconds,
+            "extra": dict(current.extra or {}),
+        }
+        return preflight.canonical_dict() == current_canonical
+    except (AttributeError, TypeError, ValueError):
+        return False
+
+def _make_live_quote_binding_hook(preflight: Any, abort_result_cls: Any):
+    """Abort before signing if the live SDK quote differs from preflight."""
+    fingerprint = preflight.fingerprint()
+
+    def before_payment(ctx: Any):
+        current = ctx.selected_requirements
+        if not _live_requirement_matches_preflight(preflight, current):
+            return abort_result_cls(
+                reason="qruntime_preflight_quote_changed",
+                message=(
+                    "payment requirement selected for signing no longer "
+                    f"matches preflight-approved quote {fingerprint}"
+                ),
+            )
+        return None
+
+    return before_payment
+
+
+
+PENDING_STORE_ENV = "Q_RUNTIME_PENDING_STORE"
+PENDING_STORE_FORMAT = "qruntime-x402-pending-store-v1"
+PENDING_STORE_ENTRY_STATES = frozenset(
+    {
+        "reserved",
+        "submission_unknown",
+        "pending",
+        "resolved_confirmed",
+        "resolved_failed",
+    }
+)
+
+
+def _pending_store_file() -> Path:
+    configured = os.environ.get(PENDING_STORE_ENV, "").strip()
+    if configured:
+        return Path(configured)
+    return Path.home() / ".qruntime" / "pending-settlements.json"
+
+
+def _pending_store_temp_file(
+    path: Path,
+) -> Path:
+    return path.with_name(
+        path.name + ".tmp"
+    )
+
+
+def _pending_store_is_unambiguously_absent(
+    path: Path,
+) -> bool:
+    """Return True only when neither main nor temp state exists."""
+
+    temp = _pending_store_temp_file(
+        path
+    )
+
+    if temp.exists():
+        raise SettlementStoreError(
+            "persistent settlement store has orphaned temp state; "
+            "refusing payment fail-closed"
+        )
+
+    return not path.exists()
+
+
+
+
+def _read_pending_store_document(
+    path: Path,
+) -> dict[str, Any]:
+    """Read and structurally validate one persisted pending store."""
+
+    try:
+        raw = json.loads(
+            path.read_text(
+                encoding="utf-8"
+            )
+        )
+    except (
+        OSError,
+        UnicodeDecodeError,
+        json.JSONDecodeError,
+    ) as exc:
+        raise SettlementStoreError(
+            "persistent settlement store is unreadable; "
+            "refusing payment fail-closed"
+        ) from exc
+
+    if not isinstance(
+        raw,
+        Mapping,
+    ):
+        raise SettlementStoreError(
+            "persistent settlement store root must be an object"
+        )
+
+    entries = raw.get(
+        "entries"
+    )
+
+    if not isinstance(
+        entries,
+        Mapping,
+    ):
+        raise SettlementStoreError(
+            "persistent settlement store entries must be an object"
+        )
+
+    for outer_key, entry in entries.items():
+        if not isinstance(
+            entry,
+            Mapping,
+        ):
+            raise SettlementStoreError(
+                "persistent settlement store entry must be an object"
+            )
+
+        state = entry.get(
+            "state"
+        )
+
+        if (
+            not isinstance(
+                state,
+                str,
+            )
+            or state
+            not in PENDING_STORE_ENTRY_STATES
+        ):
+            raise SettlementStoreError(
+                "persistent settlement store entry state is unsupported"
+            )
+
+        stored_intent_key = entry.get(
+            "intent_key"
+        )
+
+        # Legacy entries may omit intent_key.
+        # Once present, it is an integrity assertion.
+        if stored_intent_key is not None:
+            if (
+                not isinstance(
+                    stored_intent_key,
+                    str,
+                )
+                or stored_intent_key
+                != outer_key
+            ):
+                raise SettlementStoreError(
+                    "persistent settlement store entry key is inconsistent"
+                )
+
+            stored_intent_id = entry.get(
+                "intent_id"
+            )
+
+            if stored_intent_id is not None:
+                if (
+                    not isinstance(
+                        stored_intent_id,
+                        str,
+                    )
+                    or _persistent_intent_key(
+                        stored_intent_id
+                    )
+                    != stored_intent_key
+                ):
+                    raise SettlementStoreError(
+                        "persistent settlement store entry intent identity is inconsistent"
+                    )
+
+    # A persisted pending settlement is already economically
+    # significant. Its transaction identity must therefore remain
+    # recoverable; otherwise retry safety cannot be established.
+    for raw_entry in entries.values():
+        if not isinstance(
+            raw_entry,
+            Mapping,
+        ):
+            continue
+
+        if raw_entry.get(
+            "state"
+        ) != "pending":
+            continue
+
+        for field in (
+            "transaction",
+            "network",
+        ):
+            value = raw_entry.get(
+                field
+            )
+
+            if (
+                not isinstance(
+                    value,
+                    str,
+                )
+                or not value.strip()
+            ):
+                raise SettlementStoreError(
+                    "persistent pending settlement entry "
+                    f"requires non-empty {field}; "
+                    "refusing payment fail-closed"
+                )
+
+    # Terminal reconciliation states must retain the
+    # economic identity that was reconciled, and the persisted
+    # outcome must agree with the terminal state.
+    for raw_entry in entries.values():
+        if not isinstance(
+            raw_entry,
+            Mapping,
+        ):
+            continue
+
+        state = raw_entry.get(
+            "state"
+        )
+
+        expected_outcome = {
+            "resolved_confirmed": "confirmed",
+            "resolved_failed": "failed",
+        }.get(
+            state
+        )
+
+        if expected_outcome is None:
+            continue
+
+        for field in (
+            "transaction",
+            "network",
+        ):
+            value = raw_entry.get(
+                field
+            )
+
+            if (
+                not isinstance(
+                    value,
+                    str,
+                )
+                or not value.strip()
+            ):
+                raise SettlementStoreError(
+                    "persistent resolved settlement entry "
+                    f"requires non-empty {field}; "
+                    "refusing payment fail-closed"
+                )
+
+        outcome = raw_entry.get(
+            "reconciliation_outcome"
+        )
+
+        # Older v1 entries may not carry reconciliation_outcome.
+        # Absence remains readable for compatibility. Once present,
+        # however, the outcome is an integrity assertion and must
+        # agree with the terminal state.
+        if (
+            outcome is not None
+            and outcome != expected_outcome
+        ):
+            raise SettlementStoreError(
+                "persistent resolved settlement entry "
+                "has reconciliation outcome inconsistent "
+                f"with state {state}; "
+                "refusing payment fail-closed"
+            )
+
+    # P4.7c persisted authorization nonce integrity
+    # The write path already treats a nonce as unique within one
+    # persisted intent history. Exact replay is idempotent; conflicting
+    # durable envelopes for the same nonce are corruption.
+    for raw_entry in entries.values():
+        if not isinstance(
+            raw_entry,
+            Mapping,
+        ):
+            continue
+
+        if raw_entry.get(
+            "state"
+        ) != "submission_unknown":
+            continue
+
+        history_raw = raw_entry.get(
+            "authorizations"
+        )
+
+        # P4.7d authorization history structural integrity
+        # Missing/null history is legitimate while submission_unknown
+        # exists before authorization evidence reaches durable storage.
+        if history_raw is None:
+            continue
+
+        # Once materially present, authorizations must retain
+        # the list shape established by the write path.
+        if not isinstance(
+            history_raw,
+            list,
+        ):
+            raise SettlementStoreError(
+                "persistent authorization history "
+                "must be a list; refusing payment "
+                "fail-closed"
+            )
+
+        seen_by_nonce: dict[
+            str,
+            dict[str, str],
+        ] = {}
+
+        for authorization in history_raw:
+            if not isinstance(
+                authorization,
+                Mapping,
+            ):
+                raise SettlementStoreError(
+                    "persistent authorization history "
+                    "contains invalid entry; refusing "
+                    "payment fail-closed"
+                )
+
+            # P4.7f authorization envelope completeness
+            # Modern persisted authorization history must retain every
+            # field produced by the durable writer. This mirrors the
+            # write-time contract without imposing additional typing.
+            required_fields = (
+                "from",
+                "to",
+                "value",
+                "validAfter",
+                "validBefore",
+                "nonce",
+                "network",
+                "asset",
+            )
+
+            for field in required_fields:
+                if authorization.get(
+                    field
+                ) is None:
+                    raise SettlementStoreError(
+                        "persistent authorization envelope "
+                        f"is missing required field {field}; "
+                        "refusing payment fail-closed"
+                    )
+
+            # P4.7g authorization economic binding
+            # When multiple persisted representations explicitly carry
+            # the same economic dimensions, they must agree. Missing
+            # legacy representations remain outside this contract.
+            requirement_raw = raw_entry.get(
+                "requirement"
+            )
+
+            if isinstance(
+                requirement_raw,
+                Mapping,
+            ):
+                entry_network = raw_entry.get(
+                    "network"
+                )
+
+                requirement_network = (
+                    requirement_raw.get(
+                        "network"
+                    )
+                )
+
+                if (
+                    entry_network is not None
+                    and requirement_network is not None
+                    and str(entry_network)
+                    != str(requirement_network)
+                ):
+                    raise SettlementStoreError(
+                        "persistent submission_unknown network "
+                        "is inconsistent with payment requirement; "
+                        "refusing payment fail-closed"
+                    )
+
+                authorization_network = (
+                    authorization.get(
+                        "network"
+                    )
+                )
+
+                if (
+                    entry_network is not None
+                    and authorization_network is not None
+                    and str(authorization_network)
+                    != str(entry_network)
+                ):
+                    raise SettlementStoreError(
+                        "persistent authorization network "
+                        "is inconsistent with intent network; "
+                        "refusing payment fail-closed"
+                    )
+
+                requirement_asset = (
+                    requirement_raw.get(
+                        "asset"
+                    )
+                )
+
+                authorization_asset = (
+                    authorization.get(
+                        "asset"
+                    )
+                )
+
+                if (
+                    requirement_asset is not None
+                    and authorization_asset is not None
+                    and str(authorization_asset)
+                    != str(requirement_asset)
+                ):
+                    raise SettlementStoreError(
+                        "persistent authorization asset "
+                        "is inconsistent with payment requirement; "
+                        "refusing payment fail-closed"
+                    )
+
+
+            # P4.7h authorization transfer binding
+            # For the exact EVM authorization flow, the durable
+            # authorization must describe the same amount and recipient
+            # as the selected payment requirement.
+            if isinstance(
+                requirement_raw,
+                Mapping,
+            ):
+                scheme = requirement_raw.get(
+                    "scheme"
+                )
+
+                if str(
+                    scheme
+                ) == "exact":
+                    requirement_amount = (
+                        requirement_raw.get(
+                            "amount"
+                        )
+                    )
+
+                    authorization_value = (
+                        authorization.get(
+                            "value"
+                        )
+                    )
+
+                    if (
+                        requirement_amount is not None
+                        and authorization_value is not None
+                        and str(
+                            authorization_value
+                        )
+                        != str(
+                            requirement_amount
+                        )
+                    ):
+                        raise SettlementStoreError(
+                            "persistent authorization value "
+                            "is inconsistent with exact "
+                            "payment requirement amount; "
+                            "refusing payment fail-closed"
+                        )
+
+                    requirement_pay_to = (
+                        requirement_raw.get(
+                            "payTo"
+                        )
+                    )
+
+                    authorization_to = (
+                        authorization.get(
+                            "to"
+                        )
+                    )
+
+                    if (
+                        requirement_pay_to is not None
+                        and authorization_to is not None
+                        and str(
+                            authorization_to
+                        ).lower()
+                        != str(
+                            requirement_pay_to
+                        ).lower()
+                    ):
+                        raise SettlementStoreError(
+                            "persistent authorization recipient "
+                            "is inconsistent with exact "
+                            "payment requirement payTo; "
+                            "refusing payment fail-closed"
+                        )
+
+
+            nonce_raw = authorization.get(
+                "nonce"
+            )
+
+            if nonce_raw is None:
+                continue
+
+            nonce = str(
+                nonce_raw
+            )
+
+            normalized = {
+                str(key): str(value)
+                for key, value
+                in authorization.items()
+            }
+
+            previous = seen_by_nonce.get(
+                nonce
+            )
+
+            if (
+                previous is not None
+                and previous != normalized
+            ):
+                raise SettlementStoreError(
+                    "persistent authorization history "
+                    "contains conflicting envelopes for "
+                    "the same nonce; refusing payment "
+                    "fail-closed"
+                )
+
+            seen_by_nonce[
+                nonce
+            ] = normalized
+
+    # P4.7e authorization alias coherence
+    # The singular authorization field is a backwards-compatible
+    # alias for the most recently persisted authorization envelope.
+    # Its absence remains valid. Once explicitly present alongside
+    # non-empty history, however, both representations must agree.
+    for raw_entry in entries.values():
+        if not isinstance(
+            raw_entry,
+            Mapping,
+        ):
+            continue
+
+        if raw_entry.get(
+            "state"
+        ) != "submission_unknown":
+            continue
+
+        history_raw = raw_entry.get(
+            "authorizations"
+        )
+
+        if (
+            not isinstance(
+                history_raw,
+                list,
+            )
+            or not history_raw
+        ):
+            continue
+
+        if "authorization" not in raw_entry:
+            continue
+
+        alias = raw_entry.get(
+            "authorization"
+        )
+
+        if not isinstance(
+            alias,
+            Mapping,
+        ):
+            raise SettlementStoreError(
+                "persistent authorization alias "
+                "must be an object when history exists; "
+                "refusing payment fail-closed"
+            )
+
+        latest = history_raw[-1]
+
+        if not isinstance(
+            latest,
+            Mapping,
+        ):
+            raise SettlementStoreError(
+                "persistent authorization history "
+                "contains invalid latest entry; "
+                "refusing payment fail-closed"
+            )
+
+        normalized_alias = {
+            str(key): str(value)
+            for key, value
+            in alias.items()
+        }
+
+        normalized_latest = {
+            str(key): str(value)
+            for key, value
+            in latest.items()
+        }
+
+        if (
+            normalized_alias
+            != normalized_latest
+        ):
+            raise SettlementStoreError(
+                "persistent authorization alias "
+                "is inconsistent with latest history; "
+                "refusing payment fail-closed"
+            )
+
+    # P4.7i reservation scope binding
+    # A flat durable budget reservation preserves the scope checked
+    # before economic handoff. When duplicated at entry/requirement
+    # level, those persisted dimensions must remain coherent.
+    for raw_entry in entries.values():
+        if not isinstance(
+            raw_entry,
+            Mapping,
+        ):
+            continue
+
+        reservation_raw = raw_entry.get(
+            "reservation"
+        )
+
+        if not isinstance(
+            reservation_raw,
+            Mapping,
+        ):
+            continue
+
+        # BudgetSet stores constraints[] instead of one flat scope.
+        # Its contract is deliberately outside P4.7i.
+        if "constraints" in reservation_raw:
+            continue
+
+        requirement_raw = raw_entry.get(
+            "requirement"
+        )
+
+        if isinstance(
+            requirement_raw,
+            Mapping,
+        ):
+            reservation_asset = (
+                reservation_raw.get(
+                    "asset"
+                )
+            )
+
+            requirement_asset = (
+                requirement_raw.get(
+                    "asset"
+                )
+            )
+
+            if (
+                reservation_asset is not None
+                and requirement_asset is not None
+                and str(
+                    reservation_asset
+                )
+                != str(
+                    requirement_asset
+                )
+            ):
+                raise SettlementStoreError(
+                    "persistent reservation asset "
+                    "is inconsistent with payment requirement; "
+                    "refusing payment fail-closed"
+                )
+
+        for field in (
+            "agent_id",
+            "session_id",
+        ):
+            reservation_scope = (
+                reservation_raw.get(
+                    field
+                )
+            )
+
+            entry_scope = raw_entry.get(
+                field
+            )
+
+            if (
+                reservation_scope is not None
+                and entry_scope is not None
+                and str(
+                    reservation_scope
+                )
+                != str(
+                    entry_scope
+                )
+            ):
+                raise SettlementStoreError(
+                    "persistent reservation "
+                    f"{field} is inconsistent with "
+                    "payment entry scope; "
+                    "refusing payment fail-closed"
+                )
+
+        reservation_origin = (
+            reservation_raw.get(
+                "origin"
+            )
+        )
+
+        resource = raw_entry.get(
+            "resource"
+        )
+
+        if (
+            reservation_origin is not None
+            and resource is not None
+        ):
+            from qruntime.policy import (
+                _normalize_origin,
+            )
+
+            try:
+                resource_origin = (
+                    _normalize_origin(
+                        str(
+                            resource
+                        )
+                    )
+                )
+            except ValueError as exc:
+                raise SettlementStoreError(
+                    "persistent reservation resource "
+                    "has invalid origin; refusing "
+                    "payment fail-closed"
+                ) from exc
+
+            if (
+                str(
+                    reservation_origin
+                )
+                != resource_origin
+            ):
+                raise SettlementStoreError(
+                    "persistent reservation origin "
+                    "is inconsistent with payment resource; "
+                    "refusing payment fail-closed"
+                )
+
+    return dict(raw)
+
+def _classify_pending_store_format(
+    raw: Mapping[str, Any],
+) -> str:
+    """Classify a validated pending-store document."""
+
+    if "format" not in raw:
+        return "legacy"
+
+    if raw["format"] != PENDING_STORE_FORMAT:
+        raise SettlementStoreError(
+            "persistent settlement store format is unsupported; "
+            "refusing payment fail-closed"
+        )
+
+    return "current"
+
+
+def _load_pending_store() -> dict[str, Any]:
+    path = _pending_store_file()
+
+    if _pending_store_is_unambiguously_absent(
+        path
+    ):
+        return {
+            "format": PENDING_STORE_FORMAT,
+            "entries": {},
+        }
+
+    raw = _read_pending_store_document(
+        path
+    )
+
+    _classify_pending_store_format(
+        raw
+    )
+
+    return {
+        "format": PENDING_STORE_FORMAT,
+        "entries": dict(
+            raw["entries"]
+        ),
+    }
+
+
+
+
+
+
+def _write_pending_store(store: Mapping[str, Any]) -> None:
+    path = _pending_store_file()
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    temp = _pending_store_temp_file(
+        path
+    )
+    payload = json.dumps(
+        store,
+        indent=2,
+        ensure_ascii=False,
+    )
+
+    with temp.open(
+        "w",
+        encoding="utf-8",
+    ) as handle:
+        handle.write(payload)
+        handle.flush()
+        os.fsync(handle.fileno())
+
+    temp.replace(path)
+
+
+def _pending_store_transaction_lock_file() -> Path:
+    store = _pending_store_file()
+    return store.with_name(store.name + ".transaction.lock")
+
+
+def _acquire_pending_store_transaction_lock(
+    timeout: float = 5.0,
+) -> tuple[Path, int]:
+    """Acquire an OS-backed cross-process lock for store mutation."""
+    import time
+
+    if timeout <= 0:
+        raise ValueError("store lock timeout must be positive")
+
+    path = _pending_store_transaction_lock_file()
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    # The lock file itself may exist forever. Existence is NOT ownership.
+    flags = os.O_RDWR | os.O_CREAT
+    flags |= getattr(os, "O_BINARY", 0)
+    flags |= getattr(os, "O_NOINHERIT", 0)
+
+    fd = os.open(path, flags, 0o600)
+
+    try:
+        # Windows byte-range locking needs a byte to lock.
+        if os.fstat(fd).st_size == 0:
+            os.lseek(fd, 0, os.SEEK_SET)
+            os.write(fd, b"\0")
+            os.fsync(fd)
+
+        deadline = time.monotonic() + timeout
+
+        if os.name == "nt":
+            import msvcrt
+
+            while True:
+                os.lseek(fd, 0, os.SEEK_SET)
+
+                try:
+                    msvcrt.locking(
+                        fd,
+                        msvcrt.LK_NBLCK,
+                        1,
+                    )
+                    break
+
+                except OSError as exc:
+                    if time.monotonic() >= deadline:
+                        raise SettlementStoreError(
+                            "persistent settlement store is busy; "
+                            "refusing mutation fail-closed"
+                        ) from exc
+
+                    time.sleep(0.01)
+
+        else:
+            import errno
+            import fcntl
+
+            while True:
+                try:
+                    fcntl.flock(
+                        fd,
+                        fcntl.LOCK_EX | fcntl.LOCK_NB,
+                    )
+                    break
+
+                except OSError as exc:
+                    if exc.errno not in {
+                        errno.EACCES,
+                        errno.EAGAIN,
+                    }:
+                        raise
+
+                    if time.monotonic() >= deadline:
+                        raise SettlementStoreError(
+                            "persistent settlement store is busy; "
+                            "refusing mutation fail-closed"
+                        ) from exc
+
+                    time.sleep(0.01)
+
+        return path, fd
+
+    except Exception:
+        os.close(fd)
+        raise
+
+
+def _release_pending_store_transaction_lock(
+    handle: tuple[Path, int],
+) -> None:
+    _path, fd = handle
+
+    try:
+        if os.name == "nt":
+            import msvcrt
+
+            os.lseek(fd, 0, os.SEEK_SET)
+            msvcrt.locking(
+                fd,
+                msvcrt.LK_UNLCK,
+                1,
+            )
+
+        else:
+            import fcntl
+
+            fcntl.flock(
+                fd,
+                fcntl.LOCK_UN,
+            )
+
+    finally:
+        os.close(fd)
+
+
+def _migrate_pending_store_to_current_format() -> bool:
+    """Migrate one legacy versionless pending store to current format."""
+
+    lock = _acquire_pending_store_transaction_lock()
+
+    try:
+        path = _pending_store_file()
+
+        if _pending_store_is_unambiguously_absent(
+            path
+        ):
+            return False
+
+        raw = _read_pending_store_document(
+            path
+        )
+
+        format_kind = (
+            _classify_pending_store_format(
+                raw
+            )
+        )
+
+        if format_kind == "current":
+            # Already current: preserve bytes exactly.
+            return False
+
+        migrated = {
+            "format": PENDING_STORE_FORMAT,
+            "entries": dict(
+                raw["entries"]
+            ),
+        }
+
+        _write_pending_store(
+            migrated
+        )
+
+        return True
+
+    finally:
+        _release_pending_store_transaction_lock(
+            lock
+        )
+
+
+
+
+def _mutate_pending_store(mutator: Any) -> Any:
+    """Perform one atomic load-mutate-write store transaction."""
+    lock = _acquire_pending_store_transaction_lock()
+
+    try:
+        store = _load_pending_store()
+
+        result, changed = mutator(store)
+
+        if changed:
+            _write_pending_store(store)
+
+        return result
+
+    finally:
+        _release_pending_store_transaction_lock(lock)
+
+
+def _persistent_intent_key(intent_id: str) -> str:
+    import hashlib
+
+    return hashlib.sha256(intent_id.encode("utf-8")).hexdigest()
+
+
+
+def list_persistent_payment_intents() -> tuple[dict[str, Any], ...]:
+    """Return a consistent read-only snapshot of persisted payment intents."""
+
+    def read(store: dict[str, Any]):
+        entries = [
+            dict(raw_entry)
+            for raw_entry in store["entries"].values()
+            if isinstance(raw_entry, Mapping)
+        ]
+
+        entries.sort(
+            key=lambda entry: (
+                str(entry.get("updated_at", "")),
+                str(entry.get("intent_id", "")),
+            ),
+            reverse=True,
+        )
+
+        return tuple(entries), False
+
+    return _mutate_pending_store(read)
+
+
+def get_persistent_payment_intent(
+    intent_id: str,
+) -> dict[str, Any] | None:
+    """Return one persisted logical payment intent without mutating state."""
+
+    normalized = intent_id.strip()
+
+    if not normalized:
+        raise ValueError("intent_id must not be empty")
+
+    if len(normalized) > 256:
+        raise ValueError("intent_id must be at most 256 characters")
+
+    intent_key = _persistent_intent_key(normalized)
+
+    def read(store: dict[str, Any]):
+        raw_entry = store["entries"].get(intent_key)
+
+        if not isinstance(raw_entry, Mapping):
+            return None, False
+
+        return dict(raw_entry), False
+
+    return _mutate_pending_store(read)
+
+
+def _resolve_payment_intent_id(
+    intent_id: str | None,
+    resource: str,
+    requirement: Any,
+) -> str:
+    """Return a stable logical operation id.
+
+    Explicit intent ids survive quote changes. Legacy callers fall back to
+    resource + quote fingerprint for backward compatibility.
+    """
+    import hashlib
+
+    if intent_id is not None:
+        normalized = intent_id.strip()
+
+        if not normalized:
+            raise ValueError("intent_id must not be empty")
+
+        if len(normalized) > 256:
+            raise ValueError("intent_id must be at most 256 characters")
+
+        return normalized
+
+    legacy_raw = (
+        f"{resource}\n{requirement.fingerprint()}".encode("utf-8")
+    )
+    legacy_digest = hashlib.sha256(legacy_raw).hexdigest()
+    return f"legacy:{legacy_digest}"
+
+
+
+def _intent_claim_directory() -> Path:
+    store = _pending_store_file()
+    return store.parent / f"{store.name}.claims"
+
+
+def _probe_process_identity(
+    pid: int,
+) -> dict[str, str | None]:
+    """Probe one process without sending signals.
+
+    Returns:
+    - alive: process exists and has a stable creation identity;
+    - missing: process is proven absent/terminated;
+    - indeterminate: existence/identity could not be proven safely.
+
+    PID alone is insufficient because operating systems may reuse it.
+    """
+
+    import sys
+
+    if (
+        isinstance(pid, bool)
+        or not isinstance(pid, int)
+    ):
+        return {
+            "status": "indeterminate",
+            "identity": None,
+        }
+
+    if pid <= 0:
+        return {
+            "status": "missing",
+            "identity": None,
+        }
+
+    # ---------------------------------------------------------
+    # Windows
+    # ---------------------------------------------------------
+
+    if os.name == "nt":
+        import ctypes
+        from ctypes import wintypes
+
+        PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+        SYNCHRONIZE = 0x00100000
+
+        WAIT_OBJECT_0 = 0x00000000
+        WAIT_TIMEOUT = 0x00000102
+        WAIT_FAILED = 0xFFFFFFFF
+
+        ERROR_INVALID_PARAMETER = 87
+
+        kernel32 = ctypes.WinDLL(
+            "kernel32",
+            use_last_error=True,
+        )
+
+        open_process = kernel32.OpenProcess
+        open_process.argtypes = (
+            wintypes.DWORD,
+            wintypes.BOOL,
+            wintypes.DWORD,
+        )
+        open_process.restype = wintypes.HANDLE
+
+        wait_for_single_object = (
+            kernel32.WaitForSingleObject
+        )
+        wait_for_single_object.argtypes = (
+            wintypes.HANDLE,
+            wintypes.DWORD,
+        )
+        wait_for_single_object.restype = (
+            wintypes.DWORD
+        )
+
+        get_process_times = (
+            kernel32.GetProcessTimes
+        )
+        get_process_times.argtypes = (
+            wintypes.HANDLE,
+            ctypes.POINTER(
+                wintypes.FILETIME
+            ),
+            ctypes.POINTER(
+                wintypes.FILETIME
+            ),
+            ctypes.POINTER(
+                wintypes.FILETIME
+            ),
+            ctypes.POINTER(
+                wintypes.FILETIME
+            ),
+        )
+        get_process_times.restype = (
+            wintypes.BOOL
+        )
+
+        close_handle = kernel32.CloseHandle
+        close_handle.argtypes = (
+            wintypes.HANDLE,
+        )
+        close_handle.restype = (
+            wintypes.BOOL
+        )
+
+        access = (
+            PROCESS_QUERY_LIMITED_INFORMATION
+            | SYNCHRONIZE
+        )
+
+        handle = open_process(
+            access,
+            False,
+            pid,
+        )
+
+        if not handle:
+            error = ctypes.get_last_error()
+
+            if error == ERROR_INVALID_PARAMETER:
+                return {
+                    "status": "missing",
+                    "identity": None,
+                }
+
+            # Access denied or another unknown condition must
+            # never be interpreted as proof that the process died.
+            return {
+                "status": "indeterminate",
+                "identity": None,
+            }
+
+        try:
+            wait_result = (
+                wait_for_single_object(
+                    handle,
+                    0,
+                )
+            )
+
+            if wait_result == WAIT_OBJECT_0:
+                return {
+                    "status": "missing",
+                    "identity": None,
+                }
+
+            if wait_result == WAIT_FAILED:
+                return {
+                    "status": "indeterminate",
+                    "identity": None,
+                }
+
+            if wait_result != WAIT_TIMEOUT:
+                return {
+                    "status": "indeterminate",
+                    "identity": None,
+                }
+
+            creation = wintypes.FILETIME()
+            exit_time = wintypes.FILETIME()
+            kernel_time = wintypes.FILETIME()
+            user_time = wintypes.FILETIME()
+
+            ok = get_process_times(
+                handle,
+                ctypes.byref(
+                    creation
+                ),
+                ctypes.byref(
+                    exit_time
+                ),
+                ctypes.byref(
+                    kernel_time
+                ),
+                ctypes.byref(
+                    user_time
+                ),
+            )
+
+            if not ok:
+                return {
+                    "status": "indeterminate",
+                    "identity": None,
+                }
+
+            creation_ticks = (
+                (
+                    int(
+                        creation.dwHighDateTime
+                    )
+                    << 32
+                )
+                | int(
+                    creation.dwLowDateTime
+                )
+            )
+
+            if creation_ticks <= 0:
+                return {
+                    "status": "indeterminate",
+                    "identity": None,
+                }
+
+            return {
+                "status": "alive",
+                "identity": (
+                    f"windows:{creation_ticks}"
+                ),
+            }
+
+        finally:
+            close_handle(
+                handle
+            )
+
+    # ---------------------------------------------------------
+    # Linux
+    # ---------------------------------------------------------
+
+    if sys.platform.startswith(
+        "linux"
+    ):
+        stat_path = Path(
+            f"/proc/{pid}/stat"
+        )
+
+        try:
+            raw = stat_path.read_text(
+                encoding="utf-8",
+                errors="strict",
+            )
+
+        except FileNotFoundError:
+            return {
+                "status": "missing",
+                "identity": None,
+            }
+
+        except OSError:
+            return {
+                "status": "indeterminate",
+                "identity": None,
+            }
+
+        # Field 2 (comm) is parenthesized and may contain spaces.
+        # Parse from the final ')' so the remaining sequence starts
+        # at field 3 (state).
+        close_paren = raw.rfind(
+            ")"
+        )
+
+        if close_paren == -1:
+            return {
+                "status": "indeterminate",
+                "identity": None,
+            }
+
+        remaining = raw[
+            close_paren + 1:
+        ].strip().split()
+
+        # remaining[0] == field 3.
+        # starttime is field 22 => index 19 here.
+        if len(remaining) <= 19:
+            return {
+                "status": "indeterminate",
+                "identity": None,
+            }
+
+        starttime = remaining[
+            19
+        ]
+
+        if not starttime.isdigit():
+            return {
+                "status": "indeterminate",
+                "identity": None,
+            }
+
+        return {
+            "status": "alive",
+            "identity": (
+                f"linux:{starttime}"
+            ),
+        }
+
+    # Unsupported platforms remain fail-closed.
+    return {
+        "status": "indeterminate",
+        "identity": None,
+    }
+
+
+def _classify_payment_intent_claim_recovery(
+    claim: Mapping[str, Any],
+    *,
+    process_probe: Mapping[str, Any],
+) -> dict[str, Any]:
+    """Classify one persisted payment-intent claim without mutation.
+
+    A claim is reclaimable only when process evidence positively proves
+    that the original claiming process is gone or that its PID has been
+    reused by a different process instance.
+
+    Any malformed or incomplete evidence fails closed.
+    """
+
+    if not isinstance(
+        claim,
+        Mapping,
+    ):
+        return {
+            "status": "indeterminate",
+            "safe_to_reclaim": False,
+        }
+
+    if claim.get(
+        "format"
+    ) != "qruntime-x402-intent-claim-v2":
+        return {
+            "status": "indeterminate",
+            "safe_to_reclaim": False,
+        }
+
+    pid = claim.get(
+        "pid"
+    )
+
+    claimed_identity = claim.get(
+        "process_identity"
+    )
+
+    claimed_identity_status = claim.get(
+        "process_identity_status"
+    )
+
+    if (
+        isinstance(pid, bool)
+        or not isinstance(pid, int)
+        or pid <= 0
+        or not isinstance(
+            claimed_identity,
+            str,
+        )
+        or not claimed_identity
+        or claimed_identity_status != "alive"
+    ):
+        return {
+            "status": "indeterminate",
+            "safe_to_reclaim": False,
+        }
+
+    if not isinstance(
+        process_probe,
+        Mapping,
+    ):
+        return {
+            "status": "indeterminate",
+            "safe_to_reclaim": False,
+        }
+
+    probe_status = process_probe.get(
+        "status"
+    )
+
+    probe_identity = process_probe.get(
+        "identity"
+    )
+
+    if probe_status == "missing":
+        return {
+            "status": "stale_missing",
+            "safe_to_reclaim": True,
+        }
+
+    if probe_status != "alive":
+        return {
+            "status": "indeterminate",
+            "safe_to_reclaim": False,
+        }
+
+    if (
+        not isinstance(
+            probe_identity,
+            str,
+        )
+        or not probe_identity
+    ):
+        return {
+            "status": "indeterminate",
+            "safe_to_reclaim": False,
+        }
+
+    if probe_identity == claimed_identity:
+        return {
+            "status": "active",
+            "safe_to_reclaim": False,
+        }
+
+    return {
+        "status": "stale_pid_reused",
+        "safe_to_reclaim": True,
+    }
+
+
+def _preview_payment_intent_claim_recovery(
+    logical_intent_id: str,
+    *,
+    probe_process_identity=None,
+) -> dict[str, Any]:
+    """Read and classify one persisted intent claim without mutation."""
+
+    if probe_process_identity is None:
+        probe_process_identity = _probe_process_identity
+
+    claim_path = _intent_claim_path(
+        logical_intent_id
+    )
+
+    try:
+        raw = claim_path.read_bytes()
+    except OSError as exc:
+        raise SettlementStoreError(
+            "payment intent claim could not be read"
+        ) from exc
+
+    try:
+        claim = json.loads(raw)
+    except (
+        json.JSONDecodeError,
+        UnicodeDecodeError,
+    ) as exc:
+        raise SettlementStoreError(
+            "payment intent claim contains invalid JSON"
+        ) from exc
+
+    if not isinstance(claim, Mapping):
+        raise SettlementStoreError(
+            "payment intent claim must contain a JSON object"
+        )
+
+    persisted_intent_id = claim.get(
+        "intent_id"
+    )
+
+    if (
+        not isinstance(
+            persisted_intent_id,
+            str,
+        )
+        or persisted_intent_id != logical_intent_id
+    ):
+        raise SettlementStoreError(
+            "payment intent claim identity does not match requested intent"
+        )
+
+    pid = claim.get(
+        "pid"
+    )
+
+    if (
+        isinstance(pid, bool)
+        or not isinstance(pid, int)
+        or pid <= 0
+    ):
+        process_probe = {
+            "status": "indeterminate",
+            "identity": None,
+        }
+    else:
+        try:
+            process_probe = (
+                probe_process_identity(pid)
+            )
+        except Exception:
+            process_probe = {
+                "status": "indeterminate",
+                "identity": None,
+            }
+
+    if not isinstance(
+        process_probe,
+        Mapping,
+    ):
+        process_probe = {
+            "status": "indeterminate",
+            "identity": None,
+        }
+
+    decision = (
+        _classify_payment_intent_claim_recovery(
+            claim,
+            process_probe=process_probe,
+        )
+    )
+
+    return {
+        "intent_id": logical_intent_id,
+        "status": decision["status"],
+        "safe_to_reclaim": decision[
+            "safe_to_reclaim"
+        ],
+        "pid": pid,
+        "process_identity": claim.get(
+            "process_identity"
+        ),
+        "process_probe": dict(
+            process_probe
+        ),
+    }
+
+
+def _reclaim_payment_intent_claim_if_stale_unlocked(
+    logical_intent_id: str,
+    *,
+    probe_process_identity=None,
+) -> bool:
+    """Reclaim one positively stale claim while caller holds OS guard."""
+
+    if probe_process_identity is None:
+        probe_process_identity = _probe_process_identity
+
+    claim_path = _intent_claim_path(
+        logical_intent_id
+    )
+
+    try:
+        initial_raw = claim_path.read_bytes()
+    except OSError as exc:
+        raise SettlementStoreError(
+            "payment intent claim could not be read for reclaim"
+        ) from exc
+
+    try:
+        claim = json.loads(
+            initial_raw
+        )
+    except (
+        json.JSONDecodeError,
+        UnicodeDecodeError,
+    ) as exc:
+        raise SettlementStoreError(
+            "payment intent claim contains invalid JSON"
+        ) from exc
+
+    if not isinstance(
+        claim,
+        Mapping,
+    ):
+        raise SettlementStoreError(
+            "payment intent claim must contain a JSON object"
+        )
+
+    persisted_intent_id = claim.get(
+        "intent_id"
+    )
+
+    if (
+        not isinstance(
+            persisted_intent_id,
+            str,
+        )
+        or persisted_intent_id
+        != logical_intent_id
+    ):
+        raise SettlementStoreError(
+            "payment intent claim identity does not match requested intent"
+        )
+
+    pid = claim.get(
+        "pid"
+    )
+
+    if (
+        isinstance(pid, bool)
+        or not isinstance(pid, int)
+        or pid <= 0
+    ):
+        process_probe = {
+            "status": "indeterminate",
+            "identity": None,
+        }
+    else:
+        try:
+            process_probe = probe_process_identity(
+                pid
+            )
+        except Exception:
+            process_probe = {
+                "status": "indeterminate",
+                "identity": None,
+            }
+
+    if not isinstance(
+        process_probe,
+        Mapping,
+    ):
+        process_probe = {
+            "status": "indeterminate",
+            "identity": None,
+        }
+
+    decision = (
+        _classify_payment_intent_claim_recovery(
+            claim,
+            process_probe=process_probe,
+        )
+    )
+
+    if not decision["safe_to_reclaim"]:
+        return False
+
+    try:
+        current_raw = claim_path.read_bytes()
+    except OSError:
+        return False
+
+    if current_raw != initial_raw:
+        return False
+
+    try:
+        claim_path.unlink()
+    except FileNotFoundError:
+        return False
+    except OSError as exc:
+        raise SettlementStoreError(
+            "payment intent claim could not be reclaimed"
+        ) from exc
+
+    return True
+
+
+def _reclaim_payment_intent_claim_if_stale(
+    logical_intent_id: str,
+    *,
+    probe_process_identity=None,
+) -> bool:
+    """Reclaim one stale claim under its OS guard."""
+
+    guard = _acquire_payment_intent_claim_guard(
+        logical_intent_id
+    )
+
+    try:
+        return _reclaim_payment_intent_claim_if_stale_unlocked(
+            logical_intent_id,
+            probe_process_identity=probe_process_identity,
+        )
+    finally:
+        _release_payment_intent_claim_guard(
+            guard
+        )
+
+
+
+
+
+
+def _intent_claim_guard_path(
+    logical_intent_id: str,
+) -> Path:
+    return (
+        _intent_claim_directory()
+        / f"{_persistent_intent_key(logical_intent_id)}.guard"
+    )
+
+
+def _acquire_payment_intent_claim_guard(
+    logical_intent_id: str,
+) -> dict[str, Any]:
+    """Acquire a non-blocking OS-level guard for one payment intent."""
+
+    import errno
+
+    guard_path = _intent_claim_guard_path(
+        logical_intent_id
+    )
+
+    guard_path.parent.mkdir(
+        parents=True,
+        exist_ok=True,
+    )
+
+    try:
+        handle = open(
+            guard_path,
+            "a+b",
+            buffering=0,
+        )
+    except OSError as exc:
+        raise SettlementStoreError(
+            "payment intent claim guard could not be opened"
+        ) from exc
+
+    try:
+        if os.name == "nt":
+            import msvcrt
+
+            handle.seek(0)
+
+            try:
+                msvcrt.locking(
+                    handle.fileno(),
+                    msvcrt.LK_NBLCK,
+                    1,
+                )
+            except OSError as exc:
+                handle.close()
+
+                if exc.errno in (
+                    errno.EACCES,
+                    errno.EAGAIN,
+                ):
+                    raise IntentInFlightError(
+                        "payment intent guard is already held"
+                    ) from exc
+
+                raise SettlementStoreError(
+                    "payment intent claim guard lock failed"
+                ) from exc
+
+            return {
+                "backend": "msvcrt",
+                "handle": handle,
+                "path": guard_path,
+            }
+
+        try:
+            import fcntl
+        except ImportError as exc:
+            handle.close()
+
+            raise SettlementStoreError(
+                "payment intent claim guard is unsupported "
+                "on this platform"
+            ) from exc
+
+        try:
+            fcntl.flock(
+                handle.fileno(),
+                fcntl.LOCK_EX
+                | fcntl.LOCK_NB,
+            )
+        except OSError as exc:
+            handle.close()
+
+            if exc.errno in (
+                errno.EACCES,
+                errno.EAGAIN,
+            ):
+                raise IntentInFlightError(
+                    "payment intent guard is already held"
+                ) from exc
+
+            raise SettlementStoreError(
+                "payment intent claim guard lock failed"
+            ) from exc
+
+        return {
+            "backend": "fcntl",
+            "handle": handle,
+            "path": guard_path,
+        }
+
+    except Exception:
+        if not handle.closed:
+            handle.close()
+        raise
+
+
+def _release_payment_intent_claim_guard(
+    guard: Mapping[str, Any],
+) -> None:
+    """Release an OS-level payment-intent guard."""
+
+    handle = guard.get(
+        "handle"
+    )
+
+    backend = guard.get(
+        "backend"
+    )
+
+    if handle is None:
+        raise SettlementStoreError(
+            "payment intent claim guard handle is missing"
+        )
+
+    if handle.closed:
+        return
+
+    try:
+        if backend == "msvcrt":
+            import msvcrt
+
+            handle.seek(0)
+
+            msvcrt.locking(
+                handle.fileno(),
+                msvcrt.LK_UNLCK,
+                1,
+            )
+
+        elif backend == "fcntl":
+            import fcntl
+
+            fcntl.flock(
+                handle.fileno(),
+                fcntl.LOCK_UN,
+            )
+
+        else:
+            raise SettlementStoreError(
+                "payment intent claim guard backend is invalid"
+            )
+
+    finally:
+        handle.close()
+
+
+def _intent_claim_path(logical_intent_id: str) -> Path:
+    return (
+        _intent_claim_directory()
+        / f"{_persistent_intent_key(logical_intent_id)}.claim"
+    )
+
+
+def _acquire_payment_intent_claim_unlocked(
+    logical_intent_id: str,
+    resource: str,
+) -> Path:
+    """Atomically claim one logical payment intent across processes."""
+    claims = _intent_claim_directory()
+    claims.mkdir(parents=True, exist_ok=True)
+
+    path = _intent_claim_path(logical_intent_id)
+
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
+    flags |= getattr(os, "O_BINARY", 0)
+
+    try:
+        fd = os.open(path, flags, 0o600)
+    except FileExistsError as exc:
+        raise IntentInFlightError(
+            "preflight refused payment: payment intent "
+            f"{logical_intent_id} is already in-flight in another process"
+        ) from exc
+
+    try:
+        pid = os.getpid()
+        probe = _probe_process_identity(pid)
+        status = str(probe.get("status", ""))
+        identity = probe.get("identity")
+        if status != "alive" or not isinstance(identity, str) or not identity:
+            raise SettlementStoreError(
+                "current process identity could not be established safely for intent claim"
+            )
+    except Exception:
+        os.close(fd)
+        path.unlink(missing_ok=True)
+        raise
+
+    payload = {
+        "format": "qruntime-x402-intent-claim-v2",
+        "intent_id": logical_intent_id,
+        "intent_key": _persistent_intent_key(logical_intent_id),
+        "resource": resource,
+        "pid": pid,
+        "process_identity": identity,
+        "process_identity_status": status,
+        "claimed_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+    try:
+        encoded = json.dumps(
+            payload,
+            indent=2,
+            ensure_ascii=False,
+        ).encode("utf-8")
+
+        os.write(fd, encoded)
+        os.fsync(fd)
+    except Exception:
+        os.close(fd)
+        path.unlink(missing_ok=True)
+        raise
+    else:
+        os.close(fd)
+
+    return path
+
+
+def _acquire_payment_intent_claim(
+    logical_intent_id: str,
+    resource: str,
+) -> Path:
+    """Acquire a durable claim, recovering one proven stale claim once."""
+
+    guard = _acquire_payment_intent_claim_guard(
+        logical_intent_id
+    )
+
+    try:
+        try:
+            return _acquire_payment_intent_claim_unlocked(
+                logical_intent_id,
+                resource,
+            )
+
+        except IntentInFlightError:
+            reclaimed = (
+                _reclaim_payment_intent_claim_if_stale_unlocked(
+                    logical_intent_id
+                )
+            )
+
+            if not reclaimed:
+                raise
+
+            # Retry exactly once while still holding the same guard.
+            # If another non-cooperating writer created a claim anyway,
+            # O_EXCL fails closed again.
+            return _acquire_payment_intent_claim_unlocked(
+                logical_intent_id,
+                resource,
+            )
+
+    finally:
+        _release_payment_intent_claim_guard(
+            guard
+        )
+
+
+
+
+
+
+def _release_payment_intent_claim(path: Path) -> None:
+    path.unlink(missing_ok=True)
+
+
+def _reserve_aggregate_budget(
+    logical_intent_id: str,
+    resource: str,
+    requirement: Any,
+    budget: Any,
+    *,
+    agent_id: str | None = None,
+    session_id: str | None = None,
+):
+    """Atomically check and reserve aggregate budget.
+
+    The budget decision and reservation write happen
+    under the same persistent-store transaction lock.
+    """
+    from qruntime.budget import (
+        BudgetLimit,
+        evaluate_budget,
+    )
+    from qruntime.spend import (
+        _normalize_agent_id,
+        _normalize_session_id,
+        summarize_spend_entries,
+    )
+
+    if not isinstance(
+        budget,
+        BudgetLimit,
+    ):
+        raise TypeError(
+            "budget must be a BudgetLimit"
+        )
+
+    if (
+        budget.network
+        != requirement.network
+        or budget.asset
+        != requirement.asset
+    ):
+        raise ValueError(
+            "budget dimensions do not match "
+            "selected payment requirement"
+        )
+
+    if budget.origin is not None:
+        from qruntime.policy import (
+            _normalize_origin,
+        )
+
+        resource_origin = (
+            _normalize_origin(resource)
+        )
+
+        if resource_origin != budget.origin:
+            raise ValueError(
+                "budget origin does not match "
+                "selected payment resource"
+            )
+
+    payment_agent_id = None
+
+    if agent_id is not None:
+        payment_agent_id = (
+            _normalize_agent_id(
+                agent_id
+            )
+        )
+
+    if budget.agent_id is not None:
+        if payment_agent_id is None:
+            raise ValueError(
+                "agent-scoped budget requires agent_id"
+            )
+
+        if payment_agent_id != budget.agent_id:
+            raise ValueError(
+                "budget agent does not match "
+                "payment agent"
+            )
+
+    payment_session_id = None
+
+    if session_id is not None:
+        payment_session_id = (
+            _normalize_session_id(
+                session_id
+            )
+        )
+
+    if budget.session_id is not None:
+        if payment_session_id is None:
+            raise ValueError(
+                "session-scoped budget requires session_id"
+            )
+
+        if (
+            payment_session_id
+            != budget.session_id
+        ):
+            raise ValueError(
+                "budget session does not match "
+                "payment session"
+            )
+
+    intent_key = _persistent_intent_key(
+        logical_intent_id
+    )
+
+    fingerprint = (
+        requirement.fingerprint()
+    )
+
+    now = datetime.now(
+        timezone.utc
+    ).isoformat()
+
+    reservation = {
+        "intent_id": logical_intent_id,
+        "intent_key": intent_key,
+        "resource": resource,
+        "agent_id": payment_agent_id,
+        "session_id": payment_session_id,
+        "quote_fingerprint": fingerprint,
+        "requirement": (
+            requirement.canonical_dict()
+        ),
+        "transaction": None,
+        "network": requirement.network,
+        "state": "reserved",
+        "first_seen_at": now,
+        "updated_at": now,
+        "reservation": {
+            "reserved_at": now,
+            "budget_limit_atomic": (
+                budget.max_amount_atomic
+            ),
+            "network": budget.network,
+            "asset": budget.asset,
+            "origin": budget.origin,
+            "agent_id": budget.agent_id,
+            "session_id": budget.session_id,
+        },
+    }
+
+    def mutate(
+        store: dict[str, Any],
+    ):
+        existing = store[
+            "entries"
+        ].get(intent_key)
+
+        if existing is not None:
+            raise SettlementStoreError(
+                "persistent economic state "
+                "already exists for payment intent"
+            )
+
+        try:
+            summary = (
+                summarize_spend_entries(
+                    (
+                        entry
+                        for entry in (
+                            store[
+                                "entries"
+                            ].values()
+                        )
+                        if isinstance(
+                            entry,
+                            Mapping,
+                        )
+                    ),
+                    origin=budget.origin,
+                    agent_id=budget.agent_id,
+                    session_id=budget.session_id,
+                )
+            )
+        except ValueError as exc:
+            raise SettlementStoreError(
+                "persistent economic state "
+                "is invalid; refusing budget "
+                "reservation fail-closed"
+            ) from exc
+
+        decision = evaluate_budget(
+            budget,
+            summary=summary,
+            requested_amount_atomic=(
+                requirement.amount_atomic
+            ),
+        )
+
+        if not decision.allowed:
+            return decision, False
+
+        store[
+            "entries"
+        ][intent_key] = reservation
+
+        return decision, True
+
+    return _mutate_pending_store(
+        mutate
+    )
+
+
+def _reserve_budget_set(
+    logical_intent_id: str,
+    resource: str,
+    requirement: Any,
+    budget_set: Any,
+    *,
+    agent_id: str | None = None,
+    session_id: str | None = None,
+):
+    """Atomically evaluate all budget constraints and reserve once."""
+    from qruntime.budget import (
+        BudgetSet,
+        BudgetSetDecision,
+        evaluate_budget,
+    )
+    from qruntime.policy import (
+        _normalize_origin,
+    )
+    from qruntime.spend import (
+        _normalize_agent_id,
+        _normalize_session_id,
+        summarize_spend_entries,
+    )
+
+    if not isinstance(
+        budget_set,
+        BudgetSet,
+    ):
+        raise TypeError(
+            "budget_set must be a BudgetSet"
+        )
+
+    resource_origin = (
+        _normalize_origin(resource)
+    )
+
+    payment_agent_id = None
+
+    if agent_id is not None:
+        payment_agent_id = (
+            _normalize_agent_id(
+                agent_id
+            )
+        )
+
+    payment_session_id = None
+
+    if session_id is not None:
+        payment_session_id = (
+            _normalize_session_id(
+                session_id
+            )
+        )
+
+    for limit in budget_set.limits:
+        if (
+            limit.network
+            != requirement.network
+            or limit.asset
+            != requirement.asset
+        ):
+            raise ValueError(
+                "budget dimensions do not match "
+                "selected payment requirement"
+            )
+
+        if (
+            limit.origin is not None
+            and limit.origin
+            != resource_origin
+        ):
+            raise ValueError(
+                "budget origin does not match "
+                "selected payment resource"
+            )
+
+        if limit.agent_id is not None:
+            if payment_agent_id is None:
+                raise ValueError(
+                    "agent-scoped budget requires agent_id"
+                )
+
+            if (
+                payment_agent_id
+                != limit.agent_id
+            ):
+                raise ValueError(
+                    "budget agent does not match "
+                    "payment agent"
+                )
+
+        if limit.session_id is not None:
+            if payment_session_id is None:
+                raise ValueError(
+                    "session-scoped budget "
+                    "requires session_id"
+                )
+
+            if (
+                payment_session_id
+                != limit.session_id
+            ):
+                raise ValueError(
+                    "budget session does not match "
+                    "payment session"
+                )
+
+    intent_key = _persistent_intent_key(
+        logical_intent_id
+    )
+
+    now = datetime.now(
+        timezone.utc
+    ).isoformat()
+
+    reservation = {
+        "intent_id": logical_intent_id,
+        "intent_key": intent_key,
+        "resource": resource,
+        "agent_id": payment_agent_id,
+        "session_id": payment_session_id,
+        "quote_fingerprint": (
+            requirement.fingerprint()
+        ),
+        "requirement": (
+            requirement.canonical_dict()
+        ),
+        "transaction": None,
+        "network": requirement.network,
+        "state": "reserved",
+        "first_seen_at": now,
+        "updated_at": now,
+        "reservation": {
+            "reserved_at": now,
+            "constraints": [
+                {
+                    "network": limit.network,
+                    "asset": limit.asset,
+                    "origin": limit.origin,
+                    "agent_id": limit.agent_id,
+                    "session_id": limit.session_id,
+                    "budget_limit_atomic": (
+                        limit.max_amount_atomic
+                    ),
+                }
+                for limit in budget_set.limits
+            ],
+        },
+    }
+
+    def mutate(
+        store: dict[str, Any],
+    ):
+        existing = store[
+            "entries"
+        ].get(intent_key)
+
+        if existing is not None:
+            raise SettlementStoreError(
+                "persistent economic state "
+                "already exists for payment intent"
+            )
+
+        entries = tuple(
+            entry
+            for entry in (
+                store[
+                    "entries"
+                ].values()
+            )
+            if isinstance(
+                entry,
+                Mapping,
+            )
+        )
+
+        decisions = []
+
+        try:
+            for limit in budget_set.limits:
+                summary = (
+                    summarize_spend_entries(
+                        entries,
+                        origin=limit.origin,
+                        agent_id=limit.agent_id,
+                        session_id=limit.session_id,
+                    )
+                )
+
+                decision = evaluate_budget(
+                    limit,
+                    summary=summary,
+                    requested_amount_atomic=(
+                        requirement.amount_atomic
+                    ),
+                )
+
+                decisions.append(
+                    decision
+                )
+
+        except ValueError as exc:
+            raise SettlementStoreError(
+                "persistent economic state "
+                "is invalid; refusing budget "
+                "reservation fail-closed"
+            ) from exc
+
+        result = BudgetSetDecision(
+            allowed=all(
+                decision.allowed
+                for decision in decisions
+            ),
+            decisions=tuple(
+                decisions
+            ),
+        )
+
+        if not result.allowed:
+            return result, False
+
+        store[
+            "entries"
+        ][intent_key] = reservation
+
+        return result, True
+
+    return _mutate_pending_store(
+        mutate
+    )
+
+
+def _mark_payment_submission_unknown(
+    logical_intent_id: str,
+    resource: str | None = None,
+    requirement: Any | None = None,
+    *,
+    agent_id: str | None = None,
+    session_id: str | None = None,
+) -> bool:
+    """Durably mark an intent before the potentially economic handoff.
+
+    Existing reserved state is advanced to submission_unknown.
+    Without a budget reservation, a new durable economic intent entry
+    is created so a crash cannot leave only an orphaned claim file.
+    """
+    intent_key = _persistent_intent_key(
+        logical_intent_id
+    )
+
+    normalized_agent_id = None
+    if agent_id is not None:
+        from qruntime.spend import _normalize_agent_id
+
+        normalized_agent_id = _normalize_agent_id(
+            agent_id
+        )
+
+    normalized_session_id = None
+    if session_id is not None:
+        from qruntime.spend import _normalize_session_id
+
+        normalized_session_id = _normalize_session_id(
+            session_id
+        )
+
+    now = datetime.now(
+        timezone.utc
+    ).isoformat()
+
+    def mutate(
+        store: dict[str, Any],
+    ):
+        raw = store[
+            "entries"
+        ].get(intent_key)
+
+        if isinstance(
+            raw,
+            Mapping,
+        ):
+            state = str(
+                raw.get("state", "")
+            )
+
+            if state == "submission_unknown":
+                return True, False
+
+            if state != "reserved":
+                return False, False
+
+            entry = dict(raw)
+
+            entry["state"] = "submission_unknown"
+            entry["submission_unknown_since"] = now
+            entry["updated_at"] = now
+
+            store[
+                "entries"
+            ][intent_key] = entry
+
+            return True, True
+
+        if (
+            resource is None
+            or requirement is None
+        ):
+            return False, False
+
+        entry = {
+            "intent_id": logical_intent_id,
+            "intent_key": intent_key,
+            "resource": resource,
+            "agent_id": normalized_agent_id,
+            "session_id": normalized_session_id,
+            "quote_fingerprint": (
+                requirement.fingerprint()
+            ),
+            "requirement": (
+                requirement.canonical_dict()
+            ),
+            "transaction": None,
+            "network": requirement.network,
+            "state": "submission_unknown",
+            "first_seen_at": now,
+            "updated_at": now,
+            "submission_unknown_since": now,
+        }
+
+        store[
+            "entries"
+        ][intent_key] = entry
+
+        return True, True
+
+    return _mutate_pending_store(
+        mutate
+    )
+
+
+def _classify_eip3009_authorization_recovery(
+    authorization: Mapping[str, Any],
+    *,
+    now_unix: int,
+    authorization_state: bool | None,
+    event_kind: str | None,
+) -> dict[str, Any]:
+    """Classify persisted EIP-3009 recovery evidence conservatively."""
+
+    if event_kind not in {
+        None,
+        "used",
+        "canceled",
+    }:
+        raise ValueError(
+            "event_kind must be None, 'used', or 'canceled'"
+        )
+
+    try:
+        valid_after = int(
+            authorization["validAfter"]
+        )
+        valid_before = int(
+            authorization["validBefore"]
+        )
+    except (
+        KeyError,
+        TypeError,
+        ValueError,
+    ):
+        return {
+            "status": "indeterminate",
+            "safe_to_release": False,
+            "requires_reconciliation": True,
+        }
+
+    if valid_before <= valid_after:
+        return {
+            "status": "indeterminate",
+            "safe_to_release": False,
+            "requires_reconciliation": True,
+        }
+
+    # Event evidence cannot coherently coexist with
+    # authorization_state=False.
+    if (
+        event_kind is not None
+        and authorization_state is False
+    ):
+        return {
+            "status": "indeterminate",
+            "safe_to_release": False,
+            "requires_reconciliation": True,
+        }
+
+    if event_kind == "used":
+        return {
+            "status": "used",
+            "safe_to_release": False,
+            "requires_reconciliation": True,
+        }
+
+    if event_kind == "canceled":
+        return {
+            "status": "canceled",
+            "safe_to_release": True,
+            "requires_reconciliation": False,
+        }
+
+    if authorization_state is True:
+        return {
+            "status": "consumed_indeterminate",
+            "safe_to_release": False,
+            "requires_reconciliation": True,
+        }
+
+    if authorization_state is None:
+        return {
+            "status": "indeterminate",
+            "safe_to_release": False,
+            "requires_reconciliation": True,
+        }
+
+    # ERC-3009 uses strict validity:
+    # block time must be > validAfter and < validBefore.
+    if now_unix <= valid_after:
+        return {
+            "status": "unused_not_yet_valid",
+            "safe_to_release": False,
+            "requires_reconciliation": True,
+        }
+
+    if now_unix >= valid_before:
+        return {
+            "status": "expired_unused",
+            "safe_to_release": True,
+            "requires_reconciliation": False,
+        }
+
+    return {
+        "status": "unused_live",
+        "safe_to_release": False,
+        "requires_reconciliation": True,
+    }
+
+
+def _aggregate_eip3009_recovery_decisions(
+    authorizations: list[Mapping[str, Any]],
+    *,
+    now_unix: int,
+    evidence_by_nonce: Mapping[str, Mapping[str, Any]],
+) -> dict[str, Any]:
+    """Aggregate recovery evidence across all authorizations of one intent.
+
+    Release is safe only when at least one authorization exists and
+    every authorization is independently proven safe to release.
+    """
+
+    if not authorizations:
+        return {
+            "safe_to_release": False,
+            "requires_reconciliation": True,
+            "decisions": [],
+        }
+
+    decisions: list[dict[str, Any]] = []
+
+    for authorization in authorizations:
+        nonce = str(
+            authorization.get(
+                "nonce",
+                "",
+            )
+        )
+
+        evidence = evidence_by_nonce.get(
+            nonce
+        )
+
+        if not isinstance(
+            evidence,
+            Mapping,
+        ):
+            decision = {
+                "status": "indeterminate",
+                "safe_to_release": False,
+                "requires_reconciliation": True,
+            }
+
+        else:
+            decision = (
+                _classify_eip3009_authorization_recovery(
+                    authorization,
+                    now_unix=now_unix,
+                    authorization_state=(
+                        evidence.get(
+                            "authorization_state"
+                        )
+                    ),
+                    event_kind=(
+                        evidence.get(
+                            "event_kind"
+                        )
+                    ),
+                )
+            )
+
+        decisions.append(
+            decision
+        )
+
+    safe_to_release = all(
+        decision[
+            "safe_to_release"
+        ]
+        for decision in decisions
+    )
+
+    requires_reconciliation = (
+        not safe_to_release
+        or any(
+            decision[
+                "requires_reconciliation"
+            ]
+            for decision in decisions
+        )
+    )
+
+    return {
+        "safe_to_release": safe_to_release,
+        "requires_reconciliation": (
+            requires_reconciliation
+        ),
+        "decisions": decisions,
+    }
+
+
+def _collect_eip3009_recovery_evidence(
+    authorizations: list[Mapping[str, Any]],
+    *,
+    read_authorization_state,
+    read_authorization_event,
+) -> dict[str, dict[str, Any]]:
+    """Collect chain evidence for persisted EIP-3009 authorizations.
+
+    Each evidence source is queried independently. Failure of either
+    source becomes indeterminate evidence and never fails open.
+    """
+
+    evidence_by_nonce: dict[
+        str,
+        dict[str, Any],
+    ] = {}
+
+    for authorization in authorizations:
+        network = str(
+            authorization.get(
+                "network",
+                "",
+            )
+        )
+
+        asset = str(
+            authorization.get(
+                "asset",
+                "",
+            )
+        )
+
+        authorizer = str(
+            authorization.get(
+                "from",
+                "",
+            )
+        )
+
+        nonce = str(
+            authorization.get(
+                "nonce",
+                "",
+            )
+        )
+
+        if not (
+            network
+            and asset
+            and authorizer
+            and nonce
+        ):
+            # Malformed persisted evidence is never interpreted
+            # optimistically.
+            if nonce:
+                evidence_by_nonce[
+                    nonce
+                ] = {
+                    "authorization_state": None,
+                    "event_kind": None,
+                }
+
+            continue
+
+        try:
+            authorization_state = (
+                read_authorization_state(
+                    network=network,
+                    asset=asset,
+                    authorizer=authorizer,
+                    nonce=nonce,
+                )
+            )
+
+            if not isinstance(
+                authorization_state,
+                bool,
+            ):
+                authorization_state = None
+
+        except Exception:
+            authorization_state = None
+
+        try:
+            event_kind = (
+                read_authorization_event(
+                    network=network,
+                    asset=asset,
+                    authorizer=authorizer,
+                    nonce=nonce,
+                )
+            )
+
+            if event_kind not in {
+                None,
+                "used",
+                "canceled",
+            }:
+                event_kind = None
+
+        except Exception:
+            event_kind = None
+
+        evidence_by_nonce[
+            nonce
+        ] = {
+            "authorization_state": (
+                authorization_state
+            ),
+            "event_kind": event_kind,
+        }
+
+    return evidence_by_nonce
+
+
+def _preview_eip3009_intent_recovery(
+    logical_intent_id: str,
+    *,
+    now_unix: int,
+    read_authorization_state,
+    read_authorization_event,
+) -> dict[str, Any]:
+    """Preview recovery for one persisted economic intent.
+
+    This operation is observational only. It reads durable state and
+    external evidence but never mutates the persistent store.
+    """
+
+    entry = get_persistent_payment_intent(
+        logical_intent_id
+    )
+
+    if not isinstance(
+        entry,
+        Mapping,
+    ):
+        raise SettlementStoreError(
+            "persistent payment intent was not found"
+        )
+
+    state = str(
+        entry.get(
+            "state",
+            "",
+        )
+    )
+
+    history_raw = entry.get(
+        "authorizations"
+    )
+
+    authorizations: list[
+        Mapping[str, Any]
+    ] = []
+
+    if isinstance(
+        history_raw,
+        list,
+    ):
+        for item in history_raw:
+            if not isinstance(
+                item,
+                Mapping,
+            ):
+                raise SettlementStoreError(
+                    "persistent authorization history "
+                    "contains invalid entry"
+                )
+
+            authorizations.append(
+                dict(item)
+            )
+
+    else:
+        # Backwards-compatible support for entries created before
+        # authorization history was introduced.
+        legacy = entry.get(
+            "authorization"
+        )
+
+        if isinstance(
+            legacy,
+            Mapping,
+        ):
+            authorizations.append(
+                dict(legacy)
+            )
+
+    evidence = (
+        _collect_eip3009_recovery_evidence(
+            authorizations,
+            read_authorization_state=(
+                read_authorization_state
+            ),
+            read_authorization_event=(
+                read_authorization_event
+            ),
+        )
+    )
+
+    aggregate = (
+        _aggregate_eip3009_recovery_decisions(
+            authorizations,
+            now_unix=now_unix,
+            evidence_by_nonce=evidence,
+        )
+    )
+
+    return {
+        "intent_id": logical_intent_id,
+        "state": state,
+        "authorization_count": len(
+            authorizations
+        ),
+        "safe_to_release": aggregate[
+            "safe_to_release"
+        ],
+        "requires_reconciliation": aggregate[
+            "requires_reconciliation"
+        ],
+        "decisions": aggregate[
+            "decisions"
+        ],
+        "evidence_by_nonce": evidence,
+    }
+
+
+def _resolve_eip3009_intent_if_safe(
+    logical_intent_id: str,
+    *,
+    now_unix: int,
+    read_authorization_state,
+    read_authorization_event,
+) -> bool:
+    """Release ambiguous economic exposure only after proven-safe recovery.
+
+    The operation is fail-closed against TOCTOU changes. Chain evidence
+    is collected outside the store lock, then the exact durable snapshot
+    is compared again inside the mutation transaction before deletion.
+    """
+
+    initial = get_persistent_payment_intent(
+        logical_intent_id
+    )
+
+    if not isinstance(
+        initial,
+        Mapping,
+    ):
+        return False
+
+    if initial.get("state") != "submission_unknown":
+        return False
+
+    # Never destroy an intent claim blindly. A claim may belong to a
+    # process that is still alive. Stale-claim recovery is a separate
+    # operation with its own safety proof.
+    claim_path = _intent_claim_path(
+        logical_intent_id
+    )
+
+    if claim_path.exists():
+        return False
+
+    snapshot = json.dumps(
+        initial,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+    )
+
+    preview = (
+        _preview_eip3009_intent_recovery(
+            logical_intent_id,
+            now_unix=now_unix,
+            read_authorization_state=(
+                read_authorization_state
+            ),
+            read_authorization_event=(
+                read_authorization_event
+            ),
+        )
+    )
+
+    if not preview.get(
+        "safe_to_release",
+        False,
+    ):
+        return False
+
+    if preview.get(
+        "requires_reconciliation",
+        True,
+    ):
+        return False
+
+    intent_key = _persistent_intent_key(
+        logical_intent_id
+    )
+
+    def mutate(
+        store: dict[str, Any],
+    ):
+        raw = store[
+            "entries"
+        ].get(intent_key)
+
+        if not isinstance(
+            raw,
+            Mapping,
+        ):
+            return False, False
+
+        if raw.get("state") != "submission_unknown":
+            return False, False
+
+        current_snapshot = json.dumps(
+            raw,
+            sort_keys=True,
+            separators=(",", ":"),
+            ensure_ascii=False,
+        )
+
+        # Anything changed after evidence was collected:
+        # new authorization, timestamp, state, reconciliation data, etc.
+        # Old evidence must not authorize deletion of newer state.
+        if current_snapshot != snapshot:
+            return False, False
+
+        # Re-check the claim immediately before economic release.
+        if _intent_claim_path(
+            logical_intent_id
+        ).exists():
+            return False, False
+
+        del store[
+            "entries"
+        ][intent_key]
+
+        return True, True
+
+    return _mutate_pending_store(
+        mutate
+    )
+
+
+def _make_payment_authorization_persistence_hook(
+    logical_intent_id: str,
+):
+    """Persist non-secret recovery metadata after payment creation.
+
+    The signed payment payload exists at this point, but only the
+    authorization envelope is persisted. The executable signature and
+    private key are never written to durable state.
+    """
+
+    def persist(context):
+        payment_payload = getattr(
+            context,
+            "payment_payload",
+            None,
+        )
+
+        selected = getattr(
+            context,
+            "selected_requirements",
+            None,
+        )
+
+        if payment_payload is None:
+            raise SettlementStoreError(
+                "after-payment hook received no payment payload"
+            )
+
+        if selected is None:
+            raise SettlementStoreError(
+                "after-payment hook received no selected requirements"
+            )
+
+        payload = getattr(
+            payment_payload,
+            "payload",
+            None,
+        )
+
+        if not isinstance(
+            payload,
+            Mapping,
+        ):
+            raise SettlementStoreError(
+                "after-payment hook received invalid payment payload"
+            )
+
+        saved = (
+            _record_payment_authorization_envelope(
+                logical_intent_id,
+                network=str(
+                    selected.network
+                ),
+                asset=str(
+                    selected.asset
+                ),
+                payload=payload,
+            )
+        )
+
+        if not saved:
+            raise SettlementStoreError(
+                "payment authorization envelope could not "
+                "be persisted before paid request"
+            )
+
+        return None
+
+    return persist
+
+
+def _record_payment_authorization_envelope(
+    logical_intent_id: str,
+    *,
+    network: str,
+    asset: str,
+    payload: Mapping[str, Any],
+) -> bool:
+    """Persist non-secret authorization data for crash recovery.
+
+    The executable payment signature is deliberately never persisted.
+    """
+    intent_key = _persistent_intent_key(
+        logical_intent_id
+    )
+
+    authorization = payload.get(
+        "authorization"
+    )
+
+    if not isinstance(
+        authorization,
+        Mapping,
+    ):
+        raise SettlementStoreError(
+            "payment authorization payload is missing"
+        )
+
+    required_fields = (
+        "from",
+        "to",
+        "value",
+        "validAfter",
+        "validBefore",
+        "nonce",
+    )
+
+    envelope: dict[str, str] = {}
+
+    for field in required_fields:
+        value = authorization.get(
+            field
+        )
+
+        if value is None:
+            raise SettlementStoreError(
+                "payment authorization is missing "
+                f"{field}"
+            )
+
+        envelope[field] = str(
+            value
+        )
+
+    envelope["network"] = str(
+        network
+    )
+    envelope["asset"] = str(
+        asset
+    )
+
+    now = datetime.now(
+        timezone.utc
+    ).isoformat()
+
+    def mutate(
+        store: dict[str, Any],
+    ):
+        raw = store[
+            "entries"
+        ].get(intent_key)
+
+        if not isinstance(
+            raw,
+            Mapping,
+        ):
+            return False, False
+
+        if raw.get("state") != "submission_unknown":
+            return False, False
+
+        entry = dict(raw)
+
+        history_raw = entry.get(
+            "authorizations"
+        )
+
+        if history_raw is None:
+            history = []
+
+            legacy = entry.get(
+                "authorization"
+            )
+
+            if isinstance(
+                legacy,
+                Mapping,
+            ):
+                history.append(
+                    dict(legacy)
+                )
+
+        elif isinstance(
+            history_raw,
+            list,
+        ):
+            history = [
+                dict(item)
+                if isinstance(item, Mapping)
+                else item
+                for item in history_raw
+            ]
+
+        else:
+            raise SettlementStoreError(
+                "payment authorization history is invalid"
+            )
+
+        nonce = envelope[
+            "nonce"
+        ]
+
+        for existing in history:
+            if not isinstance(
+                existing,
+                Mapping,
+            ):
+                raise SettlementStoreError(
+                    "payment authorization history "
+                    "contains invalid entry"
+                )
+
+            if str(
+                existing.get(
+                    "nonce",
+                    "",
+                )
+            ) != nonce:
+                continue
+
+            normalized_existing = {
+                str(key): str(value)
+                for key, value in existing.items()
+            }
+
+            if normalized_existing != envelope:
+                raise SettlementStoreError(
+                    "conflicting payment authorization "
+                    "envelope for existing nonce"
+                )
+
+            # Idempotent replay of the exact same envelope.
+            entry[
+                "authorization"
+            ] = envelope
+
+            entry[
+                "authorizations"
+            ] = history
+
+            store[
+                "entries"
+            ][intent_key] = entry
+
+            return True, False
+
+        history.append(
+            envelope
+        )
+
+        entry[
+            "authorizations"
+        ] = history
+
+        # Backwards-compatible alias for callers that need
+        # the most recently created authorization.
+        entry[
+            "authorization"
+        ] = envelope
+
+        entry[
+            "updated_at"
+        ] = now
+
+        store[
+            "entries"
+        ][intent_key] = entry
+
+        return True, True
+
+    return _mutate_pending_store(
+        mutate
+    )
+
+
+def _release_submission_unknown_after_terminal_failure(
+    logical_intent_id: str,
+) -> bool:
+    """Release exposure only after an explicit terminal settlement failure."""
+    intent_key = _persistent_intent_key(
+        logical_intent_id
+    )
+
+    def mutate(
+        store: dict[str, Any],
+    ):
+        raw = store[
+            "entries"
+        ].get(intent_key)
+
+        if not isinstance(
+            raw,
+            Mapping,
+        ):
+            return False, False
+
+        if raw.get("state") != "submission_unknown":
+            return False, False
+
+        del store[
+            "entries"
+        ][intent_key]
+
+        return True, True
+
+    return _mutate_pending_store(
+        mutate
+    )
+
+
+def _release_aggregate_budget_reservation(
+    logical_intent_id: str,
+) -> bool:
+    """Release only a still-unbroadcast reservation."""
+
+    intent_key = _persistent_intent_key(
+        logical_intent_id
+    )
+
+    def mutate(
+        store: dict[str, Any],
+    ):
+        raw = store[
+            "entries"
+        ].get(intent_key)
+
+        if not isinstance(
+            raw,
+            Mapping,
+        ):
+            return False, False
+
+        if raw.get("state") != "reserved":
+            return False, False
+
+        del store[
+            "entries"
+        ][intent_key]
+
+        return True, True
+
+    return _mutate_pending_store(
+        mutate
+    )
+
+
+def _record_pending_settlement(
+    resource: str,
+    requirement: Any,
+    transaction: str,
+    network: str = BASE_SEPOLIA,
+    *,
+    intent_id: str | None = None,
+    agent_id: str | None = None,
+    session_id: str | None = None,
+) -> dict[str, Any]:
+    logical_intent_id = _resolve_payment_intent_id(
+        intent_id,
+        resource,
+        requirement,
+    )
+    intent_key = _persistent_intent_key(logical_intent_id)
+
+    normalized_agent_id = None
+
+    if agent_id is not None:
+        from qruntime.spend import (
+            _normalize_agent_id,
+        )
+
+        normalized_agent_id = (
+            _normalize_agent_id(
+                agent_id
+            )
+        )
+
+    normalized_session_id = None
+
+    if session_id is not None:
+        from qruntime.spend import (
+            _normalize_session_id,
+        )
+
+        normalized_session_id = (
+            _normalize_session_id(
+                session_id
+            )
+        )
+
+    fingerprint = requirement.fingerprint()
+    now = datetime.now(timezone.utc).isoformat()
+
+    entry = {
+        "intent_id": logical_intent_id,
+        "intent_key": intent_key,
+        "resource": resource,
+        "agent_id": normalized_agent_id,
+        "session_id": normalized_session_id,
+        "quote_fingerprint": fingerprint,
+        "requirement": requirement.canonical_dict(),
+        "transaction": transaction,
+        "network": network,
+        "state": "pending",
+        "first_seen_at": now,
+        "updated_at": now,
+    }
+
+    def mutate(store: dict[str, Any]):
+        pending_entry = dict(entry)
+
+        previous = store[
+            "entries"
+        ].get(intent_key)
+
+        if (
+            isinstance(
+                previous,
+                Mapping,
+            )
+            and previous.get("state")
+            == "reserved"
+            and isinstance(
+                previous.get("reservation"),
+                Mapping,
+            )
+        ):
+            pending_entry[
+                "reservation"
+            ] = dict(
+                previous["reservation"]
+            )
+
+            previous_agent_id = (
+                previous.get("agent_id")
+            )
+
+            if (
+                previous_agent_id is not None
+                and normalized_agent_id is not None
+                and previous_agent_id
+                != normalized_agent_id
+            ):
+                raise SettlementStoreError(
+                    "reserved payment agent identity "
+                    "does not match settlement agent"
+                )
+
+            if previous_agent_id is not None:
+                pending_entry[
+                    "agent_id"
+                ] = previous_agent_id
+
+            previous_session_id = (
+                previous.get("session_id")
+            )
+
+            if (
+                previous_session_id is not None
+                and normalized_session_id is not None
+                and previous_session_id
+                != normalized_session_id
+            ):
+                raise SettlementStoreError(
+                    "reserved payment session identity "
+                    "does not match settlement session"
+                )
+
+            if previous_session_id is not None:
+                pending_entry[
+                    "session_id"
+                ] = previous_session_id
+
+        store[
+            "entries"
+        ][intent_key] = pending_entry
+
+        return pending_entry, True
+
+    return _mutate_pending_store(mutate)
+
+
+def _assert_no_persistent_payment_conflict(
+    resource: str,
+    requirement: Any,
+    *,
+    intent_id: str | None = None,
+) -> None:
+    logical_intent_id = _resolve_payment_intent_id(
+        intent_id,
+        resource,
+        requirement,
+    )
+
+    intent_key = _persistent_intent_key(
+        logical_intent_id
+    )
+
+    def inspect(
+        store: Mapping[str, Any],
+    ) -> tuple[None, bool]:
+        entry = store[
+            "entries"
+        ].get(
+            intent_key
+        )
+
+        if not isinstance(
+            entry,
+            Mapping,
+        ):
+            return None, False
+
+        stored_resource = str(
+            entry.get(
+                "resource",
+                "",
+            )
+        )
+
+        if (
+            stored_resource
+            and stored_resource
+            != resource
+        ):
+            raise IntentResourceMismatchError(
+                "preflight refused payment: intent_id is already bound "
+                "to a different resource"
+            )
+
+        state = str(
+            entry.get(
+                "state",
+                "",
+            )
+        )
+
+        if state == "reserved":
+            raise IntentInFlightError(
+                "preflight refused payment: durable budget "
+                f"reservation exists for intent {logical_intent_id}; "
+                "reservation must be explicitly released or "
+                "advanced before retry"
+            )
+
+        if state == "submission_unknown":
+            raise IntentInFlightError(
+                "preflight refused payment: submission outcome "
+                "is unknown for intent "
+                f"{logical_intent_id}; economic exposure must "
+                "be reconciled before retry"
+            )
+
+        if state == "pending":
+            raise SettlementPendingError(
+                "preflight refused payment: unresolved prior settlement "
+                f"{entry.get('transaction')} exists for intent "
+                f"{logical_intent_id}; reconcile before retry",
+                transaction=(
+                    str(
+                        entry.get(
+                            "transaction"
+                        )
+                    )
+                    if entry.get(
+                        "transaction"
+                    )
+                    else None
+                ),
+                network=(
+                    str(
+                        entry.get(
+                            "network"
+                        )
+                    )
+                    if entry.get(
+                        "network"
+                    )
+                    else None
+                ),
+            )
+
+        if state == "resolved_confirmed":
+            raise DuplicateIntentError(
+                "preflight refused payment: prior settlement for intent "
+                f"{logical_intent_id} is already confirmed; "
+                "refusing duplicate economic effect"
+            )
+
+        return None, False
+
+    _mutate_pending_store(
+        inspect
+    )
+
+
+
+
+
+def _record_confirmed_settlement(
+    resource: str,
+    requirement: Any,
+    transaction: str,
+    network: str = BASE_SEPOLIA,
+    *,
+    intent_id: str | None = None,
+    agent_id: str | None = None,
+    session_id: str | None = None,
+) -> None:
+    """Durably tombstone a successful economic effect.
+
+    Write pending first so a crash between writes remains fail-closed.
+    """
+    _record_pending_settlement(
+        resource,
+        requirement,
+        transaction,
+        network,
+        intent_id=intent_id,
+        agent_id=agent_id,
+        session_id=session_id,
+    )
+
+    if not _update_persistent_reconciliation(
+        transaction,
+        "confirmed",
+    ):
+        raise SettlementStoreError(
+            "successful settlement could not be marked confirmed "
+            "in persistent state"
+        )
+
+
+def _update_persistent_reconciliation(
+    transaction: str,
+    outcome: str,
+) -> bool:
+    if outcome not in {"confirmed", "failed"}:
+        return False
+
+    now = datetime.now(timezone.utc).isoformat()
+
+    def mutate(store: dict[str, Any]):
+        changed = False
+
+        for key, raw_entry in list(store["entries"].items()):
+            if not isinstance(raw_entry, Mapping):
+                continue
+
+            if (
+                str(raw_entry.get("transaction", "")).lower()
+                != transaction.lower()
+            ):
+                continue
+
+            entry = dict(raw_entry)
+            entry["state"] = (
+                "resolved_confirmed"
+                if outcome == "confirmed"
+                else "resolved_failed"
+            )
+            entry["reconciliation_outcome"] = outcome
+            entry["updated_at"] = now
+
+            store["entries"][key] = entry
+            changed = True
+
+        return changed, changed
+
+    return _mutate_pending_store(mutate)
+
+
+def _fetch_base_sepolia_transaction(
+    transaction: str,
+    timeout: float,
+) -> dict[str, Any] | None:
+    """Read one Base-Sepolia transaction from Blockscout.
+
+    None means "not currently found", never terminal failure.
+    """
+    from urllib.error import HTTPError, URLError
+    from urllib.request import Request, urlopen
+
+    endpoint = (
+        "https://base-sepolia.blockscout.com/api/v2/transactions/"
+        f"{transaction}"
+    )
+    request = Request(
+        endpoint,
+        headers={
+            "Accept": "application/json",
+            "User-Agent": "q-runtime/0.6",
+        },
+    )
+
+    try:
+        with urlopen(request, timeout=timeout) as response:
+            raw = json.loads(response.read().decode("utf-8"))
+    except HTTPError as exc:
+        if exc.code == 404:
+            return None
+        raise ReconciliationError(
+            f"Blockscout reconciliation HTTP {exc.code}"
+        ) from exc
+    except (URLError, TimeoutError) as exc:
+        raise ReconciliationError(
+            f"Blockscout reconciliation unavailable: {exc}"
+        ) from exc
+
+    if not isinstance(raw, Mapping):
+        raise ReconciliationError(
+            "Blockscout reconciliation returned a non-object response"
+        )
+
+    return dict(raw)
+
+
+def reconcile_testnet_transaction(
+    transaction: str,
+    *,
+    out: str | Path,
+    timeout: float = 15.0,
+) -> dict[str, Any]:
+    """Reconcile an already-broadcast Base-Sepolia transaction.
+
+    This function is read-only. It never signs, broadcasts, or retries payment.
+    """
+    import re
+
+    tx = transaction.strip()
+
+    if not re.fullmatch(r"0x[a-fA-F0-9]{64}", tx):
+        raise ValueError(
+            "transaction must be a 0x-prefixed 32-byte hash"
+        )
+
+    if timeout <= 0:
+        raise ValueError("timeout must be positive")
+
+    info = _fetch_base_sepolia_transaction(tx, timeout)
+
+    if info is None:
+        outcome = "pending"
+        reason = (
+            "transaction is not currently visible; "
+            "absence is not treated as terminal"
+        )
+        status = None
+    else:
+        status = str(info.get("status", "")).lower()
+
+        if status == "ok":
+            outcome = "confirmed"
+            reason = "transaction confirmed successfully on Base Sepolia"
+        elif status == "error":
+            outcome = "failed"
+            reason = "transaction confirmed with failure on Base Sepolia"
+        else:
+            outcome = "pending"
+            reason = (
+                "transaction exists but does not yet have a terminal status"
+            )
+
+    persistent_state_updated = _update_persistent_reconciliation(
+        tx,
+        outcome,
+    )
+
+    report = {
+        "format": "qruntime-x402-reconciliation-v1",
+        "persistent_state_updated": persistent_state_updated,
+        "checked_at": datetime.now(timezone.utc).isoformat(),
+        "network": BASE_SEPOLIA,
+        "transaction": tx,
+        "outcome": outcome,
+        "terminal": outcome in {"confirmed", "failed"},
+        "reason": reason,
+        "source": "base-sepolia.blockscout.com",
+        "chain": {
+            "status": status,
+            "block_number": None if info is None else info.get("block_number"),
+            "confirmations": None if info is None else info.get("confirmations"),
+            "method": None if info is None else info.get("method"),
+        },
+    }
+
+    destination = Path(out)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_text(
+        json.dumps(report, indent=2, ensure_ascii=False),
+        encoding="utf-8",
+    )
+
+    return report
+
+
+def run_local_testnet_payment(
+    url: str,
+    *,
+    max_amount_atomic: int,
+    out: str | Path,
+    intent_id: str | None = None,
+    key_env: str = DEFAULT_KEY_ENV,
+    timeout: float = 30.0,
+    policy: Policy | None = None,
+    budget: Any | None = None,
+    agent_id: str | None = None,
+    session_id: str | None = None,
+) -> dict[str, Any]:
+    """Run one controlled Base-Sepolia x402 payment against localhost.
+
+    Safety properties:
+    - only http(s)://127.0.0.1 or localhost is accepted;
+    - only exact / eip155:84532 is accepted;
+    - preflight amount must be <= max_amount_atomic;
+    - private key is read from an environment variable and never serialized.
+    """
+    parsed_url = urlparse(url)
+    if parsed_url.scheme not in {"http", "https"} or parsed_url.hostname not in {"127.0.0.1", "localhost"}:
+        raise ValueError("live-testnet is localhost-only; use the controlled Q Runtime demo server")
+    if max_amount_atomic <= 0:
+        raise ValueError("--max-amount-atomic must be positive")
+
+    try:
+        capture = capture_payment_required(url, timeout=min(timeout, 15.0))
+    except X402CaptureError as exc:
+        raise RuntimeError(f"preflight 402 capture failed: {exc}") from exc
+
+    candidates = [
+        req for req in capture.payment_required.accepts
+        if req.scheme == "exact" and req.network == BASE_SEPOLIA and req.amount_atomic <= max_amount_atomic
+    ]
+    if not candidates:
+        offered = [
+            {"scheme": r.scheme, "network": r.network, "amount": r.amount_atomic}
+            for r in capture.payment_required.accepts
+        ]
+        raise PaymentRequirementRejectedError(
+            f"preflight refused payment: no exact/{BASE_SEPOLIA} requirement within cap "
+            f"{max_amount_atomic}; offered={offered}"
+        )
+    selected = candidates[0]
+    if capture.payment_required.resource_url != url:
+        raise PaymentRequirementMismatchError(
+            "preflight refused payment: PAYMENT-REQUIRED resource.url does not exactly match controlled request URL"
+        )
+
+    if policy is not None:
+        decision = evaluate_policy(
+            policy,
+            amount_atomic=selected.amount_atomic,
+            origin=url,
+            asset=selected.asset,
+        )
+
+        if not decision.allowed:
+            raise PolicyDeniedError(
+                decision
+            )
+
+    logical_intent_id = _resolve_payment_intent_id(
+        intent_id,
+        url,
+        selected,
+    )
+    _assert_no_persistent_payment_conflict(
+        url,
+        selected,
+        intent_id=logical_intent_id,
+    )
+
+    intent_claim = _acquire_payment_intent_claim(
+        logical_intent_id,
+        url,
+    )
+
+    budget_reserved = False
+
+    if budget is not None:
+        try:
+            from qruntime.budget import (
+                BudgetSet,
+            )
+
+            if isinstance(
+                budget,
+                BudgetSet,
+            ):
+                budget_decision = (
+                    _reserve_budget_set(
+                        logical_intent_id,
+                        url,
+                        selected,
+                        budget,
+                        agent_id=agent_id,
+                        session_id=session_id,
+                    )
+                )
+            else:
+                budget_decision = (
+                    _reserve_aggregate_budget(
+                        logical_intent_id,
+                        url,
+                        selected,
+                        budget,
+                        agent_id=agent_id,
+                        session_id=session_id,
+                    )
+                )
+        except Exception:
+            _release_payment_intent_claim(
+                intent_claim
+            )
+            raise
+
+        if not budget_decision.allowed:
+            _release_payment_intent_claim(
+                intent_claim
+            )
+
+            from qruntime.exceptions import (
+                BudgetDeniedError,
+            )
+
+            denied_decision = getattr(
+                budget_decision,
+                "first_denied",
+                None,
+            )
+
+            if denied_decision is None:
+                denied_decision = (
+                    budget_decision
+                )
+
+            raise BudgetDeniedError(
+                denied_decision
+            )
+
+        budget_reserved = True
+
+    try:
+        private_key = os.environ.get(key_env, "").strip()
+        if not private_key:
+            raise RuntimeError(
+                f"missing testnet private key environment variable: {key_env}"
+            )
+
+        try:
+            from eth_account import Account
+            from x402 import AbortResult, x402ClientSync, max_amount
+            from x402.http.clients import x402_requests
+            from x402.mechanisms.evm import EthAccountSigner
+            from x402.mechanisms.evm.exact.register import register_exact_evm_client
+        except ImportError as exc:  # pragma: no cover
+            raise RuntimeError(
+                "official x402 client dependencies are missing. Install with: "
+                'python -m pip install -e ".[official-x402]"'
+            ) from exc
+
+        account = Account.from_key(private_key)
+        client = x402ClientSync()
+        client.register_policy(max_amount(max_amount_atomic))
+        client.on_before_payment_creation(
+            _make_live_quote_binding_hook(selected, AbortResult)
+        )
+        client.on_after_payment_creation(
+            _make_payment_authorization_persistence_hook(
+                logical_intent_id
+            )
+        )
+        register_exact_evm_client(
+            client,
+            EthAccountSigner(account),
+        )
+
+    except Exception:
+        if budget_reserved:
+            released = (
+                _release_aggregate_budget_reservation(
+                    logical_intent_id
+                )
+            )
+
+            if not released:
+                _release_payment_intent_claim(
+                    intent_claim
+                )
+
+                raise SettlementStoreError(
+                    "pre-broadcast failure could not "
+                    "release durable budget reservation; "
+                    "refusing to free budget silently"
+                )
+
+        _release_payment_intent_claim(
+            intent_claim
+        )
+        raise
+
+    try:
+        submission_marked = (
+            _mark_payment_submission_unknown(
+                logical_intent_id,
+                url,
+                selected,
+                agent_id=agent_id,
+                session_id=session_id,
+            )
+        )
+    except Exception:
+        if budget_reserved:
+            released = (
+                _release_aggregate_budget_reservation(
+                    logical_intent_id
+                )
+            )
+
+            if not released:
+                _release_payment_intent_claim(
+                    intent_claim
+                )
+
+                raise SettlementStoreError(
+                    "pre-handoff failure could not release "
+                    "durable budget reservation"
+                )
+
+        _release_payment_intent_claim(
+            intent_claim
+        )
+        raise
+
+    if not submission_marked:
+        if budget_reserved:
+            _release_aggregate_budget_reservation(
+                logical_intent_id
+            )
+
+        _release_payment_intent_claim(
+            intent_claim
+        )
+
+        raise SettlementStoreError(
+            "payment submission state could not be "
+            "persisted before network handoff"
+        )
+
+    started = datetime.now(timezone.utc).isoformat()
+    with x402_requests(client) as session:
+        response = session.get(url, timeout=timeout)
+    finished = datetime.now(timezone.utc).isoformat()
+
+    settlement_header = _header_ci(response.headers, "PAYMENT-RESPONSE", "X-PAYMENT-RESPONSE")
+    if not settlement_header:
+        raise SettlementReceiptError(
+            f"paid request returned HTTP {response.status_code} without PAYMENT-RESPONSE settlement receipt"
+        )
+    settlement = parse_settlement_response(settlement_header)
+
+    if settlement.reconciliation_required:
+        _record_pending_settlement(
+            url,
+            selected,
+            settlement.transaction,
+            settlement.network,
+            intent_id=logical_intent_id,
+            agent_id=agent_id,
+            session_id=session_id,
+        )
+        raise SettlementPendingError(
+            "settlement pending after broadcast; transaction "
+            f"{settlement.transaction} was persisted and must be reconciled "
+            "before retry",
+            transaction=settlement.transaction,
+            network=settlement.network,
+        )
+
+    if settlement.success:
+        if settlement.network != BASE_SEPOLIA:
+            raise SettlementReceiptError(
+                f"unexpected settlement network: {settlement.network}"
+            )
+        if not settlement.transaction:
+            raise SettlementReceiptError(
+                "successful settlement did not return a transaction hash"
+            )
+
+        _record_confirmed_settlement(
+            url,
+            selected,
+            settlement.transaction,
+            settlement.network,
+            intent_id=logical_intent_id,
+            agent_id=agent_id,
+            session_id=session_id,
+        )
+        _release_payment_intent_claim(intent_claim)
+
+    if not settlement.success:
+        released = (
+            _release_submission_unknown_after_terminal_failure(
+                logical_intent_id
+            )
+        )
+
+        if not released:
+            raise SettlementStoreError(
+                "terminal settlement failure could not "
+                "release durable economic exposure"
+            )
+
+        _release_payment_intent_claim(
+            intent_claim
+        )
+
+        raise SettlementFailedError(
+            f"settlement failed: {settlement.error_reason or 'unknown'}",
+            reason=settlement.error_reason,
+        )
+
+    if response.status_code < 200 or response.status_code >= 300:
+        raise PaidResourceError(
+            f"paid request did not succeed: HTTP {response.status_code}",
+            status_code=response.status_code,
+            transaction=settlement.transaction or None,
+            network=settlement.network or None,
+        )
+
+    report = {
+        "format": "qruntime-x402-live-testnet-v1",
+        "started_at": started,
+        "finished_at": finished,
+        "safety": {
+            "localhost_only": True,
+            "network": BASE_SEPOLIA,
+            "scheme": "exact",
+            "max_amount_atomic": max_amount_atomic,
+            "private_key_recorded": False,
+        },
+        "payer": account.address,
+        "request_url": url,
+        "intent_id": logical_intent_id,
+        "preflight": {
+            "status": capture.status_code,
+            "resource": capture.payment_required.resource_url,
+            "quote_fingerprint": selected.fingerprint(),
+            "amount_atomic": selected.amount_atomic,
+            "asset": selected.asset,
+            "pay_to": selected.pay_to,
+        },
+        "paid_response": {
+            "http_status": response.status_code,
+            "body_preview": response.text[:2000],
+        },
+        "settlement": {
+            "success": settlement.success,
+            "transaction": settlement.transaction,
+            "network": settlement.network,
+            "payer": settlement.payer,
+            "amount_atomic": settlement.amount_atomic,
+        },
+    }
+    destination = Path(out)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_text(json.dumps(report, indent=2, ensure_ascii=False), encoding="utf-8")
+    return report