chore(gates): classify AGGREGATION_CASES in the driver conformance matrix (#6409)

Enrols driver-sql, driver-turso and driver-sqlite-wasm; records honest DEBT
rows for the two #5499-frozen packages (tracked as #6814). Regenerates the
spec API surface for the new shared exports.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RWMbS2ctjZSADPJiSdUtMA

Author: claude

packages/drivers/driver-sqlite-wasm/src/sqlite-wasm-aggregation-conformance.test.ts

@@ -0,0 +1,83 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#6409] Aggregate-vocabulary conformance for the wasm driver — the shared
+ * `@objectstack/spec/data` cases, run through this driver's own pipeline.
+ *
+ * `SqliteWasmDriver extends SqlDriver`, so the `count(distinct x)` lowering is
+ * inherited and nothing here re-implements it. What this pins is the other
+ * half, the same half its filter-logic, temporal and pagination suites pin: the
+ * compiled statement has to survive a different **engine**. This driver swaps
+ * knex's transport for a custom sql.js dialect (`Client_WasmSqlite`) that
+ * compiles the statement, binds its parameters and marshals the rows back
+ * through its own path.
+ *
+ * That last step is why this cell is not a formality. The other five aggregates
+ * come back as a plain scalar; `COUNT(DISTINCT …)` does too, but it is the one
+ * whose column expression carries a KEYWORD the dialect has to pass through
+ * untouched, and it is the one whose wrong answers are all valid numbers. A
+ * dialect that mangled the expression, or that marshalled the count back
+ * through a different type path, would fail here and in no other suite.
+ *
+ * "It inherits the compiler, therefore it is fine" is the assumption these
+ * suites exist to disprove — the judgement #4405 recorded for this driver's
+ * filter-logic cell, applied to the aggregate column.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { AGGREGATION_CASES, AGGREGATION_ROWS } from '@objectstack/spec/data';
+import type { AggregationCase, QueryAST } from '@objectstack/spec/data';
+import { SqliteWasmDriver } from './index.js';
+
+const OBJECT = 'conformance_agg';
+
+const astFor = (c: AggregationCase): QueryAST => ({
+  object: OBJECT,
+  aggregations: [{ function: c.function, ...(c.field ? { field: c.field } : {}), alias: 'n' }],
+  ...(c.groupBy ? { groupBy: [c.groupBy] } : {}),
+});
+
+const actualFor = (c: AggregationCase, rows: Array<Record<string, unknown>>) =>
+  rows
+    .map((r) => ({ group: c.groupBy ? String(r[c.groupBy]) : null, value: Number(r.n) }))
+    .sort((x, y) => String(x.group).localeCompare(String(y.group)));
+
+describe('[#6409] driver-sqlite-wasm — aggregate vocabulary conformance', () => {
+  let driver: SqliteWasmDriver;
+
+  beforeAll(async () => {
+    driver = new SqliteWasmDriver({ filename: ':memory:' });
+    await driver.initObjects([
+      {
+        name: OBJECT,
+        fields: {
+          region: { type: 'string' },
+          // Nullable — the DDL this driver generates leaves a plain string
+          // column nullable, which is what the null-bearing rows need.
+          stage: { type: 'string' },
+          score: { type: 'number' },
+        },
+      },
+    ]);
+    for (const row of AGGREGATION_ROWS) {
+      await driver.create(OBJECT, { ...row }, { bypassTenantAudit: true } as any);
+    }
+  });
+
+  afterAll(async () => {
+    await driver.disconnect();
+  });
+
+  it('the fixture is all six rows, with the nulls stored AS nulls', async () => {
+    const rows = await driver.find(OBJECT, { sort: [{ field: 'id', order: 'asc' }] });
+    expect(rows).toHaveLength(6);
+    expect((rows as any[]).filter((r) => r.stage === null)).toHaveLength(2);
+  });
+
+  for (const c of AGGREGATION_CASES) {
+    it(c.name, async () => {
+      const rows = await driver.aggregate(OBJECT, astFor(c));
+      expect(actualFor(c, rows as any[]), c.note).toEqual([...c.expected]);
+    });
+  }
+});

packages/spec/api-surface/data.json

@@ -2,6 +2,8 @@
   "description": "Every exported `name (kind)` of one published entry point of @objectstack/spec — the breadth half of the ADR-0059 backward-compatibility gate. Sharded by entry point (#5837) so two PRs touching different entry points never share a file. Reads the BUILT dist/*.d.ts: regenerate with `pnpm --filter @objectstack/spec gen:api-surface` after a real build.",
   "entry": "./data",
   "exports": [
+    "AGGREGATION_CASES (const)",
+    "AGGREGATION_ROWS (const)",
     "ALL_OPERATORS (const)",
     "API_METHOD_DERIVATION (const)",
     "API_METHOD_ORDER (const)",
@@ -12,12 +14,15 @@
     "AddressSchema (const)",
     "AddressValue (type)",
     "AddressValueSchema (const)",
+    "AggregationCase (interface)",
+    "AggregationExpectation (interface)",
     "AggregationFunction (type)",
     "AggregationMetricType (type)",
     "AggregationNode (type)",
     "AggregationNodeSchema (const)",
     "AggregationPipeline (type)",
     "AggregationPipelineSchema (const)",
+    "AggregationRow (interface)",
     "AggregationStage (type)",
     "AggregationStageSchema (const)",
     "AnalyticsQuery (type)",

packages/spec/src/data/query.zod.ts

@@ -73,8 +73,7 @@ export const SortNodeSchema = lazySchema(() => strictObject(
 const AGG_RETIRED_MIDDLE =
   ' was removed from `AggregationFunction` in @objectstack/spec 17 (#6188, ADR-0049 '
   + 'enforce-or-remove) — no SQL backend ever compiled it. `SqlDriver.mapAggregateFunc` and '
-  + '`RemoteTransport.aggregate` lower the same set of functions and refuse everything outside '
-  + 'it (`count_distinct` joined that set at #6409; these two never did), and '
+  + '`RemoteTransport.aggregate` each lower the same set of functions and refuse the rest, and '
   + "the v1 dataset runtime had to subtract this one by name to stop it reaching a `COUNT(*)` "
   + 'fallback that returns a row count in place of the value asked for. On the backend family '
   + 'this platform targets it was a declaration that could only fail. ';

scripts/check-driver-conformance.mjs

@@ -161,6 +161,11 @@ const CASE_SETS = [
     marker: 'FILTER_TEXT_CASES',
     what: 'text operators: ASCII-only case folding, literal comparands, `$regex` refused — #4706/#5701',
   },
+  {
+    file: 'aggregation-conformance.ts',
+    marker: 'AGGREGATION_CASES',
+    what: 'the value each declared AggregationFunction produces, dedup and NULLs included — #6409',
+  },
 ];
 
 // ── The ledger ──────────────────────────────────────────────────────────────
@@ -328,8 +333,24 @@ const CASE_SETS = [
 //      `code` half the case-set requires and the last place a bare `new Error`
 //      escaped the ADR-0112 envelope.
 //
-// Each row's `why` is what that driver does TODAY, measured on this branch by
-// reading the compiler and executing it. Nothing here is predicted.
+// ## AGGREGATION_CASES: two DEBT rows on arrival, and they are the same pair
+//
+// The column arrived with #6409, which lowered `count_distinct` to
+// `COUNT(DISTINCT x)` on the SQL family — the ENFORCE leg of #6188's split
+// ruling. Three of the five cells were covered by that PR: `driver-sql` and
+// `driver-turso` (its REMOTE transport, an independent compiler, which is what
+// the case-set exists to hold against the local one) plus `driver-sqlite-wasm`,
+// whose suite pins the inherited statement surviving a different ENGINE, the
+// same judgement #4405 recorded for its filter-logic cell.
+//
+// The two open cells are `driver-memory` and `driver-mongodb` — the #5499 frozen
+// family, and open by that decision rather than by difficulty. #6409's ruling
+// put both explicitly out of scope and left their partial implementations
+// untouched, so the rows below record what each ANSWERS today, read from the
+// source on this branch. Neither is a prediction, and neither is a permission
+// slip: the cell clears when a suite runs the case-set, not when someone argues
+// the driver would pass it. Both would go RED as they stand, which is the
+// reason the rows exist rather than a reason to omit them.
 
 const LEDGER = [
   {
@@ -381,6 +402,41 @@ const LEDGER = [
       + 'this cell needs a server-free half like `mongodb-filter-logic-translation.test.ts` has.',
     issue: 'https://github.com/objectstack-ai/objectstack/issues/6682',
   },
+  {
+    driver: 'driver-memory',
+    marker: 'AGGREGATION_CASES',
+    kind: 'DEBT',
+    why:
+      'Measured on this branch by reading `MemoryDriver.computeAggregate` (`memory-driver.ts`): it has arms '
+      + 'for count/sum/avg/min/max and then `default: return null`. There is NO `count_distinct` arm, so an '
+      + 'aggregation the Query Protocol declares — and that every SQL face now lowers (#6409) — resolves with '
+      + '`{ n: null }`: no error, no log, no refusal. The case-set says 2 over `AGGREGATION_ROWS`. That is a '
+      + 'wrong ANSWER rather than a wrong number, and it is the `default:`-arm shape the '
+      + '`aggregation-lockstep` guard exists to stop one layer up, reached here through a different door. '
+      + 'The package is partial in the way #6409\'s ruling described: its ANALYTICS face '
+      + '(`memory-analytics.ts`) DOES implement `count_distinct`, so this package answers one declared '
+      + 'function two ways depending on which face you enter — the divergence class #5374 fixed for '
+      + '`$contains` in this same package. #5499 freezes it, so the cell is open by decision, not by '
+      + 'difficulty: the fix is one arm beside its neighbours. Tracked as #6814.',
+    issue: 'https://github.com/objectstack-ai/objectstack/issues/6814',
+  },
+  {
+    driver: 'driver-mongodb',
+    marker: 'AGGREGATION_CASES',
+    kind: 'DEBT',
+    why:
+      'Measured on this branch by reading `mongodb-aggregation.ts`: `count_distinct` lowers to '
+      + '`{ $addToSet: fieldRef ?? null }` and `postProcessAggregation` takes the array\'s `.length`. '
+      + '`$addToSet` adds an explicit `null` to the set, so a nullable column sizes ONE HIGHER than '
+      + '`COUNT(DISTINCT col)` does — 3 where the case-set says 2 over `AGGREGATION_ROWS`. `$addToSet` on a '
+      + 'MISSING field adds nothing, so the divergence shows only for an explicitly-null value, which is '
+      + 'exactly what the fixture seeds and what a nullable column produces in practice. Not executed — this '
+      + 'package has no suite for the cell, which is the debt. #5499 freezes it; the fix is a `$ne: null` '
+      + 'before the `$addToSet` (or sizing a `$setDifference` against `[null]`). Tracked as #6814. Note the '
+      + 'real-mongod suites are opt-in since #5517, so whatever clears this cell needs a server-free half '
+      + 'like `mongodb-filter-logic-translation.test.ts` has.',
+    issue: 'https://github.com/objectstack-ai/objectstack/issues/6814',
+  },
 ];
 
 // ── Discovery ───────────────────────────────────────────────────────────────