fix(objectql)!: a per-aggregation filter that is not a filter object is refused (#20122)

The seat's amendment to the combined claim folds the per-aggregation
filter's shape door into this card. In the `aggregations[i].filter` loop,
a filter that is neither absent, `null`, a filter object nor an array (a
string, a number, a boolean, `''`, a `Map`, a `Date`) was stepped around
by every door there and then dropped: the aggregation read every row of
its group, with no error.

The loop now opens with the shape gate `where` takes on its own seam,
reusing its accept set (`isWhereFilterObject`) and its words
(`describeNonFilterWhere`), with a consequence clause for this position,
INVALID_FILTER / 400 before any driver call. An array is left to the
doors below, as `where` leaves one to its array branch. The note that
excluded this gate from the loop is removed.

Claude-Session: https://claude.ai/code/session_01Bvd69VPa6puiNzzPUroDBx
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/20122-aggregation-filter-row-independent.md

@@ -2,7 +2,7 @@
 "@objectstack/objectql": minor
 ---
 
-fix(objectql)!: a per-aggregation `filter` (`aggregations[i].filter`) on `engine.aggregate` is judged once, before any row is read — its refusals no longer depend on whether the table has rows, and it takes the comparand-type door `where` takes (#20122)
+fix(objectql)!: a per-aggregation `filter` (`aggregations[i].filter`) on `engine.aggregate` is judged once, before any row is read — its refusals no longer depend on whether the table has rows, and it takes the shape gate and the comparand-type door `where` takes (#20122)
 
 Clause-②: no (narrowing)
 
@@ -22,11 +22,12 @@ The engine evaluates a per-aggregation filter itself, in the in-memory fallback,
 | a `{ $field }` reference whose `addDays` is not an integer (`1.5`, `'7'`) | counted rows by the in-memory evaluator's own reading of that offset, which `FieldReferenceSchema` refuses | a whole-day `addDays` |
 | `{ amount: { $eq: { v: 1 } } }`, `{ amount: undefined }`, `{ $eq: new Map() }`, a function, an `undefined` `$in` member, a bigint beyond 2^53, or `{ $gt: { $field: 5 } }` | counted no row (each measured under the operator shown, or in the implicit slot). The same comparand in `where` is refused by the comparand-type door; the per-aggregation filter now gets that door's refusal, rooted at its own position | a string, number, bigint, boolean, `null` or `Date` |
 | a `Symbol` comparand | under `$ne`, counted every row; under `$gt`, threw a raw `TypeError` with no `code` and no `status` on a populated table | a literal of one of the types above |
+| a `filter` that is not a filter object: a string (`"stage = 'won'"`), a number, `true` / `false`, `''`, a `Map`, a `Date` or a `Set` | dropped: the aggregation read every row of its group, with no error. `driver-sql`'s native aggregate answered a non-empty string with `NOT_IMPLEMENTED` / 501. (The REST door already refused the JSON-expressible ones, through `AggregationNodeSchema`.) Now refused by the shape gate `where` takes (`'where' must be a filter object or condition array, received …`), in the same words, naming the aggregation | a filter object, `{ stage: 'won' }` |
 
 Not refused, but answering differently:
 
 - **An exact-range bigint comparand is narrowed to a number, as it is in `where`.** `{ amount: { $in: [400n, 20n] } }` counted no row, because `[400n].includes(400)` is false. It now counts the rows it names. The caller's aggregation entry is not edited.
 
-Who is affected: a per-aggregation filter reaches `engine.aggregate` from a direct engine call, from the REST aggregate query, and from the analytics service, which lowers a dataset measure's own `filter` onto it. On a populated table the refusals in the first and fourth rows above were already raised; what changes there is that an empty table refuses them too. Callers in a deployment were NOT measured.
+Who is affected: a per-aggregation filter reaches `engine.aggregate` from a direct engine call, from the REST aggregate query, and from the analytics service, which lowers a dataset measure's own `filter` onto it. On a populated table the refusals in the first and fourth rows above were already raised; what changes there is that an empty table refuses them too. The shape row is reachable in-process only: the REST door already refuses a non-object `filter`. Callers in a deployment were NOT measured.
 
-Not changed: implicit equality, scalar ordering bounds, `$in` / `$nin` lists, a two-bound `$between`, `$icontains` / `$startsWith` with a non-empty string, `$ne: null`, `$exists`, `$null`, `$or` / `$not` composition, a `{ $field }` reference as the whole comparand of a scalar comparison (with or without a whole-day `addDays`), an exact bigint in the implicit slot, the zero-row filter `{ $not: {} }`, and `{}`, on both drivers, measured identical before and after. A `filter` that is not a filter object at all (a string, a number, a boolean, a `Map`, an array) is answered as before.
+Not changed: implicit equality, scalar ordering bounds, `$in` / `$nin` lists, a two-bound `$between`, `$icontains` / `$startsWith` with a non-empty string, `$ne: null`, `$exists`, `$null`, `$or` / `$not` composition, a `{ $field }` reference as the whole comparand of a scalar comparison (with or without a whole-day `addDays`), an exact bigint in the implicit slot, the zero-row filter `{ $not: {} }`, and `{}`, on both drivers, measured identical before and after. `null`, an absent `filter`, a null-prototype filter object and an array are not refused by the shape gate, as they are not on `where`: `[]` is still read as no filter, and a condition array (`[['amount', '>', 100]]`) is still read by the walker as an object whose index keys are column names, so it counts no row, as before — `AggregationNodeSchema.filter` does not declare that sugar, and the REST door refuses it.

packages/objectql/src/engine-aggregate-filter.test.ts

@@ -523,3 +523,54 @@ describe('[#20122] per-aggregation filter — what the walk leaves alone answers
     });
   }
 });
