sqlguard-ninja 0.1.0__py3-none-any.whl

sqlguard_ninja/benchmarking/fixtures.py

@@ -0,0 +1,274 @@
+"""Synthetic fixture database for the benchmark schema (SQLite and PostgreSQL).
+
+The data is generated deterministically from a seed. It contains no real personal data:
+names, emails, card numbers and identifiers are fabricated and use reserved example
+domains and test card ranges.
+"""
+
+from __future__ import annotations
+
+import json
+import random
+import sqlite3
+from collections.abc import Iterator
+from datetime import date, datetime, timedelta
+from pathlib import Path
+from typing import Any, Protocol
+
+from sqlguard_ninja.policy.model import Catalog, Policy
+
+DEFAULT_SEED = 20261024
+
+_TYPE_MAP = {
+    "sqlite": {
+        "int": "INTEGER",
+        "text": "TEXT",
+        "numeric": "NUMERIC",
+        "timestamp": "TEXT",
+        "date": "TEXT",
+        "boolean": "INTEGER",
+        "json": "TEXT",
+    },
+    "postgres": {
+        "int": "BIGINT",
+        "text": "TEXT",
+        "numeric": "NUMERIC(14,2)",
+        "timestamp": "TIMESTAMP",
+        "date": "DATE",
+        "boolean": "BOOLEAN",
+        "json": "JSONB",
+    },
+}
+
+ROW_COUNTS = {
+    "tenants": 3,
+    "warehouses": 4,
+    "customers": 60,
+    "products": 30,
+    "orders": 200,
+    "order_items": 400,
+    "payments": 200,
+    "shipments": 180,
+    "employees": 40,
+    "support_tickets": 80,
+}
+
+_FIRST = ["Alex", "Sam", "Robin", "Kim", "Jordan", "Taylor", "Morgan", "Casey", "Avery", "Riley"]
+_LAST = ["Example", "Sample", "Testperson", "Placeholder", "Demo", "Fixture", "Synthetic"]
+_CITIES = ["Berlin", "Lisbon", "Dubai", "Pune", "Oslo", "Austin", "Lyon", "Kraków"]
+_COUNTRIES = ["DE", "PT", "AE", "IN", "NO", "US", "FR", "PL"]
+
+
+class _DBConnection(Protocol):
+    def cursor(self) -> Any: ...
+    def commit(self) -> None: ...
+
+
+def schema_ddl(catalog: Catalog, dialect: str) -> list[str]:
+    """CREATE TABLE statements derived from the policy catalog."""
+    types = _TYPE_MAP[dialect]
+    statements = []
+    for name, table in catalog.tables.items():
+        cols = []
+        for col, spec in table.columns.items():
+            sql_type = types.get(spec.type, "TEXT")
+            pk = " PRIMARY KEY" if col == "id" else ""
+            cols.append(f"{col} {sql_type}{pk}")
+        statements.append(f"CREATE TABLE {name} ({', '.join(cols)})")
+    return statements
+
+
+def _rows(seed: int) -> Iterator[tuple[str, list[dict[str, Any]]]]:
+    rng = random.Random(seed)
+    base = datetime(2026, 1, 1)
+
+    def ts(days: int = 300) -> str:
+        return (base + timedelta(minutes=rng.randrange(days * 24 * 60))).isoformat(sep=" ")
+
+    def person() -> str:
+        return f"{rng.choice(_FIRST)} {rng.choice(_LAST)}"
+
+    tenants = [
+        {"id": i, "name": f"Tenant {i}", "plan": rng.choice(["free", "pro"]), "created_at": ts()}
+        for i in range(1, ROW_COUNTS["tenants"] + 1)
+    ]
+    yield "tenants", tenants
+    yield (
+        "warehouses",
+        [
+            {"id": i, "name": f"WH-{i}", "region": rng.choice(["EU", "US", "MEA", "APAC"])}
+            for i in range(1, ROW_COUNTS["warehouses"] + 1)
+        ],
+    )
+    customers = []
+    for i in range(1, ROW_COUNTS["customers"] + 1):
+        k = rng.randrange(len(_CITIES))
+        customers.append(
+            {
+                "id": i,
+                "tenant_id": (i % 3) + 1,
+                "full_name": person(),
+                "email": f"user{i}@example.com",
+                "email_domain": "example.com",
+                "phone": f"+00 555 {i:04d}",
+                "date_of_birth": date(
+                    1960 + rng.randrange(40), 1 + rng.randrange(12), 1
+                ).isoformat(),
+                "country": _COUNTRIES[k],
+                "city": _CITIES[k],
+                "loyalty_tier": rng.choice(["bronze", "silver", "gold"]),
+                "marketing_opt_in": rng.random() < 0.5,
+                "created_at": ts(),
+                "profile": json.dumps(
+                    {
+                        "preferences": {"newsletter": rng.random() < 0.5, "language": "en"},
+                        "health": {"allergies": rng.choice(["none", "synthetic-allergen"])},
+                        "payment": {"card_number": "4111111111111111"},
+                    }
+                ),
+            }
+        )
+    yield "customers", customers
+    products = [
+        {
+            "id": i,
+            "tenant_id": (i % 3) + 1,
+            "sku": f"SKU-{i:04d}",
+            "name": f"Product {i}",
+            "category": rng.choice(["books", "garden", "toys", "tools"]),
+            "price": round(rng.uniform(2, 200), 2),
+        }
+        for i in range(1, ROW_COUNTS["products"] + 1)
+    ]
+    yield "products", products
+    orders = []
+    for i in range(1, ROW_COUNTS["orders"] + 1):
+        cust = rng.choice(customers)
+        orders.append(
+            {
+                "id": i,
+                "tenant_id": cust["tenant_id"],
+                "customer_id": cust["id"],
+                "status": rng.choice(["new", "paid", "shipped", "delivered", "cancelled"]),
+                "total_amount": round(rng.uniform(5, 900), 2),
+                "currency": "EUR",
+                "created_at": ts(),
+                "shipping_address": f"{i} Example Street, {cust['city']}",
+            }
+        )
+    yield "orders", orders
+    yield (
+        "order_items",
+        [
+            {
+                "id": i,
+                "tenant_id": (o := rng.choice(orders))["tenant_id"],
+                "order_id": o["id"],
+                "product_id": rng.choice(products)["id"],
+                "quantity": 1 + rng.randrange(5),
+                "unit_price": round(rng.uniform(2, 200), 2),
+            }
+            for i in range(1, ROW_COUNTS["order_items"] + 1)
+        ],
+    )
+    yield (
+        "payments",
+        [
+            {
+                "id": o["id"],
+                "tenant_id": o["tenant_id"],
+                "order_id": o["id"],
+                "card_number": "4111111111111111",  # published test card number
+                "card_last4": "1111",
+                "card_brand": "visa",
+                "iban": "XX00TEST0000000000",
+                "amount": o["total_amount"],
+                "status": rng.choice(["captured", "refunded", "failed"]),
+            }
+            for o in orders[: ROW_COUNTS["payments"]]
+        ],
+    )
+    yield (
+        "shipments",
+        [
+            {
+                "id": o["id"],
+                "tenant_id": o["tenant_id"],
+                "order_id": o["id"],
+                "warehouse_id": 1 + rng.randrange(ROW_COUNTS["warehouses"]),
+                "carrier": rng.choice(["DHL", "UPS", "Aramex"]),
+                "tracking_number": f"TRK{o['id']:06d}",
+                "status": rng.choice(["in_transit", "delivered", "returned"]),
+                "shipped_at": ts(),
+                "delivery_address": o["shipping_address"],
+            }
+            for o in orders[: ROW_COUNTS["shipments"]]
+        ],
+    )
+    yield (
+        "employees",
+        [
+            {
+                "id": i,
+                "full_name": person(),
+                "email": f"employee{i}@example.org",
+                "department": rng.choice(["warehouse", "support", "finance", "engineering"]),
+                "title": rng.choice(["associate", "lead", "manager"]),
+                "salary": round(rng.uniform(30000, 120000), 2),
+                "bank_account": f"XX00TEST{i:010d}",
+                "national_id": f"TEST-{i:06d}",
+                "health_notes": "synthetic",
+                "hire_date": date(2015 + rng.randrange(10), 1 + rng.randrange(12), 1).isoformat(),
+                "manager_id": None if i <= 3 else 1 + rng.randrange(3),
+                "warehouse_id": 1 + rng.randrange(ROW_COUNTS["warehouses"]),
+            }
+            for i in range(1, ROW_COUNTS["employees"] + 1)
+        ],
+    )
+    yield (
+        "support_tickets",
+        [
+            {
+                "id": i,
+                "tenant_id": (c := rng.choice(customers))["tenant_id"],
+                "customer_id": c["id"],
+                "subject": rng.choice(["Late delivery", "Refund", "Login issue"]),
+                "body": "Synthetic ticket body.",
+                "status": rng.choice(["open", "closed"]),
+                "priority": rng.choice(["low", "high"]),
+                "created_at": ts(),
+            }
+            for i in range(1, ROW_COUNTS["support_tickets"] + 1)
+        ],
+    )
+
+
+def populate(conn: _DBConnection, policy: Policy, dialect: str, seed: int = DEFAULT_SEED) -> None:
+    """Create the schema and load synthetic rows. Values are always bound, never interpolated."""
+    marker = "?" if dialect == "sqlite" else "%s"
+    cur = conn.cursor()
+    for stmt in schema_ddl(policy.catalog, dialect):
+        cur.execute(stmt)
+    for table, rows in _rows(seed):
+        if not rows:
+            continue
+        columns = list(policy.catalog.tables[table].columns)
+        placeholders = ", ".join([marker] * len(columns))
+        # Table and column names come from the validated policy catalog, not from input.
+        insert = f"INSERT INTO {table} ({', '.join(columns)}) VALUES ({placeholders})"  # noqa: S608
+        params = [tuple(row.get(c) for c in columns) for row in rows]
+        cur.executemany(insert, params)
+    conn.commit()
+
+
+def create_sqlite(
+    policy: Policy, path: str | Path = ":memory:", seed: int = DEFAULT_SEED
+) -> sqlite3.Connection:
+    """Return a SQLite connection with the fixture schema and data loaded.
+
+    The connection may be shared across threads (web servers run handlers in a pool);
+    :func:`sqlguard_ninja.integrations.executors.sqlite_executor` serialises access.
+    """
+    conn = sqlite3.connect(str(path), check_same_thread=False)
+    populate(conn, policy, "sqlite", seed)
+    return conn

