consequence-gate 0.1.0__tar.gz

consequence_gate-0.1.0/PKG-INFO

@@ -0,0 +1,254 @@
+Metadata-Version: 2.4
+Name: consequence-gate
+Version: 0.1.0
+Summary: Speculative outcome-simulation layer for AI agent tool calls — predicts consequence (blast radius, irreversibility, velocity) before execution and steers agents toward safer alternatives.
+Author-email: Anandkrishnan Shnn <anandkrshnn@gmail.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/anandkrshnn-ai/consequence-gate
+Project-URL: Documentation, https://github.com/anandkrshnn-ai/consequence-gate#readme
+Project-URL: Repository, https://github.com/anandkrshnn-ai/consequence-gate
+Project-URL: Issues, https://github.com/anandkrshnn-ai/consequence-gate/issues
+Keywords: ai-agents,ai-safety,ai-governance,langchain,langgraph,mcp,agent-security,runtime-governance
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: langchain>=0.3.0
+Requires-Dist: langchain-agents>=0.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Provides-Extra: strands
+Requires-Dist: strands-agents>=0.1.0; extra == "strands"
+Provides-Extra: mcp
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2.0; extra == "langgraph"
+
+# consequence-gate
+
+A speculative outcome-simulation layer for AI agent tool calls. It sits
+**upstream** of static runtime access gates (AgentWall, AWS Strands
+`BeforeToolCallEvent`, MCP proxies, Prisma AIRS) and asks a different
+question than they do.
+
+Static gates ask: *does this call match an allowed pattern?*
+`consequence-gate` asks: *what will this call actually do, and is that
+outcome safe?*
+
+## Why this exists
+
+Static runtime gates are fast (sub-millisecond) and effective at schema
+validation, RBAC, and pattern matching -- but a schema-valid,
+policy-compliant call can still be consequence-catastrophic. A
+`process_claim(amount=50000)` call can pass every static check while
+pushing an account over its daily velocity limit via an irreversible
+instant transfer. `consequence-gate` projects the *outcome* of a call
+(balance deltas, row-count blast radius, FK cascade depth,
+irreversibility) before the call reaches your existing static gate, and
+either passes it through, asks a human, denies it outright, or steers
+the agent toward a pre-vetted safer alternative.
+
+This is explicitly **not** a replacement for AgentWall / Strands / MCP
+proxies -- it's a prediction layer that runs before them, in the same
+pipeline.
+
+## Core contracts
+
+- **No silent argument mutation.** Steering returns structured guidance
+  and a suggested alternative call; the agent (or a human) still has to
+  commit to it. This preserves the audit property that every executed
+  call was one the agent explicitly chose.
+- **Idempotency keys are derived from the transaction's own natural key**
+  (e.g. `claim_id`, or `table + filter hash`), never a fresh random token
+  per retry -- otherwise a lost-response retry looks like a brand-new
+  transaction instead of a duplicate.
+- **Hard retry cap on STEER.** Regardless of guidance quality, retries
+  are capped (default: 2) before forcing escalation to a human, as a
+  backstop against loop-thrashing.
+- **Confidence-gated escalation.** Low-confidence projections route to
+  `ASK`, never to a confident-looking `ALLOW` or `DENY` -- an
+  unfounded heuristic is worse than admitting uncertainty.
+
+## Modules
+
+- `consequence_gate.simulators.financial` -- **functional**: disbursement / claim / refund
+  velocity and irreversibility modeling.
+- `consequence_gate.simulators.database` -- **functional**: row-count blast radius via the
+  DB's own query planner (`EXPLAIN`, not hardcoded selectivity constants)
+  and recursive `ON DELETE CASCADE` graph walking.
+- `consequence_gate.simulators.communications` -- **functional**: outbound email/SMS/notification
+  blast radius, unsubscribe suppression compliance, canary cohort analysis, sender reputation impact.
+- `consequence_gate.core` -- shared models, the confidence/threshold
+  evaluator, and the idempotency-locked circuit breaker.
+- `consequence_gate.integrations.strands_hook` -- **functional**: AWS Strands
+  `BeforeToolCallEvent` adapter with full `ALLOW`/`DENY`/`ASK`/`STEER` lifecycle.
+- `consequence_gate.integrations.mcp_proxy` -- **functional**: MCP stdio proxy
+  intercepting `tools/call` requests, returning JSON-RPC errors or `isError=true` tool results.
+- `consequence_gate.integrations.langgraph_hook` -- **functional**: LangGraph middleware
+  (`@wrap_tool_call`) intercepting tool execution with full `ALLOW`/`DENY`/`ASK`/`STEER` lifecycle.
+- `consequence_gate.backtest` -- offline JSONL trace replay harness and
+  four-quadrant FP/FN/TN report generator, for evaluating this layer
+  against historical execution logs with zero production integration.
+
+## Quickstart
+
+### Installation
+
+```bash
+pip install -e ".[dev]"
+pytest
+python examples/run_backtest_demo.py
+```
+
+### AWS Strands Integration
+
+```python
+from consequence_gate.integrations.strands_hook import create_financial_gate_hook
+from strands.agents import Agent
+
+hook = create_financial_gate_hook(
+    daily_tier_limit_inr=25000.0,
+    instant_wire_threshold=10000.0,
+    max_retries=2,
+    context_provider=lambda event: {
+        "account_rolling_24h_spend": get_current_spend(event),
+        "kyc_verified": is_kyc_verified(event),
+    },
+)
+
+agent = Agent(hooks=[hook])
+response = agent("Process this claim for 50,000 INR")
+```
+
+### MCP Proxy Integration
+
+Run as a standalone proxy in front of any MCP server:
+
+```bash
+# Financial disbursement gate
+python -m consequence_gate.integrations.examples.run_mcp_proxy financial \\
+    --downstream-command "npx -y @modelcontextprotocol/server-postgres postgresql://localhost/mydb" \\
+    --daily-tier-limit 25000 \\
+    --instant-wire-threshold 10000
+```
+
+Configure in Claude Desktop / Cursor / Windsurf:
+
+```json
+{
+  "mcpServers": {
+    "my-consequence-gate": {
+      "command": "python",
+      "args": ["-m", "consequence_gate.integrations.examples.run_mcp_proxy", "financial", "--downstream-command", "npx -y @modelcontextprotocol/server-postgres postgresql://localhost/mydb"]
+    }
+  }
+}
+```
+
+### LangGraph Integration
+
+```python
+from langchain.agents import create_agent
+from consequence_gate.integrations.langgraph_hook import create_financial_gate_middleware
+
+middleware = create_financial_gate_middleware(
+    daily_tier_limit_inr=25000.0,
+    instant_wire_threshold=10000.0,
+    max_retries=2,
+)
+
+agent = create_agent(
+    model="claude-sonnet-4",
+    tools=[my_tool],
+    middleware=[middleware],
+)
+```
+
+Run the example:
+
+```bash
+python -m consequence_gate.integrations.examples.run_langgraph
+```
+
+### Database Deletion Gate (Strands)
+
+```python
+from consequence_gate.integrations.strands_hook import create_database_gate_hook
+
+hook = create_database_gate_hook(
+    max_autonomous_delete_rows=100,
+    db_conn=get_db_connection(),
+    max_retries=2,
+    context_provider=lambda event: {
+        "table_metadata": get_table_metadata(event),
+    },
+)
+
+agent = Agent(hooks=[hook])
+```
+
+### Communications Blast Gate (Strands)
+
+```python
+from consequence_gate.integrations.strands_hook import create_communication_gate_hook
+
+hook = create_communication_gate_hook(
+    max_autonomous_recipients=10000,
+    canary_min_size=100,
+    canary_max_bounce_rate=0.05,
+    canary_max_complaint_rate=0.01,
+    context_provider=lambda event: {
+        "segment_counts": get_segment_counts(event),
+        "recent_unsubscribes": get_recent_unsubscribes(event),
+        "historical_bounce_rate": 0.02,
+        "historical_complaint_rate": 0.005,
+    },
+)
+
+agent = Agent(hooks=[hook])
+```
+
+## Decision Matrix
+
+| Decision | Strands | MCP | LangGraph |
+|----------|---------|-----|-----------|
+| `ALLOW` | Executes normally | Forwarded to downstream MCP server | Tool executes via handler(request) |
+| `DENY` | `BLOCKED: <reason>` | JSON-RPC error (code=-32603) | Raises `ValueError("BLOCKED: ...")` |
+| `ASK` | `ESCALATION_REQUIRED: <reason>` | `isError=true` tool result | Raises `ValueError("ESCALATION_REQUIRED: ...")` |
+| `STEER` | `STEER_GUIDANCE: <guidance>\nSuggested alternative...` | `isError=true` + guidance | `ToolMessage(content="STEER_GUIDANCE: ...", status="error")` |
+
+## Backtest Workflow
+
+Before deploying to production, run an offline backtest against historical
+execution traces:
+
+1. Export 1,000-5,000 tool-call traces as JSONL (see `examples/backtest_sample_traces.jsonl`)
+2. Run `python examples/run_backtest_demo.py` against your traces
+3. Review the four-quadrant breakdown:
+   - True Negative: correctly allowed benign operations
+   - False Negative Caught: schema-valid calls that would have breached limits
+   - False Positive Relieved: over-blocking that the simulator would have avoided
+   - Steer Recovery Rate: percentage of blocked turns that could have completed via guidance
+
+## Status
+
+- **Financial simulator**: functional with unit tests
+- **Database simulator**: functional with unit tests (EXPLAIN-based row estimation, recursive FK cascade walk)
+- **Communications simulator**: functional with unit tests (blast radius, unsubscribe compliance, canary cohorts, reputation impact)
+- **Strands integration**: functional with unit tests (full `ALLOW`/`DENY`/`ASK`/`STEER` lifecycle)
+- **MCP integration**: functional with unit tests (stdio transport, JSON-RPC error handling)
+- **LangGraph integration**: functional with unit tests (`@wrap_tool_call` middleware pattern)
+
+## License
+
+Apache-2.0

