quantlix 0.1.4__tar.gz → 0.2.0__tar.gz

{quantlix-0.1.4 → quantlix-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantlix
-Version: 0.1.4
+Version: 0.2.0
 Summary: Quantlix — AI-focused GPU inference platform
 Author: Quantlix
 License: MIT
@@ -20,6 +20,9 @@ Requires-Dist: typer[all]>=0.9.0
 Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: httpx>=0.26.0
 Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
 Provides-Extra: full
 Requires-Dist: fastapi>=0.109.0; extra == "full"
 Requires-Dist: uvicorn[standard]>=0.27.0; extra == "full"
@@ -35,19 +38,22 @@ Requires-Dist: pydantic-settings>=2.1.0; extra == "full"
 Requires-Dist: prometheus-client>=0.19.0; extra == "full"
 Requires-Dist: aiosmtplib>=3.0.0; extra == "full"
 Requires-Dist: stripe>=8.0.0; extra == "full"
+Requires-Dist: opentelemetry-api>=1.22.0; extra == "full"
+Requires-Dist: opentelemetry-sdk>=1.22.0; extra == "full"
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.22.0; extra == "full"
 Dynamic: license-file
 
 # Quantlix
 
-Deploy AI models in seconds. A simple inference platform with REST API, usage-based billing, and Kubernetes orchestration.
+The AI Runtime Control Plane. Govern ML & AI workloads at execution time. Enforce contracts. Apply policies. Control cost. Every request becomes deterministic.
 
 ## Features
 
-- **REST API** — Deploy models, run inference, check status
-- **Usage-based billing** — Free, Starter (€9/mo), Pro (€19/mo) tiers with Stripe
-- **Queue & orchestration** — Redis queue, K8s job scheduling
-- **Customer portal** — Next.js dashboard, usage graphs, real-time logs
-- **CLI** — `quantlix deploy`, `quantlix run` for local dev
+- **Runtime governance** — Contract enforcement, policy engine, budget controls
+- **Enforcement is strict by default** — Schema validation, feature contracts, drift prevention
+- **REST API** — Deploy, run, status, enforcement events, audit exports
+- **Customer portal** — Dashboard, enforcement visibility, usage
+- **CLI** — `quantlix deploy`, `quantlix run` — AI runtime control plane
 
 ## Quick start
 
@@ -68,11 +74,11 @@ export QUANTLIX_API_KEY="qxl_xxx"  # from login output
 
 # 3. Deploy and run
 quantlix deploy qx-example
-# Run inference to activate (first run moves deployment from pending to ready)
+# Run inference — request passes through enforcement before execution
 quantlix run <deployment_id> -i '{"prompt": "Hello!"}'
 ```
 
-See [docs/CLI_GUIDE.md](docs/CLI_GUIDE.md) for detailed setup.
+See [docs/CLI_GUIDE.md](docs/CLI_GUIDE.md) for detailed setup. To test Pipeline Lock locally, see [docs/TESTING_PIPELINE_LOCK.md](docs/TESTING_PIPELINE_LOCK.md). For a full pre-production test checklist, see [docs/LOCAL_TESTING_GUIDE.md](docs/LOCAL_TESTING_GUIDE.md).
 
 ## Architecture
 

{quantlix-0.1.4 → quantlix-0.2.0}/README.md

@@ -1,14 +1,14 @@
 # Quantlix
 
-Deploy AI models in seconds. A simple inference platform with REST API, usage-based billing, and Kubernetes orchestration.
+The AI Runtime Control Plane. Govern ML & AI workloads at execution time. Enforce contracts. Apply policies. Control cost. Every request becomes deterministic.
 
 ## Features
 
-- **REST API** — Deploy models, run inference, check status
-- **Usage-based billing** — Free, Starter (€9/mo), Pro (€19/mo) tiers with Stripe
-- **Queue & orchestration** — Redis queue, K8s job scheduling
-- **Customer portal** — Next.js dashboard, usage graphs, real-time logs
-- **CLI** — `quantlix deploy`, `quantlix run` for local dev
+- **Runtime governance** — Contract enforcement, policy engine, budget controls
+- **Enforcement is strict by default** — Schema validation, feature contracts, drift prevention
+- **REST API** — Deploy, run, status, enforcement events, audit exports
+- **Customer portal** — Dashboard, enforcement visibility, usage
+- **CLI** — `quantlix deploy`, `quantlix run` — AI runtime control plane
 
 ## Quick start
 
@@ -29,11 +29,11 @@ export QUANTLIX_API_KEY="qxl_xxx"  # from login output
 
 # 3. Deploy and run
 quantlix deploy qx-example
-# Run inference to activate (first run moves deployment from pending to ready)
+# Run inference — request passes through enforcement before execution
 quantlix run <deployment_id> -i '{"prompt": "Hello!"}'
 ```
 
-See [docs/CLI_GUIDE.md](docs/CLI_GUIDE.md) for detailed setup.
+See [docs/CLI_GUIDE.md](docs/CLI_GUIDE.md) for detailed setup. To test Pipeline Lock locally, see [docs/TESTING_PIPELINE_LOCK.md](docs/TESTING_PIPELINE_LOCK.md). For a full pre-production test checklist, see [docs/LOCAL_TESTING_GUIDE.md](docs/LOCAL_TESTING_GUIDE.md).
 
 ## Architecture
 

quantlix-0.2.0/api/audit_signing.py

@@ -0,0 +1,127 @@
+"""Signed audit exports — hash chain and HMAC signature for tamper-evident JSONL."""
+import hashlib
+import hmac
+import json
+import logging
+from typing import Any, AsyncIterator
+
+from api.config import settings
+
+logger = logging.getLogger(__name__)
+
+CHAIN_SEED = b"quantlix-audit-v1"
+SIGNATURE_ALGORITHM = "HMAC-SHA256"
+
+
+def _get_signing_key() -> bytes | None:
+    """Audit signing key from config. Required for signed exports."""
+    key = getattr(settings, "audit_signing_key", "") or ""
+    return key.encode() if key else None
+
+
+def _hash_line(line: str, prev_hash: str) -> str:
+    """Compute chain hash: SHA256(prev_hash + line)."""
+    payload = f"{prev_hash}\n{line}".encode()
+    return hashlib.sha256(payload).hexdigest()
+
+
+def _sign_payload(payload: str, key: bytes) -> str:
+    """HMAC-SHA256 signature of payload."""
+    return hmac.new(key, payload.encode(), hashlib.sha256).hexdigest()
+
+
+def get_audit_signing_key_id() -> str:
+    """Key ID for rotation (first 8 chars of key hash)."""
+    key = _get_signing_key()
+    if not key:
+        return "none"
+    return hashlib.sha256(key).hexdigest()[:8]
+
+
+async def stream_signed_jsonl(
+    lines: AsyncIterator[str],
+) -> AsyncIterator[str]:
+    """
+    Wrap JSONL stream with hash chain and trailing signature block.
+    Each line gets _prev_hash, _hash. Final line: {"_signature": "...", "_key_id": "...", "_algorithm": "..."}.
+    """
+    key = _get_signing_key()
+    if not key:
+        raise ValueError("AUDIT_SIGNING_KEY required for signed exports")
+
+    prev_hash = hashlib.sha256(CHAIN_SEED).hexdigest()
+    chain_payloads: list[str] = []
+
+    async for line in lines:
+        line = line.rstrip("\n")
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except json.JSONDecodeError:
+            obj = {"_raw": line}
+        canonical = json.dumps(obj, sort_keys=True, default=str)
+        current_hash = _hash_line(canonical, prev_hash)
+        chain_payloads.append(f"{prev_hash}\n{canonical}")
+
+        obj["_prev_hash"] = prev_hash
+        obj["_hash"] = current_hash
+        yield json.dumps(obj, default=str) + "\n"
+        prev_hash = current_hash
+
+    # Trailing signature block
+    full_chain = "\n".join(chain_payloads) if chain_payloads else prev_hash
+    signature = _sign_payload(full_chain, key)
+    sig_block = {
+        "_signature": signature,
+        "_key_id": get_audit_signing_key_id(),
+        "_algorithm": SIGNATURE_ALGORITHM,
+        "_chain_tail": prev_hash,
+    }
+    yield json.dumps(sig_block) + "\n"
+
+
+def verify_signed_export(lines: list[str]) -> tuple[bool, str | None]:
+    """
+    Verify a signed export. Returns (valid, error_message).
+    """
+    if not lines:
+        return False, "Empty export"
+    key = _get_signing_key()
+    if not key:
+        return False, "No signing key configured"
+
+    try:
+        sig_block = json.loads(lines[-1])
+        if not sig_block.get("_signature"):
+            return False, "Missing signature block"
+        expected_sig = sig_block["_signature"]
+        chain_tail = sig_block.get("_chain_tail", "")
+
+        prev_hash = hashlib.sha256(CHAIN_SEED).hexdigest()
+        chain_parts: list[str] = []
+        for i, line in enumerate(lines[:-1]):
+            line = line.rstrip("\n")
+            obj = json.loads(line)
+            prev = obj.pop("_prev_hash", "")
+            curr = obj.pop("_hash", "")
+            if prev != prev_hash:
+                return False, f"Chain broken at line {i+1}: prev_hash mismatch"
+            canonical = json.dumps(obj, sort_keys=True, default=str)
+            current_hash = _hash_line(canonical, prev_hash)
+            if curr != current_hash:
+                return False, f"Chain broken at line {i+1}: hash mismatch"
+            chain_parts.append(f"{prev_hash}\n{canonical}")
+            prev_hash = current_hash
+
+        if prev_hash != chain_tail:
+            return False, "Chain tail mismatch"
+
+        full_chain = "\n".join(chain_parts)
+        actual_sig = _sign_payload(full_chain, key)
+        if not hmac.compare_digest(actual_sig, expected_sig):
+            return False, "Signature invalid"
+
+        return True, None
+    except (json.JSONDecodeError, KeyError) as e:
+        return False, str(e)

quantlix-0.2.0/api/budget_hierarchy.py

@@ -0,0 +1,165 @@
+"""Budget hierarchy: org → project → deployment. Multi-level resource governance."""
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from api.models import Deployment, EnforcementEvent, Job, UsageRecord
+from api.usage_service import get_limits_for_user, get_current_period_usage
+
+
+def _get_budget_config(cfg: dict | None) -> dict:
+    if not cfg:
+        return {}
+    budget = cfg.get("budget_policies") or {}
+    pl = cfg.get("pipeline_lock") or {}
+    pl_budget = (pl.get("policies") or {}).get("budget") or {}
+    return {**pl_budget, **budget}
+
+
+async def get_budget_hierarchy(db: AsyncSession, user_id: str) -> dict[str, Any]:
+    """
+    Budget hierarchy for user. Structure: account (org-level) → deployments.
+    Returns org summary, tree nodes, and recent budget events.
+    """
+    start_of_month = datetime.now(timezone.utc).replace(day=1, hour=0, minute=0, second=0, microsecond=0)
+    cutoff_7d = datetime.now(timezone.utc) - timedelta(days=7)
+
+    # User-level limits and usage
+    token_limit, cpu_limit, gpu_limit = await get_limits_for_user(db, user_id)
+    tokens_used, cpu_used, gpu_used = await get_current_period_usage(db, user_id)
+
+    compute_pct = (cpu_used / cpu_limit * 100) if cpu_limit > 0 else 0
+    token_pct = (tokens_used / token_limit * 100) if token_limit > 0 else 0
+    gpu_pct = (gpu_used / gpu_limit * 100) if gpu_limit > 0 else 0
+
+    # Deployments with budget config and usage
+    dep_result = await db.execute(
+        select(Deployment).where(Deployment.user_id == user_id).order_by(Deployment.updated_at.desc())
+    )
+    deployments = dep_result.scalars().all()
+
+    # Per-deployment usage (this month)
+    dep_usages: dict[str, dict[str, float]] = {}
+    if deployments:
+        dep_ids = [d.id for d in deployments]
+        usage_result = await db.execute(
+            select(
+                Job.deployment_id,
+                func.coalesce(func.sum(UsageRecord.tokens_used), 0).label("tokens"),
+                func.coalesce(func.sum(UsageRecord.compute_seconds), 0).label("cpu"),
+                func.coalesce(func.sum(UsageRecord.gpu_seconds), 0).label("gpu"),
+            )
+            .select_from(Job)
+            .outerjoin(UsageRecord, Job.id == UsageRecord.job_id)
+            .where(
+                Job.user_id == user_id,
+                Job.deployment_id.in_(dep_ids),
+                Job.created_at >= start_of_month,
+            )
+            .group_by(Job.deployment_id)
+        )
+        for row in usage_result.all():
+            dep_usages[row.deployment_id] = {
+                "tokens": int(row.tokens),
+                "cpu": float(row.cpu),
+                "gpu": float(row.gpu),
+            }
+
+    # Build tree nodes
+    nodes: list[dict[str, Any]] = []
+
+    # Account (top-level)
+    nodes.append({
+        "id": "account",
+        "name": "Account",
+        "level": "org",
+        "parent_id": None,
+        "limit_tokens": token_limit if token_limit > 0 else None,
+        "limit_compute": cpu_limit if cpu_limit > 0 else None,
+        "limit_gpu": gpu_limit if gpu_limit > 0 else None,
+        "used_tokens": tokens_used,
+        "used_compute": cpu_used,
+        "used_gpu": gpu_used,
+        "usage_pct": max(compute_pct, token_pct, gpu_pct),
+        "inherited": False,
+        "override": False,
+    })
+
+    # Deployments as children
+    for d in deployments:
+        budget = _get_budget_config(d.config)
+        req_limit = int(budget.get("request_rate_per_minute") or 0)
+        compute_limit = float(budget.get("max_compute_per_request_seconds") or 0)
+        retry_ceiling = float(budget.get("retry_cost_multiplier_ceiling") or 0)
+
+        usage = dep_usages.get(d.id, {})
+        dep_cpu = usage.get("cpu", 0)
+        dep_tokens = usage.get("tokens", 0)
+
+        # Usage % for deployment: share of org compute budget
+        usage_pct = (dep_cpu / cpu_limit * 100) if cpu_limit > 0 and dep_cpu > 0 else 0.0
+
+        nodes.append({
+            "id": d.id,
+            "name": d.model_id,
+            "level": "deployment",
+            "parent_id": "account",
+            "deployment_id": d.id,
+            "limit_request_rate": req_limit if req_limit > 0 else None,
+            "limit_compute_per_request": compute_limit if compute_limit > 0 else None,
+            "retry_ceiling": retry_ceiling if retry_ceiling > 0 else None,
+            "used_tokens": dep_tokens,
+            "used_compute": dep_cpu,
+            "usage_pct": usage_pct,
+            "inherited": req_limit == 0 and compute_limit == 0,
+            "override": bool(budget),
+        })
+
+    # Recent budget events (enforcement events with budget_json)
+    dep_ids = [d.id for d in deployments]
+    events: list[dict[str, Any]] = []
+    if dep_ids:
+        events_result = await db.execute(
+            select(
+                EnforcementEvent.event_id,
+                EnforcementEvent.deployment_id,
+                EnforcementEvent.action_taken,
+                EnforcementEvent.budget_json,
+                EnforcementEvent.created_at,
+            )
+            .where(
+                EnforcementEvent.deployment_id.in_(dep_ids),
+                EnforcementEvent.created_at >= cutoff_7d,
+                EnforcementEvent.budget_json.isnot(None),
+            )
+            .order_by(EnforcementEvent.created_at.desc())
+            .limit(50)
+        )
+        for row in events_result.all():
+            events.append({
+                "event_id": row.event_id,
+                "deployment_id": row.deployment_id,
+                "action": row.action_taken,
+                "budget_json": row.budget_json,
+                "created_at": row.created_at.isoformat() if row.created_at else "",
+            })
+
+    return {
+        "org_summary": {
+            "total_tokens_limit": token_limit if token_limit > 0 else None,
+            "total_compute_limit": cpu_limit if cpu_limit > 0 else None,
+            "total_gpu_limit": gpu_limit if gpu_limit > 0 else None,
+            "used_tokens": tokens_used,
+            "used_compute": cpu_used,
+            "used_gpu": gpu_used,
+            "compute_pct": round(compute_pct, 1),
+            "token_pct": round(token_pct, 1),
+            "gpu_pct": round(gpu_pct, 1),
+        },
+        "nodes": nodes,
+        "events": events,
+    }

{quantlix-0.1.4 → quantlix-0.2.0}/api/config.py

@@ -27,7 +27,7 @@ class Settings(BaseSettings):
     # Otherwise use SMTP with smtp_user/smtp_password.
     email_enabled: bool = True
     sweego_api_key: str = ""  # When set, use Sweego HTTP API instead of SMTP
-    sweego_auth_type: str = "api_token"  # "api_token" (Api-Token), "api_key" (Api-Key), or "bearer" (Authorization: Bearer)
+    sweego_auth_type: str = "api_key"  # "api_key" (Api-Key, Sweego default), "api_token" (Api-Token), or "bearer" (Authorization: Bearer)
     smtp_host: str = "smtp.sweego.io"
     smtp_port: int = 587
     smtp_user: str = ""
@@ -45,6 +45,38 @@ class Settings(BaseSettings):
     # CORS (comma-separated extra origins, e.g. for Vercel: https://quantlix.vercel.app)
     cors_origins: str = ""
 
+    # Local dev: no orchestrator/K8s — mark deployments ready immediately
+    mock_k8s: bool = False
+
+    # Logging (DEBUG, INFO, WARNING, ERROR)
+    log_level: str = "INFO"
+
+    # Guardrails
+    guardrail_timeout_seconds: float = 5.0
+    guardrail_fail_open: bool = True  # Allow on error; False = block on error
+    guardrail_block_max_per_window: int = 5
+    guardrail_block_window_seconds: int = 300
+
+    # Enforcement event integrations (never block request path)
+    otel_enabled: bool = False
+    otel_endpoint: str = "http://localhost:4318/v1/traces"  # OTLP HTTP
+    enforcement_webhook_url: str = ""  # Global webhook for blocked/warned events
+    integration_timeout_seconds: float = 3.0  # Webhook/OTel timeout; fire-and-forget
+
+    # Audit signing (signed exports)
+    audit_signing_key: str = ""  # HMAC key for signed audit exports; rotate via env
+
+    # Retention defaults (for tenants without org config; 0 = unlimited)
+    retention_days_jobs: int = 90
+    retention_days_enforcement_events: int = 90
+    export_bucket: str = "exports"  # S3-compatible bucket for scheduled exports
+
+    # Feature flags (optional security)
+    feature_request_signing: bool = False  # Require X-Signature on /run when enabled
+    feature_ip_allowlist: bool = False  # Restrict /run to allowed IPs when enabled
+    request_signing_secret: str = ""  # Shared secret for X-Signature (HMAC-SHA256)
+    allowed_ips: str = ""  # Comma-separated IPs/CIDRs (e.g. 10.0.0.0/8, 192.168.1.1)
+
     # Stripe
     stripe_secret_key: str = ""
     stripe_webhook_secret: str = ""

quantlix-0.2.0/api/cost_estimation.py

@@ -0,0 +1,54 @@
+"""Cost estimation for inference jobs. Used for Cost Amplification Score in Decision Trace."""
+from __future__ import annotations
+
+# Rates in EUR (configurable via env in future). Pro GPU overage: €0.50/hr
+TOKEN_COST_PER_1M = 10.0  # €10 per 1M tokens (typical LLM)
+CPU_COST_PER_HOUR = 0.36  # ~€0.36/hr cloud CPU
+GPU_COST_PER_HOUR = 0.50  # €0.50/hr Pro overage
+
+
+def estimate_cost_eur(tokens: int, compute_s: float, gpu_s: float) -> float:
+    """Estimate cost in EUR from usage. Returns 0 if all zero."""
+    if tokens == 0 and compute_s == 0 and gpu_s == 0:
+        return 0.0
+    token_cost = (tokens / 1_000_000) * TOKEN_COST_PER_1M
+    cpu_cost = (compute_s / 3600) * CPU_COST_PER_HOUR
+    gpu_cost = (gpu_s / 3600) * GPU_COST_PER_HOUR
+    return round(token_cost + cpu_cost + gpu_cost, 4)
+
+
+def compute_cost_amplification(
+    *,
+    tokens: int,
+    compute_s: float,
+    gpu_s: float,
+    retry_count: int,
+    fallback_triggered: bool,
+) -> dict:
+    """
+    Compute Cost Amplification Score breakdown.
+
+    Total inference runs = 1 (base) + retry_count + (1 if fallback else 0).
+    We charge for the final successful run only; failed attempts still consume compute.
+    Cost per run = total_cost / total_runs. Base = 1 run, retry = retry_count runs, fallback = 1 run.
+    """
+    total_cost_eur = estimate_cost_eur(tokens, compute_s, gpu_s)
+    total_runs = 1 + retry_count + (1 if fallback_triggered else 0)
+    if total_runs <= 0:
+        total_runs = 1
+    cost_per_run = total_cost_eur / total_runs
+
+    base_cost = round(cost_per_run, 4)
+    retry_cost = round(retry_count * cost_per_run, 4)
+    fallback_cost = round((1 if fallback_triggered else 0) * cost_per_run, 4)
+    total_cost = round(base_cost + retry_cost + fallback_cost, 4)
+
+    amplification = round(total_runs, 2) if total_runs > 1 else 1.0
+
+    return {
+        "base_cost_eur": base_cost,
+        "retry_cost_eur": retry_cost,
+        "fallback_cost_eur": fallback_cost,
+        "total_cost_eur": total_cost,
+        "amplification_factor": amplification,
+    }

{quantlix-0.1.4 → quantlix-0.2.0}/api/email.py

@@ -32,10 +32,10 @@ async def _send_via_sweego_api(to_email: str, subject: str, body: str) -> None:
     }
     if settings.sweego_auth_type == "bearer":
         auth_header = ("Authorization", f"Bearer {settings.sweego_api_key}")