sqlguard_ninja/benchmarking/metrics.py

@@ -0,0 +1,114 @@
+"""Detection metrics with explicit definitions.
+
+Positive class: a case whose expected outcome is *not* ALLOW (``deny`` or ``review``), i.e.
+something that must not run unattended. A prediction is positive when the validator's decision
+is not ALLOW. On top of the binary view, ``exact_match_rate`` measures how often the
+three-way decision (allow/review/deny) matches exactly.
+"""
+
+from __future__ import annotations
+
+import math
+from collections import defaultdict
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Any
+
+from sqlguard_ninja.core.findings import Decision
+
+
+@dataclass(frozen=True)
+class CaseOutcome:
+    id: str
+    category: str
+    dialect: str
+    provenance: str
+    expected: Decision
+    actual: Decision
+    latency_ms: float
+    error: str | None = None
+    in_capability: bool = True
+
+    @property
+    def unsafe(self) -> bool:
+        return self.expected is not Decision.ALLOW
+
+    @property
+    def flagged(self) -> bool:
+        return self.actual is not Decision.ALLOW
+
+    @property
+    def kind(self) -> str:
+        if self.unsafe and self.flagged:
+            return "tp"
+        if self.unsafe:
+            return "fn"
+        if self.flagged:
+            return "fp"
+        return "tn"
+
+
+def _ratio(num: int, den: int) -> float | None:
+    return None if den == 0 else round(num / den, 4)
+
+
+def percentile(values: list[float], pct: float) -> float | None:
+    """Nearest-rank percentile (deterministic, no interpolation)."""
+    if not values:
+        return None
+    ordered = sorted(values)
+    rank = max(1, math.ceil(pct / 100 * len(ordered)))
+    return round(ordered[rank - 1], 4)
+
+
+def summarise(outcomes: Iterable[CaseOutcome]) -> dict[str, Any]:
+    items = list(outcomes)
+    counts = {"tp": 0, "fp": 0, "tn": 0, "fn": 0}
+    for o in items:
+        counts[o.kind] += 1
+    tp, fp, tn, fn = counts["tp"], counts["fp"], counts["tn"], counts["fn"]
+    latencies = [o.latency_ms for o in items]
+    return {
+        "cases": len(items),
+        "unsafe_cases": tp + fn,
+        "safe_cases": tn + fp,
+        **counts,
+        "recall": _ratio(tp, tp + fn),
+        "precision": _ratio(tp, tp + fp),
+        "false_positive_rate": _ratio(fp, fp + tn),
+        "false_negative_rate": _ratio(fn, fn + tp),
+        "exact_match_rate": _ratio(sum(o.expected is o.actual for o in items), len(items)),
+        "errors": sum(o.error is not None for o in items),
+        "latency_ms": {
+            "p50": percentile(latencies, 50),
+            "p95": percentile(latencies, 95),
+            "p99": percentile(latencies, 99),
+            "max": round(max(latencies), 4) if latencies else None,
+        },
+    }
+
+
+def grouped(outcomes: list[CaseOutcome], attr: str) -> dict[str, dict[str, Any]]:
+    groups: dict[str, list[CaseOutcome]] = defaultdict(list)
+    for o in outcomes:
+        key = getattr(o, attr)
+        if attr == "provenance":
+            key = key.split(":")[0] if not key.startswith("generated:") else key.split("@")[0]
+        groups[key].append(o)
+    return {k: summarise(v) for k, v in sorted(groups.items())}
+
+
+def compute_metrics(outcomes: list[CaseOutcome], examples: int = 15) -> dict[str, Any]:
+    capable = [o for o in outcomes if o.in_capability]
+    return {
+        "overall": summarise(outcomes),
+        "within_capability": summarise(capable),
+        "by_category": grouped(outcomes, "category"),
+        "by_dialect": grouped(outcomes, "dialect"),
+        "by_provenance": grouped(outcomes, "provenance"),
+        "false_negative_examples": [o.id for o in outcomes if o.kind == "fn"][:examples],
+        "false_positive_examples": [o.id for o in outcomes if o.kind == "fp"][:examples],
+        "decision_mismatch_examples": [
+            o.id for o in outcomes if o.expected is not o.actual and o.kind in ("tp", "tn")
+        ][:examples],
+    }

