diff --git a/‎.changeset/21255-having-plain-reference-class.md‎
Lines changed: 22 additions & 0 deletions b/‎.changeset/21255-having-plain-reference-class.md‎
Lines changed: 22 additions & 0 deletions
diff --git a/‎packages/objectql/src/engine-aggregate-filter.test.ts‎
Lines changed: 75 additions & 0 deletions b/‎packages/objectql/src/engine-aggregate-filter.test.ts‎
Lines changed: 75 additions & 0 deletions
diff --git a/‎packages/objectql/src/engine-aggregate-having-comparand-shape.test.ts‎
Lines changed: 91 additions & 1 deletion b/‎packages/objectql/src/engine-aggregate-having-comparand-shape.test.ts‎
Lines changed: 91 additions & 1 deletion
diff --git a/‎packages/objectql/src/engine.ts‎
Lines changed: 4 additions & 0 deletions b/‎packages/objectql/src/engine.ts‎
Lines changed: 4 additions & 0 deletions
@@ -0,0 +1,22 @@
+---
+"@objectstack/objectql": minor
+---
+
+fix(objectql)!: `having` and the per-aggregation `filter` refuse a plain `{ $field }` reference between two columns of different comparison classes with `INVALID_FILTER` / 400, as `where` refuses it
+
+Clause-②: no (narrowing)
+
+<!-- adr-0087: not-required (no-migration-prescription) a refusal of filter STRUCTURE at the engine's query door: a plain { $field } comparand whose two columns belong to different comparison classes, at having and at a per-aggregation filter. No authorable key, spelling, export or stored shape moves: FieldReferenceSchema, every query shape and every object definition parse as before, @objectstack/objectql exports nothing new and nothing less, and no stored row is read or rewritten. What is refused is a comparison the same query's where already refuses on driver-sql, and which same-class column the caller meant is not something a ledger entry can decide. The other categories are closed on facts: the package publishes (not unpublished); no ADR-0087 id covers a filter's comparison class (not registered / already-registered); and the change is runtime behaviour, not a declaration (not runtime-interface-only / type-surface-only). -->
+
+**BREAKING**: this narrows what a `{ $field }` reference may pair at two positions of `engine.aggregate`. It ships as `minor` under the launch-window convention for accept-set narrowings. No export or published type changes.
+
+**What was accepted before.** At `having` and at a per-aggregation `filter` (`aggregations[i].filter`), the comparison-class rule was applied only to a reference carrying `addDays`. A plain reference across two classes was answered: `{ closed_at: { $lte: { $field: 'due_on' } } }`, with `closed_at` a `datetime` and `due_on` a `date`, counted rows by `@objectstack/formula`'s whole-day reading of the bare day, and a `having` of `max(closed_at)` against a `day` date bucket kept groups the same way. The same comparison in a `where` is refused `INVALID_FILTER` / 400 by `driver-sql`.
+
+**What is refused now.** A scalar comparison (`$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`) whose comparand is a plain `{ $field }` naming a column of a different comparison class. The classes are the spec's `CROSS_FIELD_COMPARISON_CLASSES` (`numeric`, `text`, `boolean`, `date`, `datetime`, `time`), judged by the spec's `crossFieldComparisonVerdict`, the classification `driver-sql`'s `where` compiler reads. The refusal is `INVALID_FILTER` / 400, raised before any driver is asked for a row, on an empty set as on a populated one, through `engine.aggregate` and `POST /api/v1/data/:object/query`:
+
+- in a per-aggregation `filter`, the fields, the operator and the reason are withheld from the message and written to the server log, as `where` withholds them; the message now names the same-class rule beside the `addDays` one;
+- in `having`, the message names the two columns of the query's own projection and their classes, in the sentence `where` logs for the same pair. A `having` column's class is read off the query: a `day` date bucket is a `date`, a coarser bucket a `text` label, `count` / `count_distinct` / `sum` / `avg` are `numeric`, and `min` / `max` take the type of the field they read.
+
+**The remedy.** Compare same-class columns: a `datetime` with a `datetime`, a `date` with a `date` (a `day` bucket is one), a number with a number. A comparison between a `datetime` and a calendar day has no single answer across SQL and memory, so the platform does not define one.
+
+**Unchanged.** A reference between two columns of one class answers as before. A `{ $field, addDays }` pair keeps its judgement and its words. A column whose class the declaration cannot tell is not judged, as an `addDays` pair is not: a host with no registered object, a column the field map does not list (`id`), an aggregation over an undeclared field. A column the spec gives no comparison class at all (a structured-JSON, multi-valued or file field, a formula) is not judged by this rule either.
@@ -802,6 +802,81 @@ describe('[#20148] per-aggregation filter — a { $field } names a declared fiel
   });
 });
 
