@@ -0,0 +1,31 @@
+---
+"@objectstack/service-analytics": minor
+---
+
+fix(service-analytics)!: the analytics `where` door refuses a non-boolean `$null` / `$exists` flag, which it used to read as IS NOT NULL, the way every backend and the read-scope compiler already refuse it (#20040)
+
+Clause-②: no (narrowing)
+
+<!-- adr-0087: not-required (no-migration-prescription) no ADR-0087 ledger entry names the $null / $exists boolean domain: the refusals driver-sql makes (#5347, #5369) and the read-scope compiler makes (#6387) were never registered, and this change adds no new transition. It brings the analytics object-form `where`, its dataset and measure filters and the draft-data preview under the refusal every other face already makes. No ledger entry could carry it: a non-boolean flag has no boolean it can be mechanically rewritten to, because the backends disagreed on which one it meant and the string "false" is truthy. Which boolean the author meant is an authoring decision. The table below records the verdict each cell had and has; it prescribes no rewrite. -->
+
+**BREAKING**: this narrows what the analytics faces of `@objectstack/service-analytics` accept. A `$null` or `$exists` flag whose value is not a boolean used to compile, in a caller `where`, a dataset `filter` or a measure `filter`, at any depth under `$and` / `$or` / `$not` or inside a nested relation. That covers a string such as `"false"`, a number, `null`, an array, a `Date` and a `{ $field }` reference. It is now refused with `INVALID_FILTER` / 400, in a message that names the operator, the field and the path, before any SQL statement runs or any `engine.aggregate` call is made. It ships as `minor` under the launch-window convention for accept-set narrowings.
+
+| flag in an object-form `where` | before | now |
+|:--|:--|:--|
+| `$null` or `$exists` with a string, a number, `null`, an array, a `Date` or a `{ $field }` reference | read as IS NOT NULL on the native SQL path, the `/analytics/sql` echo and the ObjectQL engine path (the engine received `{ "$ne": null }`); `POST /api/v1/analytics/query` and `/analytics/dataset/query` answered 200 | refused 400: `Operator "$null" on field "stage" requires a boolean comparand (true or false). Received …` |
+| the same, under `$not` | the negation of IS NOT NULL: the rows with no value | refused 400 |
+| the same, in the draft-data preview | refused 400 as an operator the preview does not evaluate | refused 400, in the published door's words |
+| `true` or `false` | IS NULL or IS NOT NULL, per the contract | unchanged: the compiled tree, the SQL and the engine `where` are byte-identical |
+| `undefined`, or a plain object | refused 400 by the shared comparand-type face | unchanged, in that face's words |
+
+`FieldOperatorsSchema` in `@objectstack/spec` declares both flags as booleans. The #5347 and #5369 rulings refuse a non-boolean one in every position and on every backend, because the backends read one in opposite directions: `driver-sql` compiled IS NULL for anything but `false`, and the JavaScript drivers compiled IS NOT NULL for anything but `true`. `driver-sql` refuses it, and so does this package's read-scope compiler. This door read every non-boolean as IS NOT NULL, so `"true"` and `"false"` asked for the same rows, and `{ "$null": "true" }` asked for the rows it excludes.
+
+The repair is to write the boolean the filter means. `"$null": true` matches rows with no value and `"$null": false` rows with one; `$exists` is the exact inverse.
+
+Over HTTP, both routes type the `where`, the `runtimeFilter` and the inline `dataset.filter` as `FilterConditionSchema`, whose field entries are open, so the body parse admitted the flag and the service served it. Both routes now answer 400 `INVALID_FILTER` from the service, with no statement run.
+
+A `where` that carries a non-boolean flag and also a defect this compiler finds only while lowering (a field constraint mixing `$` and non-`$` keys, an operator outside the vocabulary, a zero-operator constraint) is now answered with the flag refusal. The code and status are the same 400 `INVALID_FILTER`. A shape or type defect elsewhere in the same `where` is still answered first.
+
+Who is affected: nothing in this repository's examples, seeds, docs or package sources authors a non-boolean flag. A text scan over 4598 tracked non-test files found 22 matches: 21 are code comments, and one is an operator-name lookup table in `driver-memory`, not a filter. Stored datasets, dashboard widget filters and report runtime filters in a deployment were NOT measured.
+
+Not changed: a `true` or `false` flag; the `FilterArray` spelling, whose `is_null` and `is_not_null` take their boolean from the operator name; the read-scope door, which already refused a non-boolean flag in its own withheld envelope.
@@ -112,7 +112,9 @@
  *   split, reconciled against `FieldOperatorsSchema` by the face's own test),
  *   so `{$null: undefined}` is refused rather than read as `set`. The boolean
  *   DOMAIN question for an ACCEPTED value (#5347 / #5369 / #6387) is not
- *   touched: `{$null: 'false'}` still lowers as before.
+ *   touched: `{$null: 'false'}` still lowers as before. [#20040] It does not
+ *   any more: the door refuses every non-boolean flag before any node is
+ *   built, and the case below that pinned the old reading is re-judged.
  *
  * `assertDefinedComparands` (#6386) stays as `fieldLeaves`' invariant and still
  * answers the positions the face does not judge — an `undefined` inside an
@@ -480,7 +482,7 @@ describe('[#6386] the #5146 rewrite cannot swallow the leaf — the gate side is
 });
 
 describe('[#6386] what the sweep deliberately leaves alone', () => {
-  it('$null / $exists: an undefined flag is refused by the type face; an accepted flag value reads as before', () => {
+  it('$null / $exists: an undefined flag is refused by the type face; a non-boolean accepted type is refused by the door (#20040)', () => {
     // Same call as `read-scope-sql`'s twin. ⚠️ The two modules read the flag
     // DIFFERENTLY — identity here, truthiness there. Which reading is right for
     // a non-boolean value is the boolean-DOMAIN question (#5347 / #5369,
@@ -496,14 +498,29 @@ describe('[#6386] what the sweep deliberately leaves alone', () => {
     // runs the same face. The domain question is still not decided here: the
     // face accepts every value of the six types, so an accepted non-boolean flag
     // keeps this module's identity reading, unchanged.
+    //
+    // [#20040] RE-JUDGED, the second half. The two lines that closed this case
+    // pinned `{$null: 'false'}` and `{$exists: 'yes'}` → `set` (IS NOT NULL):
+    // the identity reading of an ACCEPTED non-boolean flag, which this file
+    // kept deliberately undecided. #20040 decided it the way #5347 / #5369
+    // decided it for every backend, and #6387 for the sibling door: a
+    // non-boolean flag is REFUSED, because the backends read one in opposite
+    // directions and `'false'` is truthy. The door now refuses it before any
+    // node is built, in its `INVALID_FILTER` / 400 envelope, so the two cells
+    // are asserted as refusals below. The `undefined` half is unchanged: it is
+    // still the type face's refusal, in the face's sentence.
     for (const op of ['$null', '$exists'] as const) {
       const err = refusalFor({ d: { [op]: undefined } });
       expect(err?.code, op).toBe('INVALID_FILTER');
       expect(err?.status, op).toBe(400);
       expect(String(err?.message).startsWith(`Filter comparand at where.d.${op} is undefined.`), op).toBe(true);
     }
-    expect(treeFor({ d: { $null: 'false' } })).toEqual({ kind: 'leaf', member: 'd', operator: 'set', values: [] });
-    expect(treeFor({ d: { $exists: 'yes' } })).toEqual({ kind: 'leaf', member: 'd', operator: 'set', values: [] });
+    for (const [op, value] of [['$null', 'false'], ['$exists', 'yes']] as const) {
+      const err = refusalFor({ d: { [op]: value } });
+      expect(err?.code, op).toBe('INVALID_FILTER');
+      expect(err?.status, op).toBe(400);
+      expect(String(err?.message), op).toContain(`Operator "${op}" on field "d" requires a boolean comparand`);
+    }
   });
 
   it('a combinator with an undefined value gets its own, truer refusal', () => {