perf(executor): emit count(*) OVER() only when the count mode consumes it

[milmazz]

Summary

Every read query used to carry count(*) OVER() AS _bier_full_count, forcing PostgreSQL to materialize the entire filtered set through a WindowAgg before LIMIT could apply — even though only Prefer: count=exact|estimated ever consume that value (Response.render derives page rows from the body and nulls the total for count=none, and count=planned uses a separate EXPLAIN).

This branch threads the request's count mode into the SQL builders and emits the window only when it is consumed:

• Table reads (build/5): window iff count_mode in [:exact, :estimated]; otherwise full_count degrades to a cheap page-row count(*), preserving the frozen two-column [body, full_count] result contract.
• RPC reads (build_function/6): window iff count_mode != :none (RPC's count_for/2 consumes it for every non-none mode).
• Mutation representations (build_representation/4): never — only body is selected out of that subquery; the mutated-row count comes from the (SELECT count(*) FROM pgrst_source) sibling.

Why

The HTTP benchmark's R2 scenario (GET /items?category=eq.<cat>&order=id.desc&limit=25, 5k rows per category) was the only scenario where Bier lost to PostgREST (p50 2.44 ms vs 0.85 ms, 0.80x max throughput). EXPLAIN (ANALYZE) on the bench DB:

Shape	Plan	Execution
with window (before, count=none)	Bitmap Heap Scan 5,000 rows → Sort → WindowAgg → Limit	8.3 ms
without window (after, count=none)	Index Scan Backward on items_pkey, stops at 25 rows	0.095 ms

R1 (single row by PK) showed parity only because its filtered set is 1 row; writes never used this path — matching the benchmark report exactly. count=exact intentionally keeps the window (verified: WindowAgg present, 2.3 ms — unchanged behavior).

One observable output change (deliberate)

application/vnd.pgrst.plan responses now EXPLAIN the query shape the request's Prefer: count= mode would actually run (163262a, beyond the written plan): a plan request without Prefer: count= no longer shows a WindowAgg node, and one with count=exact does. Previously the endpoint always showed the windowed shape regardless of the request. Conformance cases 1625–1628 assert status/headers only and stay green; the new behavior is pinned by test/bier/plan_count_test.exs. All other HTTP behavior (bodies, statuses, Content-Range) is byte-identical.

Testing

• Full suite: 742 passed, 14 excluded, 0 failures (was 732 on main; +10 new tests in test/bier/query_executor_count_test.exs and test/bier/plan_count_test.exs). spec/** and test/support/** untouched.
• Gates: format --check-formatted, compile --warnings-as-errors, credo --strict, docs --warnings-as-errors all pass. hex.audit fails on pre-existing dependency advisories (plug 1.20.2, postgrex 0.22.2) — this branch does not touch deps.
• Live smoke against bier_bench: 25-row page correct and id-descending, Content-Range: 0-24/* without Prefer, 0-24/5000 with count=exact, unloaded p50 ≈ 1.4 ms (curl overhead dominated; the DB-side win is the EXPLAIN above).

The citable 3-round benchmark rerun (bench/http/run.sh, lives on the fix/bench-http-load-stability branch) is left to a follow-up after merge.

Follow-ups (deferred by final review, non-blocking)

• Bier.Plan.explain hardcodes the :json format arg, so plan-for-geojson EXPLAINs the JSON shape — pre-existing, worth its own issue.
• Two ~5-line coverage additions next time the count test file is touched: RPC :planned keeps the window; an embed-path mutation representation.

🤖 Generated with Claude Code

[milmazz]

Synced with main (083414a): merged 98dd0cd (geo+json broadening / byte-parity restructure of the advanced read path) and 60009e0 (JWT role-claim-key). Conflicts were confined to lib/bier/query_executor.ex; resolution notes:

• build_function is now arity 7 — both sides had added a 6th param (format on main, count_mode here); merged as (fn_def, ret_relation, args, plan, relations, format, count_mode \\\\ :none) with the RPC gate (full_count?: count_mode != :none) unchanged.
• build_representation/5 keeps main's opts (:format) and this branch's unconditional full_count?: false.
• The window-count gating was re-applied to main's new three-layer advanced shape (inner → paged → aggregate) via the same window_count_col/1 / full_count_col/1 helpers used by build_simple.

Re-verified after the merge: full suite 790 passed, 0 failures; mix precommit now green end-to-end (main's plug/postgrex bumps cleared the hex.audit advisories). Performance unaffected: R2 count=none EXPLAIN still plans a backward PK index scan with no WindowAgg (0.131 ms execution), count=exact intentionally keeps the window, and the live smoke shows p50 1.37 ms unloaded with byte-identical bodies and correct Content-Range in both modes.