fix(driver-sql): boolean aggregands answer the ruled #11249 contract — PG lowering cast + all-dialect min/max JSON-boolean presentation

[huangyiirene]

Fixes#11635

The ruling this implements

#11249 (maintainer 2026-08-23, comment 5386670755, verbatim and untranslated: 「10950 不考虑存量，其他接受你的建议」): min/max over a boolean aggregand answer false/true in JSON — order statistics return a member of the input domain, SQL drivers convert at the driver boundary; sum/avg answer arithmetic (3 / 0.5 on the 3-true/3-false fixture, the settled #11065 family shape). Cast, not refuse: a face that refuses cannot satisfy the ruled contract. This is declared = enforced restoration of an already-ruled contract, not a new capability.

Premise re-measured on current main (2a6122bd9d), before building

Both card measurements reproduced through SqlDriver.aggregate() on the live servers this container runs at CI parity (PG 16.13 timezone=Asia/Shanghai, MySQL 8.0.46 time_zone=+08:00, process TZ=America/New_York):

• PG: sum/avg/min/max over a declared boolean all threw DATABASE_ERROR/500 with cause.code=42883 (the post-driver-sql (PG): sum/avg/min/max over a boolean column throw the raw PostgreSQL 42883 with no ADR-0112 envelope (status undefined) #11455 envelope — driver-sql: an unresolvable WHERE column on aggregate() answers DATABASE_ERROR/500 where find() and count() answer INVALID_FILTER/400 — the #8790 refusal never reached the third read door #11541's classifier leaves this fault to the terminal arm).
• MySQL: min(flag) answered 0, max(flag) answered 1 (JS numbers) — the presentation gap the card asked to verify is REAL, so the MySQL half needed a fix, not just a measurement.

The change (2 seams in sql-driver.ts + tests)

1. PG lowering cast — in aggregate()'s statement builder: sum/avg/min/max over a field in booleanFields emit func(cast("col" as int)) on Postgres only. The column stays a knex identifier binding. count/count_distinct are deliberately not cast (both lower to count, defined over boolean everywhere; the acceptance keeps them unchanged). No new dialect predicate — the existing isPostgres getter selects the branch (read-coupling with driver-sql: the isSqlite/isPostgres/isMysql getters recognise fewer knex client spellings than knex accepts, so a valid client: 'postgres' silently loses every dialect-specific behaviour #11550 noted below; its getters were not edited).
2. All-dialect min/max boolean presentation — the min/max result-column tracking now presents a declared-boolean aggregand as 'boolean' on every dialect, not only under readPresentationKind's SQLite gate: MySQL's tinyint(1) and PG's casted int both answer 1/0 from the backend and leave the driver as JSON false/true. null (empty window) passes through untouched — min/max over no rows still answer null, matching emptyGroupValueFor.
3. Tests — new sql-driver-11635-boolean-aggregand-answers.test.ts pins the ruled answers on all three dialect cells (AGGREGATION_ROWS + a flag boolean column, 3 true / 3 false, declared type: 'boolean'; east group all-true so grouped min=true catches whole-table/sticky presentation). The driver-sql (PG): sum/avg/min/max over a boolean column throw the raw PostgreSQL 42883 with no ADR-0112 envelope (status undefined) #11455 suite's PG-only 42883 block is retired per its own retirement clause ("if [finding] AGGREGATION_ROWS has no boolean column, so the cross-driver aggregation conformance family cannot see a boolean aggregand on any face #11152/[Decision] min/max over a boolean aggregand: pin the cross-driver JSON answer — 0/1 (SQL) vs false/true (both in-memory faces) #11249 rule that the lowering should CAST, these cases stop failing and this block is RETIRED by that card") — the four 42883 pins, the fence case, and its log case are replaced by a tombstone naming the ruling; its count/count_distinct controls live on in the new suite; the all-dialect terminal-envelope sweep (missing table) is untouched. No pin was deleted to make room — the retirement is the honest update the ruling forces, and this paragraph is its declaration.

Acceptance numbers, measured through SqlDriver.aggregate()

	live PG 16.13	live MySQL 8.0.46	SQLite
sum(flag)	"3" (Number 3)	"3" (Number 3)	3
avg(flag)	"0.50000000000000000000" (Number 0.5)	"0.5000" (Number 0.5)	0.5
min(flag)	false (JSON boolean)	false	false
max(flag)	true (JSON boolean)	true	true
count(flag)	"6" — unchanged	6 — unchanged	6
count_distinct(flag)	"2" — unchanged	2 — unchanged	2

Contract surface (clause ②) — the answer set and its JSON types, named

• New answers on a public read door: sum/avg/min/max over a declared boolean on PG now ANSWER (previously DATABASE_ERROR/500 wrapping SQLSTATE 42883). No refusal is left behind on this route: the driver-sql (PG): sum/avg/min/max over a boolean column throw the raw PostgreSQL 42883 with no ADR-0112 envelope (status undefined) #11455 terminal envelope still owns every fault the driver-sql: an unresolvable WHERE column on aggregate() answers DATABASE_ERROR/500 where find() and count() answer INVALID_FILTER/400 — the #8790 refusal never reached the third read door #11541 classifier does not claim (missing table etc.), unchanged.
• JSON types: min/max → JSON booleans on every dialect (strictly pinned). sum/avg/count/count_distinct arrive as the dialect client's exact-numeric wire shape — node-pg and mysql2 hand bigint/DECIMAL/numeric back as STRINGS ("3", "0.5000"), for boolean and integer aggregands alike (the driver-sql (PG): sum/avg/min/max over a boolean column throw the raw PostgreSQL 42883 with no ADR-0112 envelope (status undefined) #11455 suite's control records the same convention). This PR deliberately does not touch that numeric convention: converting boolean sum/avg only would split boolean from integer aggregands on one dialect. The new suite pins the values through Number(...) and the booleans strictly.
• Typed change: min/max over a declared boolean on MySQL move from 0/1 (numbers) to false/true (booleans) — the ruled direction. The neighbouring row-read door (find()) still answers 1/0 on MySQL; filed as driver-sql (MySQL): find() answers 1/0 for a declared boolean field — the read coercion is gated to SQLite, so the storage form leaks on the row-read door #11782 (see below), not widened into this PR.

