feat(spec): declare aggregate? on IDataDriver with the signature the engine calls (#15384)

The engine dispatches native aggregation by presence
(typeof driver.aggregate === 'function') and calls
driver.aggregate(object, ast, options), but IDataDriver never declared the
member, so a custom driver's aggregate was checked in neither direction:
swapped arguments or a non-row result compiled clean and surfaced only after
the engine's having filter matched nothing. Declared optional, matching the
presence test, with the row shape aggregation-conformance pins. All four
in-repo implementations (memory, mongodb, sql, turso remote transport via
TursoDriver) already satisfy it; no driver, capability bit, or engine cast
changes.

The recording double in engine-filter-array-lowering.test.ts drops its local
RecordingDriver extension and annotates against IDataDriver directly.


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

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

Author: os-justin

.changeset/data-driver-aggregate-declared.md

@@ -0,0 +1,9 @@
+---
+"@objectstack/spec": minor
+---
+
+`IDataDriver` now declares `aggregate?` — the one engine-reached driver verb that had no signature to match against.
+
+The engine has always dispatched native aggregation by presence (`typeof driver.aggregate === 'function'`) and called `driver.aggregate(object, query, options)`, but the interface never spelled the member, so a custom driver's `aggregate` was checked in neither direction: swapped arguments or a non-row result compiled clean and surfaced only after the engine's `having` filter silently matched nothing. The member is declared optional, matching the presence test — a driver without native aggregation omits it and stays conformant, served by the `find()` + in-memory fallback.
+
+Additive: every in-repo driver already satisfies the declared signature (`(object: string, query: DriverQuery, options?: DriverOptions) => Promise<Record<string, unknown>[]>`); a wider parameter union or a looser return type stays assignable. What is newly refused is a wrong argument order or a non-array result. No `DriverCapabilities` bit is added — presence remains the capability test, as `data/driver.zod.ts` rules.

packages/objectql/src/engine-filter-array-lowering.test.ts

@@ -27,7 +27,6 @@
 
 import { describe, it, expect, beforeEach } from 'vitest';
 import type {
-  DriverOptions,
   EngineAggregateOptions,
   EngineCountOptions,
   EngineQueryOptions,
@@ -90,15 +89,14 @@ interface SeenRead { ast: DriverQuery }
  * the annotation THIS declaration is what fails when a member is added or a
  * signature moves.
  *
- * The one extension: `aggregate` is NOT on `IDataDriver`. The engine reaches it
- * by duck-typing (`typeof drv.aggregate === 'function'`, `engine.ts`), so it is
- * declared here explicitly — the pin exercises that verb and must keep
- * witnessing it. ⚠️ Declared here does NOT make it contractual; it records that
- * this double answers a call the interface does not describe.
+ * `aggregate` included: the engine reaches it by duck-typing
+ * (`typeof drv.aggregate === 'function'`, `engine.ts`), and until #14345 the
+ * interface did not declare it, so this file carried a local extension for
+ * the one verb. `IDataDriver.aggregate?` now spells the signature the engine
+ * calls, so the double's `aggregate` is checked by the same annotation as
+ * every other verb — no local extension, nothing this double answers that the
+ * contract does not describe.
  */
-interface RecordingDriver extends IDataDriver {
-  aggregate(object: string, query: DriverQuery, options?: DriverOptions): Promise<Record<string, unknown>[]>;
-}
 
 /**
  * A verb the pin does not exercise, present only because `IDataDriver` requires
@@ -152,7 +150,7 @@ function makeRecordingDriver() {
     const out = [...rows.values()].filter((r) => matches(r, ast?.where));
     return typeof ast?.limit === 'number' && ast.limit > 0 ? out.slice(0, ast.limit) : out;
   };
-  const driver: RecordingDriver = {
+  const driver: IDataDriver = {
     name: 'recording', version: '0.0.0', supports: {},
     async connect() {}, async disconnect() {}, async checkHealth() { return true; }, async execute() { return null; },
     async find(_o: string, ast: DriverQuery) { reads.push({ ast }); return run(ast); },

packages/spec/src/contracts/data-driver.ts

@@ -213,6 +213,42 @@ export interface IDataDriver {
    */
   count(object: string, query?: DriverQuery, options?: DriverOptions): Promise<number>;
 
+  /**
+   * Native aggregation pushdown: execute `query.groupBy` / `query.aggregations`
+   * inside the store and return the ALREADY-GROUPED rows.
+   *
+   * What the engine passes (objectql `engine.ts`, `ObjectQL.aggregate`): the
+   * object name; the full query AST it built for the read (`where`, `groupBy`,
+   * `aggregations`, `orderBy`, `limit`, ...) — the same {@link DriverQuery}
+   * `find()` receives, so a value that satisfies `find` satisfies this; and the
+   * per-call {@link DriverOptions}. Presence IS the capability test: the engine
+   * dispatches on `typeof driver.aggregate === 'function'` — the rule
+   * `data/driver.zod.ts` states for `DriverCapabilities`, and why there is
+   * deliberately no `queryAggregations` bit — and otherwise falls back to
+   * `find()` plus in-memory grouping. Two things the engine keeps for itself
+   * even when it dispatches here: `having` is applied AFTER this call, over the
+   * returned rows (#4286); and `aggregations[].filter` (#10576) or a non-UTC
+   * `timezone` with date bucketing (ADR-0053) force the in-memory path, so a
+   * driver never sees either on this road today.
+   *
+   * What a driver returns: one row per group, keyed by the `groupBy` field
+   * names and by each aggregation's `alias`, with the per-function value
+   * semantics `data/aggregation-conformance.ts` pins for every face that
+   * lowers this vocabulary. The engine's `having` filter reads exactly those
+   * keys, so a mis-keyed row does not error — it silently fails to match.
+   *
+   * Declared for the reason `introspectSchema` gives below: the engine reached
+   * this verb by duck-typing with no signature to mis-match against, so
+   * `aggregate(query, object)` with the arguments swapped, or a non-row
+   * result, compiled clean and surfaced only downstream of `having`. Optional,
+   * matching the presence test — a driver without native aggregation
+   * (driver-rest today) omits the member and stays conformant, served by the
+   * fallback. A wider parameter union (driver-memory also accepts a raw
+   * pipeline) or a looser return type stays assignable; what is refused is a
+   * wrong argument order or a non-array result.
+   */
+  aggregate?(object: string, query: DriverQuery, options?: DriverOptions): Promise<Record<string, unknown>[]>;
+
   // ===========================================================================
   // Bulk Operations
   // ===========================================================================