railgate 1.0.0__tar.gz

railgate-1.0.0/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 TextForAgents LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Third-party components are NOT vendored into this distribution. The x402
+Python SDK is a regular PyPI dependency (see pyproject.toml) licensed under
+the Apache License 2.0; its license text is reproduced in
+licenses/x402-Apache-2.0.txt for convenience. See THIRD-PARTY-NOTICES.md.

railgate-1.0.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: railgate
+Version: 1.0.0
+Summary: Rail-agnostic pre-signing payment policy gate with swappable settlement adapters (EVM/x402 + XRPL) — TextForAgents LLC
+Author: TextForAgents LLC
+License: MIT
+Project-URL: Homepage, https://textforagents.com/products/payment-gate-settlement-rails/
+Project-URL: Support, https://textforagents.com/products/payment-gate-settlement-rails/
+Keywords: x402,xrpl,agent-payments,policy-gate,settlement
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: x402[evm]<3,>=2.25
+Requires-Dist: xrpl-py<7,>=4
+Dynamic: license-file
+
+# railgate — payment gate settlement rails (P21)
+
+By **TextForAgents LLC** · Support: support@textforagents.com ·
+Product page: https://textforagents.com/products/payment-gate-settlement-rails/
+
+A pre-signing payment policy gate for agents that settles on more than one
+rail. One unmodified policy core (budgets, counterparty allowlists, velocity,
+intent, replay protection — every decision receipted, every refusal
+structured) drives swappable settlement adapters behind one interface:
+
+- **EVM / x402** — EIP-3009 `exact` scheme authorizations via a facilitator.
+- **XRPL** — Payments whose replay window closes at validation by protocol
+  sequence consumption; `LastLedgerSequence` is only the expiry ceiling.
+
+A rail oracle picks the rail at decide time against **your standing rail
+declaration** (pinned / cheapest / fastest finality / minimum replay
+exposure, with fee and finality caps). Rail choice is a policy decision and
+is receipted with the payment. If the settled fee disagrees with the quote
+that justified the choice, the outcome is flagged `QUOTE_MISMATCH`.
+
+**Operator-side only.** Settlement runs through *your* signer and *your*
+funds. This package never custodies funds or keys, and v1 has no hosted or
+multi-tenant mode. The adapters shipped here are test doubles encoding each
+rail's published settlement semantics; `railgate.live` adds a read-only
+live-testnet path (ServerInfo / AccountInfo) — it never signs or submits.
+
+## Install
+
+```bash
+pip install railgate-1.0.0-py3-none-any.whl   # or from the sdist
+```
+
+Dependencies: `x402[evm]` (>=2.25,<3, Apache-2.0) and `xrpl-py` — both are
+ordinary PyPI dependencies; no third-party code is vendored into this wheel.
+The vendored EXP-001 policy core *is* included (`policy_gate/`) and is
+byte-identical to the proven originals — verify after install:
+
+```bash
+cd $(python -c "import policy_gate,os;print(os.path.dirname(policy_gate.__file__))") && sha256sum -c MANIFEST.sha256
+```
+
+## Quickstart
+
+```python
+import time
+from policy_gate import PaymentPolicy, PolicyGate
+from railgate import RailGate, RailDeclaration
+from railgate.adapters import EvmX402Adapter, XrplTestnetAdapter
+
+clock = time.time
+adapters = {}
+for cls in (EvmX402Adapter, XrplTestnetAdapter):
+    a = cls(clock); adapters[a.rail] = a
+
+policy = PaymentPolicy.from_dict({
+    "per_call_cap_atomic": 1_000_000, "session_budget_atomic": 5_000_000,
+    "daily_budget_atomic": 20_000_000, "per_counterparty_cap_atomic": 10_000_000,
+    "allowed_networks": [a.network for a in adapters.values()],
+    "allowed_assets": [a.asset for a in adapters.values()],
+    "counterparty_allowlist": [a.pay_to for a in adapters.values()],
+    "max_payments_per_window": 30, "window_seconds": 60,
+    "replay_window_seconds": 300, "intent_required": True, "asset_decimals": 6,
+})
+gate = RailGate(PolicyGate(policy, "/tmp/spend.db", clock=clock), adapters)
+gate.declare_intent("buy weather data")
+out = gate.pay(amount_atomic=100_000,
+               resource_url="https://api.example.test/weather",
+               declaration=RailDeclaration(mode="cheapest"))
+print(out.status, out.rail, out.receipt)   # settled xrpl-testnet {...}
+
+# Live testnet read (read-only; no submission, no funds):
+from railgate import xrpl_server_info
+print(xrpl_server_info())
+```
+
+## Pricing
+
+The adapter package is **free** (distribution). The hosted policy + rails
+service is **$2 per agent / month flat** — no percentage of payment volume,
+ever; rail fees (e.g. XRPL ~$0.0002/tx) pass through at cost. First month
+free for the first 10 agents, once per operator. See the product page.
+
+## License
+
+MIT for this package's own code (see LICENSE). The x402 dependency is
+Apache-2.0 — see THIRD-PARTY-NOTICES.md.

