[KM-691] Bound traceability payload + reject contradictory IR filter ranges

Traceability: _truncate now summarizes embedded ToolOutputs (Pattern-A
analyze_* inputs) instead of re-embedding the full upstream table, and
executed queries get a dedicated 2000-char cap (was clipped at 300).

Planner: IRValidator rejects >=2 disjoint BETWEEN ranges on one column
(all filters are ANDed -> 0 rows), and planner.md teaches multi-period
comparisons to use one spanning range + group-by or one query per period.

src/config/prompts/planner.md

@@ -84,6 +84,13 @@ only a `TaskList` object that conforms to the provided schema.
   - For `in`/`not_in` (value is a list) or `between` (value is `[low, high]`), it
     is still the ELEMENT type — a list of names is `"string"`, a date range is
     `"date"`. It is **never** `"list"`.
+- **Filters are ANDed — never stack two disjoint ranges on one column.** Every
+  `filters[]` entry combines with AND, so two non-overlapping `between` ranges on
+  the SAME column (e.g. `order_date` in Q1 2025 AND in Q1 2026) match **zero rows**.
+  For a multi-period comparison, either (a) use ONE spanning range
+  (`between ["2025-01-01", "2026-03-31"]`) and let the analysis step group by the
+  period, or (b) emit a SEPARATE `retrieve_data` task per period. Never AND two
+  ranges on one column expecting an OR.
 - **Use only the `args` a tool lists** — e.g. `analyze_aggregate` takes only
   `data`/`aggregations`/`group_by`, so never add `order_by`/`limit` to it.
 - **Top-N ("top/most/least N by <metric>") is a single `retrieve_data` query**,

src/query/ir/validator.py

@@ -5,6 +5,8 @@ is re-prompted with the error context (max 3 retries) — error messages
 must therefore be specific enough that the LLM can self-correct.
 """
 
+from typing import Any
+
 from ...catalog.models import Catalog, Column, Source, Table
 from .models import QueryIR
 from .operators import (
@@ -80,6 +82,8 @@ class IRValidator:
                         f"(allowed: {sorted(allowed)})"
                     )
 
+        self._reject_contradictory_ranges(ir)
+
         for i, col_id in enumerate(ir.group_by):
             self._require_column(columns_by_id, col_id, f"group_by[{i}]")
 
@@ -100,6 +104,36 @@ class IRValidator:
                     f"limit {ir.limit} exceeds hard cap {LIMIT_HARD_CAP}"
                 )
 
+    @staticmethod
+    def _reject_contradictory_ranges(ir: QueryIR) -> None:
+        """Reject disjoint BETWEEN ranges on the same column.
+
+        All filters in an IR are ANDed, so two non-overlapping BETWEEN ranges on one
+        column (e.g. Q1 2025 AND Q1 2026 on order_date) match no rows — a common LLM
+        slip when it means a multi-period comparison. Rejecting lets the planner's
+        re-prompt retry correct it (one spanning range + group-by the period, or one
+        query per period). Best-effort: incomparable values are skipped, not raised.
+        """
+        ranges: dict[str, list[tuple[Any, Any]]] = {}
+        for f in ir.filters:
+            if f.op == "between" and isinstance(f.value, list) and len(f.value) == 2:
+                ranges.setdefault(f.column_id, []).append((f.value[0], f.value[1]))
+        for col_id, rs in ranges.items():
+            if len(rs) < 2:
+                continue
+            try:
+                # AND of ranges = intersection [max(lo), min(hi)]; empty when lo > hi.
+                empty = max(lo for lo, _ in rs) > min(hi for _, hi in rs)
+            except TypeError:
+                continue  # incomparable value types — skip (fail-open)
+            if empty:
+                raise IRValidationError(
+                    f"filters place {len(rs)} non-overlapping BETWEEN ranges on column "
+                    f"{col_id!r}; because all filters are ANDed this matches no rows. "
+                    "For a multi-period comparison use a single spanning range and group "
+                    "by the period, or emit one query per period."
+                )
+
     def _validate_joins(
         self, ir: QueryIR, source: Source, columns_by_id: dict[str, Column]
     ) -> None:

src/traceability/scratchpad.py

@@ -14,6 +14,8 @@ from __future__ import annotations
 
 from typing import Any
 
+from pydantic import BaseModel
+
 from src.middlewares.logging import get_logger
 
 from .schemas import PlanningInfo, PlanStep, ToolCallInfo, TraceabilityPayload
@@ -23,12 +25,26 @@ logger = get_logger("traceability")
 # Truncation caps (bound the JSONB payload) — see plan §3.
 CAP_PREVIEW_ROWS = 5
 CAP_STR = 300
+# Executed queries get a higher cap than free strings: the SQL/query is the point of
+# the feature, and 300 chars mangles all but the smallest statements.
+CAP_QUERY = 2000
 
 
 def _truncate(obj: Any) -> Any:
-    """Recursively cap any string to CAP_STR; leave numbers/None untouched."""
+    """Recursively cap strings to CAP_STR and summarize embedded tool results.
+
+    A Pattern-A `analyze_*` input carries its upstream `retrieve_data` result as a
+    `ToolOutput` (a BaseModel). Left untouched that would re-embed the FULL upstream
+    table (all rows + the untruncated query) into the payload, defeating the caps —
+    so a tool-result-shaped model is summarized via `_output_to_dict` (preview ≤ 5
+    rows, `row_count` kept), and any other BaseModel is dumped then recursed.
+    """
     if isinstance(obj, str):
         return obj[:CAP_STR]
+    if isinstance(obj, BaseModel):
+        if hasattr(obj, "kind") and hasattr(obj, "rows"):  # a ToolOutput-shaped result
+            return _output_to_dict(obj)
+        return _truncate(obj.model_dump(mode="json"))
     if isinstance(obj, dict):
         return {k: _truncate(v) for k, v in obj.items()}
     if isinstance(obj, list):
@@ -121,7 +137,7 @@ class TraceabilityScratchpad:
             "type": "database",
             "source_id": meta.get("source_id"),
             "name": table,
-            "query": _truncate(query) if isinstance(query, str) else None,
+            "query": query[:CAP_QUERY] if isinstance(query, str) else None,
             "detail": {"table": table, "row_count": meta.get("row_count")},
         })