fix(macros): direction-aware NULL fallback in cursor condition for nullable sort columns

[vindard]

Summary

CursorStruct::condition for is_optional() columns emits a fallback col IS NOT NULL that's correct for ASC NULLS FIRST but silently drops NULL rows on page 2+ of DESC NULLS LAST pagination. Flagged by Cursor Bugbot on a downstream PR (GaloyMoney/lana-bank#5898) where Desc is the default SortDirection in the public GraphQL — making the broken path the common one.

Root cause

The OR-clause's COALESCE fires whenever col <op> $cursor is NULL, which happens when either side is NULL. The fallback decides whether to include such rows — and the correct value depends on direction, which-side-is-NULL, and whether we're on page 1 vs. paginating from a NULL-row cursor.

For ASC NULLS FIRST the fallback col IS NOT NULL happens to cover all sub-cases because NULL sorts first: a non-NULL row is "after" both page-1 and cursor-on-NULL sentinels, while a NULL row with a non-NULL cursor was on page 1 already.

For DESC NULLS LAST the cases diverge:

Case	Cursor $col	Cursor $id	Row col	Expected	Old fallback	Verdict
Page 1	NULL	NULL	non-NULL	include (no cursor, everything is after)	FALSE	✗ BUG
Cursor non-NULL, row NULL	non-NULL	non-NULL	NULL	include (NULL sorts last in DESC)	FALSE	✗ BUG
Cursor NULL, row non-NULL	NULL	non-NULL	non-NULL	exclude (already shown before cursor)	TRUE	✗ BUG

Fix

Direction-aware fallback:

• ASC: col IS NOT NULL (unchanged).
• DESC: $id_cursor IS NULL OR (col IS NULL AND $cursor IS NOT NULL).

The first disjunct of the DESC fallback short-circuits page 1 to TRUE (no cursor → include everything). The second covers the "row is NULL after a non-NULL cursor" case. Both correctly evaluate to FALSE when the cursor sits on a NULL row and the row is non-NULL (already shown), or when both are NULL (handled by AND-clause's IS NOT DISTINCT FROM).

Truth-table verification (DESC NULLS LAST, post-fix)

$cursor	$id_cursor	Row col	Row id vs $id	AND	OR fallback	Final	Expected
NULL	NULL	non-NULL	any	F	T ($id IS NULL short-circuit)	T	T ✓ (page 1)
NULL	NULL	NULL	any	T	—	T	T ✓ (page 1)
non-NULL	non-NULL	non-NULL < $c	any	F	T (< definite)	T	T ✓
non-NULL	non-NULL	non-NULL = $c	id < $id	T	—	T	T ✓
non-NULL	non-NULL	non-NULL = $c	id ≥ $id	F	F (< definite)	F	F ✓
non-NULL	non-NULL	non-NULL > $c	any	F	F (< definite)	F	F ✓
non-NULL	non-NULL	NULL	any	F	T (NULL IS NULL AND $c IS NOT NULL)	T	T ✓
NULL	non-NULL	non-NULL	any	F	F (both disjuncts F)	F	F ✓
NULL	non-NULL	NULL	id < $id	T	—	T	T ✓
NULL	non-NULL	NULL	id ≥ $id	F	F (same)	F	F ✓

ASC NULLS FIRST is unchanged — col IS NOT NULL already satisfies the analogous truth table for ASC.

Single point of change

condition() is shared by list_by, list_for, and list_for_filters macros (referenced from list_for_fn.rs:102,115 and list_for_filters_fn.rs:314,328). One fix propagates to all three.

Test plan

• Updated SQL-string assertion in list_by_fn.rs for the DESC NULLS LAST case.
• All 82 macro tests pass.
• Runtime regression verification lives in the consuming repo (GaloyMoney/lana-bank#5898's core/credit/tests/loan_to_collateral_ratio_pagination.rs); the DESC half becomes reachable from there after this lands and es-entity is bumped.

🤖 Generated with Claude Code