railgate-1.0.0/README.md

@@ -0,0 +1,86 @@
+# railgate — payment gate settlement rails (P21)
+
+By **TextForAgents LLC** · Support: support@textforagents.com ·
+Product page: https://textforagents.com/products/payment-gate-settlement-rails/
+
+A pre-signing payment policy gate for agents that settles on more than one
+rail. One unmodified policy core (budgets, counterparty allowlists, velocity,
+intent, replay protection — every decision receipted, every refusal
+structured) drives swappable settlement adapters behind one interface:
+
+- **EVM / x402** — EIP-3009 `exact` scheme authorizations via a facilitator.
+- **XRPL** — Payments whose replay window closes at validation by protocol
+  sequence consumption; `LastLedgerSequence` is only the expiry ceiling.
+
+A rail oracle picks the rail at decide time against **your standing rail
+declaration** (pinned / cheapest / fastest finality / minimum replay
+exposure, with fee and finality caps). Rail choice is a policy decision and
+is receipted with the payment. If the settled fee disagrees with the quote
+that justified the choice, the outcome is flagged `QUOTE_MISMATCH`.
+
+**Operator-side only.** Settlement runs through *your* signer and *your*
+funds. This package never custodies funds or keys, and v1 has no hosted or
+multi-tenant mode. The adapters shipped here are test doubles encoding each
+rail's published settlement semantics; `railgate.live` adds a read-only
+live-testnet path (ServerInfo / AccountInfo) — it never signs or submits.
+
+## Install
+
+```bash
+pip install railgate-1.0.0-py3-none-any.whl   # or from the sdist
+```
+
+Dependencies: `x402[evm]` (>=2.25,<3, Apache-2.0) and `xrpl-py` — both are
+ordinary PyPI dependencies; no third-party code is vendored into this wheel.
+The vendored EXP-001 policy core *is* included (`policy_gate/`) and is
+byte-identical to the proven originals — verify after install:
+
+```bash
+cd $(python -c "import policy_gate,os;print(os.path.dirname(policy_gate.__file__))") && sha256sum -c MANIFEST.sha256
+```
+
+## Quickstart
+
+```python
+import time
+from policy_gate import PaymentPolicy, PolicyGate
+from railgate import RailGate, RailDeclaration
+from railgate.adapters import EvmX402Adapter, XrplTestnetAdapter
+
+clock = time.time
+adapters = {}
+for cls in (EvmX402Adapter, XrplTestnetAdapter):
+    a = cls(clock); adapters[a.rail] = a
+
+policy = PaymentPolicy.from_dict({
+    "per_call_cap_atomic": 1_000_000, "session_budget_atomic": 5_000_000,
+    "daily_budget_atomic": 20_000_000, "per_counterparty_cap_atomic": 10_000_000,
+    "allowed_networks": [a.network for a in adapters.values()],
+    "allowed_assets": [a.asset for a in adapters.values()],
+    "counterparty_allowlist": [a.pay_to for a in adapters.values()],
+    "max_payments_per_window": 30, "window_seconds": 60,
+    "replay_window_seconds": 300, "intent_required": True, "asset_decimals": 6,
+})
+gate = RailGate(PolicyGate(policy, "/tmp/spend.db", clock=clock), adapters)
+gate.declare_intent("buy weather data")
+out = gate.pay(amount_atomic=100_000,
+               resource_url="https://api.example.test/weather",
+               declaration=RailDeclaration(mode="cheapest"))
+print(out.status, out.rail, out.receipt)   # settled xrpl-testnet {...}
+
+# Live testnet read (read-only; no submission, no funds):
+from railgate import xrpl_server_info
+print(xrpl_server_info())
+```
+
+## Pricing
+
+The adapter package is **free** (distribution). The hosted policy + rails
+service is **$2 per agent / month flat** — no percentage of payment volume,
+ever; rail fees (e.g. XRPL ~$0.0002/tx) pass through at cost. First month
+free for the first 10 agents, once per operator. See the product page.
+
+## License
+
+MIT for this package's own code (see LICENSE). The x402 dependency is
+Apache-2.0 — see THIRD-PARTY-NOTICES.md.

