@@ -0,0 +1,28 @@
+---
+"@objectstack/objectql": minor
+---
+
+fix(objectql)!: a `having` key that names no column of the aggregated row is refused on `engine.aggregate`, instead of answering as if that column had no value in every group (#20123)
+
+Clause-②: no (narrowing)
+
+<!-- adr-0087: not-required (no-migration-prescription) this change adds no transition to migrate. A `having` key that names no column of the aggregated row never had a meaning: the rows carry exactly the columns the query projects, so such a key could only ever read "no value". There is no accepted spelling it can be mechanically rewritten to — which of the query's columns the author meant is an authoring decision, and the refusal prints the list. `having` is a request-only key: no metadata type stores it, so there is no stored document for `objectstack migrate meta` to rewrite. The table below records the answer each shape had and has; it prescribes no rewrite. -->
+
+**BREAKING**: this narrows what `having` accepts on `engine.aggregate`, and on the REST aggregate query (`POST /data/:object/query`) that forwards it there. A `having` key — at any depth under `$and` / `$or` / `$not` — must name a column of the aggregated row: a groupBy projection (the field name, or a structured item's `alias`) or an aggregation alias. Any other key is refused with `INVALID_FILTER` / 400, once per query, before any driver is asked for a row, on both the native `driver.aggregate()` path and the in-memory fallback, whether or not any group exists. It ships as `minor` under the launch-window convention for accept-set narrowings.
+
+The engine evaluates `having` itself, per aggregated row, and read a key the row does not carry as a column with no value. So a typo for an alias answered like a real query. Measured on the base through `engine.aggregate` on `driver-memory` and `driver-sql`, both paths, and through `POST /data/:object/query` on both, over three groups by `customer_id`, each with a positive `total` (a `sum` alias) beside a `count` alias `n`:
+
+| `having` | before | now |
+|:--|:--|:--|
+| `{ totl: { $gt: 100 } }`, `{ totl: 500 }`, or `{ amount: { $gt: 100 } }` (a source column the aggregated row does not project) | no group, no error | refused, naming the key, its position and the query's columns |
+| `{ totl: { $ne: 1 } }`, `{ totl: { $exists: false } }`, or `{ $not: { totl: { $gt: 100 } } }` | EVERY group, no error | refused |
+| `{ $or: [{ total: { $gt: 0 } }, { totl: { $gt: 100 } }] }` | every group whose `total` is positive: the walk stopped at the branch that held | refused |
+| `{ $and: [{ total: { $gt: 0 } }, { totl: { $gt: 100 } }] }` | no group | refused |
+| `{ 'customer_id.name': 'c1' }` (a dotted path) | no group | refused |
+| `{ customer_id: 'c1' }` when the groupBy item is `{ field: 'customer_id', alias: 'cust' }` | no group: the row projects `cust` | refused; `{ cust: 'c1' }` answers |
+
+The refusal opens the way the REST ingress's refusal of an unknown `where` field does ("filters on 'totl' … which is not a column of the aggregated row"), names every unknown key, and lists the aggregated row's columns. Its code is `INVALID_FILTER`, the code of every other `having` refusal: the name is a column of the query's own projection, not a field of the object. It is judged after the rest of the clause: a condition on an unknown column that also carries an unknown operator (`{ nope: { $median: 1 } }`) is still refused for its operator first, as before.
+
+Who is affected: `having` is a request-only key (`QuerySchema.having`, `EngineAggregateOptions.having`), and no metadata type stores it. Every `having` in this repository's docs and published skills names an aggregation alias of its own query (`{ order_count: { $gt: 5 } }` and the like), which answers exactly as before. Callers of `engine.aggregate` and of the REST aggregate query in a deployment were NOT measured.
+
+Not changed: a key naming a groupBy column, a structured item's alias, a `count` / `sum` / `max` alias, or any of those under `$and` / `$or` / `$not`, answers exactly as before on both paths, measured identical before and after.
@@ -667,3 +667,86 @@ describe('[#20099] having — a { $field } reference resolves against the aggreg
     }
   });
 });
