consequence-gate 0.1.0__py3-none-any.whl

consequence_gate/simulators/communications.py

@@ -0,0 +1,290 @@
+"""
+OutboundCommunicationSimulator: outcome simulator for email/SMS/notification blasts.
+
+Models:
+- Recipient blast radius (total recipients, segment breakdown)
+- Unsubscribe suppression check (cross-references recent unsubscribes)
+- Canary cohort analysis (sends to small cohort first, measures bounce/complaint rate)
+- Reputation risk scoring (sender domain reputation impact based on volume + content type)
+- Irreversibility: once sent, email/SMS cannot be recalled (1.0); in-app notifications can be retracted (0.3)
+
+Unlike financial/database simulators, this domain has no "partial execution" state —
+a send is atomic and irreversible. The gate's job is to prevent oversends before they
+happen, not to model intermediate states.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+from enum import Enum
+
+from ..core.models import GateDecision, EvaluationResult
+from ..core.circuit_breaker import SteerCircuitBreaker
+
+
+class CommunicationChannel(str, Enum):
+    EMAIL = "email"
+    SMS = "sms"
+    PUSH = "push_notification"
+    IN_APP = "in_app_notification"
+
+
+@dataclass
+class CommunicationBlastDelta:
+    tool_name: str
+    channel: str
+    total_recipients: int
+    segment_breakdown: Dict[str, int]
+    has_unsubscribe_suppression: bool
+    canary_cohort_size: int
+    predicted_bounce_rate: float
+    predicted_complaint_rate: float
+    sender_reputation_impact: float
+    irreversibility_score: float
+    confidence: float
+    natural_key: str
+    simulated_side_effects: List[str] = field(default_factory=list)
+
+
+class OutboundCommunicationSimulator:
+    """
+    Simulates outbound communication blast radius and reputation risk.
+    
+    Key design decisions:
+    - No partial execution modeling — sends are atomic and irreversible.
+    - Unsubscribe suppression is mandatory for compliance (CAN-SPAM, GDPR).
+    - Canary cohorts are optional but recommended for high-volume sends.
+    - Reputation impact is modeled as a function of volume + predicted complaint rate.
+    """
+
+    def __init__(
+        self,
+        max_autonomous_recipients: int = 10000,
+        max_daily_send_limit: int = 100000,
+        canary_min_size: int = 100,
+        canary_max_bounce_rate: float = 0.05,
+        canary_max_complaint_rate: float = 0.01,
+    ):
+        self.max_autonomous_recipients = max_autonomous_recipients
+        self.max_daily_send_limit = max_daily_send_limit
+        self.canary_min_size = canary_min_size
+        self.canary_max_bounce_rate = canary_max_bounce_rate
+        self.canary_max_complaint_rate = canary_max_complaint_rate
+
+    def simulate(
+        self,
+        tool_name: str,
+        args: Dict[str, Any],
+        context: Dict[str, Any],
+    ) -> CommunicationBlastDelta:
+        channel = args.get("channel", "email").lower()
+        recipient_list = args.get("recipients", [])
+        segment_filter = args.get("segment_filter")
+        suppress_unsubscribes = args.get("suppress_unsubscribes", True)
+        canary_enabled = args.get("canary_enabled", False)
+        canary_size = args.get("canary_size", self.canary_min_size)
+        
+        natural_key = f"{channel}:{args.get('campaign_id') or len(recipient_list)}"
+
+        # Calculate total recipients
+        if recipient_list:
+            total_recipients = len(recipient_list)
+        elif segment_filter and "segment_counts" in context:
+            total_recipients = context["segment_counts"].get(segment_filter, 0)
+        else:
+            total_recipients = 0
+
+        # Segment breakdown
+        segment_breakdown = {}
+        if "segment_counts" in context and segment_filter:
+            segment_breakdown = {segment_filter: total_recipients}
+        elif "segment_counts" in context:
+            segment_breakdown = context["segment_counts"]
+        else:
+            segment_breakdown = {"unknown": total_recipients}
+
+        # Unsubscribe suppression check
+        has_suppression = bool(suppress_unsubscribes)
+        recipients_without_suppression = total_recipients if not has_suppression else 0
+
+        # Canary cohort analysis
+        if canary_enabled and total_recipients > self.canary_min_size:
+            historical_bounce_rate = context.get("historical_bounce_rate", 0.02)
+            historical_complaint_rate = context.get("historical_complaint_rate", 0.005)
+            predicted_bounce = historical_bounce_rate
+            predicted_complaint = historical_complaint_rate
+        else:
+            predicted_bounce = 0.0
+            predicted_complaint = 0.0
+
+        # Sender reputation impact
+        reputation_impact = -(total_recipients * predicted_complaint) / 5000.0
+        if channel == "sms":
+            reputation_impact *= 1.5
+
+        # Irreversibility scoring
+        if channel in ("email", "sms"):
+            irreversibility = 1.0
+        elif channel == "push_notification":
+            irreversibility = 0.8
+        else:
+            irreversibility = 0.3
+
+        # Confidence scoring
+        has_segment_data = "segment_counts" in context
+        has_historical_data = "historical_bounce_rate" in context
+        confidence = 0.90 if (has_segment_data and has_historical_data) else 0.50
+
+        side_effects = []
+        if total_recipients > self.max_autonomous_recipients:
+            side_effects.append(
+                f"Recipient count ({total_recipients}) exceeds autonomous threshold "
+                f"({self.max_autonomous_recipients})"
+            )
+        if not suppress_unsubscribes and total_recipients > 0:
+            side_effects.append(
+                f"COMPLIANCE RISK: {recipients_without_suppression} recipients without unsubscribe suppression"
+            )
+        if canary_enabled and predicted_bounce > self.canary_max_bounce_rate:
+            side_effects.append(
+                f"Canary predicts bounce rate {predicted_bounce:.1%} exceeds threshold {self.canary_max_bounce_rate:.1%}"
+            )
+        if canary_enabled and predicted_complaint > self.canary_max_complaint_rate:
+            side_effects.append(
+                f"Canary predicts complaint rate {predicted_complaint:.2%} exceeds threshold {self.canary_max_complaint_rate:.1%}"
+            )
+        if reputation_impact < -0.5:
+            side_effects.append(
+                f"Severe sender reputation risk: {reputation_impact:.2f} impact score"
+            )
+
+        return CommunicationBlastDelta(
+            tool_name=tool_name,
+            channel=channel,
+            total_recipients=total_recipients,
+            segment_breakdown=segment_breakdown,
+            has_unsubscribe_suppression=has_suppression,
+            canary_cohort_size=canary_size if canary_enabled else 0,
+            predicted_bounce_rate=predicted_bounce,
+            predicted_complaint_rate=predicted_complaint,
+            sender_reputation_impact=reputation_impact,
+            irreversibility_score=irreversibility,
+            confidence=confidence,
+            natural_key=natural_key,
+            simulated_side_effects=side_effects,
+        )
+
+    def evaluate(
+        self,
+        delta: CommunicationBlastDelta,
+        circuit_breaker: SteerCircuitBreaker,
+    ) -> EvaluationResult:
+        if delta.confidence < 0.60:
+            return EvaluationResult(
+                decision=GateDecision.ASK,
+                confidence=delta.confidence,
+                reason="Insufficient context (missing segment or historical data) to evaluate send safely.",
+            )
+
+        if not delta.has_unsubscribe_suppression and delta.total_recipients > 0:
+            return EvaluationResult(
+                decision=GateDecision.DENY,
+                confidence=delta.confidence,
+                reason=f"COMPLIANCE VIOLATION: Cannot send to {delta.total_recipients} recipients without unsubscribe suppression (CAN-SPAM/GDPR).",
+            )
+
+        if delta.sender_reputation_impact < -0.5:
+            return EvaluationResult(
+                decision=GateDecision.DENY,
+                confidence=delta.confidence,
+                reason=f"Critical sender reputation risk: {delta.sender_reputation_impact:.2f} impact score would severely damage deliverability.",
+            )
+
+        if delta.total_recipients > self.max_autonomous_recipients:
+            canary_size = min(self.canary_min_size, delta.total_recipients // 10)
+            base_steer = {
+                "guidance": (
+                    f"Direct send to {delta.total_recipients} recipients exceeds autonomous threshold "
+                    f"({self.max_autonomous_recipients}). Option A: Run canary cohort of {canary_size} recipients first. "
+                    f"Option B: Stage send in batches of {self.max_autonomous_recipients} with manual approval between batches."
+                ),
+                "suggested_tool": "send_canary_cohort",
+                "suggested_args": {
+                    "channel": delta.channel,
+                    "recipients": f"canary_cohort_{canary_size}",
+                    "canary_enabled": True,
+                    "canary_size": canary_size,
+                    "suppress_unsubscribes": True,
+                    "idempotency_key": None,
+                },
+            }
+            return circuit_breaker.resolve(delta.natural_key, delta.confidence, base_steer)
+
+        if delta.canary_cohort_size > 0 and (
+            delta.predicted_bounce_rate > self.canary_max_bounce_rate
+            or delta.predicted_complaint_rate > self.canary_max_complaint_rate
+        ):
+            base_steer = {
+                "guidance": (
+                    f"Canary cohort predicts {delta.predicted_bounce_rate:.1%} bounce rate and "
+                    f"{delta.predicted_complaint_rate:.2%} complaint rate, exceeding safe thresholds. "
+                    f"Recommend: Run list hygiene (remove hard bounces, re-engagement campaign) before full send."
+                ),
+                "suggested_tool": "run_list_hygiene",
+                "suggested_args": {
+                    "segment": list(delta.segment_breakdown.keys())[0],
+                    "remove_hard_bounces": True,
+                    "reengagement_threshold_days": 90,
+                },
+            }
+            return circuit_breaker.resolve(delta.natural_key, delta.confidence, base_steer)
+
+        return EvaluationResult(
+            decision=GateDecision.ALLOW,
+            confidence=delta.confidence,
+            reason=f"Send to {delta.total_recipients} recipients is within safe autonomous operational boundary.",
+        )
+
+
+def create_communication_gate_hook(
+    max_autonomous_recipients: int = 10000,
+    max_daily_send_limit: int = 100000,
+    canary_min_size: int = 100,
+    canary_max_bounce_rate: float = 0.05,
+    canary_max_complaint_rate: float = 0.01,
+    max_retries: int = 2,
+    context_provider=None,
+):
+    """
+    Factory for creating a communication gate simulator.
+    
+    Usage:
+        simulator = create_communication_gate_hook(
+            max_autonomous_recipients=10000,
+            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,
+            },
+        )
+    """
+    from ..integrations.strands_hook import ConsequenceGateHook
+    
+    simulator = OutboundCommunicationSimulator(
+        max_autonomous_recipients=max_autonomous_recipients,
+        max_daily_send_limit=max_daily_send_limit,
+        canary_min_size=canary_min_size,
+        canary_max_bounce_rate=canary_max_bounce_rate,
+        canary_max_complaint_rate=canary_max_complaint_rate,
+    )
+    breaker = SteerCircuitBreaker(max_retries=max_retries)
+
+    def evaluator(delta, circuit_breaker):
+        return simulator.evaluate(delta, circuit_breaker)
+
+    return ConsequenceGateHook(
+        simulator_fn=simulator.simulate,
+        evaluator_fn=evaluator,
+        circuit_breaker=breaker,
+        context_provider=context_provider,
+    )

consequence_gate/simulators/database.py

@@ -0,0 +1,165 @@
+"""
+DataDeletionSimulator: outcome simulator for destructive DB operations.
+
+Row-count estimation uses the database's own query planner (EXPLAIN, not
+EXPLAIN ANALYZE -- so the query is never actually executed) rather than
+hardcoded selectivity constants, which have no statistical grounding and
+are demonstrably less accurate than even a real planner's known-imperfect
+estimates. FK cascade detection walks the graph depth-first and
+recursively, since ON DELETE CASCADE can compound across multiple hops.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Set
+
+from ..core.models import GateDecision, EvaluationResult
+from ..core.circuit_breaker import SteerCircuitBreaker
+
+
+@dataclass
+class DeletionBlastDelta:
+    tool_name: str
+    target_table: str
+    estimated_affected_rows: int
+    has_unindexed_where_clause: bool
+    is_hard_delete: bool
+    has_active_foreign_key_cascades: bool
+    cascade_affected_tables: List[str]
+    irreversibility_score: float
+    confidence: float
+    natural_key: str
+    simulated_side_effects: List[str] = field(default_factory=list)
+
+
+def get_planner_row_estimate(db_conn, table: str, filters: Dict[str, Any]) -> tuple:
+    """Returns (estimated_rows, used_index). Uses plain EXPLAIN so the
+    query is analyzed but never executed."""
+    if not filters:
+        where_clause = "TRUE"
+        params: List[Any] = []
+    else:
+        where_clause = " AND ".join(f"{k} = %s" for k in filters)
+        params = list(filters.values())
+
+    query = f"EXPLAIN (FORMAT JSON) SELECT 1 FROM {table} WHERE {where_clause}"
+    plan = db_conn.execute(query, params).fetchone()[0]
+    root = plan[0]["Plan"]
+    estimated_rows = root.get("Plan Rows", 0)
+    used_index = "Index" in root.get("Node Type", "")
+    return estimated_rows, used_index
+
+
+def walk_fk_cascade_depth(db_conn, table: str, visited: Optional[Set[str]] = None) -> List[str]:
+    """Recursively walks ON DELETE CASCADE foreign keys depth-first."""
+    if visited is None:
+        visited = set()
+    if table in visited:
+        return []
+    visited.add(table)
+
+    rows = db_conn.execute(
+        """
+        SELECT tc.table_name
+        FROM information_schema.table_constraints tc
+        JOIN information_schema.referential_constraints rc
+          ON tc.constraint_name = rc.constraint_name
+        JOIN information_schema.constraint_column_usage ccu
+          ON rc.unique_constraint_name = ccu.constraint_name
+        WHERE ccu.table_name = %s AND rc.delete_rule = 'CASCADE'
+        """,
+        [table],
+    ).fetchall()
+
+    affected = [table]
+    for (child_table,) in rows:
+        affected.extend(walk_fk_cascade_depth(db_conn, child_table, visited))
+    return affected
+
+
+class DataDeletionSimulator:
+    def __init__(self, max_autonomous_delete_rows: int = 100, db_conn=None):
+        self.max_autonomous_delete_rows = max_autonomous_delete_rows
+        self.db_conn = db_conn  # optional live connection for EXPLAIN / FK introspection
+
+    def simulate(self, tool_name: str, args: Dict[str, Any],
+                  context: Dict[str, Any]) -> DeletionBlastDelta:
+        table = args.get("table", "unknown")
+        filters = args.get("filters", {})
+        force_hard_delete = args.get("hard_delete", False)
+        natural_key = f"{table}:{sorted(filters.items())}"
+
+        table_stats = context.get("table_metadata", {}).get(table, {})
+        total_table_rows = table_stats.get("total_rows", 0)
+
+        if self.db_conn is not None:
+            estimated_rows, used_index = get_planner_row_estimate(self.db_conn, table, filters)
+            unindexed = not used_index
+            cascade_tables = walk_fk_cascade_depth(self.db_conn, table)[1:]
+        else:
+            estimated_rows = total_table_rows
+            unindexed = True
+            cascade_tables = table_stats.get("cascade_children", [])
+
+        has_cascades = len(cascade_tables) > 0
+        irreversibility = 1.0 if force_hard_delete else 0.2
+        confidence = 0.90 if self.db_conn is not None else 0.40
+
+        side_effects = []
+        if estimated_rows > self.max_autonomous_delete_rows:
+            side_effects.append(
+                f"Estimated row deletion ({estimated_rows}) exceeds safe autonomous threshold "
+                f"({self.max_autonomous_delete_rows})"
+            )
+        if has_cascades:
+            side_effects.append(
+                f"FK cascade will propagate to {len(cascade_tables)} additional table(s): {cascade_tables}"
+            )
+        if unindexed:
+            side_effects.append("Full table scan required; risk of lock escalation")
+
+        return DeletionBlastDelta(
+            tool_name=tool_name, target_table=table,
+            estimated_affected_rows=estimated_rows,
+            has_unindexed_where_clause=unindexed,
+            is_hard_delete=force_hard_delete,
+            has_active_foreign_key_cascades=has_cascades,
+            cascade_affected_tables=cascade_tables,
+            irreversibility_score=irreversibility, confidence=confidence,
+            natural_key=natural_key, simulated_side_effects=side_effects,
+        )
+
+    def evaluate(self, delta: DeletionBlastDelta,
+                  circuit_breaker: SteerCircuitBreaker) -> EvaluationResult:
+        if delta.confidence < 0.70:
+            return EvaluationResult(
+                decision=GateDecision.ASK, confidence=delta.confidence,
+                reason="Missing live query-planner access; unable to calculate blast radius with confidence.",
+            )
+
+        if delta.estimated_affected_rows > (self.max_autonomous_delete_rows * 10) and delta.is_hard_delete:
+            return EvaluationResult(
+                decision=GateDecision.DENY, confidence=delta.confidence,
+                reason=f"CRITICAL BLAST RADIUS: hard delete would purge ~{delta.estimated_affected_rows:,} rows.",
+            )
+
+        if delta.estimated_affected_rows > self.max_autonomous_delete_rows or delta.is_hard_delete:
+            base_steer = {
+                "guidance": (
+                    f"Direct hard deletion of {delta.estimated_affected_rows} rows from `{delta.target_table}` "
+                    f"is restricted. Option A: `archive_and_soft_delete` (sets deleted_at, 30-day retention). "
+                    f"Option B: if permanent deletion is required, call `request_bulk_purge_authorization`. "
+                    f"Note: soft delete requires all downstream queries to filter deleted_at IS NULL."
+                ),
+                "suggested_tool": "archive_and_soft_delete",
+                "suggested_args": {
+                    "table": delta.target_table,
+                    "filters": {"retention_status": "expired"},
+                    "mode": "soft_delete",
+                },
+            }
+            return circuit_breaker.resolve(delta.natural_key, delta.confidence, base_steer)
+
+        return EvaluationResult(
+            decision=GateDecision.ALLOW, confidence=delta.confidence,
+            reason=f"Delete operation is bounded (~{delta.estimated_affected_rows} rows) within safety envelope.",
+        )