+
+describe('[#20122] per-aggregation filter — the shape gate `where` takes: a filter that is not a filter object is refused', () => {
+  // Before, measured through `engine.aggregate` on driver-memory and
+  // driver-sql: each shape was DROPPED — the aggregation counted every row of
+  // its group, on a populated table, with no error (driver-sql's native
+  // aggregate answered the non-empty string with NOT_IMPLEMENTED / 501). The
+  // REST door refuses each one already, through `AggregationNodeSchema`.
+  const SHAPE_REFUSED: ReadonlyArray<readonly [string, () => unknown, string]> = [
+    ['a string', () => "stage = 'closed_won'", `received string "stage = 'closed_won'"`],
+    ['a number', () => 42, 'received number 42'],
+    ['a Map', () => new Map([['stage', 'closed_won']]), 'received Map'],
+    ['true', () => true, 'received boolean true'],
+    ['the empty string', () => '', 'received string ""'],
+    ['a Date', () => new Date(0), 'received Date'],
+  ];
+
+  for (const [name, filter, received] of SHAPE_REFUSED) {
+    it(`${name}: refused before any read, whatever the rows`, async () => {
+      const message = await expectFilterRefusal(filter);
+      expect(message).toContain(`aggregate('crm_opportunity'): '${AT}' must be a filter object or condition array, ${received}.`);
+      expect(message).toContain('It was not applied');
+    });
+  }
+
+  it('a filter object answers as before — a literal and a null-prototype one alike', async () => {
+    for (const native of [true, false]) {
+      for (const filter of [{ stage: 'closed_won' }, Object.assign(Object.create(null), { stage: 'closed_won' })]) {
+        const { driver } = makeCountingDriver(OPPORTUNITIES, native);
+        const engine = await makeEngine(driver);
+        expect(await engine.aggregate('crm_opportunity', withFilter(filter))).toEqual([{ opp_count: 6, picked: 2 }]);
+      }
+    }
+  });
+
+  it('an array is not this gate\'s to refuse, as it is not on `where` — `[]` and a FilterArray answer as before', async () => {
+    // Held, not endorsed: the FilterArray's answer is the walker's reading of an
+    // array (its index keys read as column names, so no row matches) — the
+    // pre-existing reading, left for its own decision; `[]` is the vacuous
+    // filter. What this pins is that the shape gate moves neither.
+    for (const native of [true, false]) {
+      const { driver } = makeCountingDriver(OPPORTUNITIES, native);
+      const engine = await makeEngine(driver);
+      expect(await engine.aggregate('crm_opportunity', withFilter([['amount', '>', 100]]))).toEqual([{ opp_count: 6, picked: 0 }]);
+    }
+    // `[]` is read as no filter and so keeps the native push-down; the stand-in's
+    // native door computes nothing, so it is read on the fallback door here.
+    const { driver } = makeCountingDriver(OPPORTUNITIES, false);
+    const engine = await makeEngine(driver);
+    expect(await engine.aggregate('crm_opportunity', withFilter([]))).toEqual([{ opp_count: 6, picked: 6 }]);
+  });
+});

packages/objectql/src/engine.ts

@@ -16090,6 +16090,25 @@ export class ObjectQL implements IObjectQLEngine {
           for (const [i, agg] of aggregations.entries()) {
               const aggFilter = (agg as { filter?: unknown })?.filter;
               if (aggFilter == null) continue;
+              // [#20122] The SHAPE gate `where` takes first on its own seam
+              // (`lowerWhereFilterArray`, #20121) — first here too, with its
+              // accept set and its words. A filter that is not a filter object
+              // (a string, a number, a boolean, `''`, a `Map`, a `Date`) was
+              // stepped around by every door below, each of which walks a filter
+              // node's keys, and then dropped: the fork below reads it as "no
+              // filter", so the aggregation read every row of its group
+              // (`driver-sql`'s native aggregate answered a non-empty string
+              // with a 501 instead). The wire door already refuses these shapes
+              // through `AggregationNodeSchema`; this closes the in-process one.
+              // An array is left to the doors below, as `where` leaves one to
+              // its array branch.
+              if (!Array.isArray(aggFilter) && !isWhereFilterObject(aggFilter)) {
+                  throw invalidFilterError(
+                      `aggregate('${object}'): 'aggregations[${i}].filter' must be a filter object or condition ` +
+                      `array, received ${describeNonFilterWhere(aggFilter)}. It was not applied, and an ` +
+                      `unapplied filter would have aggregated every row of each group for that aggregation.`,
+                  );
+              }
               assertListComparandShapes(object, 'aggregate', aggFilter, `aggregations[${i}].filter`);
               assertFilterIsMaterializable(object, 'aggregate', this._registry.getObject(object), aggFilter);
               // [#15661] …and the declared-type door for the text operators: a
@@ -16112,11 +16131,6 @@ export class ObjectQL implements IObjectQLEngine {
               //     walks the filter per SOURCE row, so `{ amount: { $median: 1 } }`
               //     was a 400 on a populated table and a `200 []` on an empty one,
               //     and a `$or` whose first branch held counted every row.
-              // ⛔ Not the condition-object check `having` got: a `filter` that is
-              // not a filter node at all (a string, a number, a `Map`) is a
-              // question about the clause's SHAPE, answered by the shape door
-              // for every filter position at once — not a refusal that depends
-              // on the data, which is what this block closes.
               const typed = normalizeFilterComparandTypes(aggFilter, `aggregate('${object}')`, `aggregations[${i}].filter`);
               assertAggregationFilterIsEvaluable(typed, i);
               if (typed !== aggFilter) {