[nicoloboschi]

Summary

retrieve_temporal_combined Phase 1 ranked the entire date-window match set
with a window function and then discarded all but the top 50 per fact_type.
On banks with dense or near-uniform date metadata — e.g. a retain pipeline that
stamps a large batch with a single mentioned_at/event_date — any temporal
recall window intersects (near-)all rows, so the query degraded to a full
sequential scan plus a disk-spilling sort. This is the 30s+ prod temporal recall
behind #1958.

This PR fixes the query so the temporal arm stays correct and fast at scale,
rather than skipping it.

Root cause (reproduced + EXPLAIN'd on a 680k-row dense-date bank)

The window function forces a full sort: ROW_NUMBER() OVER (PARTITION BY fact_type ORDER BY COALESCE(occurred_start, mentioned_at, occurred_end) DESC) must rank
every matched row before the outer rn <= 50 filter applies. EXPLAIN ANALYZE:

Aggregate (actual time=671 ms)
  -> WindowAgg (rows=680000)
       -> Sort  Sort Key: fact_type, COALESCE(...) DESC  (rows=680000)  -- spills to disk under prod work_mem
            -> Seq Scan on memory_units (rows=680000)  Buffers: read=140655
  -> CTE Scan ... Filter: (rn <= 50)  Rows Removed by Filter: 679,950   -- sorted 680k rows to keep 50

The date filter is index-able; the ranking sort is the trigger. When all
events share ~one date the sort key is degenerate (all tied), so the "top 50 most
recent" is 50 arbitrary rows produced by sorting the whole bank.

Fix

Rewrite Phase 1 as a CROSS JOIN LATERAL with ORDER BY … LIMIT 50 per
fact_type, backed by a new partial expression index:

CREATE INDEX idx_memory_units_temporal_recency
ON memory_units (bank_id, fact_type, (COALESCE(occurred_start, mentioned_at, occurred_end)) DESC NULLS LAST)
WHERE embedding IS NOT NULL

The planner walks the index in recency order and stops after 50 matching rows
per fact_type, so work is bounded to ~50 × len(fact_types) index entries
regardless of how many rows fall in the window. Semantics are unchanged (50
most-recent in-window per type → similarity rerank → top 10). The NULLS LAST in
the index is load-bearing: it matches the query's DESC NULLS LAST so the index
supplies the ordering directly (a regression test pins this).

Results (680k-row dense-date bank, recall_perf)

	before	after
temporal arm (recall trace)	1.174 s	0.009 s (~130×)
Phase-1 EXPLAIN exec time	672 ms	0.1 ms
Phase-1 plan	Seq Scan 680k + Sort 680k	Index Scan, no Sort

(Local pg0 has more work_mem than prod, so the absolute local number is ~1s vs
prod's 33s, but the pathology and the fix are the same.)

vs #1958

#1958 added a planner-estimate circuit breaker that skips the temporal arm
entirely above a row estimate — losing temporal recall on exactly the large
banks where it matters. This PR keeps the arm working and makes it fast, so the
circuit breaker isn't needed.

Reproduce

cd hindsight-api-slim
uv run python ../hindsight-dev/benchmarks/perf/recall_perf.py generate \
    --bank-id recall-perf-temporal --scale very-large --event-date 2025-01-15
uv run python ../hindsight-dev/benchmarks/perf/recall_perf.py benchmark \
    --bank-id recall-perf-temporal --query "database migration" \
    --temporal-date 2025-01-15 --iterations 5

generate --event-date stamps all memories into one date (dense zone);
benchmark --temporal-date appends an absolute date to the query so the temporal
arm fires on that window. Both flags are new in this PR.

Tests

tests/test_temporal_recall_bounded_scan.py (deterministic, no LLM):

• window filter + top-50-by-recency bound: an out-of-window or too-old unit
  is excluded even with a perfect-match embedding
• the recency index serves the DESC NULLS LAST ordering with no Sort node
  (guards a NULLS-order / index-shape regression)

test_migration_shape.py passes (migration dispatches through run_for_dialect;
PG-only, Oracle slot intentionally absent since the query uses pgvector <=>).