codi-api-agent 0.3.1__py3-none-any.whl

api_agent/sql_loader.py

@@ -0,0 +1,1254 @@
+"""Load a Postgres schema's functions as catalog Tools — the SQL (warehouse) backend.
+
+The mirror of `openapi_loader`: where that turns OpenAPI operations into HTTP GET tools,
+this introspects a warehouse schema's functions (``pg_proc``) and exposes each one as a
+read-only tool, so the SAME pipeline (router → executor → synthesis → evaluator) runs over
+direct SQL instead of an HTTP API. Parameter names and types come straight from the
+database catalog — ground truth, so the type-inference mismatches an HTTP wrapper can
+introduce (e.g. a text-vs-integer cast on ``p_num_months``) can't happen here.
+
+Read-only enforcement is deterministic and layered — never prompt-based:
+  * only introspected (whitelisted) functions are callable — the model can NEVER run
+    free-form SQL; there is no tool that accepts a SQL string;
+  * every connection opens with ``default_transaction_read_only=on`` plus a
+    ``statement_timeout``;
+  * arguments are server-side bound (named notation with an explicit ``::type`` cast from
+    the introspected type), never interpolated into the SQL text;
+  * every call is capped with a LIMIT mirroring the HTTP loader's list handling.
+Connect with a SELECT-only role for defense in depth: grants are the real wall — the
+options above make accidents impossible even if a wider role is supplied.
+
+Failure classification: results carry a ``kind`` (auth | unreachable | server_error) from
+the Postgres SQLSTATE, so the agent's abstain logic doesn't depend on HTTP status strings.
+Evidence sources are ``sql://host:port/db/schema.fn`` URIs — `urlparse().netloc` yields the
+"host" the agent's failure bookkeeping already keys on.
+
+psycopg (v3) is imported lazily so the rest of the package works without it
+(``pip install codi-api-agent[sql]``); tests inject a fake ``connect``.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import statistics
+from collections import Counter
+from pathlib import Path
+from urllib.parse import urlparse
+
+from .catalog import Catalog, Tool
+from .log import get_logger, trunc
+from .openapi_loader import (
+    _REDACTED,
+    _compact_json,
+    _has_phone_number,
+    _is_phone_field,
+    _is_pii_key,
+    _redact_text,
+)
+
+_LOG = get_logger("api_agent.sql")
+
+
+def _redact_row(row: dict) -> dict:
+    """The same PII policy `_compact_json` applies, for the full-width `rows` payload —
+    raw rows must never leave the executor with personal/contact values intact."""
+    out = {}
+    for k, v in row.items():
+        if _is_pii_key(k):
+            out[k] = _REDACTED
+        elif _is_phone_field(k) and _has_phone_number(v):
+            out[k] = _REDACTED
+        elif isinstance(v, str):
+            out[k] = _redact_text(v)
+        else:
+            out[k] = v
+    return out
+
+# Introspection: every plain function (prokind='f') in the schema matching the prefix.
+# pg_get_function_identity_arguments gives "p_year integer, p_name character varying" —
+# names + types, no DEFAULT clauses; pronargdefaults says how many TRAILING args have one.
+_INTROSPECT_SQL = """
+SELECT p.proname,
+       pg_get_function_identity_arguments(p.oid) AS args,
+       obj_description(p.oid, 'pg_proc')         AS comment,
+       p.pronargdefaults                          AS num_defaults,
+       pg_get_function_result(p.oid)              AS result_type
+FROM pg_proc p
+JOIN pg_namespace n ON n.oid = p.pronamespace
+WHERE n.nspname = %(schema)s
+  AND p.prokind = 'f'
+  AND p.proname LIKE %(pattern)s
+ORDER BY p.proname, p.pronargs DESC, p.oid
+"""
+# Ordering note: overloads arrive richest-signature-first (most args), so the fullest
+# variant gets the clean tool name and a legacy short-arg overload gets a `_2` suffix.
+
+# Postgres type name -> JSON-schema type the model fills in.
+_PG_INT = {"smallint", "integer", "bigint", "int2", "int4", "int8", "serial", "bigserial"}
+_PG_NUM = {"numeric", "decimal", "real", "double precision", "float4", "float8", "money"}
+_PG_BOOL = {"boolean", "bool"}
+
+_ARG_MODES = ("IN ", "INOUT ", "OUT ", "VARIADIC ")
+
+
+def _json_type(pgtype: str) -> str:
+    t = pgtype.strip().lower()
+    if t in _PG_INT:
+        return "integer"
+    if t in _PG_NUM:
+        return "number"
+    if t in _PG_BOOL:
+        return "boolean"
+    return "string"  # text/varchar/date/timestamp/uuid/json… — the ::cast restores the real type
+
+
+def parse_identity_args(args_text: str) -> list[tuple[str, str]]:
+    """Parse ``pg_get_function_identity_arguments`` output into [(name, pgtype)].
+
+    Handles multi-word types ("character varying", "timestamp with time zone"), typmod
+    parens ("numeric(10,2)") and mode prefixes. OUT args (no name binding needed) are
+    skipped; an unnamed arg (type only) gets a positional placeholder name.
+    """
+    out: list[tuple[str, str]] = []
+    if not (args_text or "").strip():
+        return out
+    # split on top-level commas only (numeric(10,2) has a comma inside parens)
+    parts, depth, cur = [], 0, ""
+    for ch in args_text:
+        if ch == "(":
+            depth += 1
+        elif ch == ")":
+            depth -= 1
+        if ch == "," and depth == 0:
+            parts.append(cur)
+            cur = ""
+        else:
+            cur += ch
+    if cur.strip():
+        parts.append(cur)
+    for i, part in enumerate(parts):
+        p = part.strip()
+        mode = "IN"
+        for m in _ARG_MODES:
+            if p.startswith(m):
+                mode = m.strip()
+                p = p[len(m):].strip()
+                break
+        if mode == "OUT":  # result column, not a call argument
+            continue
+        # First token is the arg NAME iff more tokens follow that form a type; a
+        # single-token part is an unnamed arg of that type (identity args omit names then).
+        tokens = p.split(None, 1)
+        if len(tokens) == 2 and re.fullmatch(r"[a-zA-Z_][a-zA-Z0-9_$]*", tokens[0]):
+            out.append((tokens[0], tokens[1].strip()))
+        else:
+            out.append((f"arg{i + 1}", p))
+    return out
+
+
+def _humanize(proname: str, fn_prefix: str) -> str:
+    core = proname[len(fn_prefix):] if fn_prefix and proname.startswith(fn_prefix) else proname
+    return core.replace("_", " ").strip()
+
+
+# Parameters whose text argument must be one of a fixed set of values (e.g.
+# p_time_period ∈ {MTD, QTD, YTD, TTM}). The DB catalog can't express this — the allowed
+# set lives only in the human parameter docs — so a model given just the type "text" invents
+# values like "month_to_date" that the function silently ignores, returning wrong data. The
+# reference JSON (api_reference_docs/ARQ_SQL_FUNCTIONS.json) records the set in each param's
+# description; we parse it, advertise it to the model as a JSON-schema `enum`, AND reject any
+# out-of-set value at call time (below) so a bad value can never reach SQL.
+DEFAULT_PARAM_DOC_REF = (
+    Path(__file__).resolve().parents[1] / "api_reference_docs" / "ARQ_SQL_FUNCTIONS.json"
+)
+_ENUM_TAIL = re.compile(r"\bone of\b(.*)", re.IGNORECASE | re.DOTALL)
+_QUOTED = re.compile(r"'([^']*)'")
+_param_doc_cache: dict[str, tuple[float, dict]] = {}
+
+
+def parse_enum(desc: str) -> tuple[list[str] | None, bool]:
+    """Extract a closed value set from a parameter description. Two documented forms:
+
+      * prose   — ``"one of 'MTD', 'QTD', 'YTD', 'TTM'."``
+      * pipe    — ``"'month' | 'quarter' | 'year'"`` / ``"NULL | 'doc' | 'hyg'"``
+
+    → ``(["MTD","QTD","YTD","TTM"], case_sensitive)``. Returns ``(None, False)`` when the
+    description names no set. An unquoted ``NULL`` token means "omittable", not a literal value,
+    so it's excluded (a blank arg is already dropped upstream). ``case_sensitive`` is True only
+    when the text explicitly says so (e.g. category names) — otherwise a wrong-case value is
+    normalized to the canonical form rather than rejected.
+    """
+    if not desc:
+        return None, False
+    m = _ENUM_TAIL.search(desc)
+    if m:
+        vals = _QUOTED.findall(m.group(1))
+    elif "|" in desc:  # pipe form has no lead-in; require the '|' so a stray quote isn't a set
+        vals = _QUOTED.findall(desc)
+    else:
+        return None, False
+    if len(vals) < 2:  # a single quoted token isn't a meaningful choice
+        return None, False
+    low = desc.lower()
+    case_sensitive = "case-sensitive" in low and "case-insensitive" not in low
+    return vals, case_sensitive
+
+
+def param_docs_from_reference(path: str | Path | None = None) -> dict[str, dict[str, str]]:
+    """``{proname: {param_name: description}}`` from a reference JSON (default: the bundled
+    ARQ_SQL_FUNCTIONS.json) — the authority on each parameter's allowed values. Best-effort
+    and cached by file mtime: returns ``{}`` if the file is missing or unreadable, so a
+    warehouse with no reference doc simply gets no enum constraints (unchanged behavior)."""
+    p = Path(path) if path else DEFAULT_PARAM_DOC_REF
+    try:
+        mtime = p.stat().st_mtime
+    except OSError:
+        return {}
+    cached = _param_doc_cache.get(str(p))
+    if cached and cached[0] == mtime:
+        return cached[1]
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+    except Exception:  # malformed/partial file — behave as if absent
+        return {}
+    out: dict[str, dict[str, str]] = {}
+    for fn in data.get("functions") or []:
+        name = fn.get("function")
+        if not name:
+            continue
+        docs = {prm["name"]: (prm.get("description") or "")
+                for prm in fn.get("parameters") or [] if prm.get("name")}
+        if docs:
+            out[name] = docs
+    _backfill_enum_docs(out)
+    _param_doc_cache[str(p)] = (mtime, out)
+    return out
+
+
+def _backfill_enum_docs(out: dict[str, dict[str, str]]) -> None:
+    """Within one reference, a parameter NAME maps to a single allowed set, yet some functions
+    document it (``p_period_type`` → ``'month' | 'quarter' | 'year'``) while others leave it
+    blank. Propagate the documented description to the blanks so every function that takes the
+    param is constrained — but only when the name's documented set is UNAMBIGUOUS (skip a name
+    that appears with two different sets, so we never guess). Mutates ``out`` in place."""
+    best: dict[str, str] = {}
+    conflict: set[str] = set()
+    for docs in out.values():
+        for pname, desc in docs.items():
+            vals, _ = parse_enum(desc)
+            if not vals:
+                continue
+            if pname in best and set(parse_enum(best[pname])[0]) != set(vals):
+                conflict.add(pname)
+            best.setdefault(pname, desc)
+    for pname in conflict:
+        best.pop(pname, None)
+    for docs in out.values():
+        for pname, desc in docs.items():
+            if pname in best and not parse_enum(desc)[0]:
+                docs[pname] = best[pname]
+
+
+def _param_hint(aname: str, atype: str) -> str:
+    """A model-readable description for one argument: the humanized name (so `p_num_months`
+    reads as "num months") + its type, with a format hint for dates. The function COMMENT
+    (in the tool description) carries the real semantics; this makes the arg self-describing
+    even without one."""
+    human = re.sub(r"^p_|^_", "", aname).replace("_", " ").strip()
+    t = atype.strip().lower()
+    if t == "date":
+        return f"{human} (date, YYYY-MM-DD)"[:160]
+    return f"{human} ({atype.strip()})"[:160]
+
+
+def _sanitize(name: str) -> str:
+    return (re.sub(r"[^a-zA-Z0-9_-]", "_", name)[:64]) or "fn"
+
+
+def _unique(name: str, seen: set[str]) -> str:
+    out, i = name, 2
+    while out in seen:
+        out = f"{name}_{i}"[:64]
+        i += 1
+    seen.add(out)
+    return out
+
+
+def _dsn_label(dsn: str) -> str:
+    """host:port/db from a DSN, for `sql://<label>/…` sources (netloc = the agent's 'host')."""
+    try:
+        p = urlparse(dsn if "://" in dsn else "postgresql://" + dsn)
+        host = p.hostname or "warehouse"
+        port = f":{p.port}" if p.port else ""
+        db = (p.path or "").lstrip("/")
+        return f"{host}{port}" + (f"/{db}" if db else "")
+    except Exception:
+        return "warehouse"
+
+
+def classify_pg_error(exc: Exception) -> tuple[str, str]:
+    """(kind, message) for a psycopg error — from SQLSTATE when present, else the message.
+
+    kinds match the agent's failure taxonomy: auth (bad credentials / no permission),
+    unreachable (can't connect), timeout (the statement ran past `statement_timeout` and was
+    cancelled), server_error (the query/function itself failed — the persistent-5xx detector
+    reads the message text, e.g. "function … does not exist").
+
+    `timeout` is separate from `server_error` because nothing is broken: the query is valid and
+    the data is there, it just did not finish. That is a different thing to tell the reader, and
+    a different thing for the agent to do about it (narrow the period, ask for fewer rows).
+    """
+    msg = str(exc).strip() or exc.__class__.__name__
+    state = getattr(exc, "sqlstate", None) or ""
+    if state == "57014":  # query_canceled — statement_timeout fired
+        return "timeout", msg
+    if state.startswith("28"):  # invalid_authorization_specification / invalid_password
+        return "auth", msg
+    if state == "42501":  # insufficient_privilege
+        return "auth", msg
+    if state.startswith("08"):  # connection_exception family
+        return "unreachable", msg
+    low = msg.lower()
+    if "canceling statement due to statement timeout" in low or "query_canceled" in low:
+        return "timeout", msg
+    if any(s in low for s in ("password authentication failed", "pg_hba.conf",
+                              "permission denied", "role", "authentication")):
+        return "auth", msg
+    if any(s in low for s in ("connection refused", "could not connect", "timeout expired",
+                              "could not translate host name", "connection timed out",
+                              "server closed the connection", "is the server running")):
+        return "unreachable", msg
+    return "server_error", msg
+
+
+def _jsonable(v):
+    """A DB value as something json.dumps handles (Decimal/date/UUID/bytes → primitives)."""
+    if v is None or isinstance(v, (str, int, float, bool)):
+        return v
+    if isinstance(v, (list, tuple)):
+        return [_jsonable(x) for x in v]
+    if isinstance(v, dict):
+        return {k: _jsonable(x) for k, x in v.items()}
+    if isinstance(v, bytes):
+        return f"<{len(v)} bytes>"
+    iso = getattr(v, "isoformat", None)
+    if callable(iso):  # date / datetime / time
+        return iso()
+    try:  # Decimal and other numerics
+        return float(v)
+    except Exception:
+        return str(v)
+
+
+def _default_connect(dsn: str, timeout: int, statement_timeout_ms: int):
+    try:
+        import psycopg
+    except ImportError as e:  # pragma: no cover
+        raise RuntimeError(
+            "psycopg is required for the SQL backend: pip install 'codi-api-agent[sql]'") from e
+    return psycopg.connect(
+        dsn,
+        connect_timeout=timeout,
+        autocommit=True,  # each call is a single read-only SELECT; no txn bookkeeping needed
+        options=f"-c default_transaction_read_only=on -c statement_timeout={statement_timeout_ms}",
+    )
+
+
+# --------------------------------------------------------------------------- #
+# DSN -> Catalog
+# --------------------------------------------------------------------------- #
+def load_sql_catalog(dsn: str, schema: str = "gold", fn_prefix: str = "fn_",
+                     max_functions: int = 1000, timeout: int = 20,
+                     statement_timeout_ms: int = 30000, connect=None,
+                     param_docs: dict[str, dict[str, str]] | None = None,
+                     profile_rows: int = 100_000) -> Catalog:
+    """Introspect ``schema``'s ``<fn_prefix>*`` functions and build a read-only Catalog.
+
+    ``connect(dsn, timeout, statement_timeout_ms)`` is injectable for tests; the default
+    opens a psycopg connection with the read-only + timeout session options.
+
+    ``param_docs`` (``{proname: {param: description}}``) supplies allowed-value sets the DB
+    catalog can't express; defaults to the bundled ARQ reference (harmless — only functions
+    present there are affected). Matching params gain a JSON-schema ``enum`` and are validated
+    at call time.
+    """
+    connect = connect or _default_connect
+    if param_docs is None:
+        param_docs = param_docs_from_reference()
+    label = _dsn_label(dsn)  # host:port/db only — the DSN (with credentials) is never logged
+    _LOG.info("introspect: %s schema=%s prefix=%s*", label, schema, fn_prefix)
+    with connect(dsn, timeout, statement_timeout_ms) as conn:
+        cur = conn.cursor()
+        cur.execute(_INTROSPECT_SQL, {"schema": schema, "pattern": fn_prefix + "%"})
+        rows = cur.fetchall()
+        # Location vocabulary for the p_location_names guard — loaded ONCE, and only if some
+        # function actually takes that parameter (r[1] is the identity-args text). Fail-open.
+        loc_index = (_load_location_index(conn)
+                     if any("location_names" in (r[1] or "") for r in rows) else None)
+        location_vocab: set[str] = loc_index.values if loc_index else set()
+    _LOG.info("introspect: %s → %d function(s)%s", label, len(rows),
+              f"; {len(location_vocab)} known locations" if location_vocab else "")
+
+    tools: list[Tool] = []
+    reference: list[dict] = []
+    seen: set[str] = set()
+    # CROSS-FUNCTION PARAMETER VOCABULARY: {arg_name: every value documented for it ANYWHERE}.
+    # Only 19 of 62 functions taking `p_comparison` document its allowed set, so 43 of them had
+    # NO guard — and Postgres does not reject an unknown value, it silently falls through to the
+    # default branch. Measured: p_comparison='previous' and 'garbage_value' returned byte-identical
+    # rows to 'yoy', so the agent asked for a month-over-month comparison, got year-over-year data
+    # and narrated it as month-over-month. This union ({budget, mom, qoq, yoy}) is a SAFETY NET
+    # beneath the per-function enum: it can only reject a value that is valid for NO function, so
+    # it never blocks a legitimate call, while catching invented values like those two.
+    param_vocab: dict[str, set] = {}
+    for proname, args_text, comment, num_defaults, result_type in rows[:max_functions]:
+        args = parse_identity_args(args_text or "")
+        # pronargdefaults counts TRAILING args with a DEFAULT — those are optional.
+        first_optional = len(args) - int(num_defaults or 0)
+        # Overloads (same name, different signature) each load as their own tool — the
+        # richest signature keeps the clean name (see the introspection ORDER BY), the
+        # rest get a numeric suffix. Silently skipping them loses real capabilities.
+        name = _unique(_sanitize(f"{schema}_{proname}"), seen)
+        human = _humanize(proname, fn_prefix)
+        # The COMMENT is the function's documentation — often the ONLY place semantics
+        # like a date-window contract live ("p_start_date if set, else p_num_months back").
+        # Keep it near-whole: the router tokenizes all of it, and only the few routed
+        # tools' descriptions ever reach the executor's context.
+        desc = (comment or "").strip() or f"Warehouse data: {human}."
+        description = (f"{desc} (read-only SQL function {schema}.{proname}; "
+                       f"returns {(result_type or 'rows').strip()[:160]})")[:1500]
+
+        docs = param_docs.get(proname, {})
+        properties: dict = {}
+        required: list[str] = []
+        enums: dict[str, tuple[list[str], bool]] = {}
+        for i, (aname, atype) in enumerate(args):
+            prop = {"type": _json_type(atype), "description": _param_hint(aname, atype)}
+            # Match the doc by the exact arg name or its p_-stripped core (the reference and
+            # the DB both use p_ names, but stay robust to either form).
+            doc = docs.get(aname) or docs.get(re.sub(r"^p_|^_", "", aname))
+            allowed, case_sensitive = parse_enum(doc or "")
+            if allowed:
+                prop["enum"] = allowed
+                prop["description"] = f"{_param_hint(aname, atype)} — {doc.strip()}"[:200]
+                enums[aname] = (allowed, case_sensitive)
+                # Feed the cross-function VOCABULARY (see param_vocab below). Populated as the
+                # loop runs and read lazily at call time, so every executor sees the full union.
+                param_vocab.setdefault(aname, set()).update(allowed)
+            properties[aname] = prop
+            if i < first_optional:
+                required.append(aname)
+        parameters = {"type": "object", "properties": properties, "required": required}
+
+        tools.append(Tool(
+            name=name,
+            description=description,
+            parameters=parameters,
+            data_type="structured",
+            backend="sql",
+            cache_key=label,  # results from different DSNs must never cross-serve
+            fn=_make_executor(dsn, label, schema, proname, args, connect,
+                              statement_timeout_ms, required=set(required), enums=enums,
+                              profile_rows=profile_rows, vocab=param_vocab,
+                              locations=location_vocab),
+        ))
+        reference.append({
+            "name": name, "method": "SQL", "path": f"{schema}.{proname}",
+            "summary": (comment or "").strip().splitlines()[0] if comment else human,
+            "description": (comment or "").strip()[:1200],
+            "params": [{"name": a, "in": "arg", "required": i < first_optional,
+                        "type": t, "example": None} for i, (a, t) in enumerate(args)],
+            "body": [],
+        })
+    # ---- BACKFILL THE ALLOWED VALUES the model was never shown ------------------------------
+    # `param_vocab` is the union of every closed value set the schema documents, keyed by
+    # parameter name. The CALL-TIME guard already enforces it: a value valid for no function in
+    # the catalog is rejected as an invention. But it was only ever used to REJECT, never to
+    # INFORM — so for the 42 of 62 operations that expose `p_comparison` without documenting its
+    # values, the model had nothing to go on and guessed. Measured, twice in one query:
+    # `p_comparison='current'` rejected on both calls, each costing a round-trip to recover.
+    #
+    # Advertising the set cannot be more restrictive than what is already enforced, which is what
+    # makes this safe: any value that would have been accepted still is. It only stops the model
+    # inventing one. Done as a post-pass because the union is not complete until every function
+    # has been read.
+    _backfill_enums(tools, param_vocab)
+    cat = Catalog(tools, reference=reference)
+    # Ride the resolver along on the catalog: the AGENT owns argument binding (it is the only
+    # layer that sees the user's question), while the index can only be built here, where the
+    # warehouse connection is.
+    cat.locations = loc_index
+    return cat
+
+
+
+# A closed set this large is a vocabulary, not an enum — advertising it would bloat every tool
+# definition and it is not what the model is getting wrong.
+_MAX_BACKFILL_ENUM = 12
+
+
+def _backfill_enums(tools: "list[Tool]", param_vocab: "dict[str, set]") -> int:
+    """Advertise a parameter's allowed values when the schema documents them ELSEWHERE.
+
+    Returns the number of parameters filled in. Only touches string parameters that have no enum
+    of their own; a function that documents its own set always keeps it.
+    """
+    filled = 0
+    for tool in tools:
+        props = (tool.parameters or {}).get("properties") or {}
+        for aname, prop in props.items():
+            if prop.get("enum") or prop.get("type") != "string":
+                continue
+            known = param_vocab.get(aname) or param_vocab.get(re.sub(r"^p_|^_", "", aname))
+            if not known or len(known) > _MAX_BACKFILL_ENUM:
+                continue
+            allowed = sorted(known)
+            prop["enum"] = allowed
+            prop["description"] = (
+                f"{prop.get('description', aname)} — allowed values (documented on other "
+                f"operations taking this parameter): {', '.join(repr(a) for a in allowed)}")[:300]
+            filled += 1
+    if filled:
+        _LOG.info("enum backfill: advertised allowed values for %d parameter(s) whose own "
+                  "function documents none", filled)
+    return filled
+
+
+PROFILE_MAX_COLS = 16                        # caps.md: ARQ finance tables exceed 12 cols; +4 ≈ 120 tok
+PROFILE_PERCENTILES = [0.05, 0.25, 0.5, 0.75, 0.95]
+_PROFILE_TOP_VALUES = 3                      # most-frequent values per categorical column
+
+
+PROFILE_ROW_FIELDS = 12  # fields kept from an extreme row (bounds prompt size on wide tables)
+
+
+_YEAR_ARGS = ("p_year", "year", "p_ref_year", "ref_year")
+_MONTH_ARGS = ("p_month", "month", "p_ref_month", "ref_month")
+
+
+def incomplete_period_note(bound: dict, today=None) -> str:
+    """A warning when the requested period is the CURRENT (still-running) month or a future one.
+
+    Not an empty-window check — the far more dangerous case is a PARTIAL one. Measured: asked
+    for July 2026 (day 21 of 31, partial ingestion) the warehouse returned 7,980 against June's
+    506,202, and 60 procedures against 2,913. Every figure is real and grounded, so no
+    fabrication or emptiness check fires, and the agent reported a "97.9% decline" that is
+    purely an artifact of comparing 21 days to a full month.
+
+    Uses the calendar only — the current month is incomplete by definition — so it needs no
+    warehouse-specific knowledge and holds for any schema. Informational, never blocking: a
+    user may legitimately ask how the current month is tracking."""
+    import datetime
+    today = today or datetime.date.today()
+    year = next((bound[k] for k in _YEAR_ARGS if isinstance(bound.get(k), int)), None)
+    month = next((bound[k] for k in _MONTH_ARGS if isinstance(bound.get(k), int)), None)
+    if year is None or month is None or not (1 <= month <= 12):
+        return ""
+    if (year, month) < (today.year, today.month):
+        return ""  # a past month is complete
+    which = "the CURRENT, still-running month" if (year, month) == (today.year, today.month) \
+        else "a FUTURE month"
+    last_y, last_m = (today.year, today.month - 1) if today.month > 1 else (today.year - 1, 12)
+    return (f"NOTE: you requested {year}-{month:02d}, which is {which} (today is "
+            f"{today.isoformat()}). These figures cover only part of the period, so they are "
+            f"NOT comparable with a full month and any drop against a prior month is an "
+            f"artifact of the shorter window, NOT a business decline. Say this explicitly, or "
+            f"re-run for the last COMPLETE month ({last_y}-{last_m:02d}).\n")
+
+
+def _extreme_row(row: dict) -> dict:
+    """The WHOLE row holding an extreme (trimmed for width), not just a label.
+
+    A single-field label loses the rest of the identity — `max_row="Patel"` cannot tell you
+    *which* Patel or *which month*, so an answer built from it mis-attributes the figure. The
+    full row lets both the model and the deterministic corrector name the extreme completely
+    (`Patel, Chirag — 2023-08-01`). Rows are already PII-redacted before profiling."""
+    return dict(list(row.items())[:PROFILE_ROW_FIELDS])
+
+
+def row_label(row: dict | None) -> str:
+    """A readable attribution built from an extreme ROW: its identifying (non-numeric) fields,
+    e.g. `Patel, Chirag, 2023-08-01`. Falls back to the first usable field."""
+    if not isinstance(row, dict) or not row:
+        return ""
+    parts = [str(v).strip() for v in row.values()
+             if isinstance(v, str) and str(v).strip()]
+    if parts:
+        return ", ".join(parts[:3])[:80]
+    for k, v in row.items():
+        if v is not None and not isinstance(v, (dict, list)):
+            return f"{k}={v}"
+    return ""
+
+
+def _num(v):
+    """A plain JSON-safe Python number (pandas/numpy scalars are neither)."""
+    try:
+        f = float(v)
+    except (TypeError, ValueError):
+        return None
+    if f != f or f in (float("inf"), float("-inf")):  # NaN / inf → omit
+        return None
+    return round(f, 4)
+
+
+_TERM_RE = re.compile(r"[a-z0-9][a-z0-9.'-]*")
+
+
+def _term_score(row: dict, terms: "frozenset[str]") -> int:
+    """How many of the question's own words this row NAMES, counted over text cells only."""
+    if not terms:
+        return 0
+    hit = set()
+    for v in row.values():
+        if isinstance(v, str):
+            hit |= terms & set(_TERM_RE.findall(v.lower()))
+    return len(hit)
+
+
+def _keep(ordered: list[dict], n: int, period_col: str,
+          terms: "frozenset[str]") -> list[dict]:
+    """The `n` rows to keep from a period-ordered set: the ones the question NAMES first, then the
+    most recent of the rest — re-sorted ascending so a trend still reads left-to-right."""
+    if len(ordered) <= n:
+        return ordered
+    if not terms:
+        return ordered[-n:]
+    from .metrics import _as_period
+    scored = [(-_term_score(r, terms), r) for r in ordered]
+    if not any(s for s, _ in scored):                     # nothing matched — recency stands
+        return ordered[-n:]
+    # Stable within a score band, and `ordered` is already oldest-first, so reversing before the
+    # sort keeps the MOST RECENT members of each band — recency still breaks ties.
+    kept = [r for _, r in sorted(reversed(scored), key=lambda sr: sr[0])[:n]]
+    return sorted(kept, key=lambda r: _as_period(r.get(period_col)))
+
+
+def _visible_slice(rows: list[dict], n: int,
+                   prefer_period: "tuple | None" = None,
+                   prefer_terms: "frozenset[str] | None" = None) -> list[dict]:
+    """The `n` rows to actually show. For a TIME-INDEXED result that means the most RECENT `n`,
+    not the first `n` in storage order.
+
+    Storage order buries the present. Measured live: `fn_dentrix_provider_monthly_production`
+    returns 1,295 rows spanning 2017-01 to 2026-07, and the first 150 stop at **2025-01** — so
+    asked for June 2026 the agent replied "not available … the latest data shown is for July
+    2024", when June 2026 holds 11 rows totalling $506,202.02. The same slice made an Eaglesoft
+    answer report $74,478 against a real $421,448. The rows existed; they were simply never shown.
+
+    Business questions are overwhelmingly about recent periods, so recency is the right default
+    when something must be dropped. Rows are re-sorted back into ascending period order for
+    display, so a trend still reads left-to-right. Non-temporal results keep their original order,
+    which is often meaningful (many functions pre-sort by `ABS(delta) DESC`).
+
+    `prefer_terms` are the question's own words, and they outrank recency. Many of these functions
+    take NO ARGUMENTS AT ALL — `fn_curve_provider_monthly_production()` returns 3,227 rows, every
+    provider and every month from 2023 to 2026 — so a filter the question states can never be
+    pushed into the call and must survive the cap instead. Measured: "monthly production for the
+    Curve provider Temp for the year 2025" period-scoped correctly to 2025, but 2025 alone holds
+    665 rows across all providers, so the most-recent-150 window landed on October–December and
+    the answer reported three months and a total of 100,910.7. Temp has twelve months in 2025
+    totalling 45,126.55, all of them scanned and none of them shown.
+
+    This PRIORITISES rather than filters: matching rows go first, the remainder fills what is
+    left. A spurious match therefore costs nothing but ordering, and the result can never be
+    narrowed to nothing — which a filter, applied to a term that matched by accident, could do.
+    """
+    if len(rows) <= n:
+        return rows
+    from .metrics import _as_period
+    terms = prefer_terms or frozenset()
+    period_col = next(
+        (c for c in rows[0]
+         if all(_as_period(r.get(c)) is not None for r in rows)), None) if rows else None
+    if not period_col:
+        # No time axis — original order is often meaningful (many functions pre-sort by
+        # ABS(delta) DESC), so only a term match may disturb it, and stably.
+        return sorted(rows, key=lambda r: -_term_score(r, terms))[:n] if terms else rows[:n]
+    ordered = sorted(rows, key=lambda r: _as_period(r.get(period_col)))
+    # A HISTORICAL question overrides recency. Asked for 2018 or 2024 production the agent replied
+    # "the evidence does not include any data for 2024" — true of the rows it was SHOWN and false
+    # of the table, which holds them. When the question names a period, the window is centred on
+    # it: rows AT that period first, then the ones leading up to it (so a trend still has context).
+    if prefer_period:
+        want_y, want_m = (list(prefer_period) + [None])[:2]
+        at = [r for r in ordered if _as_period(r.get(period_col))[0] == want_y
+              and (want_m is None or _as_period(r.get(period_col))[1] == want_m)]
+        if at:
+            # ONLY the requested period. Padding with the months leading up to it gives a trend
+            # context nobody asked for and makes the answer wrong in a way that is hard to see:
+            # asked for "Dentrix production for the 2024 calendar year" the answer included 2023
+            # rows and reported them as 2024. A question that names a period is answered from that
+            # period; if the reader wants the run-up they ask for it.
+            return _keep(at, n, period_col, terms)
+    return _keep(ordered, n, period_col, terms)
+
+
+def describe_rows(rows: list[dict], *, scanned: int | None = None,
+                  complete: bool = True) -> dict | None:
+    """A `DataFrame.describe()`-style statistical profile of a result set — the AUTHORITATIVE
+    aggregate handed to the model in place of a huge table.
+
+    Computed over EVERY row FETCHED, not the page the model is shown. That distinction is the
+    whole point: the agent once reported a $172,994 "maximum" and a $24,693 "average" from the
+    50 rows it could see, when the true 5,830-row values were $228,588 and $23,484. Both stated
+    figures existed in the data, so the grounding check passed — a real number attached to a
+    false claim. Real aggregates let the model state the extreme CORRECTLY rather than be told
+    not to mention one, and they cost ~10 lines of prompt instead of thousands of rows.
+
+    Percentiles (p5/p25/median/p75/p95) come along because spread and outlier questions need
+    them — "is this month unusual?" is not answerable from min/max/mean alone.
+
+    Uses pandas when importable and falls back to stdlib statistics otherwise (same pattern as
+    the optional embedding model). Returns None when there is nothing worth profiling.
+    """
+    dict_rows = [r for r in rows or [] if isinstance(r, dict)]
+    if not dict_rows:
+        return None
+    cols = list(dict_rows[0].keys())[:PROFILE_MAX_COLS]
+    numeric, categorical = _describe_pandas(dict_rows, cols)
+    if numeric is None:  # pandas unavailable
+        numeric, categorical = _describe_stdlib(dict_rows, cols)
+    if not numeric and not categorical:
+        return None
+    return {"rows_scanned": scanned if scanned is not None else len(dict_rows),
+            # False when the scan cap was hit — even the profile is then a (large) sample, and
+            # the answer must not claim a definitive overall extreme.
+            "complete": complete,
+            "numeric": numeric, "categorical": categorical}
+
+
+def _describe_pandas(dict_rows: list[dict], cols: list[str]):
+    """(numeric, categorical) via pandas, or (None, None) when pandas isn't installed."""
+    try:
+        import pandas as pd
+    except Exception:
+        return None, None
+    df = pd.DataFrame(dict_rows, columns=cols)
+    numeric: dict[str, dict] = {}
+    categorical: dict[str, dict] = {}
+    for col in cols:
+        s = pd.to_numeric(df[col], errors="coerce")
+        if s.notna().sum() >= 2:
+            d = s.describe(percentiles=PROFILE_PERCENTILES)
+            stats = {"count": int(s.notna().sum()), "nulls": int(df[col].isna().sum())}
+            for key, out in (("mean", "mean"), ("std", "stdev"), ("min", "min"), ("max", "max"),
+                             ("5%", "p5"), ("25%", "p25"), ("50%", "median"),
+                             ("75%", "p75"), ("95%", "p95")):
+                if key in d and (val := _num(d[key])) is not None:
+                    stats[out] = val
+            stats["sum"] = _num(s.sum())
+            # which ROW holds the extreme — describe() can't say, and it is what users ask for
+            stats["min_row"] = _extreme_row(dict_rows[int(s.idxmin())])
+            stats["max_row"] = _extreme_row(dict_rows[int(s.idxmax())])
+            numeric[col] = stats
+        else:
+            texts = df[col].dropna().astype(str)
+            if not texts.empty:
+                top = texts.value_counts().head(_PROFILE_TOP_VALUES)
+                categorical[col] = {
+                    "count": int(texts.size), "nulls": int(df[col].isna().sum()),
+                    "unique": int(texts.nunique()),
+                    "top": [{"value": str(v), "freq": int(n)} for v, n in top.items()]}
+    return numeric, categorical
+
+
+def _describe_stdlib(dict_rows: list[dict], cols: list[str]):
+    """Same shape as _describe_pandas, using only the standard library."""
+    numeric: dict[str, dict] = {}
+    categorical: dict[str, dict] = {}
+    for col in cols:
+        vals = [r.get(col) for r in dict_rows]
+        nulls = sum(1 for v in vals if v is None)
+        # Coerce like pandas' to_numeric rather than isinstance-testing: Postgres hands back
+        # Decimal for numeric columns, which is neither int nor float, so a strict type check
+        # silently skipped every money column and the profile came back empty.
+        pairs = [(f, r) for v, r in zip(vals, dict_rows)
+                 if (f := _num(v)) is not None and not isinstance(v, bool)]
+        if len(pairs) >= 2:
+            nums = sorted(v for v, _ in pairs)
+            lo, lo_row = min(pairs, key=lambda p: p[0])
+            hi, hi_row = max(pairs, key=lambda p: p[0])
+            lo_row, hi_row = _extreme_row(lo_row), _extreme_row(hi_row)
+            stats = {"count": len(nums), "nulls": nulls,
+                     "min": _num(lo), "min_row": lo_row,
+                     "max": _num(hi), "max_row": hi_row,
+                     "mean": _num(statistics.fmean(nums)),
+                     "median": _num(statistics.median(nums)),
+                     # SAMPLE stdev (ddof=1) to match pandas' describe(), so the two paths
+                     # never disagree on the same data.
+                     "stdev": _num(statistics.stdev(nums)) if len(nums) > 1 else 0.0,
+                     "sum": _num(sum(nums))}
+            for q, name in zip(PROFILE_PERCENTILES, ("p5", "p25", "median", "p75", "p95")):
+                stats[name] = _num(_quantile(nums, q))
+            numeric[col] = stats
+        else:
+            texts = [str(v) for v in vals if v is not None and not isinstance(v, (dict, list))]
+            if texts:
+                top = Counter(texts).most_common(_PROFILE_TOP_VALUES)
+                categorical[col] = {"count": len(texts), "nulls": nulls,
+                                    "unique": len(set(texts)),
+                                    "top": [{"value": v, "freq": n} for v, n in top]}
+    return numeric, categorical
+
+
+def _quantile(sorted_vals: list[float], q: float) -> float:
+    """Linear-interpolation quantile (pandas' default), so both paths agree."""
+    if not sorted_vals:
+        return 0.0
+    if len(sorted_vals) == 1:
+        return sorted_vals[0]
+    pos = q * (len(sorted_vals) - 1)
+    lo = int(pos)
+    hi = min(lo + 1, len(sorted_vals) - 1)
+    return sorted_vals[lo] + (sorted_vals[hi] - sorted_vals[lo]) * (pos - lo)
+
+
+
+# Warehouse location names carry an internal prefix — '001-BDD-Indianapolis IN' — that no user
+# types. Stripping it is what turns the stored value into something a question can be matched against.
+_LOC_PREFIX = re.compile(r"^\s*\d+\s*-\s*[A-Za-z&]+\s*-\s*")
+# A trailing US state code: 'Indianapolis IN' -> 'Indianapolis'.
+_LOC_STATE = re.compile(r"\s+[A-Z]{2}\b\s*$")
+# A parenthetical qualifier distinguishing sites in one city: 'Lansing MI (Lake)'.
+_LOC_QUALIFIER = re.compile(r"\s*\(([^)]+)\)\s*$")
+# "location 004", "site #12", "office 7" — the numeric code, which IS how staff refer to sites.
+_LOC_CODE = re.compile(r"\b(?:location|site|office|clinic)\s*#?\s*(\d{1,3})\b", re.IGNORECASE)
+# Below this an alias is too generic to match on: state codes ('IN', 'IL'), 'the', and any
+# two/three-letter fragment that would fire on half the questions ever asked.
+_LOC_MIN_ALIAS = 4
+
+
+class LocationIndex:
+    """Resolves the location a QUESTION names to the exact values `p_location_names` accepts.
+
+    THE DEFECT THIS EXISTS FOR. The warehouse stores '001-BDD-Indianapolis IN'; a user writes
+    "Indianapolis". Until now there was a *validator* and no *resolver* — `p_location_names` was
+    checked by exact lowercase match, so the model would have had to reproduce that string
+    verbatim. It cannot, and a wrong value is rejected outright, so the only move that always
+    "works" is to OMIT the parameter. Measured: "hygiene revenue per patient for Indianapolis"
+    called `fn_rca_hyg_rev_per_patient_trend(p_year=2026, p_month=4)` with no location at all and
+    then narrated enterprise-wide numbers as if they were one site's.
+
+    Resolution is by ALIAS, longest match wins, and ties are all returned:
+
+    - "Indianapolis"        -> ['001-BDD-Indianapolis IN']
+    - "Lansing"             -> all three Lansing sites (Lake, Cavanaugh, Oakhill) — a user naming
+                               a city with three clinics means the city, not one clinic
+    - "Lansing (Cavanaugh)" -> just that one, because it matched a LONGER alias
+    - "Dr. Sammons"         -> [] -> NULL -> all locations, because a provider name is not in this
+                               index at all. That is the guarantee asked for: only values present
+                               in `silver.dim_location` can ever reach the parameter.
+    """
+
+    def __init__(self, canonical: dict[str, set[str]], vocab: "set[str] | None" = None,
+                 pms: "dict[str, str] | None" = None, keys: "dict[str, int] | None" = None):
+        # {canonical stored value: {alias, …}} — aliases lowercased, canonical left exactly as
+        # stored because that is what the SQL parameter compares against.
+        self.canonical = canonical
+        # The VALIDATOR's vocabulary, kept deliberately wider than the canonical set: every raw
+        # name/label column of `dim_location` (NetSuite, Paycor, Denticon, Curve, Kolla). Narrowing
+        # it to the 53 canonical values would newly reject 30 spellings the guard accepts today —
+        # a regression, and the guard is a backstop for paths that never reach the resolver.
+        self._vocab = {v.lower() for v in (vocab or set())} | {v.lower() for v in canonical}
+        # {canonical location: pms_of_record}. A clinic runs ONE practice-management system, so a
+        # question about that clinic can only be answered from that system's functions. Measured:
+        # "Why is Lansing MI (Lake) down 138,029?" routed to CURVE procedure trends; Lansing runs
+        # OPENDENTAL, Curve holds nothing for it, every figure came back zero and the answer
+        # abstained. The column was there the whole time.
+        self.pms = {k: v for k, v in (pms or {}).items() if v}
+        # {canonical location: location_key}. Four functions scope by KEY rather than by name
+        # (`p_location_keys bigint[]`), and without the mapping the binder could not touch them:
+        # measured, "How much appointment time was booked during June 2026?" reached
+        # `fn_denticon_booked_time_window(p_location_keys='all')` — the model's word for "every
+        # location" in a bigint[] — Postgres rejected it, and the agent abstained on a question
+        # whose answer NULL returns immediately.
+        self.keys = {k: v for k, v in (keys or {}).items() if v is not None}
+        self._by_alias: dict[str, set[str]] = {}
+        for name, aliases in canonical.items():
+            for a in aliases:
+                self._by_alias.setdefault(a, set()).add(name)
+
+    def __len__(self) -> int:
+        return len(self.canonical)
+
+    @property
+    def values(self) -> set[str]:
+        """Every accepted value, lowercased — the validator's vocabulary."""
+        return self._vocab
+
+    def pms_for(self, names: "list[str]") -> "set[str]":
+        """The practice-management systems serving these locations, lowercased.
+
+        Empty when unknown — 14 of 53 rows have no `pms_of_record`, and an unknown source must
+        never be used to EXCLUDE anything.
+        """
+        return {self.pms[n].strip().lower() for n in names if self.pms.get(n)}
+
+    def resolve(self, text: str) -> list[str]:
+        """Canonical location values named in `text`, or [] when none are.
+
+        Longest match wins PER MENTION, not across the whole question. Getting that wrong collapsed
+        multi-location questions to a single place: "expense ratios for Indianapolis, Fort Wayne
+        and Clarksville" resolved to the two Indianapolis sites only, because `indianapolis` is a
+        longer alias than `fort wayne` and the rule was applied globally. Each mention in the text
+        is its own contest — overlapping matches compete, separate ones are unioned.
+        """
+        low = f" {(text or '').lower()} "
+        # (start, end, alias_len, {canonical names}) for every alias occurrence in the text.
+        spans: list[tuple[int, int, int, set[str]]] = []
+        for alias, names in self._by_alias.items():
+            if len(alias) < _LOC_MIN_ALIAS:
+                continue
+            for m in re.finditer(rf"(?<![\w]){re.escape(alias)}(?![\w])", low):
+                spans.append((m.start(), m.end(), len(alias), set(names)))
+        for code in _LOC_CODE.findall(text or ""):
+            for name in self.canonical:
+                if re.match(rf"^0*{int(code)}\s*-", name.strip()):
+                    spans.append((-1, -1, _LOC_MIN_ALIAS, {name}))
+        if not spans:
+            return []
+        # Cluster OVERLAPPING spans — each cluster is one mention. "Lansing MI (Cavanaugh)" puts
+        # `lansing`, `lansing mi` and the full alias in one cluster, where the longest wins;
+        # "Indianapolis … Clarksville" yields two clusters, and both are kept.
+        spans.sort()
+        clusters: list[list[tuple[int, int, int, set[str]]]] = []
+        for sp in spans:
+            if sp[0] >= 0 and clusters and clusters[-1][-1][0] >= 0 and sp[0] < clusters[-1][-1][1]:
+                clusters[-1].append(sp)
+            else:
+                clusters.append([sp])
+        out: set[str] = set()
+        for cluster in clusters:
+            best = max(c[2] for c in cluster)
+            for c in cluster:
+                if c[2] == best:
+                    out |= c[3]
+        return sorted(out)
+
+
+def _location_aliases(canonical: str, extra: "set[str]") -> set[str]:
+    """Every spelling a user might reasonably use for one stored location value."""
+    out: set[str] = set()
+    for raw in {canonical, *extra}:
+        s = (raw or "").strip()
+        if not s:
+            continue
+        out.add(s.lower())
+        human = _LOC_PREFIX.sub("", s).strip()          # '001-BDD-Lansing MI (Lake)' -> 'Lansing MI (Lake)'
+        out.add(human.lower())
+        qual = _LOC_QUALIFIER.search(human)
+        bare = _LOC_QUALIFIER.sub("", human).strip()    # -> 'Lansing MI'
+        out.add(bare.lower())
+        city = _LOC_STATE.sub("", bare).strip()         # -> 'Lansing'
+        out.add(city.lower())
+        if qual:
+            # 'Lansing (Lake)' — city + qualifier without the state, which is how staff write it.
+            out.add(f"{city} ({qual.group(1)})".lower())
+    return {a for a in out if len(a) >= _LOC_MIN_ALIAS}
+
+
+def _table_columns(cur, schema: str, table: str) -> list[str]:
+    """Column names of one table — used to detect optional columns before selecting them."""
+    cur.execute("select column_name from information_schema.columns "
+                "where table_schema = %s and table_name = %s", (schema, table))
+    return [r[0] for r in cur.fetchall()]
+
+
+def _load_location_index(conn) -> "LocationIndex | None":
+    """Build the resolver from ``silver.dim_location``.
+
+    CANONICAL values come from ``location_name`` — that is what `p_location_names` compares
+    against. ALIASES additionally include every other name column (NetSuite, Paycor, Denticon,
+    Curve, Kolla labels), so a user typing the name they see in one source system still resolves to
+    the value the warehouse parameter wants.
+
+    Fail-OPEN, exactly as the vocabulary loader it replaces: any error -> None -> the resolver is
+    inactive and nothing is bound, which is the behaviour we have today.
+    """
+    try:
+        cur = conn.cursor()
+        cur.execute(
+            "select column_name from information_schema.columns "
+            "where table_schema = 'silver' and table_name = 'dim_location' "
+            "and data_type in ('text', 'character varying') "
+            "and (column_name like %s or column_name like %s)",
+            ("%name%", "%label%"))
+        name_cols = [r[0] for r in cur.fetchall()]
+        if "location_name" not in name_cols:
+            return None
+        others = [c for c in name_cols if c != "location_name"]
+        cols = ", ".join(f'd."{c}"::text' for c in ["location_name", *others])
+        dim_cols = {c for c in _table_columns(cur, "silver", "dim_location")}
+        has_pms = "pms_of_record" in dim_cols
+        has_key = "location_key" in dim_cols
+        pms_col = ', d."pms_of_record"::text' if has_pms else ""
+        key_col = ', d."location_key"' if has_key else ""
+        cur.execute(f"select {cols}{pms_col}{key_col} from silver.dim_location d "
+                    f'where d."location_name" is not null and btrim(d."location_name") <> \'\'')
+        canonical: dict[str, set[str]] = {}
+        vocab: set[str] = set()
+        pms: dict[str, str] = {}
+        keys: dict[str, int] = {}
+        ncols = 1 + len(others)
+        for row in cur.fetchall():
+            name, extra = row[0].strip(), {x.strip() for x in row[1:ncols] if x and x.strip()}
+            if name:
+                canonical[name] = _location_aliases(name, extra)
+                vocab |= {name, *extra}
+                if has_pms and row[ncols]:
+                    pms[name] = row[ncols]
+                if has_key and row[ncols + (1 if has_pms else 0)] is not None:
+                    keys[name] = int(row[ncols + (1 if has_pms else 0)])
+        return LocationIndex(canonical, vocab, pms, keys) if canonical else None
+    except Exception as e:  # noqa: BLE001 — fail-open is the whole point
+        _LOG.info("location index unavailable — location binding inactive (%s)", e)
+        return None
+
+
+def _load_location_vocab(conn) -> set[str]:
+    """Distinct location NAMES from ``silver.dim_location`` (every *name*/*label* column),
+    lowercased — the vocabulary the ``p_location_names`` guard validates against.
+
+    A PMS/source name ('Opendental', 'Dentrix') lives in ``pms_of_record``, NOT in any name
+    column, so a source name passed as a location is not in this set and gets rejected. The
+    columns are discovered dynamically so a renamed/added name column is picked up automatically.
+
+    Fail-OPEN: any error (table absent in this deployment, no SELECT grant, unexpected shape) →
+    empty set → the guard is simply inactive, so a legitimate call is NEVER blocked by this."""
+    try:
+        cur = conn.cursor()
+        cur.execute(
+            "select column_name from information_schema.columns "
+            "where table_schema = 'silver' and table_name = 'dim_location' "
+            "and data_type in ('text', 'character varying') "
+            "and (column_name like %s or column_name like %s)",
+            ("%name%", "%label%"))
+        name_cols = [r[0] for r in cur.fetchall()]
+        if not name_cols:
+            return set()
+        arr = ", ".join(f'd."{c}"::text' for c in name_cols)
+        cur.execute(f"select distinct lower(btrim(v)) from silver.dim_location d, "
+                    f"unnest(array[{arr}]) as v where v is not null and btrim(v) <> ''")
+        return {r[0] for r in cur.fetchall() if r and r[0]}
+    except Exception as e:  # noqa: BLE001 — fail-open is the whole point
+        _LOG.info("location vocab unavailable — p_location_names guard inactive (%s)", e)
+        return set()
+
+
+def _make_executor(dsn: str, label: str, schema: str, proname: str,
+                   args_spec: list[tuple[str, str]], connect, statement_timeout_ms: int,
+                   required: set[str] | None = None,
+                   enums: dict[str, tuple[list[str], bool]] | None = None,
+                   profile_rows: int = 100_000, vocab: dict | None = None,
+                   locations: set[str] | None = None):
+    """The per-function transport: SELECT * FROM schema.fn(name := %(name)s::type) LIMIT n.
+
+    A fresh connection per call keeps the executor stateless (the agent runs calls in
+    parallel threads) — connect cost is negligible next to the LLM round-trips. The model
+    may drop a ``p_`` prefix or change case on an arg name; a normalized map recovers it.
+
+    ``enums`` (``{arg: (allowed, case_sensitive)}``) is enforced deterministically: a value
+    outside the set is rejected with a message naming the allowed values (the model then
+    self-corrects), so an invented value like ``month_to_date`` never silently returns the
+    wrong rows.
+    """
+    types = dict(args_spec)
+    required = required or set()
+    enums = enums or {}
+    locations = locations or set()
+
+    def _core(a: str) -> str:  # drop a "p_"/"_" NAME PREFIX (not lstrip — that eats chars)
+        return re.sub(r"^p_|^_", "", a.lower())
+
+    def _coerce_array(v, sql_type: str):
+        """Normalize a STRINGIFIED array the model emitted for an ``xxx[]`` parameter.
+
+        A tool call is JSON, so a model asked for ``text[]`` often sends the *string* ``"[]"``
+        rather than an empty list — and the reference docs advertise ``"example": []``, which
+        invites exactly that. Postgres array literals use braces, so ``'[]'::text[]`` raises
+        `malformed array literal: "[]"`. Measured in a live 30-case run: 8 of 10 tool failures
+        came from this one value, and one case failed EVERY call and abstained outright.
+        A real empty list and ``''`` already worked, so only the string form is repaired:
+
+          "[]" / "{}" / ""      → "" (blank; the caller then omits it or binds NULL)
+          '["a","b"]'           → ["a", "b"]   (JSON list → real list, psycopg adapts it)
+          "Main St Dental"      → ["Main St Dental"]  (a BARE scalar → one-element array)
+          '[oops' / '{a,b}'     → unchanged (a broken/pg-literal form — leave it to Postgres)
+        """
+        if not sql_type.endswith("[]") or not isinstance(v, str):
+            return v
+        s = v.strip()
+        if s in ("[]", "{}", ""):
+            return ""  # falls into the blank branch below → DEFAULT applies (or NULL if required)
+        if s.startswith("[") and s.endswith("]"):
+            try:
+                parsed = json.loads(s)
+            except ValueError:
+                return v
+            if isinstance(parsed, list):
+                return [x for x in parsed if x is not None] or ""
+            return v
+        if s.startswith(("[", "{")):
+            return v  # a bracket/brace form we didn't parse — let Postgres report it
+        # A BARE scalar for an array parameter is malformed to Postgres ("malformed array literal:
+        # 'X'"); the model means a single-element list. Measured: p_location_names='Opendental'
+        # (a SOURCE name mistaken for a location) crashed the call outright. Wrap it → then the
+        # p_location_names guard can validate the element and reject an invented location.
+        return [s]
+
+    _norm = {_core(a): a for a, _ in args_spec}
+    source = f"sql://{label}/{schema}.{proname}"
+
+    def fn(args: dict, timeout: int, list_limit: int | None = None,
+           prefer_period: "tuple | None" = None,
+           prefer_terms: "frozenset[str] | None" = None) -> dict:
+        n = max(1, list_limit or 50)
+        scan = max(n, profile_rows)  # rows fetched for PROFILING; only `n` are ever shown
+        bound: dict = {}
+        for k, v in (args or {}).items():
+            real = k if k in types else _norm.get(_core(str(k)))
+            if not real:
+                continue  # unknown arg — drop it
+            v = _coerce_array(v, types[real])
+            if v is None or v == "" or (isinstance(v, (list, tuple)) and not v):
+                # Blank OPTIONAL arg → omit it (the function's DEFAULT applies). "Blank" also
+                # covers a GENUINE empty list: the model routinely emits `p_location_names=[]`
+                # (the reference docs advertise `"example": []`), which is NOT the same as NULL.
+                # An empty array binds `{}::text[]`, and a `location = ANY(p_location_names)`
+                # filter then matches NOTHING (a silent all-zero/NULL answer), whereas the DEFAULT
+                # (NULL) means "all locations". `_coerce_array` already folds the STRING spellings
+                # ("[]"/"{}") to ""; this catches the real empty list/tuple that bypasses it.
+                # (Only empty SEQUENCES — never a falsy scalar like 0/False, which stay bound.)
+                # A REQUIRED arg has no default — omitting it makes the call match NO signature
+                # ("function … does not exist", live finding) — so bind an explicit NULL.
+                if real in required:
+                    bound[real] = None
+                continue
+            if real in enums:
+                allowed, case_sensitive = enums[real]
+                sval = str(v).strip().strip("'\"")
+                if sval in allowed:
+                    v = sval
+                elif not case_sensitive and (hit := next(
+                        (a for a in allowed if a.lower() == sval.lower()), None)):
+                    v = hit  # normalize a case-only mismatch to the canonical value
+                else:
+                    return {"ok": False, "kind": "bad_argument", "content": "",
+                            "source": source, "bad_param": real,
+                            "error": (f"invalid value {v!r} for {real}: allowed values are "
+                                      + ", ".join(repr(a) for a in allowed))}
+            elif (known := (vocab or {}).get(real)) and isinstance(v, str):
+                # VOCABULARY SAFETY NET — this function documents no allowed set, but the same
+                # parameter is documented elsewhere in the schema. A value that is valid for NO
+                # function in the catalog is an invention, and Postgres would accept it silently
+                # and return default-branch data (measured: p_comparison='previous' returned
+                # byte-identical rows to 'yoy'). Rejecting is strictly safe: any value that is
+                # legitimate somewhere passes, so a real call can never be blocked here.
+                sval = str(v).strip().strip("'\"")
+                if (hit := next((a for a in known if a.lower() == sval.lower()), None)):
+                    v = hit
+                else:
+                    return {"ok": False, "kind": "bad_argument", "content": "", "source": source,
+                            "bad_param": real,
+                            "error": (f"invalid value {v!r} for {real}: this function does not "
+                                      f"document its allowed values, but across the schema "
+                                      f"{real} only ever takes "
+                                      + ", ".join(repr(a) for a in sorted(known))
+                                      + ". Use one of those, or omit the parameter.")}
+            elif locations and _core(real) == "location_names" and isinstance(v, (list, tuple)):
+                # LOCATION GUARD — reject a value that is not a real location. The recurring defect:
+                # the model passes a PMS/SOURCE name ('Opendental', 'Dentrix') as a location, when
+                # the source is ALREADY fixed by the function name (fn_rca_OPENDENTAL_*). Postgres
+                # would return the function's shape filled with NULL/0 — a silent wrong answer.
+                # Tagged bad_argument+bad_param so the executor's recovery retries with the param
+                # DROPPED → NULL → the correct all-locations result. Fail-open when the vocab is
+                # empty; only a value that is a location NOWHERE is blocked (never a real one).
+                unknown = [x for x in v
+                           if not (isinstance(x, str)
+                                   and x.strip().strip("'\"").lower() in locations)]
+                if unknown:
+                    return {"ok": False, "kind": "bad_argument", "content": "", "source": source,
+                            "bad_param": real,
+                            "error": (f"unknown location{'s' if len(unknown) > 1 else ''} "
+                                      + ", ".join(repr(x) for x in unknown)
+                                      + f" for {real}: not a location in the warehouse. A PMS/"
+                                      "source name (e.g. 'Opendental', 'Dentrix') is NOT a "
+                                      "location — the source is already fixed by the function. "
+                                      f"Use a real location name, or omit {real} for all locations.")}
+            elif _json_type(types[real]) == "integer" and isinstance(v, str) and v.strip().lstrip("-").isdigit():
+                v = int(v.strip())  # belt: the ::cast below is the real guarantee
+            bound[real] = v
+        for a in required:  # required args the model omitted entirely → explicit NULL
+            bound.setdefault(a, None)
+        arglist = ", ".join(f'"{a}" := %({a})s::{types[a]}' for a in bound)
+        query = f'SELECT * FROM "{schema}"."{proname}"({arglist}) LIMIT {scan + 1}'
+        _LOG.debug("sql exec: %s params=%s", query, trunc(bound, 300))
+        try:
+            with connect(dsn, timeout, statement_timeout_ms) as conn:
+                cur = conn.cursor()
+                cur.execute(query, bound)
+                cols = [d[0] for d in (cur.description or [])]
+                # Scan WIDER than we display. The rows beyond the display cap are never sent to
+                # the model — they exist only so the statistical profile below describes the
+                # REAL result set. Without this, "the maximum" was whatever topped the first
+                # page (a $172,994 max over 50 of 5,830 rows; the true max was $228,588).
+                fetched = cur.fetchmany(scan + 1)
+        except Exception as e:
+            kind, msg = classify_pg_error(e)
+            return {"ok": False, "error": msg[:800], "kind": kind, "content": "",
+                    "source": source}
+        raw_rows = [{c: _jsonable(v) for c, v in zip(cols, r)} for r in fetched[:scan]]
+        # LOG_RAW_ROWS=1 — log what the database returned BEFORE redaction. Deliberately opt-in and
+        # log-only: the redaction below still runs, so the model and the answer are unaffected and
+        # the PII guarantee holds. Without this the "unredacted" payload does not exist anywhere to
+        # log, because redaction happens here, at fetch, not at log time. Writes personal/contact
+        # data to the console (and to LOG_FILE if set) — enable only where that is acceptable.
+        if os.getenv("LOG_RAW_ROWS", "").strip() not in ("", "0", "false", "False"):
+            _LOG.debug("sql raw rows (PRE-redaction) %s.%s: %s", schema, proname, trunc(raw_rows))
+        scanned_rows = [_redact_row(r) for r in raw_rows]
+        rows = _visible_slice(scanned_rows, n, prefer_period, prefer_terms)  # user/model sees
+        profile = describe_rows(scanned_rows, scanned=len(scanned_rows),
+                                complete=len(fetched) <= scan)
+        payload: dict | list = rows
+        if len(fetched) > n:
+            payload = {"rows": rows,
+                       "note": f"more rows exist beyond the first {n} (LIMIT applied)"}
+        # EMPTY-FILTER DETECTION: a filter that matches nothing does not error and does not
+        # return zero rows — the function still emits its shape, filled with zeros. Measured:
+        # the model invented p_location_names=['location1','location2'] and got 12 rows summing
+        # to 0, against 4,718,610.27 unfiltered, then analysed the zeros as real business data.
+        # Rows present + every numeric column identically zero + a filter supplied is not a
+        # legitimate result, so it is reported as a bad argument the agent can self-correct.
+        filters = {k: v for k, v in bound.items()
+                   if isinstance(v, (list, tuple)) and v}
+        empty_filter = ""
+        if filters and profile and profile.get("numeric") and scanned_rows:
+            nums = profile["numeric"].values()
+            if nums and all(s.get("min") == 0 and s.get("max") == 0 for s in nums):
+                names = ", ".join(f"{k}={v!r}" for k, v in filters.items())
+                # NOT an error: a REAL location with no activity for this system returns zeros
+                # too (verified — '001-BDD-Indianapolis IN' has no Dentrix production), so
+                # rejecting would block a legitimate "that location has none" answer. The value
+                # of the signal is that the zeros are not silently narrated as analysis, so it
+                # is surfaced in the evidence the model reads.
+                empty_filter = (f"NOTE: the filter {names} matched NO DATA — every value below "
+                                f"is zero. Either those values are not real, or they have no "
+                                f"activity here. Say so explicitly; do not analyse the zeros as "
+                                f"if they were results.\n")
+                _LOG.warning("sql: filter matched no data: %s (%s)", names, proname)
+        period_note = incomplete_period_note(bound)
+        if period_note:
+            _LOG.warning("sql: %s requested an incomplete period: %s", proname,
+                         period_note.split("(today")[0].strip())
+        content = period_note + empty_filter + _compact_json(payload, max_items=n)  # PII as HTTP
+        src = source + ("?" + json.dumps(bound, sort_keys=True, default=str) if bound else "")
+        # `rows` = the COMPLETE result (every column — no compaction field cap), so the agent
+        # can render tables deterministically and ground figures against the full width.
+        return {"ok": True, "content": content[: max(8000, n * 600)], "source": src,
+                "rows": rows, "rows_truncated": len(fetched) > n,
+                # Aggregates over `scanned_rows` (up to profile_rows), NOT over `rows`.
+                "profile": profile, "rows_scanned": len(scanned_rows)}
+
+    return fn