Linked issue

Fixes #29932

Summary

OrderByOptions accepted nulls: 'first' | 'last' but the value never reached the database — resolveOrderBy dropped it, OrderByItem had no slot for it, and neither adapter rendered NULLS FIRST/LAST, so queries silently sorted with the dialect-default NULL ordering. This threads the placement through the whole path (AST → builder → ORM plan builders → both renderers) and closes the two ways it could silently degrade: the ORM's distinct-include lowerings now remap order items through one nulls-preserving helper, and cursor pagination rejects nulls placement with ORM.CURSOR_ORDER_NULLS_UNSUPPORTED (keyset >/< predicates cannot express NULL boundaries) instead of silently dropping NULL-keyed rows. The ORM surface gains the option too: .orderBy((u) => u.name.asc('first')).

Testing performed

• pnpm typecheck && pnpm lint && pnpm test:packages
• pnpm test:integration and pnpm test:e2e (change touches the SQL runtime)
• pnpm lint:deps, pnpm fixtures:check, pnpm check:error-reference
• All new tests written red-first: AST invariants (rewrite preserves, reverse flips placement), builder threading, ORM plan shapes for both distinct-include paths and the scalar-distinct path, cursor rejection, and exact-SQL assertions in both adapter suites (select-level and window ORDER BY)
• Verified empirically that SQLite accepts NULLS FIRST/LAST in select-level, in-aggregate, and window ORDER BY (needs >= 3.30; the adapter already documents a 3.35 floor for RETURNING)
• Note: 5 tarball-packing test files fail locally because the public registry lacks the pinned @types/pg@8.20.4; they fail identically on a clean checkout of main and are unrelated to this change

Skill update

• skills/prisma-8/references/queries-postgres.md: documented the optional NULL placement on .asc()/.desc() and the cursor-pagination restriction
• docs/reference/error-reference.md: added the ORM.CURSOR_ORDER_NULLS_UNSUPPORTED entry (required by check:error-reference)

Checklist

• All commits are signed off (git commit -s) per the DCO
• I read CONTRIBUTING.md and the change is scoped to one logical concern
• Tests are updated
• Title uses the conventional-commit form per CONTRIBUTING.md (external contribution — no Linear ticket)
• Skill update section filled in

Notes for the reviewer

• Deliberately no sql.orderByNulls capability key. Both shipped targets support the syntax natively, so a gate would be unfalsifiable today, and minting a capability (catalogue row + both adapters' capability records, which feed profileHash) felt like a maintainer-owned decision. Happy to add it in this PR or a follow-up if you would rather gate now for future MySQL/MariaDB targets.
• Cursor + nulls is a hard rejection, not support. NULL-aware keyset predicates (IS NULL branches in the lexicographic WHERE) are possible future work; rejecting seemed safer than silently wrong pages.
• OrderByItem.reverse() flips an explicit placement along with direction (reversing a scan reverses where NULLs sit); unset stays unset since dialect defaults already invert with direction.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added support for specifying NULLS FIRST or NULLS LAST when sorting query results.
  • Null placement is preserved across standard, aggregate, distinct, and window-function ordering.
  • PostgreSQL and SQLite queries now render explicit null-ordering preferences correctly.

• Bug Fixes

  • Cursor pagination now clearly rejects unsupported null-ordering combinations with a documented error.

• Documentation

  • Updated sorting and error references with null-ordering behavior and cursor pagination limitations.