fix: address review feedback — Decimal money, atomic store, BudgetLimit model, scoping fix

- float → Decimal throughout: BudgetLimit.amount, BudgetWindow, store, tests
- BudgetLimit + BudgetWindow model: config refactored from flat fields to
  limits: list[BudgetLimit]; each limit has amount, currency, scope_by, window
- Atomic check_and_record(): eliminates TOCTOU race on get_spend()+record_spend();
  InMemorySpendStore implements with threading.Lock (single-process); docs note
  production stores need DB-level atomics (Postgres FOR UPDATE, Redis Lua)
- scope_by field: independent per-dimension budget isolation; scope_by=(channel,)
  means channel A spend does not count against channel B budget
- selector.path fix: config examples and README updated to use 'input' not '*';
  Step vs raw-dict distinction documented; evaluator auto-detects format
- EvaluatorResult.error usage: malformed payload returns matched=False, error=None;
  error field reserved for crashes/timeouts/missing deps only
- README: custom store example updated with scope param and check_and_record;
  stale malformed-input docs corrected; Known Limitations updated
- Tests: or True removed; all assertions verify actual store state; lan17
  channel isolation test (90 in A + 20 in B) passes with scope_by semantics

Author: up2itnow0822

evaluators/contrib/financial-governance/README.md

