fix(spec): enforce the list-comparand rule at the shared compile face (#9228)

The #5869 rule ("a list operator takes a list") shipped at the objectql
lowering seam, so it covered every query reaching a driver THROUGH the
engine and nothing else. A caller that lowers with parseFilterAST and
calls a driver directly met no gate; mingo's coercion of a non-array
$in/$nin operand hid it until mingo 7.2.3 removed the coercion, and from
7.2.4 on the same input escapes as a raw TypeError with no code/status.

Move the one implementation into packages/spec (filter-comparand-shape.ts)
and call it from parseFilterAST, shape before type — the order the engine
seam already applied. objectql's assertListComparandShapes becomes a
delegating wrapper supplying the engine's caller prefix; parseFilterAST
takes that prefix as an optional `context`, so the array branch keeps the
message it has pinned since PR #6209. No driver behaviour is patched.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HDA9nN6nXQngoQUAAzRdMb

Author: claude

.changeset/list-comparand-shape-door.md

@@ -0,0 +1,53 @@
+---
+"@objectstack/spec": patch
+"@objectstack/objectql": patch
+---
+
+fix(spec): enforce the list-comparand rule at the shared compile face, so a scalar `in`/`nin` no longer reaches a driver (#9228)
+
+<!-- adr-0087: not-required (no-migration-prescription) No authorable key is
+added, renamed, retired or tombstoned. The change moves an existing runtime rule
+from `@objectstack/objectql` to `@objectstack/spec` and calls it from
+`parseFilterAST`; the authorable metadata surface is byte-identical. -->
+
+`FieldOperatorsSchema` has always declared `$in` / `$nin` as `z.array(z.any())`
+and `$between` as `z.tuple([min, max])`, and #5869 / PR #6209 built the gate that
+enforces it — but only at `@objectstack/objectql`'s lowering seam. That covers
+every query reaching a driver **through the engine** and nothing else. A caller
+that lowers a filter with `parseFilterAST` and calls a driver directly — an
+embedder, and this repo's own driver conformance suites — met no gate at all:
+`parseFilterAST([['name', 'notin', 'alpha']])` returned `{ name: { $nin:
+'alpha' } }`, a shape the contract forbids, and handed it over.
+
+That path was carried by mingo's own coercion of a non-array `$in`/`$nin`
+operand. mingo 7.2.3 removed the coercion, so from 7.2.4 on the same input
+escapes as an unhandled third-party `TypeError: b.filter is not a function` —
+no `code`, no `status`, no field name — straight to the caller. It is the sole
+failure blocking the `mingo` 7.2.2 -> 7.2.4 bump.
+
+**Fixed at the shared face, with exactly one implementation.** The rule now
+lives in `@objectstack/spec`'s `data/filter-comparand-shape.ts`, the same place
+the comparand-TYPE door (#7872 / PR #8234) was promoted to for the same reason
+("enforced once at the shared compile face for all five drivers"), and
+`parseFilterAST` runs it on everything it returns — shape first, then type, the
+order the engine's own seam already applied. `@objectstack/objectql`'s
+`assertListComparandShapes` is now a delegating wrapper whose only remaining job
+is the engine's `find('deal'): ` caller prefix; no driver was patched (both
+driver families are under the #5499 investment freeze).
+
+**The accept/reject delta is narrow and one-directional.** Newly refused, with
+the ADR-0112 `INVALID_FILTER` / 400 envelope: a non-array `$in` / `$nin`
+comparand and a non-`[min, max]` `$between` comparand, reaching a driver via a
+direct `parseFilterAST` call. Nothing else changes — every filter the engine
+accepted still lowers byte-identically, `$in: []` / `$nin: []` remain legitimate
+declared predicates, list MEMBER types stay unjudged here, and a field spec with
+no `$` key is still not descended into. The same inputs were already refused
+with the same envelope on every engine verb and at the REST ingress, so no
+authored metadata in the repo or in `objectui` produces a shape that newly
+fails: a survey of `examples/**`, `content/docs/**`, fixtures, seeded platform
+objects and objectui's view definitions found every membership rule already
+carrying an array.
+
+`parseFilterAST` gains an optional second argument, `context` — the caller
+prefix both doors in `@objectstack/spec` already take. It is additive and
+defaulted; existing calls are unaffected.

packages/drivers/driver-memory/src/memory-filter-ast-vocabulary.test.ts

@@ -77,10 +77,36 @@ describe('InMemoryDriver filter vocabulary ↔ VALID_AST_OPERATORS', () => {
     expect(VALID_AST_OPERATORS.size).toBeGreaterThan(0);
   });
 
+  /**
+   * [#9228] Which `$` operator an authoring spelling lowers to, derived by
+   * LOWERING one rather than by hand.
+   *
+   * `valueFor` used to name the membership spellings in a literal list, and it
+   * named three of the four: `notin` (and, had it been in the vocabulary, any
+   * later spelling) fell through to the scalar default. That handed the driver
+   * `{ name: { $nin: 'alpha' } }` — a shape the declared contract forbids —
+   * which mingo silently coerced until 7.2.3 and answers with a raw
+   * `TypeError: b.filter is not a function` from 7.2.4 on. The accident was
+   * load-bearing: it was the one probe covering the shape hole #9228 closed.
+   * Deriving the value from the spec's own lowering closes the CLASS instead of
+   * the instance — a membership spelling added to `AST_OPERATOR_MAP` tomorrow
+   * gets a list here without anyone remembering to edit this line.
+   *
+   * The probe uses a two-element array, which is legal for all three list
+   * operators, so it never trips the shape door it is used to satisfy.
+   */
+  const loweredOperatorOf = (op: string): string | undefined => {
+    const lowered = parseFilterAST([['probe', op, ['a', 'b']]]) as Record<string, unknown> | undefined;
+    const spec = lowered?.probe;
+    if (spec === null || typeof spec !== 'object' || Array.isArray(spec)) return undefined;
+    return Object.keys(spec).find((key) => key.startsWith('$'));
+  };
+
   /** A representative value per operator, so each one is actually exercised. */
   const valueFor = (op: string): unknown => {
-    if (op === 'in' || op === 'nin' || op === 'not_in') return ['alpha'];
-    if (op === 'between') return [0, 100];
+    const lowered = loweredOperatorOf(op);
+    if (lowered === '$in' || lowered === '$nin') return ['alpha'];
+    if (lowered === '$between') return [0, 100];
     if (/null|empty/.test(op)) return true;
     if (/contains|like|startswith|starts_with|endswith|ends_with/.test(op)) return 'alp';
     return 'alpha';
@@ -141,6 +167,29 @@ describe('InMemoryDriver filter vocabulary ↔ VALID_AST_OPERATORS', () => {
     expect(err.message).toContain('[min, max]');
   });
 
+  it.each([['in'], ['nin'], ['not_in'], ['notin']])(
+    '[#9228] refuses a scalar comparand on %s instead of letting it reach mingo',
+    async (op) => {
+      // The escape this card closed. `valueFor` above hands every membership
+      // spelling a list now, so nothing in this suite produces the shape any
+      // more — which is exactly why it is pinned HERE, deliberately, rather
+      // than left to the accident that used to cover it.
+      //
+      // Before #9228 the shape reached `Query.compile` and answered two ways
+      // depending on a transitive dependency's minor version: mingo <= 7.2.2
+      // coerced it and returned rows; mingo >= 7.2.3 threw
+      // `TypeError: b.filter is not a function` — no `code`, no `status`, no
+      // field name — which is why BOTH envelope halves are asserted and not
+      // just "it throws". A bare `toThrow()` here passed on 7.2.4 while the
+      // defect was wide open.
+      const err = await refusalOf(() => findAuthored([['name', op, 'alpha']]));
+      expect(err.code).toBe('INVALID_FILTER');
+      expect(err.status).toBe(400);
+      expect(err.message).toContain('requires an ARRAY');
+      expect(err.message).toContain('name');
+    },
+  );
+
   it('still honours a well-formed logical node', async () => {
     const rows = await findAuthored(['or', ['name', '=', 'alpha'], ['name', '=', 'beta']]);
     expect(rows.map((r: any) => r.id).sort()).toEqual(['1', '2']);

packages/objectql/src/engine.ts

@@ -722,7 +722,13 @@ function lowerWhereFilterArray<T extends object | undefined>(
   }
 
   // (2) The declared path.
-  const condition = parseFilterAST(where);
+  // [#9228] The context prefix is passed because `parseFilterAST` now runs the
+  // #5869 shape gate itself, one step before this branch could: a scalar `$nin`
+  // is refused DURING lowering. Handing it `${operation}('${object}')` is what
+  // keeps this branch's pinned `find('deal'): ` prefix on that refusal — and on
+  // the #7872 type door's, which `parseFilterAST` has always run and which used
+  // to answer this branch unprefixed.
+  const condition = parseFilterAST(where, `${operation}('${object}')`);
   if (condition === undefined) {
     // Unreachable by construction — `isFilterAST` accepted the shape, so
     // `parseFilterAST` has a lowering for it. Loud rather than silent because
@@ -734,11 +740,14 @@ function lowerWhereFilterArray<T extends object | undefined>(
       `unfiltered (#5158).`,
     );
   }
-  // [#5869] Door 2's half of the same check. `isFilterAST` vouched for the
-  // OPERATOR and `parseFilterAST` lowered it, but neither looks at the
-  // comparand — `['status', 'not_in', 'done']` lowers to `{status: {$nin:
-  // 'done'}}` and a scalar `$nin` is what reached the driver as a 500.
-  assertListComparandShapes(object, operation, condition);
+  // [#5869] Door 2's half of the same check USED to be a second
+  // `assertListComparandShapes(object, operation, condition)` call here.
+  // [#9228] moved the rule into `parseFilterAST` itself, which this branch
+  // calls three lines up with the same context — so the call became provably
+  // unreachable (nothing between the two can introduce a list operator) and is
+  // deleted rather than kept as a gate that reads live and never fires. The
+  // OBJECT branch above keeps its call: that `where` never passes
+  // `parseFilterAST` at all, which is the whole reason both branches exist.
   // [#8296] Same door as the object branch above, on the LOWERED condition —
   // the array sugar (`[['is_open','=',true]]`) names fields too, and a gate on
   // one branch would answer one mistake two ways depending on the spelling.