+
+// ───────────────────────────────────────────────────────────────────────────
+// [#20123] A `having` key names a column of the aggregated row
+// ───────────────────────────────────────────────────────────────────────────
+
+describe('[#20123] having — a key naming no column of the aggregated row is refused, whatever the rows', () => {
+  // `AGG_QUERY` projects exactly three columns.
+  const COLUMNS = ['customer_id', 'order_count', 'total'];
+
+  // Before, measured through `engine.aggregate` on driver-memory and
+  // driver-sql, both doors, and through `POST /data/:object/query`: no row
+  // raised anything. A test for a value kept no group; a test for absence or
+  // a negation — and a `$or` whose first branch held — kept EVERY group.
+  const UNKNOWN_KEY: ReadonlyArray<readonly [string, () => Record<string, unknown>, string, string]> = [
+    ['a typo for an alias under $gt (the triage shape)', () => ({ totl: { $gt: 100 } }), 'totl', 'having.totl'],
+    ['a typo in the implicit-equality slot', () => ({ totl: 500 }), 'totl', 'having.totl'],
+    ['a typo under $ne', () => ({ totl: { $ne: 1 } }), 'totl', 'having.totl'],
+    ['a typo under $exists: false', () => ({ totl: { $exists: false } }), 'totl', 'having.totl'],
+    ['a typo nested in $and', () => ({ $and: [{ total: { $gt: 0 } }, { totl: { $gt: 100 } }] }), 'totl', 'having.$and[1].totl'],
+    ['a typo behind a $or branch that already held', () => ({ $or: [{ total: { $gt: 0 } }, { totl: { $gt: 100 } }] }), 'totl', 'having.$or[1].totl'],
+    ['a typo under $not', () => ({ $not: { totl: { $gt: 100 } } }), 'totl', 'having.$not.totl'],
+    ['a SOURCE column the aggregated row does not project', () => ({ amount: { $gt: 100 } }), 'amount', 'having.amount'],
+    ['a dotted path', () => ({ 'customer_id.name': 'c1' }), 'customer_id.name', 'having.customer_id.name'],
+    ['a key that also carries a { $field } reference', () => ({ totl: { $gt: { $field: 'total' } } }), 'totl', 'having.totl'],
+  ];
+
+  for (const [name, having, key, path] of UNKNOWN_KEY) {
+    it(`${name}: refused at ${path}, naming the columns`, async () => {
+      const message = await expectRowIndependentRefusal(offContract({ ...AGG_QUERY, having: having() }), ROWS);
+      expect(message).toContain(`'${key}' at ${path}`);
+      for (const column of COLUMNS) expect(message).toContain(column);
+    });
+  }
+
+  it('every unknown key is named — the first with its position, the rest after it', async () => {
+    const message = await expectRowIndependentRefusal(
+      offContract({ ...AGG_QUERY, having: { $and: [{ totl: 1 }, { cnt: { $gt: 1 } }, { totl: 2 }] } }), ROWS);
+    expect(message).toContain("'totl' at having.$and[0].totl");
+    expect(message).toContain('(also: cnt)');
+  });
+
+  it('an operator refusal on an unknown column is still the operator\'s — the key is judged last', async () => {
+    // The #20099 rule: a condition on a column the row does not carry is read
+    // for its operator. Held here so the new check cannot jump ahead of it.
+    const floor = syncRefusalOf(() => applyHaving([{ nope: 1 }], { nope: { $median: 1 } } as FilterCondition));
+    const message = await expectRowIndependentRefusal(offContract({ ...AGG_QUERY, having: { nope: { $median: 1 } } }), ROWS);
+    expect(message).toBe(floor!.message);
+  });
+
+  it('the source name of an ALIASED groupBy projection is not a column — its alias is', async () => {
+    // Before: `{ customer_id: 'c1' }` kept no group — the row projects `cust`.
+    const query = (having: FilterCondition): EngineAggregateOptions => ({
+      groupBy: [{ field: 'customer_id', alias: 'cust' }],
+      aggregations: [{ function: 'count', alias: 'order_count' }],
+      having,
+    });
+    const message = await expectRowIndependentRefusal(query({ customer_id: 'c1' }), ROWS);
+    expect(message).toContain("'customer_id' at having.customer_id");
+    expect(message).toContain('cust, order_count');
+    // The alias itself answers, on the door that projects it (the stand-in
+    // native driver groups by `customer_id` and ignores the alias).
+    const { engine } = await makeEngine(ROWS, false);
+    const rows = await engine.aggregate(OBJECT, query({ cust: 'c1' }));
+    expect(rows).toEqual([{ cust: 'c1', order_count: 2 }]);
+  });
+
+  // Every key names a column: answered exactly as before, both doors.
+  const PASSING: ReadonlyArray<readonly [string, FilterCondition, readonly string[]]> = [
+    ['a groupBy column', { customer_id: 'c1' }, ['c1']],
+    ['an aggregation alias', { total: { $gt: 100 } }, ['c1', 'c2']],
+    ['a count alias', { order_count: { $gte: 2 } }, ['c1', 'c2']],
+    ['columns nested under $or / $and / $not', { $or: [{ total: { $gt: 1000 } }, { $and: [{ $not: { customer_id: 'c1' } }, { order_count: 1 }] }] }, ['c2', 'c3']],
+    ['a negation of a column', { total: { $ne: 500 } }, ['c2', 'c3']],
+  ];
+  for (const [name, having, expected] of PASSING) {
+    it(`${name} answers ${JSON.stringify(expected)} on both doors`, async () => {
+      for (const [door, native] of DOORS) {
+        const { engine } = await makeEngine(ROWS, native);
+        expect(groups(await engine.aggregate(OBJECT, { ...AGG_QUERY, having })), door).toEqual([...expected]);
+      }
+    });
+  }
+});
@@ -16070,7 +16070,10 @@ export class ObjectQL implements IObjectQLEngine {
       //     position and name, judged against the aggregated row's column set
       //     read off THIS query (`assertHavingIsEvaluable`). The walker raised
       //     them per aggregated row, so an empty grouped set answered `200 []`
-      //     for a `having` a populated one refused.
+      //     for a `having` a populated one refused. [#20123] The same column
+      //     set judges every KEY too: a key naming no column read "no value"
+      //     in every group, so a typo for an alias kept no group (every group
+      //     under a negation) with no error.
       // A reference that passes is then RESOLVED against each aggregated row
       // (having-filter.ts `compareWithReference`) on both doors below.
       assertHavingIsFilterCondition(query.having);
 
@@ -414,6 +414,43 @@ function malformedFieldReferenceError(path: string, detail: string): Error {
   return invalidFilterError(`The { "$field" } reference at ${path} is malformed: ${detail}`);
 }
 
+/**
+ * [#20123] A `having` KEY that names no column of the aggregated row — the
+ * twin of {@link unresolvedFieldReferenceError} for the other place a column
+ * is named.
+ *
+ * Refused on the filter, never answered per row: {@link checkCondition} reads
+ * such a key as a column with NO VALUE in every group, so a typo for an alias
+ * (`{ totl: { $gt: 100 } }`) kept no group and a negated test on it
+ * (`$ne`, `$exists: false`, a `$not`) kept every group — an answer
+ * indistinguishable from a real one. It is the same mistake the REST
+ * ingress refuses on `where` for a field the object does not have, and the
+ * opening words follow that refusal's ("filters on 'X', which is not a …";
+ * "the query was refused instead of answered"). The code stays this face's
+ * own `INVALID_FILTER`: the name is a column of the QUERY's own projection,
+ * not a field of the object, which is what `INVALID_FIELD` answers about.
+ *
+ * Every unknown key is named, the first with its position, and the column
+ * list is printed because it is the author's own query, and it is the answer.
+ */
+function unknownHavingColumnError(
+  unknown: ReadonlyArray<{ key: string; path: string }>,
+  columns: readonly string[],
+): Error {
+  const [first] = unknown;
+  const others = [...new Set(unknown.map((u) => u.key))].filter((key) => key !== first.key);
+  const also = others.length ? ` (also: ${others.join(', ')})` : '';
+  const known = columns.length ? columns.join(', ') : '(none — the query projects no column)';
+  return invalidFilterError(
+    `\`having\` filters on '${first.key}' at ${first.path}, which is not a column of the aggregated `
+    + `row${also}. A condition on a column the row does not carry is answered as if that column had no `
+    + `value in every group — a test for a value keeps no group, and a test for its absence or a `
+    + `negation keeps every group — so the query was refused instead of answered. \`having\` filters `
+    + `the aggregated row's own columns — the groupBy projections and the aggregation aliases — which `
+    + `here are: ${known}.`,
+  );
+}
+
 /**
  * [#5905] Operators whose answer for a column with NO VALUE is decided by the
  * operator's own arm below, not by the early exit in {@link checkCondition}.
@@ -496,13 +533,22 @@ export function assertHavingIsFilterCondition(having: unknown): void {
  * - a reference outside the six scalar comparisons —
  *   {@link fieldReferencePositionError};
  * - a reference its declaration refuses (a malformed `addDays`), or one naming
- *   no column of the aggregated row — {@link unresolvedFieldReferenceError}.
+ *   no column of the aggregated row — {@link unresolvedFieldReferenceError};
+ * - [#20123] and, once the whole clause has passed those, a KEY naming no
+ *   column of the aggregated row, at any depth —
+ *   {@link unknownHavingColumnError}. Last on purpose: a condition on a column
+ *   the row does not carry is still read for its operator first (the #20099
+ *   rule above), so the refusal an author meets for `{ nope: { $median: 1 } }`
+ *   is the operator's, and fixing it does not reveal a second one they could
+ *   have been told about already.
  *
  * Read-only; `having` is assumed to have passed
  * {@link assertHavingIsFilterCondition}.
  */
 export function assertHavingIsEvaluable(having: unknown, columns: readonly string[]): void {
-  assertNodeIsEvaluable(having, 'having', { clause: HAVING_CLAUSE, columns });
+  const unknownKeys: Array<{ key: string; path: string }> = [];
+  assertNodeIsEvaluable(having, 'having', { clause: HAVING_CLAUSE, columns, unknownKeys });
+  if (unknownKeys.length > 0) throw unknownHavingColumnError(unknownKeys, columns);
 }
 
 /**
@@ -537,16 +583,18 @@ export function assertAggregationFilterIsEvaluable(filter: unknown, index: numbe
 /**
  * [#20122] What one row-independent walk judges against: the clause whose
  * words its refusals use, and — where the position has a closed namespace —
- * the column set a `{ $field }` reference must name.
+ * the column set a key and a `{ $field }` reference must name.
  */
 interface EvaluableScope {
   clause: FilterClause;
   /**
-   * The names a `{ $field }` reference may take. `undefined` when the position
-   * has no closed column set to judge a name against (the per-aggregation
-   * filter reads the object's raw columns).
+   * The names a key and a `{ $field }` reference may take. `undefined` when
+   * the position has no closed column set to judge a name against (the
+   * per-aggregation filter reads the object's raw columns).
    */
   columns?: readonly string[];
+  /** [#20123] Keys naming none of `columns`, collected in walk order. */
+  unknownKeys?: Array<{ key: string; path: string }>;
 }
 
 /** One node: the `$and` / `$or` / `$not` walk {@link matchesHaving} takes. */
@@ -565,6 +613,9 @@ function assertNodeIsEvaluable(cond: unknown, path: string, scope: EvaluableScop
     }
     if (key.startsWith('$')) throw unknownOperator(key, 'logical', [], scope.clause);
     assertConditionIsEvaluable(value, key, here, scope);
+    // [#20123] Rows carry exactly the columns the query projects, so a key
+    // outside them can only ever read "no value" — see unknownHavingColumnError.
+    if (scope.columns && !scope.columns.includes(key)) scope.unknownKeys?.push({ key, path: here });
   }
 }