Verification

• New suite: 28/28 green across sqlite + live postgres + live mysql with OS_EXPECT_LIVE_DIALECT_MATRIX=1 (no cell skipped).
• Full @objectstack/driver-sql suite with both live servers: 133 files, 2696 passed | 1 skipped — verify-lock VERDICT command-exit 0. pnpm --filter @objectstack/driver-sql typecheck VERDICT command-exit 0.
• Reverse verification (fix committed first; mutation = git restore --source=2a6122bd9d of sql-driver.ts, confirmed on disk by marker greps — castBooleanAggregand count 0 and the pre-fix bare-lowering line back — with a trap ... EXIT INT TERM restore): predicted 9 failed / 19 passed with PG reds by THROW and MySQL reds on VALUES; measured exactly that — PG: 6 red, all DATABASE_ERROR 42883 (sum/avg/min/max/grouped/empty-window); MySQL: 3 red on values (expected +0 to be false, expected 1 to be true, grouped {lo:1,hi:1}); SQLite all green. Restore confirmed (marker count back to 2, git status clean). The suite imports the driver by relative path, so vitest reads src — no build stands between the mutation and the measurement.
• Gates at final head 05c95a7b85 (union re-run after the last commit): all derived + convention families green (exit 0 each): check:changeset-gate-self-tests, check:objectui-changeset, check:published-files, check:slot-lookup, check:test-source-alias, check:type-source-resolution, check:query-options-erasure, check:type-check-coverage, check:engine-double-contract, check:cross-package-test-inputs, check:where-matcher, check:nul-bytes, check-adr-0087-registration, check-changeset-no-major, check-empty-changeset, check-plugin-teardown-shape, check-affected-docs, release-rehearsal-clone --self-test, check:driver-conformance. Declared narrowing: check:type-check-debt's --re-measure half was not run locally (needs the full workspace build) — its population is the DEBT/TEST_DEBT ledgers in check-type-check-coverage.mjs, @objectstack/driver-sql is in none of them, driver-sql's own tsc program (src/**/*, tests included) covers every file this PR touches and exits 0, and the diff moves no export surface, so no ledgered package's program reads anything this PR changed; CI runs the full re-measure regardless.
• Driver-conformance lane numbers: before 45 covered / 0 DEBT / 0 exempt → after 45 covered / 0 DEBT / 0 exempt (unchanged — this card adds per-driver pins, not a new conformance case-set enrollment).

Sequencing

• Unblocks the PG leg of [finding] AGGREGATION_ROWS has no boolean column, so the cross-driver aggregation conformance family cannot see a boolean aggregand on any face #11152 (its Blocked-by: points at driver-sql: boolean aggregands need a lowering cast on PG (+ a MySQL min/max presentation check) — the ruled false/true + arithmetic answers are unproducible on the PG face #11635) — the conformance column there is the cross-driver acceptance evidence once this lands.
• Must land before [finding] sql-driver-aggregation-conformance.test.ts hard-codes better-sqlite3, so the aggregate-vocabulary standard never runs on Postgres — its pagination sibling already uses the live-dialect cells #11456's harness conversion runs the aggregation standard on live PG.
• The mongodb face is out of scope (driver-mongodb lowers avg / sum over a boolean column to null / 0 — the same cell as #11065, one driver over #11151, frozen under the [裁决] driver-memory / driver-mongodb 投入冻结 —— 维护者 2026-08-05 口径（跨单锚点） #5499 ruling) — driver-mongodb untouched.
• Read-coupling with driver-sql: the isSqlite/isPostgres/isMysql getters recognise fewer knex client spellings than knex accepts, so a valid client: 'postgres' silently loses every dialect-specific behaviour #11550: the PG branch is selected by isPostgres; that getter (and the other driver-sql: the isSqlite/isPostgres/isMysql getters recognise fewer knex client spellings than knex accepts, so a valid client: 'postgres' silently loses every dialect-specific behaviour #11550/driver-sql (MySQL): nothing sees the 65535-byte row budget, so a table with many wide declared bounds fails CREATE with an error naming no field #11565 regions) were not edited. Pins are written against client: 'pg' and stay green whichever lands first.

Out of scope, filed

• driver-sql (MySQL): find() answers 1/0 for a declared boolean field — the read coercion is gated to SQLite, so the storage form leaks on the row-read door #11782 — find() on MySQL answers 1/0 for a declared boolean field (the booleanFields read coercion is SQLite-gated on the row-read door); measured while taking this card's readings.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)), so this run has no opinion about the docs.

What this run could not see

• 1 name(s) were too generic to anchor anything (single lowercase words)

Coarse fallback — 9 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 8b41bcd85160ac1c475d26b2968d74f84954bbfa → packageMentionDocs.