feat(verify): checkDateBucketParity — pin the seam between pushed-down and in-memory date bucketing (#3813)

A driver that advertises `supports.queryDateGranularity[g]` is telling
`engine.aggregate` it may push that granularity down as SQL instead of fetching
rows and bucketing them in JS. The two are then not two features but one feature
with two implementations, and the engine picks between them per query — a
granularity the driver advertises goes down as SQL, one it does not goes to
`applyInMemoryAggregation`, and a non-UTC timezone forces the in-memory path
regardless. A dashboard can cross that seam mid-drill-down.

Nothing checked that they agree. That is how #3773 shipped: every gate was green
while a trend chart collapsed into one bar, because the driver's own bucket
suites build fixtures with `knex.schema.createTable` + `t.string(...)` — ISO
TEXT, the half `strftime` parses natively — and the engine never second-guesses
a granularity a driver claims to support.

`checkDateBucketParity(driver)` compares the driver's pushed-down result against
the REAL `applyInMemoryAggregation` over the driver's own `find()` rows, for
every granularity it advertises, across both temporal storage forms under one
object (`Field.datetime` and `Field.date` naming the same calendar days) so a
storage-form leak surfaces as the two columns bucketing differently. A
granularity the driver does not advertise is skipped, never faulted.

Follows `checkReadCoercion`: human-readable problems (empty = conformant), no
test-runner dependency, driver taken structurally — so cloud's driver-turso,
remote SQLite with exactly the epoch storage that broke here, can run the
identical contract against itself.

Verified against the real regression, not just fakes: reverting the #3773 fix
turns the gate red on BOTH drivers with a diagnostic naming the collapsed bucket
(`null: sql=7 in-memory=—`), and the cross-column pass fires alongside it while
the TEXT-stored date column correctly stays quiet. Four negative controls pin
what the checker can detect, including a driver that advertises a granularity it
then throws on, and one that advertises nothing (must stay silent).

The three hand copies of `bucketDateValue` now state what their `⚠️ Keep in
sync` comments cannot enforce — a copy that stops tracking its original leaves
the copy and the SQL agreeing with each other while both are wrong — and point
at the executable check. The same pointer is on `bucketDateValue` itself, where
an edit would start the drift.

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/date-bucket-parity-gate.md

@@ -0,0 +1,48 @@
+---
+"@objectstack/verify": minor
+---
+
+feat(verify): `checkDateBucketParity` — pin the seam between pushed-down and in-memory date bucketing
+
+A driver that advertises `supports.queryDateGranularity[g]` is telling
+`engine.aggregate` it may push `dateGranularity: g` down as SQL instead of
+fetching rows and bucketing them in JS. The two are then not two features but
+one feature with two implementations, and the engine picks between them per
+query — a granularity the driver advertises goes down as SQL, one it does not
+goes to `applyInMemoryAggregation`, and a non-UTC timezone forces the in-memory
+path regardless. A dashboard can cross that seam mid-drill-down.
+
+Nothing checked that they agree. That is how #3773 shipped: SQLite stores a
+`Field.datetime` as INTEGER epoch milliseconds, `strftime` read the bare integer
+as a Julian day number, and every row bucketed as NULL — a trend chart collapsed
+into a single bar while every gate stayed green. The driver's own bucket suites
+build their fixtures with `knex.schema.createTable` + `t.string(...)`, which is
+ISO TEXT — the half `strftime` parses natively — and the engine never
+second-guesses a granularity a driver claims to support.
+
+`checkDateBucketParity(driver)` rounds a fixture through the driver and, for
+every granularity it advertises, compares its pushed-down result against the
+REAL `applyInMemoryAggregation` over the driver's own `find()` rows. Both
+temporal storage forms are probed under one object (`Field.datetime` and
+`Field.date` naming the same calendar days), so a storage-form leak shows up as
+the two columns bucketing differently even when each is internally consistent.
+A granularity the driver does not advertise is skipped, never faulted.
+
+It follows `checkReadCoercion`: human-readable problems (empty = conformant), no
+test-runner dependency, driver taken structurally — so an out-of-tree driver
+runs the identical contract against itself. That matters most for cloud's
+`driver-turso`, which is remote SQLite with exactly the epoch storage that broke
+here.
+
+Wired up in `packages/qa/dogfood/test/date-bucket-parity-conformance.test.ts`
+against driver-sql and driver-sqlite-wasm, with negative controls that pin what
+the checker can detect. Verified against the real regression, not just fakes:
+reverting the #3773 fix turns the gate red on both drivers with a diagnostic
+naming the collapsed bucket.
+
+The three test files that hand-copy `bucketDateValue` (driver-sql cannot depend
+on objectql) now say what their `⚠️ Keep in sync` comments cannot enforce — a
+copy that stops tracking its original leaves the copy and the SQL agreeing with
+each other while both are wrong — and point at the executable check. The same
+pointer is on `bucketDateValue` itself, which is where an edit would start the
+drift.

packages/objectql/src/in-memory-aggregation.ts

@@ -175,6 +175,20 @@ function toNumber(v: any): number {
  * Bucket a date-like value into an ISO-formatted period label. Weeks start
  * Monday and use ISO week numbering.
  *
+ * ⚠️ **This is one of two implementations of the same contract.** A driver that
+ * advertises `supports.queryDateGranularity[g]` buckets that granularity in SQL
+ * instead, and `engine.aggregate` picks between them per query — so a label
+ * produced here must equal the label that driver's SQL produces for the same
+ * instant, or a drill-down breaks when it crosses the seam. Editing the labels
+ * below means editing every driver's bucket expression too.
+ *
+ * The seam is enforced by `checkDateBucketParity` (@objectstack/verify), run
+ * against the real drivers in
+ * `packages/qa/dogfood/test/date-bucket-parity-conformance.test.ts`. Three
+ * driver test files also hand-copy this function for self-containment; those
+ * copies cannot detect their own drift, which is why the executable check
+ * exists.
+ *
  * `timezone` (ADR-0053 Phase 2) resolves the calendar day in a reference zone
  * so an instant near a tz day-boundary buckets where a user in that zone would
  * expect. An unset / `'UTC'` / invalid zone keeps the historical UTC bucketing.

packages/plugins/driver-sql/src/sql-driver-date-bucket-storage.test.ts

@@ -27,7 +27,16 @@ type Granularity = 'day' | 'month' | 'quarter' | 'year';
 /** Every granularity SQLite advertises natively (week is bucketed in-memory). */
 const GRANULARITIES: Granularity[] = ['day', 'month', 'quarter', 'year'];
 
-/** ⚠️ Keep in sync with `packages/objectql/src/in-memory-aggregation.ts#bucketDateValue` */
+/**
+ * ⚠️ Keep in sync with `packages/objectql/src/in-memory-aggregation.ts#bucketDateValue`.
+ *
+ * This copy exists because driver-sql cannot depend on objectql. Nothing here
+ * can detect it drifting from its original — a stale copy and the SQL agree
+ * with each other while both are wrong. The executable check is
+ * `checkDateBucketParity` (@objectstack/verify), run against the real drivers
+ * in `packages/qa/dogfood/test/date-bucket-parity-conformance.test.ts`, where
+ * the reference side is the REAL `applyInMemoryAggregation`.
+ */
 function bucketDateValue(value: unknown, g: Granularity): string {
   if (value == null) return '(null)';
   // A finite number is epoch milliseconds — SQLite's `Field.datetime` storage.

packages/plugins/driver-sql/src/sql-driver-date-bucket.test.ts

@@ -17,7 +17,16 @@ import { SqlDriver } from '../src/index.js';
 
 type Granularity = 'day' | 'week' | 'month' | 'quarter' | 'year';
 
-/** ⚠️ Keep in sync with `packages/objectql/src/in-memory-aggregation.ts#bucketDateValue` */
+/**
+ * ⚠️ Keep in sync with `packages/objectql/src/in-memory-aggregation.ts#bucketDateValue`.
+ *
+ * This copy exists because driver-sql cannot depend on objectql. Nothing here
+ * can detect it drifting from its original — a stale copy and the SQL agree
+ * with each other while both are wrong. The executable check is
+ * `checkDateBucketParity` (@objectstack/verify), run against the real drivers
+ * in `packages/qa/dogfood/test/date-bucket-parity-conformance.test.ts`, where
+ * the reference side is the REAL `applyInMemoryAggregation`.
+ */
 function bucketDateValue(value: unknown, g: Granularity): string {
   if (value == null) return '(null)';
   // A finite number is epoch milliseconds — SQLite's `Field.datetime` storage.

packages/plugins/driver-sqlite-wasm/src/sqlite-wasm-driver-date-bucket.test.ts

@@ -17,7 +17,16 @@ import { SqliteWasmDriver } from '../src/index.js';
 
 type Granularity = 'day' | 'week' | 'month' | 'quarter' | 'year';
 
-/** ⚠️ Keep in sync with `packages/objectql/src/in-memory-aggregation.ts#bucketDateValue` */
+/**
+ * ⚠️ Keep in sync with `packages/objectql/src/in-memory-aggregation.ts#bucketDateValue`.
+ *
+ * This copy exists because driver-sql cannot depend on objectql. Nothing here
+ * can detect it drifting from its original — a stale copy and the SQL agree
+ * with each other while both are wrong. The executable check is
+ * `checkDateBucketParity` (@objectstack/verify), run against the real drivers
+ * in `packages/qa/dogfood/test/date-bucket-parity-conformance.test.ts`, where
+ * the reference side is the REAL `applyInMemoryAggregation`.
+ */
 function bucketDateValue(value: unknown, g: Granularity): string {
   if (value == null) return '(null)';
   // A finite number is epoch milliseconds — SQLite's `Field.datetime` storage.

packages/qa/dogfood/package.json

@@ -30,6 +30,7 @@
     "@objectstack/core": "workspace:*",
     "@objectstack/driver-memory": "workspace:*",
     "@objectstack/driver-sql": "workspace:*",
+    "@objectstack/driver-sqlite-wasm": "workspace:*",
     "@types/node": "^26.1.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"

packages/qa/dogfood/test/date-bucket-parity-conformance.test.ts

@@ -0,0 +1,141 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// Date-bucket parity conformance — exercises the reusable `checkDateBucketParity`
+// helper (from @objectstack/verify) against the framework's own SQL drivers.
+// A granularity a driver ADVERTISES via `supports.queryDateGranularity` must
+// bucket identically whether `engine.aggregate` pushes it down as SQL or falls
+// back to `applyInMemoryAggregation` — they are one feature with two
+// implementations, and the engine picks between them per query.
+//
+// This is the seam #3773 crossed silently. SQLite stores a `Field.datetime` as
+// INTEGER epoch ms; `strftime` read the bare integer as a Julian day number, so
+// every row bucketed as NULL and a trend chart collapsed into one bar. Every
+// existing gate was green: the driver's own bucket suites build their tables
+// with `knex.schema.createTable` + `t.string(...)` (ISO TEXT — the half
+// `strftime` parses natively), and the engine never second-guesses a
+// granularity a driver claims to support.
+//
+// It also closes the drift the `⚠️ Keep in sync` comments cannot: three test
+// files hand-copy `bucketDateValue` because driver-sql cannot depend on
+// objectql, and a copy that stops tracking its original leaves the copy and the
+// SQL agreeing with each other while both are wrong. Here the reference side is
+// the REAL `applyInMemoryAggregation`.
+
+import { describe, it, expect } from 'vitest';
+import { checkDateBucketParity } from '@objectstack/verify';
+import { SqlDriver } from '@objectstack/driver-sql';
+import { SqliteWasmDriver } from '@objectstack/driver-sqlite-wasm';
+
+const DRIVERS = [
+  {
+    name: 'driver-sql (better-sqlite3 :memory:)',
+    make: () =>
+      new SqlDriver({
+        client: 'better-sqlite3',
+        connection: { filename: ':memory:' },
+        useNullAsDefault: true,
+      }),
+  },
+  {
+    // Inherits `buildDateBucketExpr` from SqlDriver, so it inherited #3773 too —
+    // and resolves its base class from BUILT dist, which is its own way to drift.
+    name: 'driver-sqlite-wasm (:memory:)',
+    make: () => new SqliteWasmDriver({ filename: ':memory:' }),
+  },
+];
+
+describe.each(DRIVERS)('date-bucket parity conformance: $name', ({ make }) => {
+  it('buckets identically pushed-down and in-memory, on both storage forms', async () => {
+    const problems = await checkDateBucketParity(make() as never, {
+      createOptions: { bypassTenantAudit: true },
+    });
+    expect(problems).toEqual([]);
+  });
+});
+
+describe('checkDateBucketParity detects a driver whose SQL bucketing is wrong', () => {
+  // The negative control. A gate nobody has watched fail is a gate nobody knows
+  // is wired up — and this one is cheap to fake, because the #3773 shape is
+  // exactly "advertise the granularity, then bucket everything as NULL".
+  function brokenDriver(overrides: Record<string, unknown> = {}) {
+    const rows = [
+      { id: 'b1', at: '2024-01-15T10:00:00.000Z', on: '2024-01-15', n: 1 },
+      { id: 'b2', at: '2024-06-30T23:59:59.000Z', on: '2024-06-30', n: 1 },
+      { id: 'b3', at: '2024-07-01T00:00:00.000Z', on: '2024-07-01', n: 1 },
+      { id: 'b4', at: '2024-12-30T12:00:00.000Z', on: '2024-12-30', n: 1 },
+      { id: 'b5', at: '2025-01-01T00:00:00.000Z', on: '2025-01-01', n: 1 },
+      { id: 'b6', at: '2025-05-19T09:00:00.000Z', on: '2025-05-19', n: 1 },
+      { id: 'b7', at: '2025-05-19T22:30:00.000Z', on: '2025-05-19', n: 1 },
+    ];
+    return {
+      async connect() {},
+      async disconnect() {},
+      async syncSchema() {},
+      async create() {},
+      async find() {
+        return rows;
+      },
+      // Everything collapses into one null bucket — the pre-#3773 SQLite shape.
+      async aggregate(_object: string, query: any) {
+        const field = query.groupBy[0].field;
+        return [{ [field]: null, n: rows.length }];
+      },
+      supports: { queryDateGranularity: { day: true, month: true, quarter: true, year: true, week: false } },
+      ...overrides,
+    };
+  }
+
+  it('flags every advertised granularity on both columns', async () => {
+    const problems = await checkDateBucketParity(brokenDriver() as never);
+    // 4 advertised granularities × 2 storage forms = 8 disagreements, and the
+    // cross-column pass stays quiet because both columns are broken the same way.
+    expect(problems).toHaveLength(8);
+    expect(problems.join('\n')).toMatch(/Field\.datetime 'at' @ month/);
+    expect(problems.join('\n')).toMatch(/Field\.date 'on' @ year/);
+    expect(problems.join('\n')).toMatch(/pushed-down SQL and in-memory bucketing disagree/);
+  });
+
+  it('flags a driver that advertises a granularity it cannot actually run', async () => {
+    const problems = await checkDateBucketParity(
+      brokenDriver({
+        async aggregate() {
+          throw new Error("dateGranularity 'month' not supported on dialect");
+        },
+      }) as never,
+    );
+    expect(problems.join('\n')).toMatch(/advertises this granularity but aggregate\(\) threw/);
+  });
+
+  it('flags a storage-form leak — one column right, the other collapsed', async () => {
+    // The #3773 shape exactly: the TEXT-stored `date` column buckets fine while
+    // the epoch-stored `datetime` column does not.
+    const problems = await checkDateBucketParity(
+      brokenDriver({
+        async aggregate(_object: string, query: any) {
+          const field = query.groupBy[0].field;
+          if (field === 'on') {
+            return [
+              { on: '2024', n: 4 },
+              { on: '2025', n: 3 },
+            ];
+          }
+          return [{ at: null, n: 7 }];
+        },
+        supports: { queryDateGranularity: { year: true } },
+      }) as never,
+    );
+    expect(problems.join('\n')).toMatch(/Field\.datetime 'at' @ year/);
+    expect(problems.join('\n')).toMatch(
+      /describe the same days but bucket differently/,
+    );
+  });
+
+  it('stays quiet on a driver that advertises nothing', async () => {
+    const problems = await checkDateBucketParity(
+      brokenDriver({ supports: { queryDateGranularity: {} } }) as never,
+    );
+    // Nothing advertised ⇒ the engine buckets everything in-memory ⇒ nothing to
+    // disagree about. A driver is never faulted for declining.
+    expect(problems).toEqual([]);
+  });
+});