fix(driver-sql): declared booleans answer JSON booleans on MySQL's row-read doors (find/distinct/group keys)

[os-warren]

Fixes#11782

What this changes

formatOutput's boolean read coercion and readPresentationKind's boolean arm were gated isSqlite-only, so a declared Field.boolean leaked its storage form on MySQL: tinyint(1) reaches mysql2 as a JS number, and nothing downstream converted. The boolean presentation now runs on the two dialects whose stored boolean is a number — SQLite (INTEGER 0/1) and MySQL (tinyint(1)). Postgres stores a real boolean that node-pg parses, so its stored form already IS the presented form and it deliberately stays outside the gate: its answers are byte-identical before and after.

Contract surface — answer set per door, per dialect (dispatched at tier; stated explicitly)

Measured live before (main @ d63b014360) and after (this branch), on MySQL 8.0.46, PostgreSQL 16.13, embedded SQLite, through the driver boundary (driver.create(...) + each read door — the card's own instrument):

Door	sqlite before → after	pg before → after	mysql before → after
find() row value	true/false → unchanged	true/false → unchanged	1/0 (number) → true/false (boolean)
distinct() values	[true,false] → unchanged	[true,false] → unchanged	[0,1] (number) → [true,false] (boolean)
aggregate() group keys	true/false → unchanged	true/false → unchanged	1/0 (number) → true/false (boolean)
aggregate()min/max	false/true → unchanged	false/true → unchanged	false/true → unchanged (#11635 already presented this door; it now short-circuits on readPresentationKind instead of the call-site fallback — same answers)
NULL boolean, every door	null → unchanged	null → unchanged	null → unchanged (absence is not false)
Controls: declared number / string columns, every door	unchanged	unchanged	unchanged

The aggregate min/max row is the cross-door disagreement this card exists to close: since #11635, max(flag) answered true on MySQL while find() on the same column over the same connection answered 1. The group-key cells are the same gate consumed through the groupBy tracking sites — before this fix MySQL was also the one dialect whose group keys disagreed with SQLite/Postgres. distinct() was recorded on the card as UNMEASURED; it is measured here (before: [0,1] on MySQL) and decided alongside find(), through the shared gate.

Scope fence honoured: aggregate()'s lowering and its #11635 call-site fallback are behaviourally untouched (one comment updated to stay accurate). The fallback is NOT dead code after this change — it is what carries Postgres, where cast(?? as int) makes the backend answer 1/0 while row reads need no presentation.

Regions (declared by symbol — serial constraint vs #11876)

• formatOutput — the booleanFields read coercion, moved out of the SQLite-only block behind an isSqlite || isMysql gate.
• readPresentationKind — the boolean arm now applies on SQLite and MySQL; the numeric arm stays SQLite-only (it exists for legacy TEXT-affinity columns, which only SQLite has).
• The distinct() seam consumes the re-gated readPresentationKind; no code in distinct() itself changed.
• Comment-only accuracy updates in presentReadValue's doc and at the 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 aggregate min/max tracking site (its prose described a "SQLite gate" that no longer exists as stated; no behaviour touched).

Disjoint from #11876's regions (createColumn / varchar width mirror). origin/main merged before opening this PR (merge commit 0091979a8e); no upstream driver-sql movement between base and merge (path-filtered log empty). A mariadb client spelling stays outside MYSQL_EMIT_CLIENTS and therefore outside this gate — that is the standing #11756 support-scope decision, not this card's.

Evidence

• Pin: sql-driver-11782-boolean-row-read-presentation.test.ts — 9 tests per dialect cell over the live matrix + the axis guard (28 total). Asserts cross-door agreement on the same column (find + distinct + group keys + min/max), per the triage note — a one-door pin passes on an implementation where the doors still disagree. Booleans asserted strictly (toBe(true); 1 is truthy and would pass a toBeTruthy pin). Negative controls: declared number/string columns and NULL passthrough.
• Ablation (fix reverted to the SQLite-only gate, from the committed state): direction predicted in advance per cell — sqlite 9 green, pg 9 green, mysql 5 red / 4 green with named failure modes. Observed exactly that: 23 pass / 5 fail, all five in the live mysql cell (expected 1 to be true // Object.is equality; Set{1, null, +0} ≠ Set{true, false, null}; group count under key true undefined). Mutation proven on disk before any result was read (anchored greps: union-gate spelling 2→0, #11782 tags 4→0), restore under trap … EXIT INT TERM, post-restore anchors 2/4 and clean git status --porcelain. No build leg owed: the suite imports ./sql-driver.js relative from src, so the subject never resolves through a dependency exports map — no dist is involved in the measurement.
• Full package suite at 0091979a8e under CI-parity skew (PG Asia/Shanghai, MySQL +08:00, process America/New_York, OS_EXPECT_LIVE_DIALECT_MATRIX=1, both live servers attached): 138 files, 2778 passed, 1 skipped, 0 failed.
• Downstream live-MySQL consumers (@objectstack/metadata-protocol migration suites): 10/10 green.
• Driver-conformance census before (BASE tree) and after: identical — 5 drivers × 9 case-sets, 45 covered cells, 0 debt, 0 exempt.
• Typecheck: pnpm --filter @objectstack/driver-sql typecheck green at 0091979a8e (script echo verified).
• Gate union derived (node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack; the script derives the changeset itself from the merge-base; its stderr attribution line names this repo at this checkout): 14 path-matched + 6 convention-triggered (new test file) + check:nul-bytes. All 21 ran at 0091979a8e (this PR's head), every exit captured before any pipe, all EXIT=0. Verdict lines from the gates' own output include: check-driver-conformance: OK — 45 covered cell(s), 0 in the DEBT ledger, 0 exempt; check-type-check-coverage --re-measure: OK — 32 ledger entr(ies) re-measured in 346.6s, 1898 raw tsc error(s) total, none above its recorded number (the debt gate, run on the freshly built ./packages/* closure); check-engine-double-contract: OK — 405 pinned, 133 in the DEBT ledger, 2 exempt; where-matcher conformance holds: 297 matcher(s) discovered, 297 answer the combinator battery correctly or refuse it loudly; check-nul-bytes: OK (scanned 6664 text file(s) … no raw ASCII control bytes); OK: 16 package(s) read outside themselves, all declared (cross-package-test-inputs); query-options-erasure ratchet holds: 67 unswept non-test site(s) in 17 file(s), none new.
• ESLint (repo scan is CI's; declared narrowing with its three-part proof): the diff's lintable population is exactly the two .ts files — the changeset .md returns eslint's own "File ignored because no matching configuration was supplied"; --format json counts 2 files linted, 0 errors, 0 warnings; and this repo's eslint.config.mjs states in its own docblock that type-aware linting is never enabled for any file, so a diff cannot move an untouched file's lint verdict.
• Upstream re-checked after the union ran: origin/main gained 3 commits past this branch's merge point (spec maxLength, release CI, a showcase test) — none touch packages/drivers/driver-sql/ or any file in this diff, and fix(driver-sql): richtext and code take an unbounded TEXT column, restoring the declared Rich Content grouping #11876 has not landed, so the serial trigger ("merge again if fix(driver-sql): richtext and code take an unbounded TEXT column, restoring the declared Rich Content grouping #11876 lands first") has not fired. The full package suite and typecheck above were re-run at 0091979a8e after that check.

Changeset

@objectstack/driver-sql patch — user-visible presentation change on MySQL row-read doors.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/driver-sql, touching 3 documentable anchor(s).

6 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/data-modeling/drivers.mdx(via SqlDriver (symbol))
• content/docs/data-modeling/index.mdx(via SqlDriver (symbol))
• content/docs/plugins/packages.mdx(via SqlDriver (symbol))
• content/docs/protocol/kernel/index.mdx(via SqlDriver (symbol))
• content/docs/protocol/kernel/lifecycle.mdx(via SqlDriver (symbol))
• content/docs/protocol/objectql/query-syntax.mdx(via SqlDriver (symbol))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17.mdx(via SqlDriver (symbol))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 45 of 222 client-bound route-ledger rows — the other 177 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

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 1620c1de2805ade35890c38470a57c9b4fe3eb70 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 8ee4089e093ff330c08154fc8f37c84a27f629a7 — the merge of head 0091979a8e7dc90f15de8d27d222bec854e38d03 into base 1620c1de2805ade35890c38470a57c9b4fe3eb70, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 8ee4089e093ff330c08154fc8f37c84a27f629a7 && git checkout 8ee4089e093ff330c08154fc8f37c84a27f629a7
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 1620c1de2805ade35890c38470a57c9b4fe3eb70 0091979a8e7dc90f15de8d27d222bec854e38d03 && git checkout -B drift-repro 1620c1de2805ade35890c38470a57c9b4fe3eb70 && git merge --no-ff 0091979a8e7dc90f15de8d27d222bec854e38d03
node scripts/docs-audit/affected-docs.mjs --json 1620c1de2805ade35890c38470a57c9b4fe3eb70

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 1620c1de2805ade35890c38470a57c9b4fe3eb70 → pass the list as
args.docs, on the commit named under Which tree this was computed on.