perf: emit sargable per-state SQL for list queries

[nicolasburtey]

Summary

Root fix for the non-sargable es-entity list queries found in the
sb-st7-2lps stress test (2 loans/s, 4h soak): every generated list query
wrapped optional filters in COALESCE(col = $k, $k IS NULL) and the cursor
predicate in COALESCE((col, id) < ($c, $i), $i IS NULL). Under generic
plans those predicates can never become index quals, so every call
full-scans the entity table (and the events table on the join side). On
core_disbursals the windowed mean exec time grew linearly with total
table size (2.1 ms @ 1.8k rows → 6.1 ms @ 17.4k rows), ~300 buffer blocks
hit per call, called ~2.5x per loan from the admin GraphQL
creditFacility { disbursals } resolver.

This is a class problem — every list whose filters are all-optional had
the same shape; disbursals is just the first table big enough to expose it.

What changed

Cursor specialization (list_by_fn.rs, shared by list_for_fn.rs and
list_for_filters_fn.rs): each generated list fn now dispatches at runtime
on the destructured cursor values and emits distinct static es_query!
literals per state:

• Page 1 (no cursor): no cursor predicate at all — rides index ordering
  with early-exit LIMIT.
• Cursor page: bare (col, id) {comp} ($c, $i) row comparison —
  sargable against composite indexes.
• Nullable sort columns: dedicated NULL-cursor variants replicating the
  exact NULLS FIRST/LAST edge semantics previously encoded in the COALESCE
  fallbacks (col IS NOT NULL OR id > $i ASC; col IS NULL AND id < $i
  DESC; col IS NULL OR (col, id) < ($c, $i) for non-NULL cursors DESC).
• nullable-annotated non-Option columns: NULL-ness of the cursor
  value is invisible to Rust, so the cursor-present variant keeps the
  legacy predicate; page 1 still gets the bare form.

Filter-combination specialization (list_for_filters_fn.rs):
list_for_filters_by_* now emits one static query per filter Some-ness
combination — present filters compile to sargable col = $k (or
col IS NULL for optional columns filtering on None), absent filters
are omitted entirely. Capped above 4 filter columns (only no-filter /
single-filter / all-filter combinations specialize); the legacy COALESCE
query is retained as the wildcard fallback arm, so correctness is
preserved for every combination.

Public API is unchanged — Filters structs, list* signatures, cursor
types all stay the same. Consumers only need to regenerate their sqlx
offline cache.

Verification

• New integration harness (tests/sargable_list_queries.rs +
  tests/entities/transfer.rs) mirroring lana's Disbursal repo shape
  (2 non-optional + 1 optional list_for filters, by(created_at) sort,
  nullable score sort column).
• Plan shape: EXPLAIN with enable_seqscan = off shows
  Index Cond for the specialized page-1 and cursor-page queries, and no
  Index Cond for the legacy COALESCE catch-all (documents the
  before/after).
• Correctness: reference-implementation test paginates every filter
  combination x sort x direction and asserts exact row/order equality
  against in-Rust filtering/sorting; NULL-cursor transitions on the
  nullable sort column are exercised in both directions.
• All 127 pre-existing integration tests, 95 macro unit tests, mdbook
  tests pass; all feature combos (graphql, instrument,
  event-context, ...) compile.

Watch items (from the brief)

• Codegen size: the matrix is (filter combos) x (cursor states) x
  (directions) per sort column; the >4-column cap bounds this. Worth
  eyeballing macro-expansion compile time on lana's biggest repos
  (CreditFacility) during adoption.
• sqlx cache churn: consumers must re-run sqlx prepare.
• Index coverage: sargable SQL only helps where indexes exist; lana
  needs the core_disbursals(credit_facility_id, created_at DESC, id DESC)
  composite index (separate lana PR).

---

Note

Medium Risk
Changes SQL for every generated list path while preserving the public API; correctness hinges on nullable sort and filter edge cases, though new integration tests reduce regression risk. Consumers must regenerate sqlx offline caches and rely on appropriate indexes for the performance win.

Overview
Generated list repo methods no longer rely on a single COALESCE(..., $ IS NULL) query shape. Codegen now emits static es_query! literals chosen at runtime from cursor presence and filter Some/None state, so predicates can become index quals instead of forcing generic plans and table scans.

Cursor pagination (list_by_*, list_for_*): first page drops the cursor predicate; later pages use bare (col, id) comparisons. Nullable Option sort columns add explicit NULL-cursor arms; nullable-annotated non-Option types still use the legacy COALESCE cursor form when Rust cannot distinguish SQL NULL.

Multi-filter lists (list_for_filters_by_*): each active filter combination gets its own query with sargable col = $k or col IS NULL; inactive filters are omitted. Above four list_for columns, only no-filter, single-filter, and all-filter combinations are specialized; other combos keep the COALESCE fallback arm.

Book docs for list_for_filters describe the new matrix and cap. Integration coverage (transfer entity + sargable_list_queries) paginates filter × sort × direction against a Rust reference and exercises NULL sort pagination.

^{Reviewed by Cursor Bugbot for commit 1086a35. Bugbot is set up for automated code reviews on this repo. Configure here.}

[bodymindarts]

Taking this PR over

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 4a5677c. Configure here.}