consequence_gate-0.1.0/README.md

@@ -0,0 +1,218 @@
+# consequence-gate
+
+A speculative outcome-simulation layer for AI agent tool calls. It sits
+**upstream** of static runtime access gates (AgentWall, AWS Strands
+`BeforeToolCallEvent`, MCP proxies, Prisma AIRS) and asks a different
+question than they do.
+
+Static gates ask: *does this call match an allowed pattern?*
+`consequence-gate` asks: *what will this call actually do, and is that
+outcome safe?*
+
+## Why this exists
+
+Static runtime gates are fast (sub-millisecond) and effective at schema
+validation, RBAC, and pattern matching -- but a schema-valid,
+policy-compliant call can still be consequence-catastrophic. A
+`process_claim(amount=50000)` call can pass every static check while
+pushing an account over its daily velocity limit via an irreversible
+instant transfer. `consequence-gate` projects the *outcome* of a call
+(balance deltas, row-count blast radius, FK cascade depth,
+irreversibility) before the call reaches your existing static gate, and
+either passes it through, asks a human, denies it outright, or steers
+the agent toward a pre-vetted safer alternative.
+
+This is explicitly **not** a replacement for AgentWall / Strands / MCP
+proxies -- it's a prediction layer that runs before them, in the same
+pipeline.
+
+## Core contracts
+
+- **No silent argument mutation.** Steering returns structured guidance
+  and a suggested alternative call; the agent (or a human) still has to
+  commit to it. This preserves the audit property that every executed
+  call was one the agent explicitly chose.
+- **Idempotency keys are derived from the transaction's own natural key**
+  (e.g. `claim_id`, or `table + filter hash`), never a fresh random token
+  per retry -- otherwise a lost-response retry looks like a brand-new
+  transaction instead of a duplicate.
+- **Hard retry cap on STEER.** Regardless of guidance quality, retries
+  are capped (default: 2) before forcing escalation to a human, as a
+  backstop against loop-thrashing.
+- **Confidence-gated escalation.** Low-confidence projections route to
+  `ASK`, never to a confident-looking `ALLOW` or `DENY` -- an
+  unfounded heuristic is worse than admitting uncertainty.
+
+## Modules
+
+- `consequence_gate.simulators.financial` -- **functional**: disbursement / claim / refund
+  velocity and irreversibility modeling.
+- `consequence_gate.simulators.database` -- **functional**: row-count blast radius via the
+  DB's own query planner (`EXPLAIN`, not hardcoded selectivity constants)
+  and recursive `ON DELETE CASCADE` graph walking.
+- `consequence_gate.simulators.communications` -- **functional**: outbound email/SMS/notification
+  blast radius, unsubscribe suppression compliance, canary cohort analysis, sender reputation impact.
+- `consequence_gate.core` -- shared models, the confidence/threshold
+  evaluator, and the idempotency-locked circuit breaker.
+- `consequence_gate.integrations.strands_hook` -- **functional**: AWS Strands
+  `BeforeToolCallEvent` adapter with full `ALLOW`/`DENY`/`ASK`/`STEER` lifecycle.
+- `consequence_gate.integrations.mcp_proxy` -- **functional**: MCP stdio proxy
+  intercepting `tools/call` requests, returning JSON-RPC errors or `isError=true` tool results.
+- `consequence_gate.integrations.langgraph_hook` -- **functional**: LangGraph middleware
+  (`@wrap_tool_call`) intercepting tool execution with full `ALLOW`/`DENY`/`ASK`/`STEER` lifecycle.
+- `consequence_gate.backtest` -- offline JSONL trace replay harness and
+  four-quadrant FP/FN/TN report generator, for evaluating this layer
+  against historical execution logs with zero production integration.
+
+## Quickstart
+
+### Installation
+
+```bash
+pip install -e ".[dev]"
+pytest
+python examples/run_backtest_demo.py
+```
+
+### AWS Strands Integration
+
+```python
+from consequence_gate.integrations.strands_hook import create_financial_gate_hook
+from strands.agents import Agent
+
+hook = create_financial_gate_hook(
+    daily_tier_limit_inr=25000.0,
+    instant_wire_threshold=10000.0,
+    max_retries=2,
+    context_provider=lambda event: {
+        "account_rolling_24h_spend": get_current_spend(event),
+        "kyc_verified": is_kyc_verified(event),
+    },
+)
+
+agent = Agent(hooks=[hook])
+response = agent("Process this claim for 50,000 INR")
+```
+
+### MCP Proxy Integration
+
+Run as a standalone proxy in front of any MCP server:
+
+```bash
+# Financial disbursement gate
+python -m consequence_gate.integrations.examples.run_mcp_proxy financial \\
+    --downstream-command "npx -y @modelcontextprotocol/server-postgres postgresql://localhost/mydb" \\
+    --daily-tier-limit 25000 \\
+    --instant-wire-threshold 10000
+```
+
+Configure in Claude Desktop / Cursor / Windsurf:
+
+```json
+{
+  "mcpServers": {
+    "my-consequence-gate": {
+      "command": "python",
+      "args": ["-m", "consequence_gate.integrations.examples.run_mcp_proxy", "financial", "--downstream-command", "npx -y @modelcontextprotocol/server-postgres postgresql://localhost/mydb"]
+    }
+  }
+}
+```
+
+### LangGraph Integration
+
+```python
+from langchain.agents import create_agent
+from consequence_gate.integrations.langgraph_hook import create_financial_gate_middleware
+
+middleware = create_financial_gate_middleware(
+    daily_tier_limit_inr=25000.0,
+    instant_wire_threshold=10000.0,
+    max_retries=2,
+)
+
+agent = create_agent(
+    model="claude-sonnet-4",
+    tools=[my_tool],
+    middleware=[middleware],
+)
+```
+
+Run the example:
+
+```bash
+python -m consequence_gate.integrations.examples.run_langgraph
+```
+
+### Database Deletion Gate (Strands)
+
+```python
+from consequence_gate.integrations.strands_hook import create_database_gate_hook
+
+hook = create_database_gate_hook(
+    max_autonomous_delete_rows=100,
+    db_conn=get_db_connection(),
+    max_retries=2,
+    context_provider=lambda event: {
+        "table_metadata": get_table_metadata(event),
+    },
+)
+
+agent = Agent(hooks=[hook])
+```
+
+### Communications Blast Gate (Strands)
+
+```python
+from consequence_gate.integrations.strands_hook import create_communication_gate_hook
+
+hook = create_communication_gate_hook(
+    max_autonomous_recipients=10000,
+    canary_min_size=100,
+    canary_max_bounce_rate=0.05,
+    canary_max_complaint_rate=0.01,
+    context_provider=lambda event: {
+        "segment_counts": get_segment_counts(event),
+        "recent_unsubscribes": get_recent_unsubscribes(event),
+        "historical_bounce_rate": 0.02,
+        "historical_complaint_rate": 0.005,
+    },
+)
+
+agent = Agent(hooks=[hook])
+```
+
+## Decision Matrix
+
+| Decision | Strands | MCP | LangGraph |
+|----------|---------|-----|-----------|
+| `ALLOW` | Executes normally | Forwarded to downstream MCP server | Tool executes via handler(request) |
+| `DENY` | `BLOCKED: <reason>` | JSON-RPC error (code=-32603) | Raises `ValueError("BLOCKED: ...")` |
+| `ASK` | `ESCALATION_REQUIRED: <reason>` | `isError=true` tool result | Raises `ValueError("ESCALATION_REQUIRED: ...")` |
+| `STEER` | `STEER_GUIDANCE: <guidance>\nSuggested alternative...` | `isError=true` + guidance | `ToolMessage(content="STEER_GUIDANCE: ...", status="error")` |
+
+## Backtest Workflow
+
+Before deploying to production, run an offline backtest against historical
+execution traces:
+
+1. Export 1,000-5,000 tool-call traces as JSONL (see `examples/backtest_sample_traces.jsonl`)
+2. Run `python examples/run_backtest_demo.py` against your traces
+3. Review the four-quadrant breakdown:
+   - True Negative: correctly allowed benign operations
+   - False Negative Caught: schema-valid calls that would have breached limits
+   - False Positive Relieved: over-blocking that the simulator would have avoided
+   - Steer Recovery Rate: percentage of blocked turns that could have completed via guidance
+
+## Status
+
+- **Financial simulator**: functional with unit tests
+- **Database simulator**: functional with unit tests (EXPLAIN-based row estimation, recursive FK cascade walk)
+- **Communications simulator**: functional with unit tests (blast radius, unsubscribe compliance, canary cohorts, reputation impact)
+- **Strands integration**: functional with unit tests (full `ALLOW`/`DENY`/`ASK`/`STEER` lifecycle)
+- **MCP integration**: functional with unit tests (stdio transport, JSON-RPC error handling)
+- **LangGraph integration**: functional with unit tests (`@wrap_tool_call` middleware pattern)
+
+## License
+
+Apache-2.0