@@ -10,10 +10,12 @@ As agents transact autonomously via protocols like [x402](https://github.com/coi
 
 Tracks cumulative agent spend and enforces rolling budget limits. Stateful — records approved transactions and checks new ones against accumulated spend.
 
-- **Per-transaction cap** — reject any single payment above a threshold
-- **Rolling period budget** — reject payments that would exceed a time-windowed budget
-- **Context-aware overrides** — different limits per channel, agent, or session via evaluate metadata
+- **Per-transaction cap** — reject any single payment above a threshold (`BudgetLimit` with no window)
+- **Rolling period budget** — reject payments that would exceed a time-windowed budget (`BudgetWindow(kind="rolling", ...)`)
+- **Calendar-aligned budget** — reject payments that exceed a day/week/month budget (`BudgetWindow(kind="fixed", ...)`)
+- **Scoped budgets** — independent counters per channel, agent, or session via `scope_by`
 - **Pluggable storage** — abstract `SpendStore` protocol with built-in `InMemorySpendStore`; bring your own PostgreSQL, Redis, etc.
+- **Atomic enforcement** — `check_and_record()` prevents TOCTOU races in single-process deployments
 
 ### `financial_governance.transaction_policy`
 
@@ -35,16 +37,25 @@ pip install -e ".[dev]"
 
 ### Spend Limit
 
+The `spend_limit` evaluator is configured via a list of `BudgetLimit` objects. Each limit is evaluated independently — the first violation wins.
+
 ```yaml
 controls:
   - name: spend-limit
     evaluator:
       type: financial_governance.spend_limit
       config:
-        max_per_transaction: 100.0    # Max USDC per single payment
-        max_per_period: 1000.0        # Rolling 24h budget
-        period_seconds: 86400         # Budget window (default: 24 hours)
-        currency: USDC                # Currency to govern
+        limits:
+          # Per-transaction cap: single payment ≤ 100 USDC
+          - amount: "100.00"
+            currency: USDC
+          # Per-channel rolling 24h budget: each channel limited to 1000 USDC/day
+          - amount: "1000.00"
+            currency: USDC
+            scope_by: [channel]
+            window:
+              kind: rolling
+              seconds: 86400
     selector:
       path: input                     # Extract step.input (transaction dict)
     action: deny
@@ -61,8 +72,8 @@ controls:
         allowed_currencies: [USDC, USDT]
         blocked_recipients: ["0xDEAD..."]
         allowed_recipients: ["0xALICE...", "0xBOB..."]
-        min_amount: 0.01
-        max_amount: 5000.0
+        min_amount: "0.01"
+        max_amount: "5000.00"
     selector:
       path: input
     action: deny
@@ -82,58 +93,106 @@ The transaction dict (from `step.input`) should contain:
 ```python
 # step.input — transaction payload
 {
-    "amount": 50.0,              # required — transaction amount
-    "currency": "USDC",          # required — payment currency
-    "recipient": "0xABC...",     # required — payment recipient
+    "amount": "50.00",             # required — Decimal or numeric string
+    "currency": "USDC",            # required — payment currency
+    "recipient": "0xABC...",       # required — payment recipient
+    # optional context fields (used for scope_by)
+    "channel": "slack",
+    "agent_id": "agent-42",
+    "session_id": "sess-1",
 }
 ```
 
+> **Note:** Use `Decimal` or string representations for `amount` — never raw `float`. Floating-point arithmetic is imprecise for money. The evaluator internally converts to `Decimal`.
+
+## BudgetLimit Model
+
+```python
+from decimal import Decimal
+from agent_control_evaluator_financial_governance.spend_limit import (
+    BudgetLimit, BudgetWindow, SpendLimitConfig, SpendLimitEvaluator,
+)
+
+# Per-transaction cap (no window)
+cap = BudgetLimit(amount=Decimal("100"), currency="USDC")
+
+# Rolling 24-hour budget, scoped per channel
+rolling = BudgetLimit(
+    amount=Decimal("1000"),
+    currency="USDC",
+    scope_by=("channel",),
+    window=BudgetWindow(kind="rolling", seconds=86400),
+)
+
+# Calendar-day budget (UTC)
+daily = BudgetLimit(
+    amount=Decimal("500"),
+    currency="USDC",
+    window=BudgetWindow(kind="fixed", unit="day"),
+)
+
+config = SpendLimitConfig(limits=[cap, rolling, daily])
+evaluator = SpendLimitEvaluator(config)
+```
+
+### BudgetWindow
+
+| kind | Required fields | Notes |
+|------|----------------|-------|
+| `"rolling"` | `seconds` | Sliding window from `now - seconds` |
+| `"fixed"` | `unit` (`"day"`, `"week"`, or `"month"`) | Calendar-aligned, UTC by default |
+
+### scope_by semantics
+
+`scope_by` lists the context dimension keys to isolate spend buckets. Each dimension is **independent**:
+
+- `scope_by=()` (default) — global budget: all spend in that currency shares one counter
+- `scope_by=("channel",)` — one counter per unique `channel` value
+- `scope_by=("agent_id",)` — one counter per unique `agent_id`
+- `scope_by=("channel", "agent_id")` — one counter per unique `(channel, agent_id)` pair
+
+Spend in `channel-A` does **not** count against `channel-B`'s budget.
+
 ## Context-Aware Limits
 
-Context fields (`channel`, `agent_id`, `session_id`) and per-context limit overrides can be provided in two ways:
+Context fields (`channel`, `agent_id`, `session_id`) can be provided in two ways:
 
 **Option A: Via `step.context`** (recommended for engine integration)
 
 ```python
 step = Step(
     type="tool",
     name="payment",
-    input={"amount": 75.0, "currency": "USDC", "recipient": "0xABC"},
+    input={"amount": "75.00", "currency": "USDC", "recipient": "0xABC"},
     context={
         "channel": "experimental",
         "agent_id": "agent-42",
-        "channel_max_per_transaction": 50.0,
-        "channel_max_per_period": 200.0,
     },
 )
 ```
 
-When using `selector.path: "*"`, the evaluator merges `step.context` fields into the transaction data automatically. When using `selector.path: "input"`, context fields must be included directly in `step.input`.
+When using `selector.path: "*"`, the evaluator merges `step.context` fields into the transaction data automatically. Fields already present in `step.input` are never overwritten by context.
 
 **Option B: Inline in the transaction dict** (simpler, for direct SDK use)
 
 ```python
 result = await evaluator.evaluate({
-    "amount": 75.0,
+    "amount": "75.00",
     "currency": "USDC",
     "recipient": "0xABC",
     "channel": "experimental",
-    "channel_max_per_transaction": 50.0,
-    "channel_max_per_period": 200.0,
+    "agent_id": "agent-42",
 })
 ```
 
-Spend budgets are **scoped by context** — spend in channel A does not count against channel B's budget. When no context fields are present, budgets are global.
-
 ## Custom SpendStore
 
-The `SpendStore` protocol requires two methods. Implement them for your backend:
+The `SpendStore` protocol requires three methods. Implement them for your backend:
 
 ```python
+from decimal import Decimal
 from agent_control_evaluator_financial_governance.spend_limit import (
-    SpendStore,
-    SpendLimitConfig,
-    SpendLimitEvaluator,
+    SpendStore, SpendLimitConfig, SpendLimitEvaluator,
 )
 
 class PostgresSpendStore:
@@ -142,24 +201,70 @@ class PostgresSpendStore:
     def __init__(self, connection_string: str):
         self._conn = connect(connection_string)
 
-    def record_spend(self, amount: float, currency: str, metadata: dict | None = None) -> None:
+    def record_spend(
+        self,
+        amount: Decimal,
+        currency: str,
+        metadata: dict | None = None,
+    ) -> None:
         self._conn.execute(
-            "INSERT INTO agent_spend (amount, currency, metadata, recorded_at) VALUES (%s, %s, %s, NOW())",
-            (amount, currency, json.dumps(metadata)),
+            "INSERT INTO agent_spend (amount, currency, metadata, recorded_at)"
+            " VALUES (%s, %s, %s, NOW())",
+            (str(amount), currency, json.dumps(metadata)),
         )
 
-    def get_spend(self, currency: str, since_timestamp: float) -> float:
+    def get_spend(
+        self,
+        currency: str,
+        start: float,
+        end: float | None = None,
+        scope: dict[str, str] | None = None,
+    ) -> Decimal:
+        # Build WHERE clause for scope filtering
+        clauses = [
+            "currency = %s",
+            "recorded_at >= to_timestamp(%s)",
+        ]
+        params = [currency, start]
+        if end is not None:
+            clauses.append("recorded_at <= to_timestamp(%s)")
+            params.append(end)
+        if scope:
+            for k, v in scope.items():
+                clauses.append(f"metadata->>{k!r} = %s")
+                params.append(v)
+        where = " AND ".join(clauses)
         row = self._conn.execute(
-            "SELECT COALESCE(SUM(amount), 0) FROM agent_spend WHERE currency = %s AND recorded_at >= to_timestamp(%s)",
-            (currency, since_timestamp),
+            f"SELECT COALESCE(SUM(amount), 0) FROM agent_spend WHERE {where}",
+            params,
         ).fetchone()
-        return float(row[0])
+        return Decimal(str(row[0]))
+
+    def check_and_record(
+        self,
+        amount: Decimal,
+        currency: str,
+        limit: Decimal,
+        start: float,
+        end: float | None = None,
+        scope: dict[str, str] | None = None,
+        metadata: dict | None = None,
+    ) -> tuple[bool, Decimal]:
+        # Use a DB transaction for atomicity
+        with self._conn.transaction():
+            current = self.get_spend(currency, start, end, scope)
+            if current + amount > limit:
+                return False, current
+            self.record_spend(amount, currency, metadata)
+            return True, current
 
 # Use it:
 store = PostgresSpendStore("postgresql://...")
 evaluator = SpendLimitEvaluator(config, store=store)
 ```
 
+> **Single-process atomicity note:** `InMemorySpendStore.check_and_record()` uses a `threading.Lock` to atomically check-and-record within a single process. For multi-process or distributed deployments, your custom store must implement true database-level atomics (e.g., PostgreSQL `SELECT ... FOR UPDATE`, Redis Lua scripts).
+
 ## Running Tests
 
 ```bash
@@ -170,10 +275,12 @@ pytest tests/ -v
 
 ## Design Decisions
 
-1. **Decoupled from data source** — The `SpendStore` protocol means no new tables in core Agent Control. Bring your own persistence.
-2. **Context-aware limits** — Override keys in the evaluate data dict allow per-channel, per-agent, or per-session limits without multiple evaluator instances.
-3. **Python SDK compatible** — Uses the standard evaluator interface; works with both the server and the Python SDK evaluation engine.
-4. **Fail-open on errors** — Missing or malformed data returns `matched=False` with an `error` field, following Agent Control conventions.
+1. **Decimal for money** — All monetary amounts use `Decimal`, never `float`. Floating-point arithmetic is unsuitable for financial calculations.
+2. **BudgetLimit + BudgetWindow models** — Expressive, composable budget definitions that replace the previous flat config. Each limit is independent; first violation wins.
+3. **Independent scope dimensions** — `scope_by=("channel",)` creates a separate counter for each channel value. Spend in one channel is completely isolated from another.
+4. **Atomic check_and_record()** — Eliminates the TOCTOU race of separate `get_spend()` + `record_spend()` calls. Single-process safe with `threading.Lock`; production stores should use DB-level atomics.
+5. **Decoupled from data source** — The `SpendStore` protocol means no new tables in core Agent Control. Bring your own persistence.
+6. **Fail-open on malformed input** — Missing or malformed data returns `matched=False, error=None`, following Agent Control conventions. The `error` field is reserved for evaluator crashes, not policy decisions.
 
 ## Related Projects
 

evaluators/contrib/financial-governance/src/agent_control_evaluator_financial_governance/__init__.py

@@ -3,7 +3,8 @@
 Provides two evaluators for enforcing financial policy on AI agent transactions:
 
 - ``financial_governance.spend_limit``: Tracks cumulative spend against rolling
-  period budgets and per-transaction caps.
+  period budgets and per-transaction caps.  Uses the :class:`BudgetLimit` /
+  :class:`BudgetWindow` model for expressive, scoped budget definitions.
 - ``financial_governance.transaction_policy``: Static policy checks — allowlists,
   blocklists, amount bounds, and permitted currencies.
 
@@ -14,14 +15,22 @@
 
     {
       "condition": {
-        "selector": {"path": "*"},
+        "selector": {"path": "input"},
         "evaluator": {
           "name": "financial_governance.spend_limit",
           "config": {
-            "max_per_transaction": 100.0,
-            "max_per_period": 1000.0,
-            "period_seconds": 86400,
-            "currency": "USDC"
+            "limits": [
+              {
+                "amount": "100.00",
+                "currency": "USDC"
+              },
+              {
+                "amount": "1000.00",
+                "currency": "USDC",
+                "scope_by": ["channel"],
+                "window": {"kind": "rolling", "seconds": 86400}
+              }
+            ]
           }
         }
       },
@@ -30,6 +39,8 @@
 """
 
 from agent_control_evaluator_financial_governance.spend_limit import (
+    BudgetLimit,
+    BudgetWindow,
     SpendLimitConfig,
     SpendLimitEvaluator,
 )
@@ -41,6 +52,8 @@
 __all__ = [
     "SpendLimitEvaluator",
     "SpendLimitConfig",
+    "BudgetLimit",
+    "BudgetWindow",
     "TransactionPolicyEvaluator",
     "TransactionPolicyConfig",
 ]

evaluators/contrib/financial-governance/src/agent_control_evaluator_financial_governance/spend_limit/__init__.py

@@ -1,12 +1,14 @@
 """Spend-limit evaluator package."""
 
-from .config import SpendLimitConfig
+from .config import BudgetLimit, BudgetWindow, SpendLimitConfig
 from .evaluator import SpendLimitEvaluator
 from .store import InMemorySpendStore, SpendStore
 
 __all__ = [
     "SpendLimitEvaluator",
     "SpendLimitConfig",
+    "BudgetLimit",
+    "BudgetWindow",
     "SpendStore",
     "InMemorySpendStore",
 ]