fix(driver-sql): present declared booleans as JSON booleans on MySQL row reads (#11782 scope: find/distinct/group keys) (#12019)

formatOutput's boolean read coercion and readPresentationKind's boolean arm
were gated isSqlite-only, so a declared boolean answered 1/0 on MySQL
(tinyint(1) via mysql2) through find(), distinct() and aggregate group keys
while SQLite and Postgres answered true/false — and after #11635 the
aggregate door and the row-read door gave opposite answers on the same MySQL
connection. The boolean presentation now runs on the two dialects whose
stored boolean is a number; Postgres stays ungated (native boolean).

Measured live before/after on MySQL 8.0.46, PG 16.13 and embedded SQLite.
Pinned by a cross-door agreement suite over the live dialect matrix.


Claude-Session: https://claude.ai/code/session_01W6HFzyH98W1YaQXhJUJt6o

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-warren

.changeset/mysql-boolean-row-read-presentation.md

@@ -0,0 +1,22 @@
+---
+"@objectstack/driver-sql": patch
+---
+
+fix(driver-sql): a declared `Field.boolean` answers JSON booleans on MySQL's row-read doors (#11782)
+
+`formatOutput`'s boolean read coercion — and its per-column mirror
+`readPresentationKind`, which `distinct()` and the aggregate group-key /
+`min`/`max` tracking consume — was gated `isSqlite`-only. On MySQL the storage
+is `tinyint(1)` and mysql2 hands back a JS number, so a declared boolean
+answered `1`/`0` through `find()`, `distinct()` and aggregate group keys while
+SQLite and Postgres answered `true`/`false` — and, after #11635 presented
+aggregate `min`/`max` on every dialect, `max(flag) === true` and
+`row.flag === 1` disagreed on the same column over the same MySQL connection.
+
+Measured on live MySQL 8.0.46 before the fix: `find().flag` → `1` (`typeof
+number`), `distinct('flag')` → `[0, 1]`, aggregate group keys → `1`/`0`. The
+boolean presentation now runs on the two dialects whose stored boolean is a
+number (SQLite `INTEGER` 0/1, MySQL `tinyint(1)`); Postgres stores a real
+`boolean` node-pg already parses, so it deliberately stays outside the gate and
+its answers are byte-identical. A `NULL` boolean stays `null` on every door
+(absence is not `false`), and declared `number`/`string` columns are untouched.

packages/drivers/driver-sql/src/sql-driver-11782-boolean-row-read-presentation.test.ts

@@ -0,0 +1,190 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#11782] A declared `Field.boolean` answers JSON booleans on EVERY read door,
+ * on every dialect this driver speaks — one column, one answer set, whichever
+ * door it is read through.
+ *
+ * ## The measured gap this suite exists to keep closed
+ *
+ * Measured 2026-08-25 on live MySQL 8.0.46 through the driver boundary, on
+ * `main` @ `d63b014360`, before the fix (the same instrument as the card:
+ * `driver.create(...)` + the read doors, over `flag` declared
+ * `type: 'boolean'`, stored as `tinyint(1)`):
+ *
+ * - `find().flag`                → `1` / `0`   (`typeof number`)
+ * - `distinct('flag')`           → `[0, 1]`    (`typeof number`)
+ * - `aggregate` groupBy(`flag`)  → keys `1`/`0` (`typeof number`)
+ * - `aggregate` `min`/`max`      → `false`/`true` (correct since #11635/#11785)
+ *
+ * while SQLite and Postgres answered `true`/`false` on all four. The boolean
+ * read coercion in `formatOutput` — and its per-column mirror
+ * `readPresentationKind`, which `distinct()` and the aggregate group-key /
+ * `min`/`max` tracking consume — was gated `isSqlite`-only, so MySQL's storage
+ * form leaked. Worse than a one-dialect leak: after #11635 presented the
+ * aggregate door everywhere, `max(flag)` answered `true` while `find()` on the
+ * SAME column over the SAME connection answered `1` — two doors, opposite
+ * answers, in one request cycle. The fix runs the boolean presentation on the
+ * two dialects whose stored boolean is a number (SQLite INTEGER 0/1, MySQL
+ * `tinyint(1)`); Postgres stores a real `boolean` node-pg parses, so its
+ * stored form already IS the presented form and it stays ungated.
+ *
+ * ## Assertion conventions
+ *
+ * Booleans are asserted STRICTLY (`toBe(true)` / `toBe(false)`, `toEqual` on
+ * exact values): the before-state is a WRONG VALUE, not an absence — `1` is
+ * truthy, so a `toBeTruthy()` pin would have passed on the defect this suite
+ * went red on. The cross-door test asserts the doors against EACH OTHER on the
+ * same column (per the triage note on the card: a one-door pin passes on an
+ * implementation where the doors still disagree).
+ *
+ * ## Controls
+ *
+ * A declared `number` and a declared `string` column ride the same fixture and
+ * must come back untouched — the presentation is per declared-boolean column,
+ * never per row. A NULL boolean stays `null` on every door: absence is not
+ * `false`, and `Boolean(null)` would manufacture one.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import type { DriverQuery } from '@objectstack/spec/contracts';
+import { SqlDriver } from './sql-driver.js';
+import { DIALECT_CELLS, declareDialectCell, type DialectCell } from './live-dialect-matrix.testkit.js';
+
+const TABLE = 'bool_row_read_presentation';
+
+/** 1 true / 2 false / 1 null — asymmetric so a sticky constant shows. */
+const ROWS = [
+  { label: 'a', flag: true, score: 10 },
+  { label: 'b', flag: false, score: 20 },
+  { label: 'c', flag: false, score: 30 },
+  { label: 'd', flag: null, score: 40 },
+] as const;
+
+function declarePresentation(cell: DialectCell): void {
+describe(`[#11782] driver-sql — boolean row reads answer JSON booleans (${cell.label})`, () => {
+  let driver: SqlDriver;
+
+  beforeAll(async () => {
+    driver = new SqlDriver(cell.config());
+    await driver.execute(`drop table if exists ${TABLE}`).catch(() => {});
+    await driver.initObjects([
+      {
+        name: TABLE,
+        fields: {
+          label: { type: 'string' },
+          flag: { type: 'boolean' },
+          score: { type: 'number' },
+        },
+      },
+    ]);
+    for (const row of ROWS) {
+      await driver.create(TABLE, { ...row }, { bypassTenantAudit: true });
+    }
+  });
+
+  afterAll(async () => {
+    await driver.execute(`drop table if exists ${TABLE}`).catch(() => {});
+    await driver.disconnect();
+  });
+
+  // The fixture read back rather than trusted: four rows under their labels —
+  // a seed that dropped or folded a row would turn every assertion below into
+  // a test of the wrong table.
+  it('the fixture is four rows: T, F, F, NULL', async () => {
+    const rows = (await driver.find(TABLE, {})) as Array<{ label: string }>;
+    expect(rows.map((r) => r.label).sort()).toEqual(['a', 'b', 'c', 'd']);
+  });
+
+  // ─── The row-read door (`find()`) — the card's own surface ───────────────
+
+  it('find() answers the JSON boolean true — not 1', async () => {
+    const rows = (await driver.find(TABLE, { where: { label: 'a' } } as DriverQuery)) as any[];
+    expect(rows).toHaveLength(1);
+    // STRICT: `1` — the exact value this suite went red on — is truthy.
+    expect(rows[0].flag).toBe(true);
+  });
+
+  it('find() answers the JSON boolean false — not 0', async () => {
+    const rows = (await driver.find(TABLE, { where: { label: 'b' } } as DriverQuery)) as any[];
+    expect(rows).toHaveLength(1);
+    expect(rows[0].flag).toBe(false);
+  });
+
+  it('find() passes a NULL boolean through — absence is not false', async () => {
+    const rows = (await driver.find(TABLE, { where: { label: 'd' } } as DriverQuery)) as any[];
+    expect(rows).toHaveLength(1);
+    expect(rows[0].flag).toBeNull();
+  });
+
+  it('CONTROL find() leaves declared number and string columns untouched', async () => {
+    const rows = (await driver.find(TABLE, { where: { label: 'a' } } as DriverQuery)) as any[];
+    expect(rows[0].score).toBe(10);
+    expect(rows[0].label).toBe('a');
+  });
+
+  // ─── The values door (`distinct()`) — measured here, shares the gate ─────
+
+  it('distinct(flag) answers JSON booleans — not 0/1', async () => {
+    const values = await driver.distinct(TABLE, 'flag');
+    // Set-compare: order is the dialect's; membership is the contract.
+    // `toEqual` does not coerce, so a `Set {0, 1, null}` fails here.
+    expect(new Set(values)).toEqual(new Set([true, false, null]));
+  });
+
+  it('CONTROL distinct(score) still answers numbers', async () => {
+    const values = await driver.distinct(TABLE, 'score');
+    expect(new Set(values)).toEqual(new Set([10, 20, 30, 40]));
+  });
+
+  // ─── Cross-door agreement — the assertion the triage note asked for ──────
+
+  it('find(), distinct() and aggregate() answer the SAME JSON booleans for the same column', async () => {
+    const found = new Set(
+      ((await driver.find(TABLE, {})) as any[]).map((r) => r.flag),
+    );
+    const listed = new Set(await driver.distinct(TABLE, 'flag'));
+    const grouped = (await driver.aggregate(TABLE, {
+      groupBy: ['flag'],
+      aggregations: [{ function: 'count', field: 'score', alias: 'n' }],
+    } as DriverQuery)) as any[];
+    const groupKeys = new Set(grouped.map((g) => g.flag));
+    const agg = (await driver.aggregate(TABLE, {
+      aggregations: [
+        { function: 'min', field: 'flag', alias: 'lo' },
+        { function: 'max', field: 'flag', alias: 'hi' },
+      ],
+    } as DriverQuery)) as any[];
+
+    const domain = new Set([true, false, null]);
+    expect(found, 'find()').toEqual(domain);
+    expect(listed, 'distinct()').toEqual(domain);
+    expect(groupKeys, 'aggregate group keys').toEqual(domain);
+    expect(agg[0].lo, 'min(flag)').toBe(false);
+    expect(agg[0].hi, 'max(flag)').toBe(true);
+  });
+
+  it('aggregate group keys carry per-group counts under the presented key', async () => {
+    const grouped = (await driver.aggregate(TABLE, {
+      groupBy: ['flag'],
+      aggregations: [{ function: 'count', field: 'score', alias: 'n' }],
+    } as DriverQuery)) as any[];
+    const byKey = new Map(grouped.map((g) => [g.flag, Number(g.n)]));
+    expect(byKey.get(true), 'count under key true').toBe(1);
+    expect(byKey.get(false), 'count under key false').toBe(2);
+    expect(byKey.get(null), 'count under key null').toBe(1);
+  });
+});
+}
+
+// A matrix that silently finds zero cells reports OK — assert the axis is real
+// before iterating it (the #11455 suite's own guard, kept in force here).
+describe('[#11782] the dialect axis this suite runs', () => {
+  it('runs every dialect this driver speaks', () => {
+    expect(DIALECT_CELLS.map((c) => c.id)).toEqual(['sqlite', 'pg', 'mysql']);
+  });
+});
+
+for (const cell of DIALECT_CELLS) {
+  declareDialectCell(cell, 'boolean row-read presentation', declarePresentation);
+}

packages/drivers/driver-sql/src/sql-driver.ts

@@ -7987,13 +7987,15 @@ export class SqlDriver implements IDataDriver {
           // only, so it is deliberately not tracked.
           if ((funcName === 'min' || funcName === 'max') && agg.field) {
             // [#11249/#11635] A boolean aggregand presents on EVERY dialect,
-            // not only under `readPresentationKind`'s SQLite gate. That gate
-            // mirrors `formatOutput`'s ROW reads, where the native dialects
-            // hand storage back as-is — but on this door the backend answers
-            // `min`/`max` as 1/0 on MySQL (`tinyint(1)`) and on Postgres (the
-            // `cast(?? as int)` above), and the ruled contract is `false` /
-            // `true` in JSON: order statistics return a member of the input
-            // domain, and SQL drivers convert at the driver boundary.
+            // not only under `readPresentationKind`'s dialect gate. That gate
+            // mirrors `formatOutput`'s ROW reads (SQLite + MySQL since #11782;
+            // SQLite-only when this landed), where the storage-form dialects
+            // hand back a number — but on this door the backend ALSO answers
+            // `min`/`max` as 1/0 on Postgres (the `cast(?? as int)` above,
+            // over a column whose row reads need no presentation), and the
+            // ruled contract is `false` / `true` in JSON: order statistics
+            // return a member of the input domain, and SQL drivers convert at
+            // the driver boundary. The `??` fallback is what carries Postgres.
             // `presentReadValue('boolean', …)` leaves `null` (no rows / all
             // NULL) untouched and is idempotent on a value already boolean.
             const kind =
@@ -11590,9 +11592,13 @@ export class SqlDriver implements IDataDriver {
    * row, asked one field at a time so the paths that return raw builder output
    * can ask it too. `null` means the stored form already IS the presented form.
    *
-   * The boolean / numeric rules are SQLite-only because `formatOutput` gates
-   * them that way: SQLite is the dialect without a native boolean, and the
-   * numeric repair only exists for legacy TEXT-affinity columns.
+   * The boolean rule runs on SQLite AND MySQL — the two dialects that store a
+   * declared boolean as a number (INTEGER 0/1, `tinyint(1)`) — because
+   * `formatOutput` gates its row reads that way (#11782; SQLite-only before,
+   * which is how a declared boolean answered `1`/`0` on MySQL). Postgres
+   * stores a real `boolean` node-pg parses, so there the stored form already
+   * IS the presented form. The numeric repair stays SQLite-only: it exists
+   * for legacy TEXT-affinity columns, which no other dialect has.
    */
   protected readPresentationKind(
     table: string | null | undefined,
@@ -11601,8 +11607,10 @@ export class SqlDriver implements IDataDriver {
     if (!table) return null;
     const temporal = this.temporalFieldKind(table, field);
     if (temporal) return temporal;
+    if ((this.isSqlite || this.isMysql) && this.booleanFields[table]?.includes(field)) {
+      return 'boolean';
+    }
     if (!this.isSqlite) return null;
-    if (this.booleanFields[table]?.includes(field)) return 'boolean';
     if (this.numericFields[table]?.includes(field)) return 'number';
     return null;
   }
@@ -11613,10 +11621,11 @@ export class SqlDriver implements IDataDriver {
    * (`aggregate`, `distinct` — #3797 for instants, #3849 for scalars).
    *
    * The dialect gating mirrors `formatOutput`: the `Field.datetime` repair and
-   * the boolean / numeric coercions are SQLite-only (it is the one dialect where
-   * storage ≠ presentation), while the `Field.date` → `YYYY-MM-DD` collapse runs
-   * everywhere. {@link readPresentationKind} does the SQLite gating for the
-   * scalar kinds, so by the time one arrives here the dialect is settled.
+   * the numeric coercion are SQLite-only, the boolean coercion runs on SQLite
+   * and MySQL (#11782 — the two dialects whose stored boolean is a number),
+   * and the `Field.date` → `YYYY-MM-DD` collapse runs everywhere.
+   * {@link readPresentationKind} does the dialect gating for the scalar kinds,
+   * so by the time one arrives here the dialect is settled.
    */
   protected presentReadValue(kind: ReadPresentationKind, value: any): any {
     if (value == null) return value;
@@ -14371,15 +14380,6 @@ export class SqlDriver implements IDataDriver {
         }
       }
 
-      const booleanFields = this.booleanFields[object];
-      if (booleanFields && booleanFields.length > 0) {
-        for (const field of booleanFields) {
-          if (data[field] !== undefined && data[field] !== null) {
-            data[field] = Boolean(data[field]);
-          }
-        }
-      }
-
       // Numeric scalars stored on a legacy TEXT-affinity column come back as
       // strings ('4'); coerce numeric-looking strings back to numbers so the
       // declared type wins regardless of when the column was created. Only
@@ -14427,6 +14427,29 @@ export class SqlDriver implements IDataDriver {
       }
     }
 
+    // [#11782] Present a declared `Field.boolean` as a JSON boolean on the
+    // dialects whose STORAGE form is a number: SQLite (INTEGER 0/1) and MySQL
+    // (`tinyint(1)`, which mysql2 hands back as a JS number). Postgres stores a
+    // real `boolean` and node-pg already parses it, so its stored form IS the
+    // presented form and it deliberately stays outside the gate — the same
+    // per-dialect posture {@link readPresentationKind} takes for the read doors
+    // that return raw builder output (`distinct`; `aggregate` tracks its own
+    // result columns per #11635). Before this, the gate was SQLite-only and a
+    // declared boolean answered `1`/`0` on MySQL's row-read door while
+    // answering `true`/`false` on the other two dialects — and, once #11635
+    // presented `min`/`max` everywhere, `find()` and `aggregate()` gave
+    // OPPOSITE answers for the same column on the same MySQL connection.
+    if (this.isSqlite || this.isMysql) {
+      const booleanFields = this.booleanFields[object];
+      if (booleanFields && booleanFields.length > 0) {
+        for (const field of booleanFields) {
+          if (data[field] !== undefined && data[field] !== null) {
+            data[field] = Boolean(data[field]);
+          }
+        }
+      }
+    }
+
     // ADR-0053 Phase 1: present `Field.date` as a timezone-naive `YYYY-MM-DD`
     // string, slicing any stored time component. This transparently repairs
     // legacy rows written as a full timestamp before this normalization, so