consequence_gate-0.1.0/consequence_gate/__init__.py

@@ -0,0 +1,3 @@
+"""consequence-gate: speculative outcome-simulation layer for AI agent tool calls."""
+
+__version__ = "0.1.0"

consequence_gate-0.1.0/consequence_gate/backtest/harness.py

@@ -0,0 +1,43 @@
+"""
+Offline backtest harness: replays historical JSONL tool-call traces
+through a simulator + evaluator, WITHOUT re-executing anything, to
+measure the four-quadrant FP/FN/TN/steer-recovery breakdown against
+the trace's recorded existing_gate_decision and actual_execution_status.
+"""
+
+import json
+from typing import Callable, Dict, Iterable, List
+
+
+def load_traces(path: str) -> List[Dict]:
+    traces = []
+    with open(path) as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                traces.append(json.loads(line))
+    return traces
+
+
+def run_backtest(traces: Iterable[Dict], simulate_and_evaluate: Callable[[Dict], str]) -> List[Dict]:
+    """
+    simulate_and_evaluate: function(trace) -> decision string ("ALLOW"/"DENY"/"ASK"/"STEER")
+    Returns per-trace records annotated with quadrant classification.
+    """
+    results = []
+    for trace in traces:
+        new_decision = simulate_and_evaluate(trace)
+        old_decision = trace.get("existing_gate_decision", "ALLOW")
+        outcome = trace.get("actual_execution_status", "UNKNOWN")
+
+        if old_decision == "ALLOW" and new_decision in ("DENY", "STEER", "ASK") and outcome != "SUCCESS":
+            quadrant = "FALSE_NEGATIVE_CAUGHT"
+        elif old_decision in ("DENY", "ASK") and new_decision == "ALLOW":
+            quadrant = "FALSE_POSITIVE_RELIEVED"
+        elif old_decision == "ALLOW" and new_decision == "ALLOW":
+            quadrant = "TRUE_NEGATIVE"
+        else:
+            quadrant = "OTHER"
+
+        results.append({**trace, "simulated_decision": new_decision, "quadrant": quadrant})
+    return results

