@@ -0,0 +1,59 @@
+---
+"@objectstack/spec": minor
+"@objectstack/metadata-protocol": minor
+"@objectstack/objectql": minor
+---
+
+feat(objectql,metadata-protocol): refuse a dotted filter key whose head is a relation, a formula, or a plain scalar — at both doors (#8371)
+
+<!-- adr-0087: registered engine-dotted-filter-refused -->
+
+**BREAKING** accept-set narrowing on the FILTER axis, landing after the v17.0.0
+cut (the lockstep launch-window convention ships it as `minor`; the migration
+prescription is registered under protocol major 18, where `objectstack migrate
+meta` users will look).
+
+FILTER was the last of the four query axes with no verdict for a dotted name:
+SORT refuses it (#4256), PROJECTION refuses it at both doors (#7589), while
+`where: { 'project_id.name': 'Apollo' }` cleared the unknown-field check on its
+head segment and answered `200` with zero rows. Measured across all three
+drivers before ruling (#8371): relation-head, formula-head, system-column-head
+and plain-scalar-head dotted filters return zero rows on `driver-memory`,
+`driver-sql` and `driver-mongodb` alike — a lookup stores the related record's
+scalar id, so there is no working capability for this refusal to remove; every
+answer was a silent empty list indistinguishable from an empty table, and the
+virtual case answered one unserviceable intent two ways by spelling
+(`{is_open: true}` refused since #8296, `{'is_open.x': true}` not).
+
+**What is refused:** a dotted filter key whose head field is a relation
+(`lookup`/`master_detail`/`user`/`tree`), a virtual `formula`, or a plain
+scalar — `400 INVALID_FIELD`, naming the whole offending key, at both the REST
+ingress (`assertFilterFieldsExist`) and the engine's own filter seam
+(`assertFilterIsMaterializable`, reached by saved reports, flows and dashboard
+widgets whose filters never pass the ingress). Both doors judge the head by the
+shared `@objectstack/spec/data` classification (`classifyDottedFilterHead`,
+new export), so they cannot drift apart. Precedence mirrors the sort axis:
+`unknown` > `dotted` > unmaterializable.
+
+**What stays accepted:** a dotted path into a structured/JSON head
+(`{'address.city': 'Beijing'}`) — deliberately unjudged per the ruling, since
+it genuinely works on two of three backends; array-valued and file heads, for
+the same reason; the nested-relation OBJECT form `{ owner: { region: 'NA' } }`;
+and every undotted spelling, byte-identically.
+
+## FROM → TO
+
+```ts
+// before — 200, zero rows, indistinguishable from an empty table
+await engine.find('task', { where: { 'project_id.name': 'Apollo' } });
+
+// after — 400 INVALID_FIELD naming 'project_id.name', with the remedy:
+// denormalise the value onto a stored field of the queried object and
+// filter that (or, to test the relation itself, filter the head field):
+await engine.find('task', { where: { project_id: apolloId } });
+```
+
+There is deliberately no automatic rewrite: the platform cannot invent the
+stored column the remedy prescribes, and it must not join or post-filter
+instead — the drivers have already applied `limit`/`offset`, so a post-hoc
+predicate would filter an arbitrary page.
@@ -56,6 +56,7 @@ import {
     AggregationFunction, DateGranularity, resolveSearchFieldResolution,
     SEARCHABLE_TEXTUAL_TYPES, SEARCHABLE_ENUM_TYPES, SEARCH_AUTO_EXCLUDED_FIELDS,
     isVirtualSearchField,
+    classifyDottedFilterHead,
     RUNTIME_OWNED_FIELD_TYPES,
     RPC_QUERY_ALIAS_SLOTS, foldQueryAliasSlots,
     type QueryAliasConflict, type QueryAliasSlot,
@@ -6766,6 +6767,17 @@ export class ObjectStackProtocolImplementation implements
      * honour is refused at the latest checkpoint that can see the whole
      * picture, naming the offending key path, never answered 200.
      *
+     * [#8371] THREE now — third, "can a DOTTED key's head serve a path". A
+     * dotted key with a real head rode past the first verdict on its head
+     * segment while SORT (#4256) and PROJECTION (#7589) refused the same
+     * spelling; measured on all three drivers, a relation-, virtual- or
+     * scalar-headed dotted filter matches zero rows everywhere. Judged
+     * between the two verdicts above (`unknown` > `dotted` > type — the sort
+     * axis' ladder) by the classification both doors share
+     * (`classifyDottedFilterHead`, `@objectstack/spec/data`); the
+     * structured/JSON head (`address.city`) is DELIBERATELY unjudged — see the
+     * inline note.
+     *
      * SCOPE: this is an INGRESS gate, so it covers what reaches {@link
      * findData}. The half it cannot reach — a caller handing a `where` straight
      * to `engine.find` / `findOne` / `count` / `aggregate` / `update` /
@@ -6803,7 +6815,79 @@ export class ObjectStackProtocolImplementation implements
             throw err;
         }
 
-        // [#8296] The SECOND verdict on this axis: a name that is a REAL field
+        // [#8371] The DOTTED verdict — second in precedence, mirroring the
+        // sort axis' `unknown` > `dotted` > unmaterializable ladder exactly
+        // (identity errors first, then shape, then type). A dotted key with a
+        // REAL head cleared the check above precisely BECAUSE the head is
+        // declared, then reached a driver that answers it with zero rows —
+        // measured on ALL THREE drivers (the #8371 table): a relation head
+        // stores the related record's scalar id (Mongo's dotted paths traverse
+        // embedded documents, not references), a virtual head materialises no
+        // column anywhere, a scalar head has nothing beneath it. Every answer
+        // was a silent 200 + empty list — and the virtual case answered one
+        // unserviceable intent two ways by spelling ({ is_open: true } refused
+        // below since #8296, { 'is_open.x': true } rode through).
+        //
+        // Judged by the ONE classification both doors share
+        // ({@link classifyDottedFilterHead}, `@objectstack/spec/data`), never a
+        // ladder minted here — the same one-source move the #8296 verdict below
+        // makes with `isVirtualSearchField`. ⛔ A structured/JSON head
+        // (`address.city`) answers `null` there and stays DELIBERATELY
+        // unjudged: the drivers genuinely disagree on it (live on memory and
+        // mongodb, silently empty on sql), so a refusal would delete a working
+        // capability — the carve-out the #8371 ruling names. Array-valued,
+        // file and unknown heads answer `null` for the same fail-open reason
+        // the collector documents: a hole, never a false 400.
+        //
+        // The nested-relation OBJECT form `{ owner: { region: 'NA' } }` is NOT
+        // this shape and keeps working: the collector never descends into a
+        // field key's value, so only the head `owner` is judged — undotted,
+        // real, and passed. The refusal targets the DOTTED-STRING spelling
+        // alone.
+        const dotted = names.filter(
+            (f) => f.includes('.') && classifyDottedFilterHead(gate.fields[f.split('.')[0]]) !== null,
+        );
+        if (dotted.length > 0) {
+            const first = dotted[0];
+            const head = first.split('.')[0];
+            const headDef = gate.fields[head];
+            const headClass = classifyDottedFilterHead(headDef);
+            const headType = String(headDef?.type ?? '');
+            const body = headClass === 'relation'
+                ? `filters on '${first}', which follows the relationship '${head}' into another `
+                  + `object — a filter reaches only columns of '${object}' itself, and '${head}' `
+                  + 'stores the related record\'s id, not an embedded document'
+                : headClass === 'virtual'
+                    ? `filters on '${first}', a dotted path whose head '${head}' is a virtual `
+                      + `'${headType}' field on object '${object}' — its value is computed on read, `
+                      + 'so no driver materialises a column for the path to reach into'
+                    : `filters on '${first}', a dotted path into '${head}', a '${headType}' field `
+                      + `on object '${object}' that stores a single scalar value — there is nothing `
+                      + 'beneath it for a path to reach';
+            const err: any = new Error(
+                `Query parameter '${param}' ${body}`
+                + (dotted.length > 1 ? ` (also: ${dotted.slice(1).join(', ')})` : '')
+                + '. No backend serves the path, so the predicate can only match zero records: the '
+                + 'query was refused instead of answered with an empty list.'
+                // Deliberately the same remedy, in the same words, as this
+                // axis' #8296 virtual refusal below and the SORT axis' dotted
+                // refusal (#4256/#6924), with only the verb naming this axis.
+                // One vocabulary across the doors.
+                + ` Denormalise the value onto '${object}' (a stored field, written when the source`
+                + ' changes) and filter that.',
+            );
+            err.code = 'INVALID_FIELD';
+            err.status = 400;
+            err.field = first;
+            err.fields = dotted;
+            err.object = object;
+            err.param = param;
+            throw err;
+        }
+
+        // [#8296] The unmaterializable verdict — third in precedence since
+        // #8371 slotted the dotted verdict above it, exactly where the sort
+        // axis keeps its own third verdict. A name that is a REAL field
         // of this object and still cannot be filtered on, because its TYPE
         // materialises no column. It is the FILTER axis finally growing the
         // verdict its two neighbours already have — {@link
@@ -6838,13 +6922,13 @@ export class ObjectStackProtocolImplementation implements
         // correctly — a gate widened to the spec's `COMPUTED_VALUE_TYPES` (the
         // WRITE contract) would refuse two working types.
         //
-        // PRECEDENCE — `unknown` first, then this, mirroring the sort axis'
-        // `unknown` > `dotted` > unmaterializable: identity errors before type
-        // errors. DOTTED names are deliberately NOT judged here: a dotted
-        // filter path has no verdict on this axis at all (its head being a real
-        // field is what carries it through the check above), and inventing one
-        // for the formula-headed case alone would answer two spellings of one
-        // unjudged shape differently.
+        // PRECEDENCE — `unknown` > `dotted` (#8371) > this, the sort axis'
+        // ladder verdict for verdict: identity errors before shape errors
+        // before type errors. DOTTED names are excluded HERE because the
+        // dotted verdict above already judged them — a dotted path whose head
+        // is a formula field keeps the dotted answer, exactly as it does on
+        // the sort axis (it is wrong about the shape too, and the shape is
+        // what the caller wrote).
         const virtual = names.filter((f) => !f.includes('.') && isVirtualSearchField(gate.fields[f]));
         if (virtual.length === 0) return;
         const virtualFirst = virtual[0];
 
@@ -72,7 +72,7 @@
  */
 
 import { StandardErrorCode } from '@objectstack/spec/api';
-import { isVirtualSearchField } from '@objectstack/spec/data';
+import { isVirtualSearchField, classifyDottedFilterHead } from '@objectstack/spec/data';
 
 /**
  * The operators whose comparand `FieldOperatorsSchema` declares as a list, with
@@ -350,13 +350,20 @@ function assertFieldListComparands(
  * declaration the caller can fix, and refusing one would turn a policy into a
  * 400 nobody can act on.
  *
- * SCOPE — the unmaterializable verdict ONLY. An UNKNOWN filter field is not
- * judged here: that is the ingress gate's first verdict
- * (`assertFilterFieldsExist`, #7534), the engine deliberately keeps its
- * registry-less tolerance, and widening this door to it is a separate posture
- * change on a second verdict, exactly as #7095 declined to inherit sort's
- * `unknown` and `dotted` legs. DOTTED filter paths are likewise untouched —
- * they have no verdict on this axis at either door.
+ * SCOPE — the unmaterializable verdict and, since #8371, the DOTTED-head
+ * verdict. An UNKNOWN filter field is still not judged here: that is the
+ * ingress gate's first verdict (`assertFilterFieldsExist`, #7534), the engine
+ * deliberately keeps its registry-less tolerance, and widening this door to it
+ * is a separate posture change on a second verdict, exactly as #7095 declined
+ * to inherit sort's `unknown` leg. The dotted verdict IS inherited (unlike
+ * sort's) because it is author-reachable through the exact same forwarded
+ * surfaces as the virtual one — a saved report's `query.filter` never passes
+ * the ingress — and because the #8371 measurement showed the refused head
+ * classes (relation / virtual / scalar) match zero rows on every backend, so
+ * this door refuses nothing a driver could have served. A dotted key whose
+ * head this door cannot classify — structured/JSON (the ruling's deliberate
+ * carve-out: live on two of three backends), arrays, files, heads absent from
+ * the field map — passes through unchanged.
  *
  * A registry-less host (`schema.fields` undefined) returns early, exactly as
  * the ingress gate returns early when `resolveQueryFields` cannot answer: a
@@ -377,7 +384,63 @@ export function assertFilterIsMaterializable(
 ): void {
   const fields = (schema as { fields?: Record<string, unknown> } | undefined)?.fields;
   if (!fields || typeof fields !== 'object') return;
-  const named = collectFilterFieldNames(where);
+  const { named, dotted } = collectFilterFieldNames(where);
+  if (named.length === 0 && dotted.length === 0) return;
+
+  // [#8371] The DOTTED verdict, before the virtual one — mirroring the ingress
+  // door's `unknown` > `dotted` > unmaterializable ladder, so a dotted path
+  // whose head is a formula field gets the same answer at both doors (the
+  // dotted one: it is wrong about the shape too, and the shape is what the
+  // caller wrote). Judged by the ONE classification both doors share
+  // (`classifyDottedFilterHead`, `@objectstack/spec/data`): relation, virtual
+  // and plain-scalar heads matched ZERO rows on all three drivers in the
+  // #8371 measurement, so this refusal takes nothing from anyone — it renames
+  // a silent wrong answer into a loud one. A head the classifier answers
+  // `null` for — structured/JSON (⛔ the ruling's deliberate carve-out, live
+  // on memory and mongodb), arrays, files, or a head not in this field map —
+  // passes through unchanged, the same fail-open direction the collector
+  // documents.
+  const judgedDotted = dotted.filter(
+    (f) => classifyDottedFilterHead(fields[f.split('.')[0]] as never) !== null,
+  );
+  if (judgedDotted.length > 0) {
+    const first = judgedDotted[0];
+    const head = first.split('.')[0];
+    const headDef = fields[head] as { type?: unknown } | undefined;
+    const headClass = classifyDottedFilterHead(headDef as never);
+    const headType = String(headDef?.type ?? '');
+    const body = headClass === 'relation'
+      ? `filters on '${first}', which follows the relationship '${head}' into another object — `
+        + `a filter reaches only columns of '${object}' itself, and '${head}' stores the related `
+        + 'record\'s id, not an embedded document'
+      : headClass === 'virtual'
+        ? `filters on '${first}', a dotted path whose head '${head}' is a virtual ${headType} `
+          + `field on '${object}' — its value is computed on read, so no driver materialises a `
+          + 'column for the path to reach into'
+        : `filters on '${first}', a dotted path into '${head}', a ${headType} field on `
+          + `'${object}' that stores a single scalar value — there is nothing beneath it for a `
+          + 'path to reach';
+    const dottedErr = new Error(
+      `ObjectQL.${operation}('${object}') ${body}`
+      + (judgedDotted.length > 1 ? ` (also: ${judgedDotted.slice(1).join(', ')})` : '')
+      + '. No backend serves the path, so the predicate can only match zero records: the query '
+      + 'was refused instead of answered with an empty list.'
+      // Deliberately the SAME remedy, in the same words, as the ingress
+      // door's dotted refusal and both doors' #8296 virtual refusals. One
+      // vocabulary across the doors.
+      + ` Denormalise the value onto '${object}' (a stored field, written when the source`
+      + ' changes) and filter that.',
+    ) as Error & { code?: string; status?: number; field?: string; fields?: string[]; object?: string };
+    // Same identity argument as the virtual verdict below: the question is
+    // about the NAME (its head's type), so `INVALID_FIELD`/400 — never a new
+    // code, per the #8371 ruling's own words.
+    dottedErr.status = 400;
+    dottedErr.code = StandardErrorCode.enum.INVALID_FIELD;
+    dottedErr.field = first;
+    dottedErr.fields = judgedDotted;
+    dottedErr.object = object;
+    throw dottedErr;
+  }
   if (named.length === 0) return;
   // Judged by the same `@objectstack/spec/data` predicate the SEARCH axis and
   // the ingress door use, never a list minted here, so gate and drivers cannot
@@ -435,15 +498,21 @@ export function assertFilterIsMaterializable(
  *   (`{$gte: 18}`) or a nested-relation condition (`{owner: {region: 'NA'}}`),
  *   and the latter's keys belong to a DIFFERENT object whose field map this
  *   gate has not resolved.
- * - **A DOTTED key is dropped here**, not judged on its head: this door has one
- *   verdict and a dotted filter path has none on this axis (see the scope note
- *   above).
+ * - **A DOTTED key is collected SEPARATELY** (#8371), never merged into
+ *   `named`: its verdict is its own (judged on the head's type by
+ *   `classifyDottedFilterHead`), and folding it into the undotted list would
+ *   hand `'owner.region'` to a virtual check that reads `fields['owner.region']`
+ *   — a lookup that can only miss.
  *
  * `depth` is a cheap backstop against a self-referential `where` — in-process
  * callers hand over live objects, and a gate that can hang the read path is
  * worse than the defect it closes.
  */
-function collectFilterFieldNames(where: unknown, out: string[] = [], depth = 0): string[] {
+function collectFilterFieldNames(
+  where: unknown,
+  out: { named: string[]; dotted: string[] } = { named: [], dotted: [] },
+  depth = 0,
+): { named: string[]; dotted: string[] } {
   if (depth > 32) return out;
   if (!isFilterNode(where)) return out;
   for (const [key, value] of Object.entries(where)) {
@@ -456,8 +525,8 @@ function collectFilterFieldNames(where: unknown, out: string[] = [], depth = 0):
       }
       continue;
     }
-    if (key.includes('.')) continue;
-    out.push(key);
+    if (key.includes('.')) { out.dotted.push(key); continue; }
+    out.named.push(key);
   }
   return out;
 }