-    elif settings.sweego_auth_type == "api_key":
-        auth_header = ("Api-Key", settings.sweego_api_key)
+    elif settings.sweego_auth_type == "api_token":
+        auth_header = ("Api-Token", settings.sweego_api_key)
     else:
-        auth_header = ("Api-Token", settings.sweego_api_key)  # default: api_token
+        auth_header = ("Api-Key", settings.sweego_api_key)  # default: api_key (Sweego docs)
     async with httpx.AsyncClient(timeout=30.0) as client:
         resp = await client.post(
             SWEEGO_API_URL,
@@ -53,7 +53,10 @@ async def _send_via_sweego_api(to_email: str, subject: str, body: str) -> None:
                 resp.status_code,
                 body_preview,
             )
-        resp.raise_for_status()
+            raise RuntimeError(
+                f"Sweego API error {resp.status_code}: {body_preview}"
+            ) from None
+        return
 
 
 async def _send_email(to_email: str, subject: str, body: str) -> None:
@@ -84,7 +87,7 @@ async def send_verification_email(to_email: str, token: str) -> bool:
         logger.warning("Email not configured; skipping verification email to %s", to_email)
         return False
 
-    verify_url = f"{settings.app_base_url.rstrip('/')}/auth/verify?token={token}"
+    verify_url = f"{settings.portal_base_url.rstrip('/')}/verify?token={token}"
     subject = "Verify your Quantlix account"
     body = f"""Hello,
 

quantlix-0.2.0/api/enforcement_events.py

@@ -0,0 +1,118 @@
+"""Enforcement event recording — audit spine. Internal, not exposed in UI.
+Integrations (OTel, webhook) run fire-and-forget with timeouts; never block request path."""
+import asyncio
+import logging
+from typing import Any
+
+from api.config import settings
+from api.db import async_session_maker
+from api.enforcement_webhook import notify_webhook
+from api.models import EnforcementEvent
+from api.policy_engine.models import PolicyDecision
+
+logger = logging.getLogger(__name__)
+
+CONTRACT_VERSION = "1.0"
+
+
+def _action_taken(decision: PolicyDecision) -> str:
+    """Map PolicyDecision to action_taken."""
+    if not decision.allowed:
+        return "blocked"
+    if decision.severity == "warn":
+        return "warned"
+    return "allowed"
+
+
+def _resolve_webhook_url(deployment_config: dict[str, Any] | None) -> str:
+    """Resolve webhook URL: per-deployment overrides global."""
+    if deployment_config:
+        integrations = deployment_config.get("integrations") or {}
+        url = integrations.get("webhook_url") or ""
+        if url:
+            return url
+    return settings.enforcement_webhook_url or ""
+
+
+async def record_enforcement_event(
+    request_id: str,
+    deployment_id: str,
+    decision: PolicyDecision,
+    deployment_config: dict[str, Any] | None = None,
+    trace_context: dict[str, Any] | None = None,
+) -> None:
+    """
+    Store every enforcement decision in enforcement_events.
+    Uses own session so events are persisted even when main request raises (blocked).
+    Fire-and-forget: log on error but don't fail the request.
+    Triggers OTel export and webhook when configured.
+    """
+    try:
+        budget_json = None
+        if decision.budget_status:
+            budget_json = decision.budget_status
+        elif decision.error_code and decision.error_code.startswith("budget_"):
+            budget_json = {"error_code": decision.error_code}
+
+        action_taken = _action_taken(decision)
+        violations = decision.violations if decision.violations else None
+
+        event = EnforcementEvent(
+            request_id=request_id,
+            deployment_id=deployment_id,
+            contract_version=CONTRACT_VERSION,
+            policy_version=decision.policy_version,
+            violations_json=violations,
+            action_taken=action_taken,
+            budget_json=budget_json,
+            trace_context=trace_context,
+        )
+        async with async_session_maker() as session:
+            session.add(event)
+            await session.flush()
+            event_id = event.event_id
+            await session.commit()
+
+        # OpenTelemetry trace export (fire-and-forget, never blocks)
+        def _do_otel():
+            from api.enforcement_otel import export_enforcement_span
+            export_enforcement_span(
+                request_id=request_id,
+                deployment_id=deployment_id,
+                event_id=event_id,
+                action_taken=action_taken,
+                contract_version=CONTRACT_VERSION,
+                policy_version=decision.policy_version,
+                violations=violations,
+                budget_json=budget_json,
+                trace_context=trace_context,
+            )
+
+        async def _otel_with_timeout():
+            try:
+                await asyncio.wait_for(
+                    asyncio.to_thread(_do_otel),
+                    timeout=settings.integration_timeout_seconds,
+                )
+            except asyncio.TimeoutError:
+                logger.warning("OTel export timed out")
+            except Exception as e:
+                logger.warning("OTel export failed: %s", e)
+
+        asyncio.create_task(_otel_with_timeout())
+
+        # Webhook for violations (blocked/warned)
+        webhook_url = _resolve_webhook_url(deployment_config)
+        notify_webhook(
+            webhook_url=webhook_url,
+            request_id=request_id,
+            deployment_id=deployment_id,
+            event_id=event_id,
+            action_taken=action_taken,
+            contract_version=CONTRACT_VERSION,
+            policy_version=decision.policy_version,
+            violations=violations,
+            budget_json=budget_json,
+        )
+    except Exception as e:
+        logger.warning("Failed to record enforcement event: %s", e)