consequence_gate-0.1.0/consequence_gate/backtest/reporter.py

@@ -0,0 +1,20 @@
+"""
+Generates the four-quadrant FP/FN breakdown report from backtest results.
+"""
+
+from collections import Counter
+from typing import Dict, List
+
+
+def generate_report(results: List[Dict]) -> Dict:
+    counts = Counter(r["quadrant"] for r in results)
+    total = len(results)
+    return {
+        "total_traces": total,
+        "true_negative": counts.get("TRUE_NEGATIVE", 0),
+        "false_negative_caught": counts.get("FALSE_NEGATIVE_CAUGHT", 0),
+        "false_positive_relieved": counts.get("FALSE_POSITIVE_RELIEVED", 0),
+        "other": counts.get("OTHER", 0),
+        "false_negative_rate": counts.get("FALSE_NEGATIVE_CAUGHT", 0) / total if total else 0.0,
+        "false_positive_relief_rate": counts.get("FALSE_POSITIVE_RELIEVED", 0) / total if total else 0.0,
+    }

consequence_gate-0.1.0/consequence_gate/cli.py

@@ -0,0 +1,75 @@
+"""
+CLI entry point for consequence-gate.
+"""
+
+import argparse
+import json
+import sys
+from consequence_gate import __version__
+from consequence_gate.backtest.harness import load_traces, run_backtest
+from consequence_gate.backtest.reporter import generate_report
+
+
+def default_evaluator(trace: dict) -> str:
+    """Heuristic evaluator for CLI demo and trace analysis."""
+    tool = trace.get("tool_name", "")
+    args = trace.get("tool_args", {})
+
+    tool_lower = tool.lower()
+    args_str = str(args).lower()
+
+    if any(k in tool_lower for k in ("delete", "drop", "purge", "truncate")) or any(
+        k in args_str for k in ("drop ", "delete from", "truncate ", "purge")
+    ):
+        return "DENY"
+    if "transfer" in tool.lower() or "pay" in tool.lower():
+        amount = args.get("amount", 0)
+        if isinstance(amount, (int, float)) and amount > 5000:
+            return "ASK"
+    return "ALLOW"
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="consequence-gate",
+        description="Speculative outcome-simulation gate & trace backtesting for AI agent tool calls.",
+    )
+    parser.add_argument("-v", "--version", action="version", version=f"%(prog)s {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command", help="Available subcommands")
+
+    # Backtest subcommand
+    bt_parser = subparsers.add_parser("backtest", help="Run offline backtesting on a JSONL trace file")
+    bt_parser.add_argument("file", help="Path to JSONL file containing recorded agent traces")
+    bt_parser.add_argument("--json", action="store_true", help="Output results in JSON format")
+
+    args = parser.parse_args()
+
+    if args.command == "backtest":
+        try:
+            traces = load_traces(args.file)
+            results = run_backtest(traces, default_evaluator)
+            report = generate_report(results)
+
+            if args.json:
+                print(json.dumps(report, indent=2))
+            else:
+                print("\n================ CONSEQUENCE GATE BACKTEST REPORT ================")
+                print(f"Total Traces Evaluated:      {report['total_traces']}")
+                print(f"True Negatives:              {report['true_negative']}")
+                print(f"False Negatives Caught:      {report['false_negative_caught']}")
+                print(f"False Positives Relieved:    {report['false_positive_relieved']}")
+                print(f"Other / Unclassified:        {report['other']}")
+                print("-----------------------------------------------------------------")
+                print(f"False Negative Catch Rate:   {report['false_negative_rate']:.2%}")
+                print(f"False Positive Relief Rate:  {report['false_positive_relief_rate']:.2%}")
+                print("=================================================================\n")
+        except Exception as e:
+            print(f"Error executing backtest: {e}", file=sys.stderr)
+            sys.exit(1)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