railgate-1.0.0/policy_gate/MANIFEST.sha256

@@ -0,0 +1,3 @@
+bdbff3b6c8a22b1c8d06e50a5043ae9cef9bc17f202085e3ae5d909fe9851dfb  policy.py
+6acc91164c89ae08003ba53fb77ca21c45439ca2fa68e3344c8c402b8ffd2298  store.py
+bdaec65f0a1cb3174e16ab6025a1f67c177b41102c3e1384dbe892059762185f  gate.py

railgate-1.0.0/policy_gate/__init__.py

@@ -0,0 +1,7 @@
+"""Pre-signing payment policy gate for x402 buyer agents (EXP-001)."""
+from .factory import GatedClient, create_gated_client
+from .gate import PolicyGate, PolicyRefusal
+from .policy import PaymentPolicy, PolicyError
+
+__all__ = ["GatedClient", "create_gated_client", "PolicyGate", "PolicyRefusal",
+           "PaymentPolicy", "PolicyError"]

railgate-1.0.0/policy_gate/factory.py

@@ -0,0 +1,80 @@
+"""Mandatory-construction factory for gated x402 clients (EXP-001).
+
+AgentBadge's evidence line is the spec: "a cap you can forget is a cap you
+will forget." So there is no code path here that builds a paying client
+without a policy — create_gated_client(policy=None) raises TypeError with
+the same shape AgentBadge used: refusing to create an uncapped paying
+client. The vendored SDK's own SpendControls are ALSO set from the same
+policy (defense in depth): the SDK filters non-allowlisted assets and
+over-cap accepts during selection, and this gate enforces the stateful
+layer (budgets, counterparty, velocity, intent, replay) at the
+pre-signing hook.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from x402 import x402Client
+from x402.mechanisms.evm.exact import ExactEvmScheme
+from x402.schemas import PaymentAbortedError
+
+from .gate import PolicyGate, PolicyRefusal
+from .policy import PaymentPolicy, usd_money_string
+
+
+@dataclass
+class GatedClient:
+    client: x402Client
+    gate: PolicyGate
+    policy: PaymentPolicy
+
+    async def pay(self, payment_required, *, intent: str | None = None,
+                  expected_pay_to: str | None = None,
+                  expected_resource: str | None = None):
+        """Create a payment payload through the gate.
+
+        Declares intent first when given. On policy denial raises
+        PolicyRefusal with the structured refusal dict (never a bare
+        exception string to parse).
+        """
+        if intent is not None:
+            self.gate.declare_intent(intent, expected_pay_to=expected_pay_to,
+                                     expected_resource=expected_resource)
+        self.gate.last_refusal = None
+        try:
+            return await self.client.create_payment_payload(payment_required)
+        except PaymentAbortedError:
+            if self.gate.last_refusal is not None:
+                raise PolicyRefusal(self.gate.last_refusal) from None
+            raise
+
+
+def create_gated_client(policy: PaymentPolicy | None, signer, *,
+                        store_path: str, audit_path: str | None = None,
+                        clock=None) -> GatedClient:
+    if policy is None:
+        raise TypeError("PaymentPolicy required — refusing to create an uncapped paying client")
+    if signer is None:
+        raise TypeError("signer required — refusing to create a paying client without a signer")
+    gate = PolicyGate(policy, store_path, audit_path=audit_path, clock=clock)
+    client = x402Client()
+    for network in policy.allowed_networks:
+        if ":*" in network:
+            raise ValueError("factory needs concrete networks to register schemes; "
+                             "wildcard network patterns are enforced by the gate but "
+                             "cannot be registered — list networks explicitly")
+        client.register(network, ExactEvmScheme(signer=signer))
+    allowed_assets = [
+        {"network": network, "asset": asset,
+         "max_amount_per_payment": str(policy.per_call_cap_atomic)}
+        for network in policy.allowed_networks
+        for asset in policy.allowed_assets
+    ]
+    client.set_spend_controls({
+        "max_amount_per_payment": usd_money_string(policy.per_call_cap_atomic, policy.asset_decimals),
+        "allowed_assets": allowed_assets,
+    })
+    client.on_before_payment_creation(gate.before_hook)
+    client.on_after_payment_creation(gate.after_hook)
+    client.on_payment_creation_failure(gate.failure_hook)
+    return GatedClient(client=client, gate=gate, policy=policy)

railgate-1.0.0/policy_gate/gate.py

@@ -0,0 +1,273 @@
+"""PolicyGate — the pre-signing enforcement layer (EXP-001).
+
+Sits on the REAL x402 client's payment-creation hooks:
+
+  before-hook  -> evaluate policy; on deny return AbortResult (the client
+                  raises PaymentAbortedError and the scheme/signer is NEVER
+                  invoked, so no signature exists); on allow, atomically
+                  reserve budget in the SpendStore.
+  after-hook   -> commit the reservation (a signature now exists).
+  failure-hook -> release the reservation (creation failed downstream).
+
+Every decision (allow and deny) is appended to an audit JSONL. Every denial
+builds a structured refusal {code, detail, amount, pay_to, network,
+suggested_action, ...} — MEMO-003 Q3: the caller never parses prose.
+
+Refusal actions:
+  do_not_retry           — same request can never pass (allowlist, mismatch)
+  escalate_to_operator   — a human/policy change is the way out (budgets, caps)
+  degrade_or_skip        — try a cheaper resource or proceed without it
+  retry_after_window     — velocity / replay window; wait, then retry
+  declare_intent_and_retry — intent was missing; declare it and retry
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import threading
+import time
+import uuid
+from collections import defaultdict
+from datetime import datetime, timezone
+
+from x402.schemas import AbortResult
+
+from .policy import PaymentPolicy, parse_atomic_amount
+from .store import SpendStore, StoreError
+
+_ACTION = {
+    "PER_CALL_CAP": "degrade_or_skip",
+    "SESSION_BUDGET": "escalate_to_operator",
+    "DAILY_BUDGET": "escalate_to_operator",
+    "COUNTERPARTY_CAP": "escalate_to_operator",
+    "COUNTERPARTY_NOT_ALLOWED": "escalate_to_operator",
+    "NETWORK_NOT_ALLOWED": "do_not_retry",
+    "ASSET_NOT_ALLOWED": "do_not_retry",
+    "VELOCITY": "retry_after_window",
+    "REPLAY_DUPLICATE": "retry_after_window",
+    "INTENT_REQUIRED": "declare_intent_and_retry",
+    "INTENT_MISMATCH": "do_not_retry",
+    "MALFORMED_AMOUNT": "do_not_retry",
+    "UNSUPPORTED_VERSION": "do_not_retry",
+    "INTERNAL_FAIL_CLOSED": "escalate_to_operator",
+}
+
+
+class PolicyRefusal(Exception):
+    """Structured refusal raised by GatedClient.pay(). Carries the refusal dict."""
+
+    def __init__(self, refusal: dict):
+        self.refusal = refusal
+        super().__init__(f"{refusal.get('code')}: {refusal.get('detail')}")
+
+
+class PolicyGate:
+    def __init__(self, policy: PaymentPolicy, store_path: str,
+                 audit_path: str | None = None, clock=None):
+        if policy is None:
+            raise TypeError("PaymentPolicy required — refusing to create an uncapped paying client")
+        self.policy = policy
+        self._clock = clock or time.time
+        self.session_id = uuid.uuid4().hex
+        self.store = SpendStore(store_path, self.session_id)
+        self._audit_path = audit_path
+        self._audit_lock = threading.Lock()
+        self._pending: dict[str, list[int]] = defaultdict(list)
+        self._pending_lock = threading.Lock()
+        # Intent state: a declaration authorizes payments that match it.
+        # Each declare_intent() bumps the declaration counter; the counter is
+        # part of the payment fingerprint, so re-declaring intent is what
+        # makes a deliberate repeat purchase distinguishable from a loop
+        # replaying one authorization forever (CARD-003 loss mode #1).
+        self._intent_text: str | None = None
+        self._intent_hash: str | None = None
+        self._intent_pay_to: str | None = None
+        self._intent_resource: str | None = None
+        self._intent_decl_id = 0
+        self.last_refusal: dict | None = None
+
+    # ---------------------------------------------------------------- intent
+    def declare_intent(self, text: str, *, expected_pay_to: str | None = None,
+                       expected_resource: str | None = None) -> int:
+        """Declare what the next payment(s) are FOR. Returns declaration id.
+
+        expected_pay_to / expected_resource bind the intent: a payment whose
+        counterparty or resource differs is refused INTENT_MISMATCH — the
+        signature is bound to the declared purpose before it exists.
+        """
+        if not isinstance(text, str) or not text.strip():
+            raise ValueError("intent text must be a non-empty string")
+        self._intent_text = text
+        self._intent_hash = hashlib.sha256(text.encode("utf-8")).hexdigest()
+        self._intent_pay_to = expected_pay_to.lower() if expected_pay_to else None
+        self._intent_resource = expected_resource
+        self._intent_decl_id += 1
+        return self._intent_decl_id
+
+    # ---------------------------------------------------------------- helpers
+    def _now(self) -> float:
+        return float(self._clock())
+
+    @staticmethod
+    def _day_start(now: float) -> float:
+        dt = datetime.fromtimestamp(now, tz=timezone.utc)
+        return dt.replace(hour=0, minute=0, second=0, microsecond=0).timestamp()
+
+    @staticmethod
+    def _fingerprint(*, intent_hash: str | None, decl_id: int, network: str,
+                     asset: str, pay_to: str, amount: int, resource_url: str | None) -> str:
+        raw = "|".join([intent_hash or "", str(decl_id), network, asset.lower(),
+                        pay_to.lower(), str(amount), resource_url or ""])
+        return hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+    def _audit(self, record: dict) -> None:
+        if not self._audit_path:
+            return
+        record = {"ts": self._now(), "session_id": self.session_id, **record}
+        line = json.dumps(record, sort_keys=True)
+        with self._audit_lock:
+            with open(self._audit_path, "a", encoding="utf-8") as f:
+                f.write(line + "\n")
+
+    def _deny(self, code: str, detail: str, *, amount=None, pay_to=None,
+              network=None, resource_url=None) -> AbortResult:
+        refusal = {
+            "code": code,
+            "detail": detail,
+            "suggested_action": _ACTION[code],
+            "amount_atomic": amount,
+            "pay_to": pay_to,
+            "network": network,
+            "resource_url": resource_url,
+            "session_id": self.session_id,
+        }
+        if code in ("VELOCITY", "REPLAY_DUPLICATE"):
+            refusal["retry_after_seconds"] = (
+                self.policy.window_seconds if code == "VELOCITY"
+                else self.policy.replay_window_seconds)
+        self.last_refusal = refusal
+        self._audit({"decision": "deny", **refusal})
+        return AbortResult(reason="policy_refusal:" + json.dumps(refusal, sort_keys=True))
+
+    # ---------------------------------------------------------------- hooks
+    def before_hook(self, ctx) -> AbortResult | None:
+        """x402 on_before_payment_creation hook. None = allow."""
+        req = ctx.selected_requirements
+        payment_required = ctx.payment_required
+        resource_url = None
+        if getattr(payment_required, "resource", None) is not None:
+            resource_url = payment_required.resource.url
+        try:
+            amount_raw = req.get_amount() if hasattr(req, "get_amount") else getattr(req, "amount", None)
+            pay_to = getattr(req, "pay_to", None)
+            network = getattr(req, "network", None)
+            asset = getattr(req, "asset", None)
+            if pay_to is None or network is None or asset is None:
+                return self._deny("UNSUPPORTED_VERSION",
+                                  "requirements shape not supported by the gate (V2 required)",
+                                  resource_url=resource_url)
+            amount = parse_atomic_amount(amount_raw)
+            if amount is None:
+                return self._deny("MALFORMED_AMOUNT",
+                                  f"amount {amount_raw!r} is not an integer atomic amount",
+                                  pay_to=pay_to, network=network, resource_url=resource_url)
+            p = self.policy
+            if not p.network_allowed(str(network)):
+                return self._deny("NETWORK_NOT_ALLOWED", f"network {network} not in policy allowlist",
+                                  amount=amount, pay_to=pay_to, network=network, resource_url=resource_url)
+            if not p.asset_allowed(str(asset)):
+                return self._deny("ASSET_NOT_ALLOWED", f"asset {asset} not in policy allowlist",
+                                  amount=amount, pay_to=pay_to, network=network, resource_url=resource_url)
+            if not p.counterparty_allowed(str(pay_to)):
+                return self._deny("COUNTERPARTY_NOT_ALLOWED", f"pay_to {pay_to} not in counterparty allowlist",
+                                  amount=amount, pay_to=pay_to, network=network, resource_url=resource_url)
+            if amount > p.per_call_cap_atomic:
+                return self._deny("PER_CALL_CAP",
+                                  f"amount {amount} exceeds per-call cap {p.per_call_cap_atomic}",
+                                  amount=amount, pay_to=pay_to, network=network, resource_url=resource_url)
+            if amount <= 0:
+                return self._deny("MALFORMED_AMOUNT", "amount must be positive",
+                                  amount=amount, pay_to=pay_to, network=network, resource_url=resource_url)
+            if p.intent_required and self._intent_hash is None:
+                return self._deny("INTENT_REQUIRED", "no intent declared for this payment",
+                                  amount=amount, pay_to=pay_to, network=network, resource_url=resource_url)
+            if self._intent_pay_to is not None and str(pay_to).lower() != self._intent_pay_to:
+                return self._deny("INTENT_MISMATCH",
+                                  f"payment pay_to {pay_to} does not match intent-bound counterparty {self._intent_pay_to}",
+                                  amount=amount, pay_to=pay_to, network=network, resource_url=resource_url)
+            if self._intent_resource is not None and resource_url != self._intent_resource:
+                return self._deny("INTENT_MISMATCH",
+                                  f"payment resource {resource_url} does not match intent-bound resource {self._intent_resource}",
+                                  amount=amount, pay_to=pay_to, network=network, resource_url=resource_url)
+            now = self._now()
+            fingerprint = self._fingerprint(
+                intent_hash=self._intent_hash, decl_id=self._intent_decl_id,
+                network=str(network), asset=str(asset), pay_to=str(pay_to),
+                amount=amount, resource_url=resource_url)
+            status, value = self.store.check_and_reserve(
+                fingerprint=fingerprint, intent_hash=self._intent_hash,
+                amount=amount, pay_to=str(pay_to), network=str(network),
+                asset=str(asset), resource_url=resource_url, now=now,
+                day_start=self._day_start(now),
+                session_budget=p.session_budget_atomic,
+                daily_budget=p.daily_budget_atomic,
+                per_counterparty_cap=p.per_counterparty_cap_atomic,
+                max_per_window=p.max_payments_per_window,
+                window_seconds=p.window_seconds,
+                replay_window=p.replay_window_seconds)
+            if status == "deny":
+                return self._deny(str(value), f"aggregate policy limit reached: {value}",
+                                  amount=amount, pay_to=pay_to, network=network, resource_url=resource_url)
+            with self._pending_lock:
+                self._pending[fingerprint].append(int(value))
+            self._audit({"decision": "allow", "amount_atomic": amount, "pay_to": pay_to,
+                         "network": network, "resource_url": resource_url,
+                         "intent_hash": self._intent_hash, "reservation_id": int(value)})
+            return None
+        except StoreError as e:
+            return self._deny("INTERNAL_FAIL_CLOSED", f"spend store unavailable; failing closed: {e}",
+                              resource_url=resource_url)
+        except Exception as e:  # any unexpected gate error must fail closed, never open
+            return self._deny("INTERNAL_FAIL_CLOSED", f"gate evaluation error; failing closed: {e!r}",
+                              resource_url=resource_url)
+
+    def _pop_reservation(self, ctx) -> int | None:
+        req = ctx.selected_requirements
+        payment_required = ctx.payment_required
+        resource_url = None
+        if getattr(payment_required, "resource", None) is not None:
+            resource_url = payment_required.resource.url
+        amount = parse_atomic_amount(req.get_amount() if hasattr(req, "get_amount") else None)
+        if amount is None:
+            return None
+        fingerprint = self._fingerprint(
+            intent_hash=self._intent_hash, decl_id=self._intent_decl_id,
+            network=str(req.network), asset=str(req.asset), pay_to=str(req.pay_to),
+            amount=amount, resource_url=resource_url)
+        with self._pending_lock:
+            stack = self._pending.get(fingerprint)
+            if stack:
+                rid = stack.pop()
+                if not stack:
+                    del self._pending[fingerprint]
+                return rid
+        return None
+
+    def after_hook(self, ctx) -> None:
+        rid = self._pop_reservation(ctx)
+        if rid is not None:
+            try:
+                self.store.commit(rid)
+            except StoreError:
+                # Signature exists but ledger failed: keep counting it as
+                # reserved (it still counts against budgets). Never release.
+                pass
+
+    def failure_hook(self, ctx) -> None:
+        rid = self._pop_reservation(ctx)
+        if rid is not None:
+            try:
+                self.store.release(rid)
+            except StoreError:
+                pass
+        return None