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

api_agent/metrics.py

@@ -0,0 +1,1030 @@
+"""DERIVED METRICS — the arithmetic the model is forbidden to do, done by code.
+
+Why this module exists
+----------------------
+`SYNTHESIS_SYSTEM` bans the model from computing any number (no sums, deltas, percentages,
+margins, shares). That ban was earned: every prompt-level attempt to make the model do arithmetic
+correctly has failed, and a wrong total stated confidently is worse than no total. See the
+`reliability-over-prompts` rule.
+
+But the ban is also the quality ceiling. Measured against the incumbent agent we are replacing,
+its substantive answers average ~24 derived expressions ("$1.2M (-18.7%) versus prior year",
+"margin collapsed from 25.8% to 8.5%", "three locations account for $1.1M of the decline") and
+ours contain **zero** — because `_computed_facts` only ever offered min, max and average, so
+min/max/average is the entire analytical vocabulary the model has to work with.
+
+This module widens that vocabulary without touching the guarantee. Everything here is computed
+deterministically from the evidence rows and handed to synthesis as VERIFIED facts; the model
+quotes, it never calculates. Each fact also enters the grounding pool, so a figure the model
+copies from here validates instead of being flagged as unsupported.
+
+Design rules
+------------
+- **Pure.** No LLM, no I/O, no config. Rows in, facts out.
+- **Never guess a pairing.** A delta is emitted only when the two columns are unambiguously
+  related by naming convention (see `_classify`). An unrecognised column produces no fact rather
+  than a wrong one.
+- **Distinguish a DELTA column from a LEVEL column.** The warehouse ships both: `rev_vs_ly` is
+  already a difference, while `prior_year_actual` is a level. Treating one as the other silently
+  doubles or halves every percentage, so the distinction is explicit, not inferred from position.
+- **Bounded output.** Facts are capped per evidence item; a 60-column table must not flood the
+  prompt with 400 derived figures.
+"""
+from __future__ import annotations
+
+import itertools
+import re
+import statistics
+from dataclasses import dataclass
+
+# Columns whose values must not be summed or differenced as if they were quantities. Mirrors
+# agent._NON_ADDITIVE_KEY; duplicated here to keep this module free of agent imports (agent
+# imports metrics, not the other way round).
+_NON_ADDITIVE = re.compile(
+    r"pct|percent|%|ratio|(?:^|_)rate(?:$|_)|margin|average|(?:^|_)avg(?:$|_)|(?:^|_)mean(?:$|_)"
+    r"|median|(?:^|_| )per(?:$|_| )|yoy|mom|qoq|growth", re.I)
+_ID_LIKE = re.compile(r"(?:^|_)(?:id|ids|code|zip|postal|rank|index|idx|key)(?:$|_)", re.I)
+# A bare calendar column is a dimension, not a measure — but only when the WHOLE name is that
+# dimension. `year`/`p_month` are dimensions; `prior_year_actual` is a money column and matching
+# it here silently deleted every year-over-year comparison the warehouse ships.
+_CALENDAR_COL = re.compile(r"^(?:p_)?(?:year|month|quarter|week|day|period)$", re.I)
+_LABEL_HINT = ("month", "period", "date", "name", "label", "account", "item", "location",
+               "category", "card", "procedure", "provider")
+
+# --- column-role vocabulary -------------------------------------------------------------------- #
+# A column that is ALREADY a difference (actual minus comparison). Emitting `actual - column`
+# for one of these would be nonsense, so they are handled as deltas: the comparison LEVEL is
+# recovered as `actual - delta`.
+_DELTA_LY = re.compile(r"(?:^|_)(?:vs_ly|vs_last_year|var_ly|delta_ly)(?:$|_)", re.I)
+_DELTA_BUDGET = re.compile(r"(?:^|_)(?:vs_budget|vs_bud|var_budget|delta_budget)(?:$|_)", re.I)
+_DELTA_PLAIN = re.compile(r"(?:^|_)(?:delta|variance|var)(?:$|_)", re.I)
+# A column that is a LEVEL for a comparison period (a value, not a difference).
+_LEVEL_PRIOR = re.compile(r"(?:^|_)(?:prior_year|prior|last_year|ly|py|previous)(?:$|_)", re.I)
+_LEVEL_BUDGET = re.compile(r"(?:^|_)(?:budget|bud|plan|target)(?:$|_)", re.I)
+# The current-period value.
+_ACTUAL = re.compile(r"(?:^|_)(?:actual|curr|current|value|ytd_value|net|total)(?:$|_)", re.I)
+_PCT_COL = re.compile(r"(?:^|_)(?:pct|percent|percentage)(?:$|_)|_pct$", re.I)
+
+# Margin = profit / revenue. Both sides matched by name so a margin is only ever computed from
+# two columns that genuinely are a profit and a revenue.
+_PROFIT_COL = re.compile(r"ebitda|profit|income|margin_dollars", re.I)
+_REVENUE_COL = re.compile(r"(?:^|_)(?:rev|revenue|net_production|production|sales)(?:$|_)|^rev", re.I)
+
+MAX_FACTS_PER_ITEM = 24   # keeps a wide table from flooding the synthesis prompt
+TOP_N = 3                 # "the top 3 movers account for X of the change"
+SMALL_TABLE = 12          # at or below this, every row gets its own derived comparison
+
+# --- WHEN MAY WE AGGREGATE ACROSS ROWS? --------------------------------------------------------- #
+# This is the guard that stops this module manufacturing confident nonsense, and it is deliberately
+# structural rather than a list of known column names — a name list would encode one warehouse's
+# conventions and fail silently on the next.
+#
+# The hazard: a result may be one metric across many entities/periods (summable), or a list where
+# each row is a DIFFERENT metric. A chain-total result returns Revenue, Staff Expenses, Non Staff
+# Expenses, Office Adj. and Adjusted EBITDA as five rows; summing that column adds revenue to
+# expenses to EBITDA and yields a meaningless figure carrying a "code-verified" label — precisely
+# the failure the no-derived-numbers rule exists to prevent.
+#
+# The rule adopted: CROSS-ROW SUMS ARE ALLOWED ONLY WHEN THE ROWS ARE INDEXED BY TIME. Summing a
+# measure over successive periods is valid by construction; summing it over arbitrary row keys is
+# not. PER-ROW arithmetic (a row's own actual against its own budget) is always safe because it
+# involves no cross-row addition at all, and it carries most of the value anyway — "Adjusted EBITDA
+# $5.5M, -18.7% versus prior year" is one row's numbers.
+#
+# `_has_rollup_row` is kept as a second, independent guard for the contribution analysis: if one
+# row equals the sum of the others, the rows are components of a rollup rather than peers.
+
+
+@dataclass(frozen=True)
+class Fact:
+    """One code-computed number, with the arithmetic that produced it.
+
+    `basis` is shown to the model and to the user-facing trace: a derived figure that cannot say
+    how it was derived is exactly the kind of unfalsifiable claim this project refuses to make.
+    """
+    label: str
+    value: float
+    basis: str
+    unit: str = ""          # "" money/count · "%" percent · "pp" percentage points
+
+    def render(self) -> str:
+        if self.unit == "%":
+            num = f"{self.value:+,.1f}%"
+        elif self.unit == "pp":
+            num = f"{self.value:+,.1f} pp"
+        else:
+            num = f"{self.value:,.2f}"
+        return f"{self.label} = {num}  [{self.basis}]"
+
+
+# --------------------------------------------------------------------------- #
+# Column inspection
+# --------------------------------------------------------------------------- #
+def _num(v) -> float | None:
+    """A cell → float, or None when it isn't a real number.
+
+    COERCES rather than isinstance-tests. Postgres returns `Decimal` for every numeric column,
+    which is neither `int` nor `float`; a strict type check therefore skips every money column and
+    yields an empty result against the live warehouse while passing every test written with float
+    literals. That exact trap has already been paid for once in `sql_loader._describe_stdlib`.
+    Strings are not coerced — a numeric-looking label is a label, not a measure.
+    """
+    if isinstance(v, bool) or isinstance(v, str) or v is None:
+        return None
+    try:
+        f = float(v)
+    except (TypeError, ValueError):
+        return None
+    return None if f != f or f in (float("inf"), float("-inf")) else f
+
+
+def numeric_columns(rows: list[dict]) -> dict[str, list[float]]:
+    """`{column: values}` for every column numeric in at least one row, skipping id-like columns.
+
+    Rows with a missing/non-numeric cell contribute nothing for that column, so a column that is
+    numeric in only some rows still yields facts over the rows where it is real.
+    """
+    cols: dict[str, list[float]] = {}
+    for row in rows:
+        if not isinstance(row, dict):
+            continue
+        for k, v in row.items():
+            if _ID_LIKE.search(k or "") or _CALENDAR_COL.match(k or ""):
+                continue
+            if (f := _num(v)) is not None:
+                cols.setdefault(k, []).append(f)
+    return cols
+
+
+def label_of(row: dict) -> str:
+    """Best-effort human label for a row — a period/name/label field, else the first string."""
+    if not isinstance(row, dict):
+        return "?"
+    for k, v in row.items():
+        if isinstance(v, str) and v.strip() and any(t in k.lower() for t in _LABEL_HINT):
+            return v.strip()
+    for k, v in row.items():
+        if isinstance(v, str) and v.strip() and not _ID_LIKE.search(k):
+            return v.strip()
+    return "?"
+
+
+def _classify(col: str) -> tuple[str, str]:
+    """`column -> (role, stem)`.
+
+    role ∈ {actual, delta_ly, delta_budget, delta, level_prior, level_budget, pct, other}
+    stem  is the column with its role marker stripped, so `rev_actual` and `rev_vs_ly` share the
+    stem "rev" and can be paired. A flat schema (`actual` / `vs_ly`) shares the empty stem.
+
+    Order matters: `vs_ly_pct` is a percentage, not a delta, so pct is tested first; and
+    `prior_year_actual` is a prior LEVEL, not an actual, so level markers are tested before
+    `_ACTUAL`.
+    """
+    c = col or ""
+    def stem(pattern: re.Pattern) -> str:
+        return re.sub(r"_+", "_", pattern.sub("_", c)).strip("_").replace("actual", "").strip("_")
+
+    if _PCT_COL.search(c):
+        return "pct", stem(_PCT_COL)
+    if _DELTA_LY.search(c):
+        return "delta_ly", stem(_DELTA_LY)
+    if _DELTA_BUDGET.search(c):
+        return "delta_budget", stem(_DELTA_BUDGET)
+    if _LEVEL_PRIOR.search(c):
+        return "level_prior", stem(_LEVEL_PRIOR)
+    if _LEVEL_BUDGET.search(c):
+        return "level_budget", stem(_LEVEL_BUDGET)
+    if _DELTA_PLAIN.search(c):
+        return "delta", stem(_DELTA_PLAIN)
+    if _ACTUAL.search(c):
+        return "actual", stem(_ACTUAL)
+    # A bare metric name (`ebitda`, `rev`, `curr_val`) IS the current-period level — the warehouse
+    # only spells out "actual" when a comparison column sits beside it in the same grid. Defaulting
+    # these to `actual` is what lets `ebitda` pair with `ebitda_prior`.
+    return "actual", c
+
+
+_ISO_DATE = re.compile(r"^\s*(\d{4})-(\d{2})(?:-(\d{2}))?")
+
+
+def _as_period(v) -> tuple | None:
+    """A cell → a sortable period key, or None when it isn't a period.
+
+    Detected by VALUE, not by column name, so this works on any warehouse: a `date`/`datetime`
+    object, or a string starting with an ISO year-month. Anything else is not a period.
+    """
+    if hasattr(v, "year") and hasattr(v, "month"):          # date / datetime
+        return (v.year, v.month, getattr(v, "day", 1))
+    if isinstance(v, str) and (m := _ISO_DATE.match(v)):
+        return (int(m.group(1)), int(m.group(2)), int(m.group(3) or 1))
+    return None
+
+
+def period_column(rows: list[dict]) -> str | None:
+    """The column that indexes these rows by TIME, or None.
+
+    Requires every row to carry a parseable period, all distinct, in non-decreasing order — i.e.
+    a genuine time series as the warehouse returns it. This is the sole licence for cross-row
+    aggregation (see the guard note above).
+    """
+    if len(rows) < 2 or not isinstance(rows[0], dict):
+        return None
+    for col in rows[0]:
+        keys = [_as_period(r.get(col)) for r in rows if isinstance(r, dict)]
+        if len(keys) != len(rows) or any(k is None for k in keys):
+            continue
+        if len(set(keys)) == len(keys) and keys == sorted(keys):
+            return col
+    return None
+
+
+def _has_rollup_row(vals: list[float]) -> bool:
+    """True when one value equals the sum of the others — the rows are components of a total,
+    not peers, so ranking or combining them double-counts."""
+    for i, v in enumerate(vals):
+        others = sum(x for j, x in enumerate(vals) if j != i)
+        if abs(v - others) <= max(1.0, abs(v) * 0.001):
+            return True
+    return False
+
+
+def _pct(delta: float, base: float) -> float | None:
+    """Percent change, or None when the base is zero/absent — a percentage off a zero base is
+    meaningless (it is how "-100.3% YoY" got reported as a business fact off a broken load)."""
+    if not base:
+        return None
+    return round(delta / abs(base) * 100.0, 1)
+
+
+# --------------------------------------------------------------------------- #
+# Fact producers
+# --------------------------------------------------------------------------- #
+# The metric's identity is often NOT in the column name. Every `fn_rca_*_trend` in this warehouse
+# returns the same generic `actual` / `budget` / `prior_year`, and names what it measures in the
+# FUNCTION: `fn_rca_opendental_hyg_rev_per_patient_trend`. So a per-patient ratio arrived in a
+# column called `actual`, `_NON_ADDITIVE` saw nothing to object to, and twelve months of "hygiene
+# revenue per patient" were added together into a "Total: 10,614.9" — a number that is not a
+# quantity of anything. Set by the caller from the evidence's tool name; blank keeps the old
+# column-only behaviour, so nothing that does not pass it can change.
+_CONTEXT_NON_ADDITIVE = _NON_ADDITIVE
+
+
+def _is_additive(col: str, source: str = "") -> bool:
+    """Can this column be summed across rows? The COLUMN name decides, and the SOURCE can veto."""
+    if _NON_ADDITIVE.search(col or ""):
+        return False
+    # Only a GENERIC column defers to its source. A column that names its own measure is trusted:
+    # `fn_..._per_patient_trend` also returns real money columns, and letting the function name
+    # veto them all would delete every legitimate total the warehouse ships.
+    if source and col.lower() in _GENERIC_MEASURE and _CONTEXT_NON_ADDITIVE.search(source):
+        return False
+    return True
+
+
+# Columns that carry no measure identity of their own — whatever the operation happens to return.
+_GENERIC_MEASURE = frozenset({
+    "actual", "value", "current", "current_value", "curr_val", "amount", "total",
+    "budget", "prior_year", "prior", "prior_value", "last_year", "last_year_val",
+})
+
+
+def column_totals(rows: list[dict], source: str = "") -> list[Fact]:
+    """Sum every additive numeric column — TIME SERIES ONLY.
+
+    Gated on `period_column` because a total is only meaningful when the rows are successive
+    periods of the same measure. See the guard note above for the failure this prevents.
+
+    `source` is the operation the rows came from, and it exists because being a time series is not
+    on its own a licence to add: twelve successive months of hygiene revenue PER PATIENT are a
+    perfectly good series whose sum means nothing. The measure's name lives in the function, not in
+    the generic `actual` column, so without it the guard has nothing to see (`_is_additive`).
+    """
+    period = period_column(rows)
+    if not period:
+        return []
+    span = f"{label_of(rows[0])} to {label_of(rows[-1])}"
+    return [Fact(f"{col}: total", round(sum(vals), 2), f"sum of {len(vals)} periods, {span}")
+            for col, vals in numeric_columns(rows).items()
+            if len(vals) >= 2 and _is_additive(col, source) and _classify(col)[0] != "pct"]
+
+
+def _pairs_in(cols) -> list[tuple[str, str, str]]:
+    """Every `(actual_column, comparison_column, against)` pair implied by the column names."""
+    roles = {c: _classify(c) for c in cols}
+    actuals = {stem: c for c, (role, stem) in roles.items() if role == "actual"}
+    # Flat single-actual fallback: `curr_val` + `delta` don't share a stem, but if the table has
+    # exactly one actual-like column the pairing is unambiguous.
+    lone = next(iter(actuals.values())) if len(actuals) == 1 else None
+    out = []
+    for col, (role, stem) in roles.items():
+        if role not in ("delta_ly", "delta_budget", "delta", "level_prior", "level_budget"):
+            continue
+        actual_col = actuals.get(stem) or lone
+        if actual_col and actual_col != col:
+            out.append((actual_col, col, {"delta_ly": "last year", "level_prior": "last year",
+                                          "delta_budget": "budget", "level_budget": "budget"
+                                          }.get(role, "comparison")))
+    return out
+
+
+def _compare(actual: float, other: float, is_delta: bool) -> tuple[float, float]:
+    """`(change, base)` for one actual/comparison pair.
+
+    The two warehouse shapes differ and conflating them halves or doubles every percentage:
+      * DELTA column (`rev_vs_ly`) — the change is GIVEN; the comparison level is `actual - change`.
+      * LEVEL column (`prior_year_actual`) — the change is `actual - level`.
+    """
+    return (other, actual - other) if is_delta else (round(actual - other, 2), other)
+
+
+def row_comparison_facts(rows: list[dict], focus: "tuple | set" = ()) -> list[Fact]:
+    """Per-row change and percent change against each comparison column.
+
+    Always safe: every figure comes from a single row, so no cross-row addition happens and the
+    homogeneity of the rows is irrelevant. Emitted exhaustively for a small result (a KPI-card
+    list, a handful of locations); larger grids are covered by `contribution_facts` instead, which
+    surfaces the movers that matter rather than all N rows.
+
+    Skipped entirely for a TIME SERIES. There, the aggregates (year-to-date total, change versus
+    last year over the whole span, growth across the period) ARE the story, and the per-period
+    detail is already visible in the rendered table. Emitting twelve monthly comparisons alongside
+    them measurably backfired: the model quoted two arbitrary months and omitted the total and the
+    year-over-year change entirely, because the useful four facts were buried under a dozen
+    lookalikes. Fewer, better facts beat more facts.
+    """
+    if period_column(rows) or not rows:
+        return []
+    if len(rows) > SMALL_TABLE:
+        # A BIG GRID still owes its comparisons to the rows the QUESTION is about. Suppressing
+        # them wholesale was measured as the largest single scoring defect: `fn_category_view` has
+        # no location parameter, so "the category view for Indianapolis, Fort Wayne and Clyde"
+        # fetches all 41 locations, per-row facts were dropped, and the answer could only state
+        # "revenue actual is 0.0, staff actual is 0.0 …" — no versus-last-year, no versus-budget,
+        # because the prompt forbids computing them and none had been supplied. Seven cases in one
+        # run stated no comparison at all while the data carried it.
+        #
+        # `focus` names the entities the question asked about; only those rows get their
+        # comparisons, so the "fewer, better facts" reasoning below still holds for the rest.
+        if not focus:
+            return []
+        want = {f.strip().lower() for f in focus if f and len(f.strip()) >= 4}
+        rows = [r for r in rows
+                if any(w in label_of(r).lower() for w in want)][:SMALL_TABLE]
+        if not rows:
+            return []
+    pairs = _pairs_in(numeric_columns(rows))
+    multi = len(rows) > 1
+    out: list[Fact] = []
+    for row in rows:
+        who = f"{label_of(row)}: " if multi else ""
+        for actual_col, other_col, against in pairs:
+            a, o = _num(row.get(actual_col)), _num(row.get(other_col))
+            if a is None or o is None:
+                continue
+            change, base = _compare(a, o, _classify(other_col)[0].startswith("delta"))
+            out.append(Fact(f"{who}{actual_col} vs {against}: change", round(change, 2),
+                            f"{a:,.2f} against {o:,.2f}"))
+            if (p := _pct(change, base)) is not None:
+                out.append(Fact(f"{who}{actual_col} vs {against}: change %", p, unit="%",
+                                basis=f"{change:,.2f} / {abs(base):,.2f}"))
+    return out
+
+
+def series_comparison_facts(rows: list[dict], source: str = "") -> list[Fact]:
+    """Pooled change vs last year / budget over a TIME SERIES — the year-to-date comparison.
+
+    Gated on `period_column` for the same reason as `column_totals`: this sums each column before
+    differencing them, which is only meaningful across periods — and it takes the same `source`
+    veto, because a year-to-date comparison of two summed RATIOS is exactly as meaningless as the
+    total was. Both sums would be nonsense, so their difference is too.
+    """
+    if not period_column(rows):
+        return []
+    cols = {c: v for c, v in numeric_columns(rows).items() if _is_additive(c, source)}
+    sums = {c: round(sum(v), 2) for c, v in cols.items()}
+    span = f"{len(rows)} periods, {label_of(rows[0])} to {label_of(rows[-1])}"
+    out: list[Fact] = []
+    for actual_col, other_col, against in _pairs_in(cols):
+        change, base = _compare(sums[actual_col], sums[other_col],
+                                _classify(other_col)[0].startswith("delta"))
+        out.append(Fact(f"{actual_col} vs {against}: change over {len(rows)} periods",
+                        round(change, 2), f"{sums[actual_col]:,.2f} against {sums[other_col]:,.2f}, {span}"))
+        if (p := _pct(change, base)) is not None:
+            out.append(Fact(f"{actual_col} vs {against}: change % over {len(rows)} periods", p,
+                            unit="%", basis=f"{change:,.2f} / {abs(base):,.2f}"))
+    return out
+
+
+def margin_facts(rows: list[dict]) -> list[Fact]:
+    """Margin (profit ÷ revenue) for the row set, and the widest/narrowest per-row margins.
+
+    A per-location margin is what turns "revenue is flat" into "revenue is flat but the margin
+    fell 17 points" — a movement invisible in the level columns alone.
+    """
+    cols = numeric_columns(rows)
+    prof = next((c for c in cols if _PROFIT_COL.search(c) and _classify(c)[0] == "actual"), None)
+    rev = next((c for c in cols if _REVENUE_COL.search(c) and _classify(c)[0] == "actual"), None)
+    if not prof or not rev or prof == rev:
+        return []
+    out: list[Fact] = []
+    # An overall margin needs a pooled numerator and denominator, so it is allowed only where
+    # pooling is — across periods. Across arbitrary rows the per-row margins below stand alone.
+    if period_column(rows):
+        tot_p, tot_r = sum(cols[prof]), sum(cols[rev])
+        if tot_r:
+            out.append(Fact(f"{prof} margin (overall)", round(tot_p / tot_r * 100, 1), unit="%",
+                            basis=f"{tot_p:,.2f} / {tot_r:,.2f} over {len(rows)} periods"))
+    per: list[tuple[float, str]] = []
+    for row in rows:
+        p, r = _num(row.get(prof)), _num(row.get(rev))
+        if p is not None and r:
+            per.append((round(p / r * 100, 1), label_of(row)))
+    if len(per) >= 2:
+        hi, lo = max(per), min(per)
+        out.append(Fact(f"{prof} margin: widest", hi[0], unit="%", basis=f"at {hi[1]}"))
+        out.append(Fact(f"{prof} margin: narrowest", lo[0], unit="%", basis=f"at {lo[1]}"))
+        out.append(Fact(f"{prof} margin: spread", round(hi[0] - lo[0], 1), unit="pp",
+                        basis=f"{hi[1]} minus {lo[1]}"))
+    return out
+
+
+def contribution_facts(rows: list[dict]) -> list[Fact]:
+    """Top-N contributors to a change, and how concentrated that change is.
+
+    This is the "three locations account for $1.1M of the decline" shape — the single most
+    load-bearing sentence in an executive briefing, and one the model must never estimate.
+    """
+    if len(rows) < 3:
+        return []
+    cols = numeric_columns(rows)
+    delta_col = next((c for c, (role, _) in ((c, _classify(c)) for c in cols)
+                      if role in ("delta_ly", "delta_budget", "delta")), None)
+    if not delta_col:
+        return []
+    pairs = [(f, label_of(r)) for r in rows if (f := _num(r.get(delta_col))) is not None]
+    # Second guard, independent of the time-series rule: if one row equals the sum of the others,
+    # these rows are components of a rollup rather than peers, so ranking them and calling the
+    # leader a "top contributor" double-counts the total it is being measured against.
+    if len(pairs) < 3 or _has_rollup_row([v for v, _ in pairs]):
+        return []
+    falls = sorted((p for p in pairs if p[0] < 0), key=lambda p: p[0])
+    top = falls[:TOP_N]
+    out: list[Fact] = []
+    for val, name in top:
+        out.append(Fact(f"{delta_col}: {name}", round(val, 2), "row value"))
+    if not top:
+        return out
+    share = sum(v for v, _ in top)
+    out.append(Fact(f"{delta_col}: worst {len(top)} combined", round(share, 2),
+                    basis=" + ".join(n for _, n in top)))
+    # Share is measured against the TOTAL DECLINE (the sum of the negative movers), not the net
+    # change. Against the net it exceeds 100% whenever gainers offset losers — arithmetically
+    # true, but "the top 3 are 108.7% of the change" reads as an error to an executive and
+    # invites them to distrust the rest of the briefing.
+    decline = sum(v for v, _ in falls)
+    # A share is only informative when something was left out; "the worst 3 are 100% of the
+    # decline" when exactly 3 rows declined states nothing and reads as padding.
+    if len(falls) > len(top) and (p := _pct(share, decline)) is not None:
+        out.append(Fact(f"{delta_col}: worst {len(top)} share of the total decline", abs(p),
+                        unit="%", basis=f"{share:,.2f} of {decline:,.2f} across "
+                                        f"{len(falls)} declining rows"))
+    return out
+
+
+def series_facts(rows: list[dict]) -> list[Fact]:
+    """First/last levels and the growth between them, for a time-ordered table.
+
+    Only fires when a period column is present AND rows are already in period order, which is how
+    the warehouse returns trends. Growth is stated over the actual span so "+11% over 12 months"
+    can never be mistaken for a monthly rate.
+    """
+    if len(rows) < 3 or not period_column(rows):
+        return []
+    out: list[Fact] = []
+    for col, vals in numeric_columns(rows).items():
+        if len(vals) < 3 or not _is_additive(col) or _classify(col)[0] in ("pct", "delta",
+                                                                          "delta_ly", "delta_budget"):
+            continue
+        first, last = vals[0], vals[-1]
+        span = f"{label_of(rows[0])} to {label_of(rows[-1])}"
+        out.append(Fact(f"{col}: change over the period", round(last - first, 2),
+                        f"{last:,.2f} at {label_of(rows[-1])} minus {first:,.2f} at {label_of(rows[0])}"))
+        if (p := _pct(last - first, first)) is not None:
+            out.append(Fact(f"{col}: change over the period %", p, unit="%", basis=span))
+    return out
+
+
+# --------------------------------------------------------------------------- #
+# ATTRIBUTION — why a number moved, derived from structured data
+# --------------------------------------------------------------------------- #
+# The incumbent agent's most impressive answers quote manager commentary ("Dr. Peterson on personal
+# leave since late Feb"). That data does not exist in this warehouse and cannot be obtained, so the
+# causal story is reconstructed from the numbers instead — which is reproducible and checkable
+# where a quoted note is neither.
+#
+# Two independent detectors, both self-gating on the SHAPE of the result, so neither needs to know
+# which function produced it:
+#   * `decomposition_facts`  — "the change splits into price / volume / mix"
+#   * `provider_continuity_facts` — "this earner's output stopped in March"
+
+def _additive_identity(rows: list[dict]) -> tuple[str, list[str]] | None:
+    """Find `(total_column, [component_columns])` where the components SUM to the total in every
+    row — i.e. the result is already a decomposition of a change into its drivers.
+
+    Detected ARITHMETICALLY rather than by column name, so this works on any warehouse that ships
+    a decomposition under any naming convention. An identity that holds across every row of a
+    real result is not a coincidence: with 100+ rows a spurious 3-column match is vanishingly
+    unlikely, and the all-rows requirement is what makes name-free detection safe here.
+    """
+    cols = {c: v for c, v in numeric_columns(rows).items() if len(v) == len(rows)}
+    # A decomposition splits a CHANGE into its drivers, so every column in it — the total and each
+    # component — must be able to go negative. This is what separates the useful identity from the
+    # trivial one: a result carrying `curr_prod`, `prior_prod` and `total_delta` satisfies BOTH
+    # `total_delta = mix + price + volume` and `curr_prod = prior_prod + total_delta`, and the
+    # second is a bigger number but says nothing — it just restates that the level moved. Level
+    # columns are never negative; delta columns are, so requiring a negative excludes them.
+    signed = {c: v for c, v in cols.items() if any(x < 0 for x in v)}
+    if len(signed) < 3:
+        return None
+    names = sorted(signed)
+    best: tuple[str, list[str]] | None = None
+    for total in names:
+        others = [c for c in names if c != total]
+        if len(others) > 12:                      # keep the combinatorics bounded on a wide table
+            others = others[:12]
+        # THREE components minimum. A two-way split is an ACCOUNTING IDENTITY, not a decomposition
+        # of drivers: `revenue = ebitda + expenses` is exactly true on every row and says only that
+        # the books balance. Live, it was picked up on a financial trend and produced "change
+        # attributed to expenses" — a meaningless attribution, which then let the repair below
+        # overwrite an unrelated number in the prose. A driver split (price / volume / mix) has
+        # three or more.
+        for size in (3, 4):
+            for combo in itertools.combinations(others, size):
+                if all(abs(sum(r[c] for c in combo) - r[total]) <= max(0.01, abs(r[total]) * 1e-6)
+                       for r in ({k: _num(v) for k, v in row.items()} for row in rows)
+                       if all(r.get(c) is not None for c in combo) and r.get(total) is not None):
+                    cand = (total, list(combo))
+                    # Prefer the identity over the LARGEST total — among genuine change
+                    # decompositions that is the headline one, not an internal sub-total.
+                    if best is None or abs(sum(signed[total])) > abs(sum(signed[best[0]])):
+                        best = cand
+                    break
+    return best
+
+
+def _shared_affix(names: list[str]) -> str:
+    """The common trailing token shared by every component column (`mix_delta`, `price_delta`,
+    `volume_delta` → `_delta`), so labels can be shortened to `mix` / `price` / `volume` without
+    hardcoding what the columns are called."""
+    parts = [n.split("_") for n in names]
+    if len(parts) < 2 or not all(len(p) > 1 for p in parts):
+        return ""
+    tail = parts[0][-1]
+    return f"_{tail}" if all(p[-1] == tail for p in parts) else ""
+
+
+def decomposition_facts(rows: list[dict]) -> list[Fact]:
+    """Split a change into the drivers that produced it — the "why", not just the "what".
+
+    This is the analysis the incumbent explicitly told us it does NOT have ("a formal
+    volume/mix/price analysis is not available"), while our warehouse ships it per procedure code.
+    Rolling the per-item rows up to `total = A + B + C` turns a 162-row table nobody reads into
+    one sentence: the change was $X, of which $A came from price, $B from volume, and mix cost $C.
+    """
+    if len(rows) < 3:
+        return []
+    ident = _additive_identity(rows)
+    if not ident:
+        return []
+    total_col, comps = ident
+    cols = numeric_columns(rows)
+    total = round(sum(cols[total_col]), 2)
+    if not total:
+        return []
+    affix = _shared_affix(comps)
+
+    def nice(c: str) -> str:
+        return (c[:-len(affix)] if affix and c.endswith(affix) else c).replace("_", " ")
+
+    out = [Fact("total change", total, f"sum of {len(rows)} items")]
+    # Largest absolute contribution first — the driver that explains the move leads.
+    for comp in sorted(comps, key=lambda c: -abs(sum(cols[c]))):
+        val = round(sum(cols[comp]), 2)
+        out.append(Fact(f"change attributed to {nice(comp)}", val,
+                        f"sum of {comp} across {len(rows)} items"))
+        # SIGNED share, unlike `contribution_facts`' share-of-a-decline: here the sign is the
+        # whole point. Price and volume ADDED to the move while mix SUBTRACTED from it, and an
+        # unsigned "62.3%" next to a negative dollar figure reads as a contradiction.
+        if (p := _pct(val, total)) is not None:
+            out.append(Fact(f"change attributed to {nice(comp)}: share of the move", p,
+                            unit="%", basis=f"{val:,.2f} of {total:,.2f}"))
+    return out
+
+
+# A provider/employee production series: one row per person per period. Detected structurally —
+# a repeating period column plus a text key — never by column name.
+_COLLAPSE_RATIO = 0.25   # below a quarter of the person's own median = a discontinuity, not a dip
+_ARTIFACT_SHARE = 0.6    # this share of people collapsing AT ONCE means the PERIOD is incomplete
+
+
+def _entity_period_value(rows: list[dict]) -> tuple[list[str], str, str] | None:
+    """`(entity_columns, period_column, value_column)` for a per-entity-per-period table."""
+    if len(rows) < 6 or not isinstance(rows[0], dict):
+        return None
+    period = next((c for c in rows[0]
+                   if all(_as_period(r.get(c)) is not None for r in rows)
+                   and len({_as_period(r.get(c)) for r in rows}) < len(rows)), None)
+    if not period:
+        return None                                # every period distinct → a plain trend, not this
+    entity = [c for c in rows[0]
+              if c != period and all(isinstance(r.get(c), str) for r in rows)]
+    nums = [c for c, v in numeric_columns(rows).items() if _is_additive(c) and len(v) == len(rows)]
+    if not entity or len(nums) != 1:
+        return None
+    return entity, period, nums[0]
+
+
+def provider_continuity_facts(rows: list[dict]) -> list[Fact]:
+    """Detect an earner whose output STOPPED — the structured, dated shadow of the staffing event
+    a manager's note would have described.
+
+    Deliberately excludes an INCOMPLETE trailing period, detected structurally: if most people
+    collapse in the same final period, that is a partial data load, not simultaneous resignations.
+    Verified on the live warehouse — 9% of providers "collapsed" in each of the last two complete
+    months versus **100%** in the partial current month. Without this the detector would announce
+    that the entire clinical staff quit, every single month.
+
+    Reports nothing when nothing dropped out. That is the honest answer, and the whole point: it
+    is what lets an analysis say "the driver is not identifiable from the data" instead of
+    inventing a cause.
+    """
+    shape = _entity_period_value(rows)
+    if not shape:
+        return []
+    ent_cols, period, value = shape
+    series: dict[str, dict] = {}
+    for r in rows:
+        key = " ".join(str(r[c]).strip() for c in ent_cols if r.get(c))
+        p, v = _as_period(r.get(period)), _num(r.get(value))
+        if key and p and v is not None:
+            series.setdefault(key, {})[p] = v
+    periods = sorted({p for s in series.values() for p in s})
+    if len(periods) < 4 or len(series) < 2:
+        return []
+
+    def collapsed(at, known: list) -> list[tuple[str, float, float]]:
+        """(name, own median before `at`, value at `at`) for everyone who fell off a cliff.
+
+        A missing row is only read as zero when the person was ACTIVE IN THE PERIOD IMMEDIATELY
+        BEFORE — that is what makes it a stop rather than an absence. Without that check, anyone
+        who left years ago has no rows at all, reads as zero forever, and is re-reported as having
+        "just stopped" in whatever period is currently last: three long-departed providers were
+        announced as June departures on the live data.
+        """
+        idx = known.index(at)
+        if idx == 0:
+            return []
+        just_before = known[idx - 1]
+        hits = []
+        for name, s in series.items():
+            prior = [v for p, v in s.items() if p < at]
+            was_active = s.get(just_before, 0.0)
+            if len(prior) < 3 or was_active <= 1000:
+                continue
+            base = statistics.median(prior[-6:])   # their own recent run-rate, not a lifetime mean
+            cur = s.get(at, 0.0)
+            if base > 1000 and cur < base * _COLLAPSE_RATIO:
+                hits.append((name, round(base, 2), round(cur, 2)))
+        return hits
+
+    last = periods[-1]
+    # Everyone who was active in the period before `last` is a candidate to have stopped at it;
+    # if MOST of them appear to have stopped at once, the period is a partial load, not an exodus.
+    eligible = sum(1 for s in series.values()
+                   if len(s) >= 4 and s.get(periods[-2], 0.0) > 1000)
+    if eligible and len(collapsed(last, periods)) >= _ARTIFACT_SHARE * eligible:
+        periods = periods[:-1]                     # partial load — not a staffing event
+        if len(periods) < 4:
+            return []
+        last = periods[-1]
+
+    hits = sorted(collapsed(last, periods), key=lambda h: -(h[1] - h[2]))[:TOP_N]
+    when = f"{last[0]}-{last[1]:02d}"
+    return [Fact(f"production stopped: {name}", round(cur, 2),
+                 f"ran at {base:,.2f}/period before {when}, then {cur:,.2f} in {when}")
+            for name, base, cur in hits]
+
+
+# --------------------------------------------------------------------------- #
+# DATA QUALITY — values that are almost certainly a loading fault, not a result
+# --------------------------------------------------------------------------- #
+# A broken load looks exactly like a catastrophic business event, and the difference is invisible
+# to grounding: the figure IS in the data, so a "-100.3% year over year" reads as fully verified.
+# Measured on this warehouse — enterprise revenue runs ~$5.2M/month for ten months, then reports
+# -$32,063 and -$13,748, and expenses go NEGATIVE. Left unflagged, an answer reports that as a
+# collapse and an executive acts on it.
+#
+# Every check is convention-free. Nothing here knows that "revenue" should be positive or that
+# "expenses" are stored negative — sign conventions differ per table and per warehouse. What it
+# knows is that a column which held ONE sign for months does not legitimately flip, and that a
+# metric running at millions does not legitimately land near zero. Both are properties of the
+# series, not of the domain.
+
+COLLAPSE_FLOOR = 0.10   # under a tenth of the established run-rate is a fault, not a bad month
+STABLE_MIN = 4          # periods needed before "normal" is established at all
+ZERO_SHARE = 0.6        # this share of entities reporting nothing = the load, not the business
+
+
+@dataclass(frozen=True)
+class Flag:
+    """One data-quality finding. `where` locates it, `detail` states the evidence for it."""
+    kind: str           # collapse | sign_flip | all_null | zero_population
+    column: str
+    where: str
+    detail: str
+
+    def render(self) -> str:
+        return f"{self.column} — {self.detail} ({self.where})"
+
+
+def _series_flags(rows: list[dict], period: str) -> list[Flag]:
+    """Trailing periods where a column breaks from its own established behaviour."""
+    out: list[Flag] = []
+    # Label from the PERIOD column itself, not `label_of` — the period is frequently a `date`
+    # object, and `label_of` only considers string fields, so every flag came out labelled "?".
+    labels = []
+    for r in rows:
+        p = _as_period(r.get(period))
+        labels.append(f"{p[0]}-{p[1]:02d}" if p else label_of(r))
+    for col, vals in numeric_columns(rows).items():
+        if len(vals) != len(rows) or not _is_additive(col) or _classify(col)[0] == "pct":
+            continue
+        bad: list[tuple[int, str]] = []
+        for i in range(len(vals) - 1, STABLE_MIN - 1, -1):
+            prior = vals[:i]
+            if len(prior) < STABLE_MIN:
+                break
+            base = statistics.median([abs(v) for v in prior])
+            if base < 1000:                       # too small for "collapse" to mean anything
+                break
+            signs = {v > 0 for v in prior if v}
+            flipped = len(signs) == 1 and vals[i] and (vals[i] > 0) not in signs
+            collapsed = abs(vals[i]) < base * COLLAPSE_FLOOR
+            if not (flipped or collapsed):
+                break                             # the trailing run of anomalies ends here
+            bad.append((i, "sign_flip" if flipped else "collapse"))
+        for i, kind in reversed(bad):
+            base = statistics.median([abs(v) for v in vals[:i]])
+            out.append(Flag(
+                kind=kind, column=col, where=labels[i],
+                detail=(f"{vals[i]:,.2f} against a {base:,.2f} run-rate over the preceding "
+                        f"{i} periods"
+                        + (" — and the opposite sign to every one of them" if kind == "sign_flip"
+                           else ""))))
+    return out
+
+
+def _population_flags(rows: list[dict]) -> list[Flag]:
+    """A per-entity result where most entities report nothing.
+
+    Deliberately a NOTE, never a rejection: a real location with no activity legitimately returns
+    zero, so this reports the shape of the result and lets the reader judge. It is a majority
+    threshold precisely so a handful of genuinely quiet entities never trips it.
+    """
+    out: list[Flag] = []
+    for col, vals in numeric_columns(rows).items():
+        if len(vals) != len(rows) or len(vals) < 5 or not _is_additive(col):
+            continue
+        if _classify(col)[0] != "actual":         # a delta is legitimately zero for a flat entity
+            continue
+        quiet = sum(1 for v in vals if abs(v) < 1)
+        if quiet >= ZERO_SHARE * len(vals) and max(abs(v) for v in vals) > 1000:
+            out.append(Flag(kind="zero_population", column=col,
+                            where=f"{quiet} of {len(vals)} rows",
+                            detail="report no value while others in the same result do"))
+    return out
+
+
+def data_quality_flags(rows: list[dict]) -> list[Flag]:
+    """Values that are almost certainly a data fault rather than a result. See the note above.
+
+    Returns [] for healthy data, which is the common case and costs nothing.
+    """
+    rows = [r for r in (rows or []) if isinstance(r, dict)]
+    if len(rows) < 2:
+        return []
+    out: list[Flag] = []
+    try:
+        if period := period_column(rows):
+            out += _series_flags(rows, period)
+        else:
+            out += _population_flags(rows)
+        # A column declared by the result but null in EVERY row — the model otherwise reports the
+        # metric as though it were measured and found to be nothing.
+        keys = {k for r in rows for k in r}
+        numeric = set(numeric_columns(rows))
+        for k in sorted(keys - numeric):
+            if all(r.get(k) is None for r in rows):
+                out.append(Flag(kind="all_null", column=k, where=f"all {len(rows)} rows",
+                                detail="present in the result but empty throughout"))
+    except Exception:      # a quality check must never be the reason an answer fails
+        return out
+    return out[:6]
+
+
+# --------------------------------------------------------------------------- #
+# Public entry points
+# --------------------------------------------------------------------------- #
+def derive(rows: list[dict], cap: int = MAX_FACTS_PER_ITEM,
+           focus: "tuple | set" = (), source: str = "",
+           cumulative: bool = False) -> list[Fact]:
+    """Every derived fact for one result set, de-duplicated and capped.
+
+    Ordered by usefulness to an executive summary, because `cap` truncates the tail: the pooled
+    comparisons and contributions carry the story ("down $4.2M, -11.5% versus last year"; "three
+    locations are 60% of the decline"), so they must survive the cap. Exhaustive per-row facts go
+    last and simply spend whatever budget remains — on a 12-month trend they would otherwise
+    crowd out the year-to-date totals they are far less useful than.
+
+    `cumulative` says each row ALREADY CONTAINS the rows before it — a trailing-twelve-month or
+    to-date series. Summing those double-counts every period: measured, a TTM revenue trend was
+    added up into "Total: $652,831,245.13", roughly twelve times the revenue that exists, and the
+    same rolling values were narrated as "the monthly actual revenue figures" when a month is
+    ~$5M and the rows read ~$57M. Neither the column name (`actual`) nor the function name
+    (`fn_income_statement_trend`) says so — the fact lives in the ARGUMENT (`p_time_period=TTM`),
+    which is why `_is_additive`'s column/source test cannot see it and the caller must pass it.
+    """
+    rows = [r for r in (rows or []) if isinstance(r, dict)]
+    if not rows:
+        return []
+    facts: list[Fact] = []
+    # ATTRIBUTION FIRST. When a result carries a decomposition or a dropped-out earner, that IS
+    # the answer to "why did this move" — it must survive the cap ahead of the ordinary totals and
+    # comparisons, which are merely restating what the table already shows.
+    # WHEN THE QUESTION NAMES ENTITIES, their own comparisons lead. `row_comparison_facts` runs
+    # last by default — right for a briefing, where the aggregates carry the story — but the cap
+    # then truncates before reaching it, so a question about three named locations got the
+    # enterprise decomposition and none of its own figures. Asked for, so first.
+    order = (decomposition_facts, provider_continuity_facts,
+             series_comparison_facts, contribution_facts, margin_facts, series_facts,
+             column_totals, row_comparison_facts)
+    if focus:
+        order = (row_comparison_facts,) + tuple(p for p in order if p is not row_comparison_facts)
+    if cumulative:
+        # The two producers that ADD ACROSS ROWS. Everything else — per-row comparisons, margins,
+        # extremes — stays: a rolling series has a perfectly good highest and lowest month, and
+        # that is most of what a trend question wants.
+        order = tuple(p for p in order if p not in (column_totals, series_comparison_facts))
+    for producer in order:
+        try:
+            if producer is row_comparison_facts:
+                facts.extend(producer(rows, focus))
+            elif producer in (column_totals, series_comparison_facts):
+                facts.extend(producer(rows, source))   # these two add ACROSS periods
+            else:
+                facts.extend(producer(rows))
+        except Exception:      # a derived fact is an enhancement; never let one break synthesis
+            continue
+    seen, out = set(), []
+    for f in facts:
+        if f.label in seen:
+            continue
+        seen.add(f.label)
+        out.append(f)
+    return out[:cap]
+
+
+def facts_block(by_item: list[tuple[str, list[Fact]]]) -> str:
+    """The DERIVED FACTS section appended to the synthesis prompt.
+
+    Deliberately emphatic about provenance: the model's standing instruction is that it may not
+    compute anything, so these have to read as values it is permitted to quote — otherwise it
+    omits them and we are back to the min/max/average ceiling.
+    """
+    blocks = [f"[{eid}]\n" + "\n".join(f"  - {f.render()}" for f in facts)
+              for eid, facts in by_item if facts]
+    if not blocks:
+        return ""
+    return (
+        "\n\nDERIVED FACTS — computed by CODE from the evidence above, VERIFIED and safe to quote. "
+        "These are the ONLY derived figures you may state (totals, changes, percentages, margins, "
+        "shares). Use them verbatim — do NOT recompute, adjust or round them differently, and do "
+        "NOT derive any figure that is not listed here. Each is followed by the arithmetic that "
+        "produced it; quote the figure, not the arithmetic:\n" + "\n\n".join(blocks)
+    )
+
+
+# Facts an executive summary is incomplete without, most important first: the movement against
+# last year, then against budget, then the period total, then growth across the span. Matched as
+# SUBSTRINGS — the labels carry a trailing qualifier ("change over 12 periods"), and an
+# `endswith` test silently dropped the single most important fact of the set.
+_HEADLINE = ("vs last year: change", "vs budget: change", ": total", ": change over the period")
+
+
+def headline_facts(facts: list[Fact], limit: int = 3) -> list[Fact]:
+    """The few facts a summary must not omit, most important first.
+
+    Each absolute figure is returned with its percentage immediately after it, so the guard can
+    never emit a bare "-2.6%" with nothing to anchor it. `limit` counts absolute figures, not
+    list entries — the percentages ride along.
+    """
+    out: list[Fact] = []
+    for key in _HEADLINE:
+        for f in facts:
+            # A total of the COMPARISON column (last year's, budget's) is not a headline — it is
+            # the base the headline is measured against, and printing both reads as clutter.
+            if key == ": total" and _classify(f.label.split(":")[0])[0] != "actual":
+                continue
+            if key in f.label and f.unit != "%" and f not in out:
+                out.append(f)
+                # The percentage's label is the absolute one with "%" inserted, so it does not
+                # start with it — pair by normalising the "%" away rather than by prefix.
+                pct = next((p for p in facts
+                            if p.unit == "%" and p.label.replace(" %", "") == f.label), None)
+                if pct:
+                    out.append(pct)
+                if sum(1 for x in out if x.unit != "%") >= limit:
+                    return out
+    return out
+
+
+def _is_movement(f: Fact) -> bool:
+    """A change carries an explicit sign; a level does not."""
+    return "change" in f.label or " vs " in f.label
+
+
+def _fmt(f: Fact, money: str) -> str:
+    if f.unit == "%":
+        return f"{f.value:+,.1f}%"
+    if f.unit == "pp":
+        return f"{f.value:+,.1f} pp"
+    body = f"{money}{abs(f.value):,.2f}"
+    if f.value < 0:
+        return f"-{body}"
+    return f"+{body}" if _is_movement(f) else body
+
+
+def headline_facts_by_item(by_item: list[tuple[str, list[Fact]]], limit: int = 3) -> list[Fact]:
+    """Headline facts from ONE evidence item — the first one that has any. NEVER blended across
+    items, and this is the entry point `agent.py` must call (not `headline_facts` on a pooled
+    list).
+
+    The hazard: two evidence items of the same shape (this year's trend, fetched alongside last
+    year's trend as its own call for comparison) produce IDENTICALLY LABELED facts with different
+    values — both are "actual vs last year: change", one -$2.5M, the other +$2.7M for an unrelated
+    older window. `derive()` dedupes by label WITHIN one item, so the collision only exists once
+    facts from several items are pooled. Pooling let the wrong item's figure outrank the one the
+    narrative actually discussed, appended right beside a different number under the identical
+    name — confusing at best, and it silently mispairs the percentage too, since a label-based
+    pairing search finds whichever item's percentage comes first, not the one beside the value
+    being paired. Scoping to one item at a time is the same principle as this codebase's existing
+    ONE SOURCE PER TABLE rule (`agent.py`): each evidence item tells its own story.
+    """
+    for _eid, facts in by_item:
+        if heads := headline_facts(facts, limit):
+            return heads
+    return []
+
+
+def render_headline(facts: list[Fact], currency: bool = True) -> str:
+    """One compact line of headline figures, each change followed by its percentage in brackets.
+
+    Pairing normalises the "%" away rather than testing a prefix: the percentage's label is the
+    absolute one with "%" INSERTED (`change % over 12 periods`), so it never starts with the
+    absolute label, and a prefix test silently split the pair across two clauses.
+    """
+    money = "$" if currency else ""
+    parts, i = [], 0
+    while i < len(facts):
+        f = facts[i]
+        nxt = facts[i + 1] if i + 1 < len(facts) else None
+        paired = (nxt is not None and nxt.unit == "%"
+                  and nxt.label.replace(" %", "") == f.label)
+        tail = f" ({nxt.value:+,.1f}%)" if paired else ""
+        parts.append(f"{_clean(f.label)} {_fmt(f, money)}{tail}")
+        i += 2 if paired else 1
+    return " · ".join(parts)
+
+
+def _clean(label: str) -> str:
+    """A fact label → a short phrase a reader can parse without the column name.
+
+    `actual vs last year: change over 12 periods` → `vs last year`
+    `prior_year: total`                          → `prior year total`
+    `actual: change over the period`             → `change across the period`
+    """
+    s = re.sub(r"\s*over \d+ periods$", "", label)
+    s = re.sub(r"^actual\b\s*", "", s)               # the default column name says nothing
+    s = s.replace(": change over the period", "change across the period")
+    s = re.sub(r":\s*change$", "", s)
+    s = s.replace(": total", " total")
+    return re.sub(r"\s+", " ", s.replace("_", " ")).strip(": ").strip() or label
+
+
+def fact_values(by_item: list[tuple[str, list[Fact]]]) -> list[float]:
+    """Every derived value, for the grounding pool.
+
+    Without this the model quotes a figure we handed it and the grounding check flags its own
+    verified number as unsupported — which then sinks the rubric and can trigger an abstain.
+    """
+    return [f.value for _eid, facts in by_item for f in facts]