consequence_gate-0.1.0/consequence_gate/core/circuit_breaker.py

@@ -0,0 +1,56 @@
+"""
+SteerCircuitBreaker: idempotency-locked retry cap for STEER decisions.
+
+Design contract (see project history / design notes):
+- The idempotency token is derived ONCE from the transaction's own natural
+  key (e.g. claim_id, table+filter hash) -- never regenerated per retry.
+  A fresh UUID per attempt defeats duplicate-execution protection.
+- Responses are cached per token, so a retry with the same natural key
+  returns the cached result instead of re-executing (Stripe-style contract).
+- Retry count is tracked server-side per token, with a hard cap. Once
+  exceeded, the breaker forces ASK (human escalation) regardless of how
+  good the steering guidance is -- this is a backstop against
+  loop-thrashing, independent of guidance quality.
+"""
+
+from typing import Any, Dict
+from .models import GateDecision, EvaluationResult
+
+
+class SteerCircuitBreaker:
+    def __init__(self, max_retries: int = 2):
+        self.max_retries = max_retries
+        self._attempts: Dict[str, int] = {}
+        self._responses: Dict[str, EvaluationResult] = {}
+
+    def token_for(self, natural_key: str) -> str:
+        return f"steer_{natural_key}"
+
+    def resolve(self, natural_key: str, confidence: float,
+                base_steer: Dict[str, Any]) -> EvaluationResult:
+        token = self.token_for(natural_key)
+
+        if token in self._responses:
+            return self._responses[token]
+
+        attempt = self._attempts.get(token, 0)
+
+        if attempt >= self.max_retries:
+            result = EvaluationResult(
+                decision=GateDecision.ASK,
+                confidence=confidence,
+                reason=f"Steer circuit breaker tripped ({attempt}/{self.max_retries}). Escalating to human.",
+            )
+            self._responses[token] = result
+            return result
+
+        self._attempts[token] = attempt + 1
+        base_steer.setdefault("suggested_args", {})["idempotency_key"] = token
+
+        result = EvaluationResult(
+            decision=GateDecision.STEER,
+            confidence=confidence,
+            reason=f"Steered to safer path (attempt {attempt + 1}/{self.max_retries}).",
+            steer_payload=base_steer,
+        )
+        return result