polyrob 0.5.0__py3-none-any.whl

core/tool_catalog.py

@@ -0,0 +1,192 @@
+"""Product-facing tool catalog built from the descriptor source of truth."""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+def _load_descriptors_module():
+    """Load tools/descriptors.py without importing tools/__init__.py."""
+    path = Path(__file__).resolve().parents[1] / "tools" / "descriptors.py"
+    spec = importlib.util.spec_from_file_location("_polyrob_tool_descriptors", path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"could not load tool descriptors from {path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+_DESCRIPTORS = _load_descriptors_module()
+TOOL_DESCRIPTORS = _DESCRIPTORS.TOOL_DESCRIPTORS
+ToolCategory = _DESCRIPTORS.ToolCategory
+ToolDescriptor = _DESCRIPTORS.ToolDescriptor
+
+
+_CATEGORY_LABELS = {
+    ToolCategory.CORE: "core",
+    ToolCategory.BROWSER: "automation",
+    ToolCategory.COMMUNICATION: "integration",
+    ToolCategory.SEARCH: "automation",
+    ToolCategory.VERIFICATION: "integration",
+    ToolCategory.INTEGRATION: "integration",
+}
+
+_PERMISSIONS = {
+    "filesystem": ["fs.read", "fs.write"],
+    "task": ["memory.read", "memory.write"],
+    "browser_manager": ["browser.control", "network.read"],
+    "perplexity": ["network.read"],
+    "twitter": ["network.read", "network.write", "social.post"],
+    "email": ["network.write", "email.send"],
+    "collabland": ["network.read"],
+    "alchemy": ["network.read"],
+    "mcp": ["mcp.call", "network.read"],
+    "anysite": ["network.read", "process.spawn"],
+    "polymarket": ["network.read", "trade.execute"],
+    "hyperliquid": ["network.read", "trade.execute"],
+    # Read-only split tools: market data only, no wallet/signing.
+    "polymarket_data": ["network.read"],
+    "hyperliquid_data": ["network.read"],
+}
+
+_HIGH_RISK_TOOLS = {"twitter", "email", "polymarket", "hyperliquid"}
+_MEDIUM_RISK_TOOLS = {"mcp", "anysite", "browser_manager", "perplexity"}
+_ENABLE_FLAGS = {
+    "twitter": "TWITTER_ENABLED",
+}
+_DB_CREDENTIAL_TOOLS = {
+    "polymarket": "requires database-stored trading credentials and explicit operator enablement",
+    "hyperliquid": "requires database-stored trading credentials and explicit operator enablement",
+}
+
+
+@dataclass(frozen=True)
+class ToolCatalogEntry:
+    """Stable product metadata for one tool."""
+
+    id: str
+    display_name: str
+    category: str
+    model_description: str
+    human_description: str
+    permissions: List[str] = field(default_factory=list)
+    scope: str = "session"
+    enabled: bool = True
+    disabled_reason: Optional[str] = None
+    required_config: List[str] = field(default_factory=list)
+    required_services: List[str] = field(default_factory=list)
+    optional_services: List[str] = field(default_factory=list)
+    rate_limited: bool = False
+    rate_limits: Dict[str, Any] = field(default_factory=dict)
+    cost_risk: str = "low"
+    security_risk: str = "low"
+    audit_events: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+def build_tool_catalog(env: Optional[Dict[str, str]] = None) -> List[ToolCatalogEntry]:
+    """Return catalog entries sorted by category and id."""
+    env = os.environ if env is None else env
+    entries = [_entry_from_descriptor(name, desc, env) for name, desc in TOOL_DESCRIPTORS.items()]
+    return sorted(entries, key=lambda e: (e.category, e.id))
+
+
+def find_tool(tool_id: str, env: Optional[Dict[str, str]] = None) -> Optional[ToolCatalogEntry]:
+    needle = tool_id.lower().strip()
+    for entry in build_tool_catalog(env=env):
+        if entry.id == needle:
+            return entry
+    return None
+
+
+def permission_catalog() -> Dict[str, List[str]]:
+    """Return permission class -> tool ids."""
+    result: Dict[str, List[str]] = {}
+    for entry in build_tool_catalog():
+        for permission in entry.permissions:
+            result.setdefault(permission, []).append(entry.id)
+    return {key: sorted(value) for key, value in sorted(result.items())}
+
+
+def _entry_from_descriptor(
+    name: str,
+    desc: ToolDescriptor,
+    env: Dict[str, str],
+) -> ToolCatalogEntry:
+    required_config = list(desc.required_config)
+    missing = [key for key in required_config if not _config_present(key, env)]
+    gated_reason = _gated_reason(name, env)
+    enabled = not missing
+    disabled_reason = None
+    if missing:
+        disabled_reason = "missing config: " + ", ".join(missing)
+    if gated_reason:
+        enabled = False
+        disabled_reason = gated_reason
+
+    return ToolCatalogEntry(
+        id=name,
+        display_name=name.replace("_", " ").title(),
+        category=_CATEGORY_LABELS.get(desc.category, desc.category.value),
+        model_description=_model_description(desc.description),
+        human_description=desc.description,
+        permissions=list(_PERMISSIONS.get(name, [])),
+        enabled=enabled,
+        disabled_reason=disabled_reason,
+        required_config=required_config,
+        required_services=list(desc.required_services),
+        optional_services=list(desc.optional_services),
+        rate_limited=desc.rate_limited,
+        rate_limits=dict(desc.rate_limit_settings),
+        cost_risk=_risk_for(name),
+        security_risk=_risk_for(name),
+        audit_events=_audit_events(name),
+    )
+
+
+def _config_present(key: str, env: Dict[str, str]) -> bool:
+    variants = {
+        key,
+        key.upper(),
+        key.lower(),
+        key.replace("_api_key", "_API_KEY").upper(),
+    }
+    return any(bool(env.get(variant)) for variant in variants)
+
+
+def _model_description(description: str) -> str:
+    first_sentence = description.split(".", 1)[0].strip()
+    return first_sentence or description.strip()
+
+
+def _risk_for(name: str) -> str:
+    if name in _HIGH_RISK_TOOLS:
+        return "high"
+    if name in _MEDIUM_RISK_TOOLS:
+        return "medium"
+    return "low"
+
+
+def _gated_reason(name: str, env: Dict[str, str]) -> Optional[str]:
+    flag = _ENABLE_FLAGS.get(name)
+    if flag and not _truthy(env.get(flag)):
+        return f"gated by {flag}=false"
+    return _DB_CREDENTIAL_TOOLS.get(name)
+
+
+def _truthy(value: Optional[str]) -> bool:
+    return str(value or "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _audit_events(name: str) -> List[str]:
+    permissions = _PERMISSIONS.get(name, [])
+    events = ["tool.call"]
+    if any(p.endswith(".write") or p in {"social.post", "email.send", "trade.execute"} for p in permissions):
+        events.append("external.write")
+    return events

core/version.py

@@ -0,0 +1,75 @@
+"""Single source of truth for the project version at runtime.
+
+Build-time SSOT is pyproject.toml. Resolution order at runtime:
+
+1. The **source** ``pyproject.toml`` next to this checkout — authoritative when you
+   run ``polyrob`` from a source tree. This is FIRST on purpose: a stale editable
+   or wheel install (e.g. a venv still carrying ``polyrob 1.0.0`` while the source
+   is ``0.4.2``) must NOT shadow the version of the code you're actually running.
+2. Installed package metadata — for a real ``pip install`` where there's no source
+   ``pyproject.toml`` adjacent to this module (site-packages).
+3. The literal fallback below (tests pin it to pyproject.toml so it can't drift).
+"""
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+from pathlib import Path
+from typing import Optional
+
+# Dev-checkout fallback. MUST equal pyproject.toml [project].version.
+_FALLBACK_VERSION = "0.5.0"
+
+# Project names this module is willing to claim from an adjacent pyproject.toml, so
+# a parent/monorepo pyproject can never mislabel the version.
+_OWN_PROJECT_NAMES = {"polyrob", "polyrob-core", "rob"}
+
+
+def _load_toml(text: str) -> Optional[dict]:
+    try:
+        import tomllib  # py3.11+
+    except ModuleNotFoundError:  # pragma: no cover - older interpreters
+        try:
+            import tomli as tomllib  # type: ignore
+        except ModuleNotFoundError:
+            return None
+    try:
+        return tomllib.loads(text)
+    except Exception:
+        return None
+
+
+def _source_pyproject_version() -> Optional[str]:
+    """Version from the checkout's own ``pyproject.toml``, or None.
+
+    ``core/version.py`` → repo root is ``parents[1]``. Only trusted when the file's
+    ``[project].name`` is one of ours, so a wrong/parent pyproject is ignored. Fully
+    fail-open: any read/parse problem returns None and we fall through to metadata.
+    """
+    try:
+        pyproject = Path(__file__).resolve().parents[1] / "pyproject.toml"
+        if not pyproject.is_file():
+            return None
+        data = _load_toml(pyproject.read_text(encoding="utf-8"))
+        if not data:
+            return None
+        project = data.get("project", {}) or {}
+        name = str(project.get("name", "")).strip().lower()
+        ver = project.get("version")
+        if ver and name in _OWN_PROJECT_NAMES:
+            return str(ver)
+    except Exception:
+        return None
+    return None
+
+
+def get_version() -> str:
+    src = _source_pyproject_version()
+    if src:
+        return src
+    try:
+        return _pkg_version("polyrob")
+    except PackageNotFoundError:
+        return _FALLBACK_VERSION
+
+
+__version__ = get_version()

core/wallet/__init__.py

@@ -0,0 +1,5 @@
+"""Agent personal wallet (core-tier). The agent's own wallet, used as a tool.
+
+Deliberately separate from the server-tier tariffing gateway (modules/x402,
+modules/payments). MUST NOT import any server-tier billing module.
+"""

core/wallet/agent_wallet.py

@@ -0,0 +1,59 @@
+"""AgentWallet: the agent's single, operator-funded personal wallet (core-tier).
+
+Hub-and-spoke topology: one master seed → a treasury key + domain-separated
+per-venue keys. Hyperliquid trades via its own delegated key (the venue's
+built-in withdrawal firewall); x402 pays from its own small float.
+"""
+from __future__ import annotations
+
+import hashlib
+from typing import Callable, List, Optional
+
+from core.wallet.config import WalletConfig
+from core.wallet.policy import PolicyGate
+from core.wallet.signer import LocalEoaSigner
+
+VENUES = frozenset({"treasury", "x402", "polymarket", "hyperliquid"})
+
+_PBKDF2_ITERS = 100_000
+
+
+class AgentWallet:
+    def __init__(self, config: WalletConfig, audit_sink: Optional[List[dict]] = None,
+                 on_record: Optional[Callable[[dict], None]] = None):
+        self._config = config
+        if config.enabled:
+            if not config.master_seed or len(config.master_seed) < 32:
+                raise ValueError("AGENT_WALLET_MASTER_SEED must be set and >=32 chars when enabled")
+        self._seed = config.master_seed or ""
+        self._signers: dict[str, LocalEoaSigner] = {}
+        self._policy = PolicyGate(
+            max_per_tx_usd=config.max_per_tx_usd,
+            audit_sink=audit_sink,
+            daily_cap_usd=getattr(config, "daily_cap_usd", None),
+            per_venue_daily_cap_usd=getattr(config, "per_venue_daily_cap_usd", None),
+            on_record=on_record,
+        )
+
+    def _derive_key(self, venue: str) -> bytes:
+        # Domain-separated label keeps venue keys independent and recoverable.
+        label = f"agent-wallet:{venue}".encode("utf-8")
+        return hashlib.pbkdf2_hmac("sha256", self._seed.encode("utf-8"), label, _PBKDF2_ITERS, dklen=32)
+
+    def signer_for(self, venue: str) -> LocalEoaSigner:
+        if venue not in VENUES:
+            raise ValueError(f"unknown venue '{venue}' (expected one of {sorted(VENUES)})")
+        if venue not in self._signers:
+            self._signers[venue] = LocalEoaSigner(self._derive_key(venue))
+        return self._signers[venue]
+
+    def account_for(self, venue: str):
+        return self.signer_for(venue).account
+
+    @property
+    def address(self) -> str:
+        return self.signer_for("treasury").address
+
+    @property
+    def policy(self) -> PolicyGate:
+        return self._policy

core/wallet/audit_sink.py

@@ -0,0 +1,61 @@
+"""Durable, append-only audit sink for the wallet PolicyGate (G3).
+
+An in-memory ``list`` of audit entries is lost on restart, so the harness can't sum
+lifetime/rolling spend across a service restart — a mainnet prerequisite. This sink
+is a ``list`` subclass that mirrors every appended entry to an append-only JSONL file
+and reloads prior entries on construction, so a fresh ``PolicyGate(audit_sink=...)``
+sees the full history. Default behavior is unchanged: PolicyGate uses a plain list
+unless a sink is injected (only the factory does, when the wallet is enabled).
+
+Fail-open: a file I/O error never blocks an action (the in-memory copy is always
+authoritative for the live process); persistence is best-effort.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import List
+
+logger = logging.getLogger(__name__)
+
+
+class JsonlAuditSink(list):
+    """A list of audit dicts mirrored to an append-only JSONL file."""
+
+    def __init__(self, path: str):
+        super().__init__()
+        self._path = path
+        parent = os.path.dirname(path)
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        self._load()
+
+    def _load(self) -> None:
+        if not os.path.exists(self._path):
+            return
+        try:
+            with open(self._path, "r", encoding="utf-8") as fh:
+                for line in fh:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        list.append(self, json.loads(line))  # base append: no re-write
+                    except json.JSONDecodeError:
+                        continue  # skip a corrupt line, keep the rest
+        except OSError as e:
+            logger.warning("wallet audit sink load failed (%s): %s", self._path, e)
+
+    def append(self, entry: dict) -> None:  # type: ignore[override]
+        list.append(self, entry)
+        try:
+            with open(self._path, "a", encoding="utf-8") as fh:
+                fh.write(json.dumps(entry) + "\n")
+        except OSError as e:
+            logger.warning("wallet audit sink write failed (%s): %s", self._path, e)
+
+
+def default_audit_sink(data_dir: str = "data") -> List[dict]:
+    """The factory's default persistent sink at ``<data_dir>/wallet/audit.jsonl``."""
+    return JsonlAuditSink(os.path.join(data_dir, "wallet", "audit.jsonl"))

core/wallet/config.py

@@ -0,0 +1,70 @@
+"""Agent-wallet configuration (env-driven, default-safe)."""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Dict, Mapping, Optional
+
+TESTNET_FACILITATOR_URL = "https://x402.org/facilitator"
+
+_TRUE = {"1", "true", "yes", "on"}
+
+
+def _b(env: Mapping[str, str], key: str, default: bool) -> bool:
+    raw = env.get(key)
+    return default if raw is None else raw.strip().lower() in _TRUE
+
+
+@dataclass(frozen=True)
+class WalletConfig:
+    enabled: bool
+    backend: str
+    master_seed: Optional[str]
+    network: str
+    max_per_tx_usd: float
+    x402_client_enabled: bool
+    x402_facilitator_url: str
+    daily_cap_usd: Optional[float] = None
+    per_venue_daily_cap_usd: Dict[str, float] = field(default_factory=dict)
+
+
+def _opt_float(env: Mapping[str, str], key: str) -> Optional[float]:
+    raw = env.get(key)
+    if raw is None or not str(raw).strip():
+        return None
+    try:
+        return float(raw)
+    except ValueError:
+        return None
+
+
+def _load_per_venue_caps(env: Mapping[str, str]) -> Dict[str, float]:
+    """Parse WALLET_VENUE_DAILY_CAP_<VENUE>_USD env vars into {venue: cap}."""
+    prefix, suffix = "WALLET_VENUE_DAILY_CAP_", "_USD"
+    caps: Dict[str, float] = {}
+    for key in env:
+        if key.startswith(prefix) and key.endswith(suffix):
+            venue = key[len(prefix):-len(suffix)].lower()
+            val = _opt_float(env, key)
+            if venue and val is not None:
+                caps[venue] = val
+    return caps
+
+
+def load_wallet_config(env: Optional[Mapping[str, str]] = None) -> WalletConfig:
+    env = os.environ if env is None else env
+    network = env.get("AGENT_WALLET_NETWORK", "testnet").strip().lower()
+    return WalletConfig(
+        enabled=_b(env, "AGENT_WALLET_ENABLED", False),
+        backend=env.get("AGENT_WALLET_BACKEND", "local_eoa").strip().lower(),
+        master_seed=env.get("AGENT_WALLET_MASTER_SEED"),
+        network=network if network in ("testnet", "mainnet") else "testnet",
+        # Safety default: a catastrophic per-tx ceiling, NOT a budget. Was
+        # $1,000,000 (a typo could drain funds); raise it explicitly if needed.
+        max_per_tx_usd=float(env.get("AGENT_WALLET_MAX_PER_TX_USD", "1000")),
+        x402_client_enabled=_b(env, "X402_CLIENT_ENABLED", False),
+        x402_facilitator_url=env.get("X402_CLIENT_FACILITATOR_URL", TESTNET_FACILITATOR_URL),
+        # Rolling 24h spend cap; unset = disabled = legacy behavior (per-tx ceiling only).
+        daily_cap_usd=_opt_float(env, "WALLET_DAILY_CAP_USD"),
+        per_venue_daily_cap_usd=_load_per_venue_caps(env),
+    )

core/wallet/factory.py

@@ -0,0 +1,87 @@
+"""Process-level AgentWallet singleton (the agent's wallet is single/operator-owned)."""
+from __future__ import annotations
+
+from typing import Optional
+
+from core.wallet.agent_wallet import AgentWallet
+from core.wallet.config import load_wallet_config
+from core.wallet.policy import PolicyGate
+
+_cached: Optional[AgentWallet] = None
+_resolved = False
+_standalone_policy: Optional[PolicyGate] = None
+
+
+def _emit_spend_to_event_log(entry: dict) -> None:
+    """PolicyGate.on_record hook: mirror each recorded spend into the durable
+    telemetry event log so money movement survives a restart and is queryable
+    cross-session (telemetry audit 2026-07-04). LAZY import keeps the core/wallet
+    tier free of a top-level agents-tier dependency; fail-open throughout."""
+    try:
+        from agents.task.telemetry.event_log import get_event_log, event_log_enabled
+        if not event_log_enabled():
+            return
+        get_event_log().record(
+            "wallet_spend",
+            source="wallet",
+            venue=entry.get("venue"),
+            action=entry.get("action"),
+            amount_usd=entry.get("amount_usd"),
+            counterparty=entry.get("counterparty"),
+            result_ref=entry.get("result_ref"),
+            ts=entry.get("ts"),
+        )
+    except Exception:
+        pass
+
+
+def get_agent_wallet() -> Optional[AgentWallet]:
+    global _cached, _resolved
+    if _resolved:
+        return _cached
+    cfg = load_wallet_config()
+    if cfg.enabled:
+        # Persist the audit trail so rolling-spend/lifetime tracking survives a
+        # restart (mainnet prerequisite). Fail-open: fall back to in-memory if the
+        # durable sink can't be created.
+        sink = None
+        try:
+            from core.wallet.audit_sink import default_audit_sink
+            sink = default_audit_sink()
+        except Exception:
+            sink = None
+        _cached = AgentWallet(cfg, audit_sink=sink, on_record=_emit_spend_to_event_log)
+    else:
+        _cached = None
+    _resolved = True
+    return _cached
+
+
+def get_policy_gate() -> PolicyGate:
+    """The PolicyGate that guards value-moving actions (trades + payments).
+
+    Returns the agent wallet's gate when the wallet is enabled; otherwise a
+    standalone gate built from wallet config so the catastrophic per-tx ceiling
+    and daily/venue caps STILL apply to DB-credential trading (which has no
+    agent wallet). Cached so rolling-spend/replay state persists within a process.
+    """
+    wallet = get_agent_wallet()
+    if wallet is not None:
+        return wallet.policy
+    global _standalone_policy
+    if _standalone_policy is None:
+        cfg = load_wallet_config()
+        _standalone_policy = PolicyGate(
+            max_per_tx_usd=cfg.max_per_tx_usd,
+            daily_cap_usd=cfg.daily_cap_usd,
+            per_venue_daily_cap_usd=cfg.per_venue_daily_cap_usd,
+            on_record=_emit_spend_to_event_log,
+        )
+    return _standalone_policy
+
+
+def reset_agent_wallet_cache() -> None:
+    global _cached, _resolved, _standalone_policy
+    _cached = None
+    _resolved = False
+    _standalone_policy = None

core/wallet/policy.py

@@ -0,0 +1,104 @@
+"""PolicyGate: cheap, backend-independent hygiene for value-moving actions.
+
+NOT a budget engine (the operator asked for 'no limits now'); it enforces ONE
+catastrophic per-tx ceiling, idempotency de-dup, and an append-only audit trail.
+A future budget engine can extend `check`."""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Callable, List, Optional
+
+_DAY_SECONDS = 86_400
+
+
+@dataclass(frozen=True)
+class PolicyDecision:
+    allowed: bool
+    reason: Optional[str]
+
+
+class PolicyGate:
+    def __init__(self, max_per_tx_usd: float, audit_sink: Optional[List[dict]] = None,
+                 daily_cap_usd: Optional[float] = None,
+                 per_venue_daily_cap_usd: Optional[dict] = None,
+                 clock: Callable[[], float] = time.time,
+                 on_record: Optional[Callable[[dict], None]] = None):
+        self._ceiling = float(max_per_tx_usd)
+        # Telemetry hook (audit 2026-07-04): fired with each recorded spend entry so
+        # a durable sink can capture money movement. Fail-open — never break record().
+        self._on_record = on_record
+        self._audit: List[dict] = audit_sink if audit_sink is not None else []
+        self._daily_cap: Optional[float] = (
+            None if daily_cap_usd is None else float(daily_cap_usd)
+        )
+        # Per-venue rolling-24h caps so one venue can't drain the global budget.
+        self._per_venue_cap: dict = {
+            str(k).lower(): float(v)
+            for k, v in (per_venue_daily_cap_usd or {}).items()
+        }
+        self._now = clock
+        # Rebuild the replay-guard set from a pre-loaded (persistent) sink so
+        # idempotency survives a restart. No-op for the default empty list.
+        self._seen_idempotency: set[str] = {
+            e["idempotency_key"] for e in self._audit
+            if e.get("idempotency_key")
+        }
+
+    def _rolling_24h_spend(self, venue: Optional[str] = None) -> float:
+        window_start = self._now() - _DAY_SECONDS
+        return sum(
+            float(e.get("amount_usd") or 0.0)
+            for e in self._audit
+            if float(e.get("ts") or 0.0) >= window_start
+            and (venue is None or e.get("venue") == venue)
+        )
+
+    def check(self, *, venue: str, amount_usd: float, idempotency_key: Optional[str]) -> PolicyDecision:
+        if amount_usd > self._ceiling:
+            return PolicyDecision(False, f"amount ${amount_usd:.2f} exceeds catastrophic ceiling ${self._ceiling:.2f}")
+        if idempotency_key and idempotency_key in self._seen_idempotency:
+            return PolicyDecision(False, f"idempotency key '{idempotency_key}' already used (replay blocked)")
+        if self._daily_cap is not None:
+            spent = self._rolling_24h_spend()
+            if spent + amount_usd > self._daily_cap:
+                return PolicyDecision(
+                    False,
+                    f"daily spend cap ${self._daily_cap:.2f} would be exceeded "
+                    f"(trailing-24h ${spent:.2f} + ${amount_usd:.2f})",
+                )
+        venue_cap = self._per_venue_cap.get(str(venue).lower())
+        if venue_cap is not None:
+            venue_spent = self._rolling_24h_spend(venue=venue)
+            if venue_spent + amount_usd > venue_cap:
+                return PolicyDecision(
+                    False,
+                    f"venue '{venue}' daily cap ${venue_cap:.2f} would be exceeded "
+                    f"(trailing-24h ${venue_spent:.2f} + ${amount_usd:.2f})",
+                )
+        return PolicyDecision(True, None)
+
+    def record(self, *, venue: str, action: str, amount_usd: float,
+               counterparty: Optional[str], idempotency_key: Optional[str],
+               result_ref: Optional[str]) -> None:
+        if idempotency_key:
+            self._seen_idempotency.add(idempotency_key)
+        entry = {
+            "ts": self._now(),
+            "venue": venue,
+            "action": action,
+            "amount_usd": amount_usd,
+            "counterparty": counterparty,
+            "idempotency_key": idempotency_key,
+            "result_ref": result_ref,
+        }
+        self._audit.append(entry)
+        if self._on_record is not None:
+            try:
+                self._on_record(entry)
+            except Exception:
+                pass  # fail-open: telemetry must never break a recorded spend
+
+    @property
+    def audit_log(self) -> List[dict]:
+        return list(self._audit)