fix: address lan17 review — Decimal money, scoped budgets, store API

Addresses all feedback from lan17's review:

- Float → Decimal: All money amounts use Decimal for precision. Config,
  store protocol, evaluator, and transaction_policy all updated.
  Decimal(str(raw)) for safe conversion, float() only in metadata output.

- Scoped budget semantics: Documented tuple-based scope behavior.
  Channel+agent_id+session_id form a composite scope key. Independent
  per-dimension budgets documented as requiring separate get_spend calls.

- Store API: get_spend() now accepts start/end range instead of just
  since_timestamp. Backward compatible (end defaults to None).

- Fixed always-passing test: Removed 'or True' from context override
  test. Now asserts concrete store state per scope.

- Added lan17's exact test case: 90 USDC channel A, then 20 USDC
  channel B with channel_max_per_period=100. Second tx allowed.

- README: Updated custom store example with scope param and Decimal
  return. Fixed error handling docs. Added Known Limitations section
  (race condition, tuple scoping, package wiring).

- __init__.py: selector.path '*' → 'input' with context merge note.

67/67 tests passing.

Signed-off-by: up2itnow0822 <up2itnow0822@users.noreply.github.com>

Author: up2itnow0822

evaluators/contrib/financial-governance/README.md

@@ -26,11 +26,14 @@ Static policy checks with no state tracking. Enforces structural rules on indivi
 ## Installation
 
 ```bash
-# From the repo root (development)
+# From the repo root (development) — install directly from contrib path
 cd evaluators/contrib/financial-governance
 pip install -e ".[dev]"
 ```
 
+> **Note:** This package is not yet wired into `agent-control-evaluators` extras.
+> Install directly from the contrib path as shown above.
+
 ## Configuration
 
 ### Spend Limit
@@ -41,12 +44,12 @@ controls:
     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
+        max_per_transaction: "100.00"   # Max USDC per single payment (Decimal string)
+        max_per_period: "1000.00"       # Rolling 24h budget
+        period_seconds: 86400           # Budget window (default: 24 hours)
+        currency: USDC                  # Currency to govern
     selector:
-      path: input                     # Extract step.input (transaction dict)
+      path: input                       # Extract step.input (transaction dict)
     action: deny
 ```
 
@@ -61,8 +64,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
@@ -72,7 +75,7 @@ controls:
 
 Both evaluators support two selector configurations:
 
-- **`selector.path: "input"`** (recommended) — The evaluator receives `step.input` directly, which should be the transaction dict.
+- **`selector.path: "input"`** (recommended) — The evaluator receives `step.input` directly, which should be the transaction dict. Context fields (`channel`, `agent_id`, `session_id`) are merged from `step.context` into the transaction dict by the engine before evaluation.
 - **`selector.path: "*"`** — The evaluator receives the full Step object. It automatically extracts `step.input` for transaction fields and `step.context` for channel/agent/session metadata.
 
 ## Input Data Schema
@@ -82,7 +85,7 @@ The transaction dict (from `step.input`) should contain:
 ```python
 # step.input — transaction payload
 {
-    "amount": 50.0,              # required — transaction amount
+    "amount": "50.00",           # required — transaction amount (Decimal-compatible)
     "currency": "USDC",          # required — payment currency
     "recipient": "0xABC...",     # required — payment recipient
 }
@@ -98,28 +101,28 @@ Context fields (`channel`, `agent_id`, `session_id`) and per-context limit overr
 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,
+        "channel_max_per_transaction": "50.00",
+        "channel_max_per_period": "200.00",
     },
 )
 ```
 
-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: "input"`, context fields (channel, agent_id, session_id) are merged from `step.context` into the transaction dict by the engine. When using `selector.path: "*"`, the evaluator merges `step.context` fields itself.
 
 **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,
+    "channel_max_per_transaction": "50.00",
+    "channel_max_per_period": "200.00",
 })
 ```
 
@@ -130,6 +133,7 @@ Spend budgets are **scoped by context** — spend in channel A does not count ag
 The `SpendStore` protocol requires two methods. Implement them for your backend:
 
 ```python
+from decimal import Decimal
 from agent_control_evaluator_financial_governance.spend_limit import (
     SpendStore,
     SpendLimitConfig,
@@ -142,24 +146,39 @@ 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)),
+            (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:
+        end_clause = "AND recorded_at <= to_timestamp(%s)" if end is not None else ""
+        params = [currency, start]
+        if end is not None:
+            params.append(end)
         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 "
+            f"WHERE currency = %s AND recorded_at >= to_timestamp(%s) {end_clause}",
+            params,
         ).fetchone()
-        return float(row[0])
+        return Decimal(str(row[0]))
 
 # Use it:
 store = PostgresSpendStore("postgresql://...")
 evaluator = SpendLimitEvaluator(config, store=store)
 ```
 
+## Error Handling
+
+Malformed or incomplete runtime payloads (missing `amount`, missing `currency`, non-numeric values, etc.) return `matched=False, error=None` — they are treated as non-matching transactions, not evaluator errors. The `error` field is reserved for evaluator infrastructure failures (crashes, timeouts, missing dependencies).
+
 ## Running Tests
 
 ```bash