sqlguard_ninja/benchmarking/runner.py

@@ -0,0 +1,126 @@
+"""Run a dataset through an adapter and produce a versioned, machine-readable result."""
+
+from __future__ import annotations
+
+import json
+import platform
+import subprocess
+import sys
+from datetime import UTC, datetime
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+from typing import Any
+
+from sqlguard_ninja.benchmarking.adapters import BenchmarkAdapter
+from sqlguard_ninja.benchmarking.dataset import BenchmarkCase, Dataset
+from sqlguard_ninja.benchmarking.metrics import CaseOutcome, compute_metrics
+
+RESULT_SCHEMA = "sqlninja.benchmark-result/1"
+
+
+def _pkg_version(name: str) -> str | None:
+    try:
+        return version(name)
+    except PackageNotFoundError:
+        return None
+
+
+def _git_revision(root: Path) -> str | None:
+    try:
+        out = subprocess.run(
+            ["git", "rev-parse", "--short", "HEAD"],  # noqa: S607
+            cwd=root,
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return out.stdout.strip() or None
+
+
+def run_benchmark(
+    dataset: Dataset,
+    adapter: BenchmarkAdapter,
+    cases: list[BenchmarkCase] | None = None,
+    *,
+    warmup: int = 3,
+) -> dict[str, Any]:
+    """Evaluate every case and return the result document (see ``RESULT_SCHEMA``)."""
+    selected = dataset.cases if cases is None else cases
+    for case in selected[:warmup]:  # first parses pay one-time import/JIT costs
+        adapter.evaluate(case)
+    caps = adapter.capabilities
+    records: list[dict[str, Any]] = []
+    outcomes: list[CaseOutcome] = []
+    for case in selected:
+        verdict = adapter.evaluate(case)
+        outcome = CaseOutcome(
+            id=case.id,
+            category=case.category,
+            dialect=case.dialect,
+            provenance=case.provenance,
+            expected=case.expected,
+            actual=verdict.decision,
+            latency_ms=verdict.latency_ms,
+            error=verdict.error,
+            in_capability=caps is None or case.category in caps,
+        )
+        outcomes.append(outcome)
+        records.append(
+            {
+                "id": case.id,
+                "category": case.category,
+                "dialect": case.dialect,
+                "provenance": case.provenance,
+                "classification": case.classification.value,
+                "reason": case.reason.value,
+                "expected": case.expected.value,
+                "actual": verdict.decision.value,
+                "kind": outcome.kind,
+                "reasons": list(verdict.reasons),
+                "latency_ms": round(verdict.latency_ms, 4),
+                "error": verdict.error,
+                "in_capability": outcome.in_capability,
+            }
+        )
+    return {
+        "schema": RESULT_SCHEMA,
+        "created_at": datetime.now(UTC).isoformat(timespec="seconds"),
+        "benchmark": {
+            "name": dataset.manifest.name,
+            "version": dataset.manifest.version,
+            "fingerprint": dataset.fingerprint,
+            "cases_evaluated": len(selected),
+        },
+        "adapter": {
+            "name": adapter.name,
+            "version": adapter.version,
+            "capabilities": sorted(caps) if caps is not None else "all",
+        },
+        "environment": {
+            "python": sys.version.split()[0],
+            "platform": platform.platform(),
+            "machine": platform.machine(),
+            "sqlglot": _pkg_version("sqlglot"),
+            "sqlguard_ninja": _pkg_version("sqlguard-ninja"),
+            "git_revision": _git_revision(dataset.root),
+        },
+        "metrics": compute_metrics(outcomes),
+        "cases": records,
+    }
+
+
+def write_result(result: dict[str, Any], path: str | Path) -> Path:
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(json.dumps(result, indent=2, sort_keys=False) + "\n", encoding="utf-8")
+    return p
+
+
+def load_result(path: str | Path) -> dict[str, Any]:
+    data: dict[str, Any] = json.loads(Path(path).read_text(encoding="utf-8"))
+    if data.get("schema") != RESULT_SCHEMA:
+        raise ValueError(f"{path}: not a {RESULT_SCHEMA} document")
+    return data

sqlguard_ninja/benchmarking/translate.py

@@ -0,0 +1,64 @@
+"""Translate a SQLGuard Ninja policy + role into the simpler models of external validators.
+
+External tools have no roles or classification labels. The translation is deliberately
+*conservative* and documented, so the comparison is about enforcement quality and not about
+a hostile translation:
+
+* granted tables → table allowlist;
+* granted columns whose labels resolve to ``allow`` → column allowlist;
+* columns that are ungranted or whose labels resolve to anything else (deny, aggregate-only,
+  review) → column denylist (the external models cannot express aggregate-only or review);
+* tenant column of a tenant-scoped table → required equality predicate with the context value.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sqlguard_ninja.policy.model import Access, Policy
+from sqlguard_ninja.privacy.rules import resolve_column_access
+
+
+def translate_for_role(policy: Policy, role_name: str | None, dialect: str) -> dict[str, Any]:
+    """Return a JSON-serialisable, tool-neutral description of what ``role_name`` may read."""
+    _, role = policy.role(role_name)
+    tables: dict[str, Any] = {}
+    denied_names: set[str] = set()
+    for tname, tdef in policy.catalog.tables.items():
+        grant = role.tables.get(tname) if role is not None else None
+        if role is not None and grant is None:
+            denied_names.update(c for c in tdef.columns)
+            continue
+        allowed, denied = [], []
+        for cname in tdef.columns:
+            listed = grant is None or grant.columns == "*" or cname in grant.columns
+            if grant is not None and cname in grant.deny_columns:
+                listed = False
+            access = resolve_column_access(policy, role, tname, cname).strongest
+            if listed and access is Access.ALLOW:
+                allowed.append(cname)
+            else:
+                denied.append(cname)
+        tenant_scoped = role is None or role.tenant_scoped
+        tables[tname] = {
+            "allow_columns": allowed,
+            "deny_columns": denied,
+            "tenant_column": tdef.tenant_column if tenant_scoped else None,
+            "large": (tdef.estimated_rows or 0) >= policy.cost.large_table_rows,
+        }
+        denied_names.update(denied)
+    allowed_anywhere = {c for t in tables.values() for c in t["allow_columns"]}
+    limits = policy.effective_limits(role)
+    return {
+        "dialect": dialect,
+        "tables": tables,
+        # Name-only denylists cannot be table-scoped; a name that is allowed on some granted
+        # table is not denylisted (avoids penalising a tool for a translation artefact).
+        "pii_denylist": sorted(denied_names - allowed_anywhere),
+        "tenant_context_key": policy.tenant.context_key,
+        "limits": {
+            "max_joins": limits.max_joins,
+            "max_subquery_depth": limits.max_subquery_depth,
+            "max_limit": limits.max_limit,
+        },
+    }

sqlguard_ninja/benchmarking/workers/_protocol.py

@@ -0,0 +1,53 @@
+"""Shared JSON Lines loop for external-validator workers.
+
+Workers run inside a *separate* virtual environment where sqlguard_ninja is not installed,
+so this file is executed by path (copied into each worker by ``exec``) rather than imported.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import time
+import traceback
+from collections.abc import Callable
+from typing import Any
+
+Evaluator = Callable[[str, str, dict[str, Any], dict[str, Any]], tuple[str, list[str]]]
+
+
+def serve(library: str, version: str, build: Callable[[dict[str, Any]], Evaluator]) -> None:
+    """Answer one JSON request per stdin line until EOF."""
+    out = sys.stdout
+    out.write(json.dumps({"library": library, "version": version}) + "\n")
+    out.flush()
+    cache: dict[str, Evaluator] = {}
+    for line in sys.stdin:
+        if not line.strip():
+            continue
+        req = json.loads(line)
+        key = json.dumps(req["config"], sort_keys=True)
+        reply: dict[str, Any]
+        try:
+            if key not in cache:
+                cache[key] = build(req["config"])
+            started = time.perf_counter()
+            decision, reasons = cache[key](
+                req["sql"], req["dialect"], req["context"], req["config"]
+            )
+            reply = {
+                "decision": decision,
+                "reasons": reasons,
+                "latency_ms": (time.perf_counter() - started) * 1000,
+                "error": None,
+            }
+        except Exception as exc:  # report, fail closed, keep serving
+            reply = {
+                "decision": "deny",
+                "reasons": [],
+                "latency_ms": 0.0,
+                "error": f"{type(exc).__name__}: {exc}",
+                "trace": traceback.format_exc(limit=3),
+            }
+        out.write(json.dumps(reply) + "\n")
+        out.flush()

sqlguard_ninja/benchmarking/workers/agent_sql_guard_worker.py

@@ -0,0 +1,40 @@
+"""Worker for sakura-sky/sql-guard (PyPI ``agent-sql-guard``, import name ``sql_guard``)."""
+
+from __future__ import annotations
+
+from importlib.metadata import version
+from pathlib import Path
+from typing import Any
+
+exec((Path(__file__).parent / "_protocol.py").read_text(encoding="utf-8"))
+
+from sql_guard import PiiDenylist, SqlGuard, SqlGuardConfig  # type: ignore[import-not-found]
+
+_OUTCOME = {"allow": "allow", "confirm": "review", "deny": "deny"}
+
+
+def build(config: dict[str, Any]):  # type: ignore[no-untyped-def]
+    guard = SqlGuard(
+        SqlGuardConfig.from_settings(
+            # Pass "substrings" explicitly: upstream from_mapping() defaults a missing key to
+            # () and then rejects it as "not a list" (agent-sql-guard 0.2.0).
+            pii_denylist=PiiDenylist.from_mapping(
+                {"columns": config["pii_denylist"], "substrings": []}
+            ),
+            allowed_tables=list(config["tables"]),
+            dialect=config["dialect"],
+        )
+    )
+
+    def evaluate(sql, dialect, context, _config):  # type: ignore[no-untyped-def]
+        # evaluate_static() returns CONFIRM ("awaiting cost evaluation") for every query that
+        # passes the static rules; the cost stage needs a warehouse dry-run. This benchmark is
+        # static, so supply a zero-byte dry-run and let only the static rules decide.
+        decision = guard.evaluate(sql, bytes_processed=0)
+        outcome = _OUTCOME.get(str(decision.outcome.value).lower(), "deny")
+        return outcome, [decision.reason[:120]] if outcome != "allow" else []
+
+    return evaluate
+
+
+serve("agent-sql-guard", version("agent-sql-guard"), build)