consequence_gate/simulators/financial.py

@@ -0,0 +1,102 @@
+"""
+FinancialDeltaPredictor: outcome simulator for disbursements, claims, refunds.
+Sub-5ms evaluation budget (well within published MCP-proxy overhead norms).
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from ..core.models import GateDecision, EvaluationResult
+from ..core.circuit_breaker import SteerCircuitBreaker
+
+
+@dataclass
+class FinancialStateDelta:
+    tool_name: str
+    proposed_args: Dict[str, Any]
+    projected_net_delta_inr: float
+    rolling_24h_exposure_inr: float
+    policy_tier_limit_inr: float
+    irreversibility_score: float
+    confidence: float
+    natural_key: str
+    simulated_side_effects: List[str] = field(default_factory=list)
+
+
+class FinancialDeltaPredictor:
+    def __init__(self, daily_tier_limit_inr: float = 25000.0,
+                 instant_wire_threshold: float = 10000.0):
+        self.daily_tier_limit_inr = daily_tier_limit_inr
+        self.instant_wire_threshold = instant_wire_threshold
+
+    def simulate(self, tool_name: str, args: Dict[str, Any],
+                 context: Dict[str, Any]) -> FinancialStateDelta:
+        amount = float(args.get("amount", 0.0))
+        currency = args.get("currency", "INR").upper()
+        payout_method = args.get("payout_method", "standard_ach")
+        natural_key = args.get("claim_id") or args.get("transaction_ref") or f"{tool_name}:{amount}"
+
+        conversion_rate = 1.0 if currency == "INR" else context.get("exchange_rates", {}).get(currency, 0.0)
+        net_amount_inr = amount * conversion_rate
+
+        current_24h_spend = context.get("account_rolling_24h_spend", 0.0)
+        projected_24h_spend = current_24h_spend + net_amount_inr
+
+        irreversibility = 1.0 if payout_method in ("instant_upi", "rtgs", "wire") else 0.4
+
+        has_verified_kyc = context.get("kyc_verified", False)
+        has_fresh_balance = "account_rolling_24h_spend" in context
+        confidence = 0.95 if (has_verified_kyc and has_fresh_balance) else 0.45
+
+        side_effects = []
+        if projected_24h_spend > self.daily_tier_limit_inr:
+            side_effects.append(
+                f"Exceeds tier velocity limit by INR {projected_24h_spend - self.daily_tier_limit_inr:,.2f}"
+            )
+        if net_amount_inr > self.instant_wire_threshold and irreversibility > 0.8:
+            side_effects.append("Irreversible transfer above single-transaction threshold")
+
+        return FinancialStateDelta(
+            tool_name=tool_name, proposed_args=args,
+            projected_net_delta_inr=net_amount_inr,
+            rolling_24h_exposure_inr=projected_24h_spend,
+            policy_tier_limit_inr=self.daily_tier_limit_inr,
+            irreversibility_score=irreversibility, confidence=confidence,
+            natural_key=natural_key, simulated_side_effects=side_effects,
+        )
+
+    def evaluate(self, delta: FinancialStateDelta,
+                 circuit_breaker: SteerCircuitBreaker) -> EvaluationResult:
+        if delta.confidence < 0.70:
+            return EvaluationResult(
+                decision=GateDecision.ASK, confidence=delta.confidence,
+                reason="Low simulation confidence: stale ledger or unverified KYC context.",
+            )
+
+        if delta.rolling_24h_exposure_inr > (delta.policy_tier_limit_inr * 2.0) and delta.irreversibility_score >= 0.9:
+            return EvaluationResult(
+                decision=GateDecision.DENY, confidence=delta.confidence,
+                reason=f"Projected delta INR {delta.projected_net_delta_inr:,.2f} critically breaches velocity envelope.",
+            )
+
+        if delta.rolling_24h_exposure_inr > delta.policy_tier_limit_inr:
+            max_allowed_instant = max(0.0, delta.policy_tier_limit_inr -
+                                       (delta.rolling_24h_exposure_inr - delta.projected_net_delta_inr))
+            base_steer = {
+                "guidance": (
+                    f"Cannot process full INR {delta.projected_net_delta_inr:,.2f} as instant disbursement. "
+                    f"Option A: Process INR {max_allowed_instant:,.2f} instant + route remainder to dual-sign queue. "
+                    f"Option B: Route entire claim to `submit_manual_review_ticket`."
+                ),
+                "suggested_tool": "create_staged_disbursement",
+                "suggested_args": {
+                    "immediate_amount": max_allowed_instant,
+                    "escrow_amount": delta.projected_net_delta_inr - max_allowed_instant,
+                },
+            }
+            return circuit_breaker.resolve(delta.natural_key, delta.confidence, base_steer)
+
+        return EvaluationResult(
+            decision=GateDecision.ALLOW, confidence=delta.confidence,
+            reason="Projected balance delta is within safe autonomous operational boundary.",
+        )