@@ -170,10 +189,26 @@ 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` to avoid float precision errors in financial calculations.
+2. **Decoupled from data source** — The `SpendStore` protocol means no new tables in core Agent Control. Bring your own persistence.
+3. **Context-aware limits** — Override keys in the evaluate data dict allow per-channel, per-agent, or per-session limits without multiple evaluator instances.
+4. **Python SDK compatible** — Uses the standard evaluator interface; works with both the server and the Python SDK evaluation engine.
+5. **Fail-open on malformed data** — Missing or invalid fields return `matched=False` with `error=None`, following Agent Control conventions.
+
+## Known Limitations
+
+### Race Condition (read-then-write is not atomic)
+The spend-limit evaluator reads current period spend and then writes a new record as two separate operations. Under concurrent load this can allow transactions to slip through just above the budget. For hard enforcement use a `SpendStore` implementation that provides atomic `check_and_record` semantics (e.g., a Redis `MULTI`/`EXEC` block or a PostgreSQL `SELECT ... FOR UPDATE`). The `InMemorySpendStore` is thread-safe within a single process but does not provide atomic check-and-record.
+
+### Tuple-Scoped Budgets
+When context fields (`channel`, `agent_id`, `session_id`) are all present, they form a **single composite scope key** — not independent per-dimension budgets. For example, a scope of `{"channel": "A", "agent_id": "bot-1"}` matches only records that have *both* `channel=="A"` AND `agent_id=="bot-1"`. To enforce truly independent per-channel and per-agent budgets you would need separate `get_spend()` calls with separate scope dicts.
+
+### Package Not Yet in Extras
+This package is not yet wired into the `agent-control-evaluators` extras install target. Install directly from the contrib path:
+
+```bash
+pip install -e "evaluators/contrib/financial-governance"
+```
 
 ## Related Projects
 

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

@@ -14,19 +14,28 @@
 
     {
       "condition": {
-        "selector": {"path": "*"},
+        "selector": {"path": "input"},
         "evaluator": {
           "name": "financial_governance.spend_limit",
           "config": {
-            "max_per_transaction": 100.0,
-            "max_per_period": 1000.0,
+            "max_per_transaction": "100.00",
+            "max_per_period": "1000.00",
             "period_seconds": 86400,
             "currency": "USDC"
           }
         }
       },
       "action": {"decision": "deny"}
     }
+
+Note on ``selector.path``:
+    Use ``selector.path: "input"`` (recommended) to pass ``step.input``
+    directly as the transaction dict.  Context fields (``channel``,
+    ``agent_id``, ``session_id``) are merged from ``step.context`` into
+    the transaction dict by the engine before evaluation.
+
+    Use ``selector.path: "*"`` to pass the full Step object; the evaluator
+    will extract ``step.input`` and merge ``step.context`` fields itself.
 """
 
 from agent_control_evaluator_financial_governance.spend_limit import (

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

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from decimal import Decimal
+
 from pydantic import Field, field_validator
 
 from agent_control_evaluators import EvaluatorConfig
@@ -15,9 +17,10 @@ class SpendLimitConfig(EvaluatorConfig):
     Attributes:
         max_per_transaction: Hard cap on any single transaction amount.  A
             transaction whose ``amount`` exceeds this value is blocked
-            regardless of accumulated period spend.  Set to ``0.0`` to disable.
+            regardless of accumulated period spend.  Set to ``Decimal("0")``
+            to disable.
         max_per_period: Maximum total spend allowed within the rolling
-            *period_seconds* window.  Set to ``0.0`` to disable.
+            *period_seconds* window.  Set to ``Decimal("0")`` to disable.
         period_seconds: Length of the rolling budget window in seconds.
             Defaults to ``86400`` (24 hours).
         currency: Currency symbol this policy applies to (e.g. ``"USDC"``).
@@ -27,27 +30,27 @@ class SpendLimitConfig(EvaluatorConfig):
     Example config dict::
 
         {
-          "max_per_transaction": 500.0,
-          "max_per_period": 5000.0,
+          "max_per_transaction": "500.00",
+          "max_per_period": "5000.00",
           "period_seconds": 86400,
           "currency": "USDC"
         }
     """
 
-    max_per_transaction: float = Field(
-        default=0.0,
-        ge=0.0,
+    max_per_transaction: Decimal = Field(
+        default=Decimal("0"),
+        ge=0,
         description=(
             "Per-transaction spend cap in *currency* units. "
-            "0.0 means no per-transaction limit."
+            "0 means no per-transaction limit."
         ),
     )
-    max_per_period: float = Field(
-        default=0.0,
-        ge=0.0,
+    max_per_period: Decimal = Field(
+        default=Decimal("0"),
+        ge=0,
         description=(
             "Maximum cumulative spend allowed in the rolling period window. "
-            "0.0 means no period limit."
+            "0 means no period limit."
         ),
     )
     period_seconds: int = Field(