+// ───────────────────────────────────────────────────────────────────────────
+// [#21255] A plain { $field } takes the class rule `where` gives every reference
+// ───────────────────────────────────────────────────────────────────────────
+
+describe('[#21255] per-aggregation filter — a plain { $field } across two comparison classes is refused, as where refuses it', () => {
+  // Before (2791138cbf), the class rule judged only an `addDays` pair, so the
+  // card's query — `closed_at` (datetime) `$lte` `{ $field: 'due_on' }` (date)
+  // — was answered by `@objectstack/formula`'s whole-day reading of the bare
+  // day: 3 of these 6 rows (o1, o2, o5), measured here with the rule reverted,
+  // and the same shape counted on `SqlDriver` over better-sqlite3 through
+  // `engine.aggregate`, while its `where` twin was refused 400 by `driver-sql`'s
+  // cross-field compiler. The twin itself runs in `packages/rest`
+  // (`aggregation-filter-where-doors.test.ts`), where a real `SqlDriver`
+  // refuses it; the engine judges no `where` reference (the #20148 control
+  // above).
+  const CROSS_CLASS: ReadonlyArray<readonly [string, () => Record<string, unknown>, string]> = [
+    ['a datetime against a date (the card\'s measured query)', () => ({ closed_at: { $lte: { $field: 'due_on' } } }), '"closed_at" is datetime but "due_on" is date'],
+    ['a date against a datetime', () => ({ due_on: { $gte: { $field: 'closed_at' } } }), '"due_on" is date but "closed_at" is datetime'],
+    ['a text against a number', () => ({ customer_id: { $gt: { $field: 'amount' } } }), '"customer_id" is text but "amount" is numeric'],
+    ['a time against a datetime', () => ({ slot: { $lt: { $field: 'opened_at' } } }), '"slot" is time but "opened_at" is datetime'],
+    ['a datetime against a date under $ne', () => ({ closed_at: { $ne: { $field: 'due_on' } } }), '"closed_at" is datetime but "due_on" is date'],
+    ['a datetime against a date behind a $or branch that holds', () => ({ $or: [{ amount: { $gt: 0 } }, { closed_at: { $lte: { $field: 'due_on' } } }] }), '"closed_at" is datetime but "due_on" is date'],
+    ['a datetime against a date under $not', () => ({ $not: { closed_at: { $lte: { $field: 'due_on' } } } }), '"closed_at" is datetime but "due_on" is date'],
+  ];
+
+  for (const [name, filter, diagnostic] of CROSS_CLASS) {
+    it(`${name}: refused before any read, whatever the rows, the names withheld and logged`, async () => {
+      const { message, warnings } = await expectOrderFilterRefusal(filter);
+      expect(message).toContain(`\`${AT}\``);
+      expect(message).toContain('withheld from the message');
+      for (const field of ['closed_at', 'due_on', 'customer_id', 'amount', 'slot', 'opened_at']) {
+        expect(message).not.toContain(`"${field}"`);
+      }
+      // The withheld half names both fields and both classes, once per refusal.
+      expect(warnings).toHaveLength(8);
+      for (const line of warnings) expect(line).toContain(diagnostic);
+    });
+  }
+
+  // Answered exactly as before, on both driver kinds: one class on both sides.
+  const SAME_CLASS: ReadonlyArray<readonly [string, () => Record<string, unknown>, number]> = [
+    ['a date against a date', () => ({ placed_on: { $lte: { $field: 'due_on' } } }), 3],
+    ['a datetime against a datetime', () => ({ closed_at: { $gt: { $field: 'opened_at' } } }), 4],
+    ['a number against a number', () => ({ cap: { $lt: { $field: 'amount' } } }), 4],
+    ['a time against a time', () => ({ slot: { $lte: { $field: 'slot' } } }), 6],
+    ['a text against a text', () => ({ customer_id: { $ne: { $field: 'customer_id' } } }), 0],
+  ];
+
+  for (const [name, filter, populatedCount] of SAME_CLASS) {
+    it(`${name} counts ${populatedCount} of 6, and 0 on an empty table`, async () => {
+      for (const native of [true, false]) {
+        const { driver } = makeCountingDriver(ORDERS, native);
+        const populated = await makeOrderEngine(driver);
+        expect(await populated.aggregate('crm_order', withFilter(filter()))).toEqual([{ opp_count: 6, picked: populatedCount }]);
+        const { driver: emptyDriver } = makeCountingDriver([], native);
+        const empty = await makeOrderEngine(emptyDriver);
+        expect(await empty.aggregate('crm_order', withFilter(filter()))).toEqual([{ opp_count: 0, picked: 0 }]);
+      }
+    });
+  }
+
+  it('an object the registry does not declare is not judged — the card\'s query is answered as before', async () => {
+    // The fail-open direction an `addDays` pair already takes for a
+    // registry-less host: no declaration, no class, no verdict.
+    for (const native of [true, false]) {
+      const { driver } = makeCountingDriver(ORDERS, native);
+      const engine = new ObjectQL();
+      engine.registerDriver(driver, true);
+      await engine.init();
+      expect(await engine.aggregate('crm_order', withFilter({ closed_at: { $lte: { $field: 'due_on' } } })))
+        .toEqual([{ opp_count: 6, picked: 3 }]);
+    }
+  });
+});
+
 describe('[#20148] a Date bound is compared as an instant — as the same bound in a where is', () => {
   // Before, measured through `engine.aggregate` on driver-memory and
   // driver-sql: every Date row below counted NO row (`$ne` / `$nin` / the
 
@@ -822,7 +822,7 @@ describe('[#20127] having — a { $field, addDays } pair is judged by each aggre
     ['date / date with a numeric offset column (a max)', { last_placed: { $lte: { $field: 'first_due', addDays: { $field: 'max_grace' } } } }, ['c1']],
     ['date / date with a numeric offset column (a count)', { last_placed: { $lte: { $field: 'first_due', addDays: { $field: 'order_count' } } } }, ['c3']],
     ['datetime / datetime', { last_closed: { $gte: { $field: 'first_opened', addDays: 1 } } }, ['c1', 'c2']],
-    ['a numeric pair with NO addDays (the rule is the offset\'s)', { total: { $gt: { $field: 'max_cap' } } }, ['c1']],
+    ['a numeric pair with NO addDays (one class on both sides)', { total: { $gt: { $field: 'max_cap' } } }, ['c1']],
   ];
 
   for (const [name, having, expected] of ANSWERED) {
@@ -865,4 +865,94 @@ describe('[#20127] having — a { $field, addDays } pair is judged by each aggre
       expect(groups(await engine.aggregate(OBJECT, query)), door).toEqual([]);
     }
   });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // [#21255] …and a PLAIN { $field } — the class rule `where` gives every reference
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe('[#21255] a plain { $field } across two comparison classes is refused, as where refuses it', () => {
+    // The card's measured shape: `max(closed_at)` (a datetime) against a `day`
+    // bucket (a date). Before (2791138cbf) it was answered by
+    // `@objectstack/formula`'s whole-day reading of the bucket's day — here 3
+    // of the 6 groups (due 2026-01-05, 2026-01-20 and 2026-03-01), measured
+    // with the rule reverted, and the same shape kept groups on `SqlDriver`
+    // over better-sqlite3 through `engine.aggregate` — while its `where` twin,
+    // `closed_at` against `due_on`, was refused 400 by `driver-sql`'s
+    // cross-field compiler. The twin itself runs in `packages/rest`
+    // (`aggregation-filter-where-doors.test.ts`).
+    const BUCKETED: EngineAggregateOptions = {
+      groupBy: [{ field: 'due_on', dateGranularity: 'day', alias: 'due_day' }],
+      aggregations: [{ function: 'max', field: 'closed_at', alias: 'last_closed' }],
+    };
+
+    it('the card\'s query — max(closed_at) against a day bucket — is refused in driver-sql\'s words', async () => {
+      const message = await expectRowIndependentRefusal(
+        { ...BUCKETED, having: { last_closed: { $lte: { $field: 'due_day' } } } }, DT_ROWS);
+      expect(message).toContain('having.last_closed.$lte');
+      expect(message).toContain('"last_closed" is datetime but "due_day" is date');
+      // A plain reference is named as one — it carries no offset.
+      expect(message).toContain('({ "$field": "due_day" })');
+    });
+
+    const REFUSED: ReadonlyArray<readonly [string, () => Record<string, unknown>, string, string]> = [
+      ['a datetime against a date', () => ({ last_closed: { $lte: { $field: 'first_due' } } }), 'having.last_closed.$lte', '"last_closed" is datetime but "first_due" is date'],
+      ['a date against a datetime', () => ({ first_due: { $gte: { $field: 'last_closed' } } }), 'having.first_due.$gte', '"first_due" is date but "last_closed" is datetime'],
+      ['a groupBy text column against a sum', () => ({ customer_id: { $gt: { $field: 'total' } } }), 'having.customer_id.$gt', '"customer_id" is text but "total" is numeric'],
+      ['a sum against a date', () => ({ total: { $gt: { $field: 'last_placed' } } }), 'having.total.$gt', '"total" is numeric but "last_placed" is date'],
+      ['a count against a datetime under $ne', () => ({ order_count: { $ne: { $field: 'first_opened' } } }), 'having.order_count.$ne', '"order_count" is numeric but "first_opened" is datetime'],
+      ['a datetime against a date behind a $or branch that holds', () => ({ $or: [{ total: { $gt: 0 } }, { last_closed: { $lte: { $field: 'first_due' } } }] }), 'having.$or[1].last_closed.$lte', '"last_closed" is datetime but "first_due" is date'],
+      ['a datetime against a date under $not', () => ({ $not: { last_closed: { $lte: { $field: 'first_due' } } } }), 'having.$not.last_closed.$lte', '"last_closed" is datetime but "first_due" is date'],
+    ];
+
+    for (const [name, having, path, fragment] of REFUSED) {
+      it(`${name}: refused at ${path}, whatever the rows`, async () => {
+        const message = await expectRowIndependentRefusal(offContract({ ...DT_QUERY, having: having() }), DT_ROWS);
+        expect(message).toContain(path);
+        expect(message).toContain(fragment);
+      });
+    }
+
+    it('a coarser bucket is a text label — against a date it is refused too', async () => {
+      const message = await expectRowIndependentRefusal({
+        groupBy: [{ field: 'placed_on', dateGranularity: 'month', alias: 'placed' }],
+        aggregations: [{ function: 'min', field: 'due_on', alias: 'first_due' }],
+        having: { placed: { $lte: { $field: 'first_due' } } },
+      }, DT_ROWS);
+      expect(message).toContain('"placed" is text but "first_due" is date');
+    });
+
+    // Answered exactly as before, on both doors: one class on both sides. The
+    // numeric pair is the `ANSWERED` row above ("a numeric pair with NO addDays").
+    const SAME_CLASS: ReadonlyArray<readonly [string, EngineAggregateOptions, (rows: any[]) => unknown, unknown]> = [
+      ['a day bucket against a date (date / date)', {
+        groupBy: [{ field: 'placed_on', dateGranularity: 'day', alias: 'placed' }],
+        aggregations: [{ function: 'min', field: 'due_on', alias: 'first_due' }],
+        having: { placed: { $lte: { $field: 'first_due' } } },
+      }, (rows) => rows.map((r: any) => r.placed).sort(), ['2026-01-02', '2026-01-15']],
+      ['datetime / datetime', { ...DT_QUERY, having: { last_closed: { $gt: { $field: 'first_opened' } } } }, groups, ['c1', 'c2']],
+      ['a count against a max (numeric / numeric)', { ...DT_QUERY, having: { order_count: { $gte: { $field: 'max_grace' } } } }, groups, ['c2', 'c3']],
+    ];
+
+    for (const [name, query, read, expected] of SAME_CLASS) {
+      it(`${name} answers ${JSON.stringify(expected)} on both doors`, async () => {
+        for (const [door, native] of DOORS) {
+          const { engine } = await makeEngine(DT_ROWS, native);
+          expect(read(await engine.aggregate(OBJECT, query)), door).toEqual(expected);
+        }
+      });
+    }
+
+    it('a registry-less host is not judged — the pair is answered as before, as an addDays pair is', async () => {
+      // No declaration, so no column has a type or a class: the fail-open
+      // direction #20127 took for an `addDays` pair, kept for a plain one.
+      for (const [door, native] of DOORS) {
+        const { driver } = makeDriver(DT_ROWS, native);
+        const engine = new ObjectQL();
+        engine.registerDriver(driver, true);
+        await engine.init();
+        const rows = await engine.aggregate(OBJECT, { ...DT_QUERY, having: { last_closed: { $lte: { $field: 'first_due' } } } });
+        expect(groups(rows), door).toEqual(['c1']);
+      }
+    });
+  });
 });
@@ -17318,6 +17318,10 @@ export class ObjectQL implements IObjectQLEngine {
               having,
               aggregatedRowColumns(query.groupBy, query.aggregations),
               havingColumnClasses,
+              // [#21255] …and each column's TYPE, which a plain `{ $field }`
+              // reference's class rule asks the spec's verdict of — the rule
+              // `where` applies to every reference, not only an `addDays` pair.
+              aggregatedRowColumnTypes(query.groupBy, query.aggregations, declaredFields),
           );
           // [#20263] …and last, the TEMPORAL-comparand door `where` (#8690) and
           // the per-aggregation `filter` (#20148) take: the same walk and the