@object-ui/data-objectstack 16.1.0 → 17.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/data-objectstack",
-  "version": "16.1.0",
+  "version": "17.1.0",
   "description": "ObjectStack Data Adapter for Object UI",
   "license": "MIT",
   "type": "module",
@@ -22,11 +22,12 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@objectstack/client": "^16.0.0-rc.0",
-    "@object-ui/core": "16.1.0",
-    "@object-ui/types": "16.1.0"
+    "@objectstack/client": "^17.0.0-rc.0",
+    "@object-ui/core": "17.1.0",
+    "@object-ui/types": "17.1.0"
   },
   "devDependencies": {
+    "@objectstack/spec": "^17.0.0-rc.0",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"

package/src/aggregate-capability.test.ts

@@ -0,0 +1,177 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * `aggregate()` against an analytics endpoint that cannot answer.
+ *
+ * WHY THIS EXISTS. `@objectstack/client`'s `analytics.query()` returns
+ * `res.json()` WITHOUT checking `res.ok`, so a non-2xx never throws — the error
+ * body arrives where rows were expected. The adapter's row parser matched none
+ * of its shapes, produced `[]`, and returned it as a RESULT: the `catch` that
+ * promises a client-side fallback never ran, and a KPI on a deployment without
+ * `@objectstack/service-analytics` rendered a confident **zero**.
+ *
+ * That is the same lie framework#3891 removed from the server side (a degraded
+ * shim answering 200 with unscoped numbers), reproduced one layer up. These
+ * tests pin the three outcomes:
+ *   - capability absent (404 / 501)  → client-side fallback over a scoped find();
+ *   - our body is off-contract (400) → THROWS, never silently re-answered;
+ *   - a normal result                → untouched.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { ObjectStackAdapter, clearSharedDiscoveryCache } from './index';
+
+const RECORDS = [
+  { id: '1', stage: 'won', amount: 100 },
+  { id: '2', stage: 'won', amount: 50 },
+  { id: '3', stage: 'lost', amount: 20 },
+];
+
+/**
+ * A fetch mock answering discovery, the analytics query (with `analyticsBody`
+ * at `analyticsStatus`), and the `/data` read the fallback performs.
+ */
+function makeFetch(analyticsStatus: number, analyticsBody: unknown) {
+  const calls: string[] = [];
+  const fetchImpl = vi.fn(async (url: any, init?: any) => {
+    const u = String(url);
+    calls.push(`${init?.method ?? 'GET'} ${u}`);
+    if (u.includes('/api/v1/discovery')) {
+      return { ok: true, status: 200, statusText: 'OK', json: async () => ({ success: true, data: { version: 'v1', routes: {} } }) } as any;
+    }
+    if (u.includes('/api/v1/analytics/query')) {
+      return {
+        ok: analyticsStatus >= 200 && analyticsStatus < 300,
+        status: analyticsStatus,
+        statusText: 'x',
+        json: async () => analyticsBody,
+      } as any;
+    }
+    // The fallback's scoped read.
+    return {
+      ok: true, status: 200, statusText: 'OK',
+      json: async () => ({ success: true, data: { object: 'opportunity', records: RECORDS, total: RECORDS.length } }),
+    } as any;
+  });
+  return { fetchImpl, calls };
+}
+
+function makeAdapter(fetchImpl: any) {
+  return new ObjectStackAdapter({
+    baseUrl: 'http://localhost:3000',
+    autoReconnect: false,
+    fetch: fetchImpl as any,
+  });
+}
+
+const SUM_BY_STAGE = { function: 'sum', field: 'amount', groupBy: 'stage' };
+
+describe('aggregate() when the analytics capability is absent', () => {
+  beforeEach(() => clearSharedDiscoveryCache());
+
+  it('404 (routes not mounted, framework#4019) falls back instead of returning an empty result', async () => {
+    const { fetchImpl, calls } = makeFetch(404, { error: 'Not found' });
+    const rows = await makeAdapter(fetchImpl).aggregate('opportunity', SUM_BY_STAGE);
+
+    // Pre-fix this was `[]` — a chart reading "no data" on a populated table.
+    expect(rows.length).toBeGreaterThan(0);
+    const won = rows.find((r: any) => r.stage === 'won');
+    expect(won?.amount).toBe(150);
+    // It really did fall back to a server-side read (not invent numbers).
+    expect(calls.some((c) => c.includes('/api/v1/data'))).toBe(true);
+  });
+
+  it('501 NOT_IMPLEMENTED (REST route, no service) falls back the same way', async () => {
+    const { fetchImpl } = makeFetch(501, {
+      code: 'NOT_IMPLEMENTED',
+      message: 'Analytics is not available on this deployment.',
+    });
+    const rows = await makeAdapter(fetchImpl).aggregate('opportunity', SUM_BY_STAGE);
+    expect(rows.find((r: any) => r.stage === 'won')?.amount).toBe(150);
+  });
+
+  it('warns ONCE per adapter, not once per widget', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const { fetchImpl } = makeFetch(404, { error: 'Not found' });
+      const adapter = makeAdapter(fetchImpl);
+      await adapter.aggregate('opportunity', SUM_BY_STAGE);
+      await adapter.aggregate('opportunity', SUM_BY_STAGE);
+      await adapter.aggregate('opportunity', SUM_BY_STAGE);
+
+      const capabilityWarnings = warn.mock.calls.filter((c) =>
+        String(c[0]).includes('analytics capability unavailable'),
+      );
+      expect(capabilityWarnings).toHaveLength(1);
+      expect(String(capabilityWarnings[0][0])).toContain('@objectstack/service-analytics');
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it('forwards the widget filter into the fallback (never aggregates the whole table)', async () => {
+    const { fetchImpl, calls } = makeFetch(404, { error: 'Not found' });
+    await makeAdapter(fetchImpl).aggregate('opportunity', { ...SUM_BY_STAGE, filter: { stage: 'won' } });
+
+    const dataCall = calls.find((c) => c.includes('/api/v1/data'));
+    expect(dataCall).toBeDefined();
+    expect(decodeURIComponent(dataCall!)).toContain('won');
+  });
+});
+
+describe('aggregate() when the server REJECTS our query body', () => {
+  beforeEach(() => clearSharedDiscoveryCache());
+
+  // framework#4010 validates /analytics/query at the entry. A 400 means the
+  // adapter sent an off-contract body — answering it with numbers from the
+  // client-side path would bury our own bug behind plausible output, which is
+  // exactly the misdirection framework#3878 documented.
+  it('400 VALIDATION_FAILED throws — it must NOT be answered by the fallback', async () => {
+    const { fetchImpl, calls } = makeFetch(400, {
+      success: false,
+      error: {
+        code: 'VALIDATION_FAILED',
+        httpStatus: 400,
+        message: 'Invalid AnalyticsQuery body: measures: Invalid input',
+        details: { fields: [{ field: 'measures', code: 'invalid_type' }] },
+      },
+    });
+
+    const err = await makeAdapter(fetchImpl).aggregate('opportunity', SUM_BY_STAGE).catch((e) => e);
+
+    expect(err).toBeInstanceOf(Error);
+    expect((err as { code?: string }).code).toBe('ANALYTICS_QUERY_REJECTED');
+    expect(String(err.message)).toContain('measures');
+    // No silent second answer from a different code path.
+    expect(calls.some((c) => c.includes('/api/v1/data'))).toBe(false);
+  });
+});
+
+describe('aggregate() on a healthy analytics endpoint', () => {
+  beforeEach(() => clearSharedDiscoveryCache());
+
+  it('returns the server rows untouched (no false capability detection)', async () => {
+    const { fetchImpl, calls } = makeFetch(200, {
+      rows: [{ stage: 'won', amount_sum: 150 }],
+      fields: [{ name: 'amount_sum', type: 'number' }],
+    });
+
+    const rows = await makeAdapter(fetchImpl).aggregate('opportunity', SUM_BY_STAGE);
+
+    // Measure key mapped back to the caller's column (`amount`), rows from the server.
+    expect(rows).toEqual([{ stage: 'won', amount: 150 }]);
+    expect(calls.some((c) => c.includes('/api/v1/data'))).toBe(false);
+  });
+
+  it('a `{ success, data: { rows } }` envelope is still a result, not an error', async () => {
+    const { fetchImpl } = makeFetch(200, { success: true, data: { rows: [{ stage: 'won', amount_sum: 150 }] } });
+    const rows = await makeAdapter(fetchImpl).aggregate('opportunity', SUM_BY_STAGE);
+    expect(rows).toEqual([{ stage: 'won', amount: 150 }]);
+  });
+});

package/src/exportDownload.test.ts

@@ -97,3 +97,45 @@ describe('ObjectStackAdapter.exportDownload', () => {
     });
   });
 });
+
+/**
+ * `search` — the half of a list this request could not carry.
+ *
+ * The route mirrored `filter` and `orderby` only, so an export taken while a
+ * search was active downloaded the UNSEARCHED superset: more rows than the
+ * screen showed, in a file that looks authoritative. Server half:
+ * objectstack#4230.
+ */
+describe('ObjectStackAdapter.exportDownload — search', () => {
+  const paramsFor = async (request: Record<string, unknown>) => {
+    const fetchImpl = vi.fn(async (_url: string, _init: RequestInit) => csvResponse());
+    await makeDS(fetchImpl).exportDownload('task', request);
+    return new URL(fetchImpl.mock.calls[0][0]).searchParams;
+  };
+
+  it('sends the term as `search`', async () => {
+    expect((await paramsFor({ search: 'acme' })).get('search')).toBe('acme');
+  });
+
+  it('sends `searchFields` as a comma list alongside the term', async () => {
+    const p = await paramsFor({ search: 'acme', searchFields: ['name', 'stage'] });
+    expect(p.get('searchFields')).toBe('name,stage');
+  });
+
+  it('omits both when no term is given — `searchFields` alone means nothing', async () => {
+    const p = await paramsFor({ searchFields: ['name'] });
+    expect(p.get('search')).toBeNull();
+    expect(p.get('searchFields')).toBeNull();
+  });
+
+  it('treats a whitespace-only term as absent, and trims a real one', async () => {
+    expect((await paramsFor({ search: '   ' })).get('search')).toBeNull();
+    expect((await paramsFor({ search: '  acme  ' })).get('search')).toBe('acme');
+  });
+
+  it('carries search and filter together — neither replaces the other', async () => {
+    const p = await paramsFor({ search: 'acme', filter: [['status', '=', 'open']] });
+    expect(p.get('search')).toBe('acme');
+    expect(JSON.parse(p.get('filter')!)).toEqual([['status', '=', 'open']]);
+  });
+});

package/src/filter-entry-translation.test.ts

@@ -0,0 +1,360 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Object-form filter entries (`[{ field, operator, value }, ...]`) → filter AST.
+ *
+ * `find()` has TWO routes to the server and both translate the filter: a plain
+ * read goes through `convertQueryParams`, while a read with `$expand`/`$search`
+ * goes through `rawFindWithPopulate`. They used to carry independent copies of
+ * the "is this object form?" test, and the copies had already drifted — so the
+ * tests below run every case down BOTH routes and assert they agree.
+ *
+ * The stakes are the same as objectstack#3948: a filter this layer fails to
+ * translate is not a filter it may skip. Skipping one entry of an `and` returns
+ * a superset of the rows asked for, and skipping the last one sends no filter
+ * at all — every row in the table, reported as success.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { isFilterAST } from '@objectstack/spec/data';
+import { ObjectStackAdapter, clearSharedDiscoveryCache, isMalformedFilterError } from './index';
+
+function makeAdapter() {
+  const calls: string[] = [];
+  const fetchImpl = vi.fn(async (url: any) => {
+    const u = String(url);
+    calls.push(u);
+    if (u.includes('/api/v1/discovery')) {
+      return {
+        ok: true, status: 200, statusText: 'OK',
+        json: async () => ({ success: true, data: { version: 'v1', routes: {} } }),
+      } as any;
+    }
+    return {
+      ok: true, status: 200, statusText: 'OK',
+      json: async () => ({ success: true, data: { object: 'account', records: [], total: 0 } }),
+    } as any;
+  });
+  const adapter = new ObjectStackAdapter({
+    baseUrl: 'http://localhost:3000', token: 't', autoReconnect: false, fetch: fetchImpl as any,
+  });
+  return { adapter, calls };
+}
+
+/** The `filter=` this filter produced on the wire, or `undefined` if none was sent. */
+async function filterOnWire(
+  $filter: unknown,
+  route: 'plain' | 'expand',
+): Promise<unknown | undefined> {
+  const { adapter, calls } = makeAdapter();
+  await adapter.find('account', {
+    $filter,
+    ...(route === 'expand' ? { $expand: ['owner'] } : {}),
+  } as any);
+  const dataCall = calls.filter((u) => u.includes('/data/account')).pop();
+  const raw = dataCall ? new URL(dataCall).searchParams.get('filter') : null;
+  return raw === null ? undefined : JSON.parse(raw);
+}
+
+/** Run one input down both `find()` routes. */
+function bothRoutes(name: string, $filter: unknown, assert: (wire: unknown | undefined) => void) {
+  for (const route of ['plain', 'expand'] as const) {
+    it(`${name} (${route} route)`, async () => assert(await filterOnWire($filter, route)));
+  }
+}
+
+async function findRejects($filter: unknown, route: 'plain' | 'expand') {
+  const { adapter } = makeAdapter();
+  return adapter
+    .find('account', { $filter, ...(route === 'expand' ? { $expand: ['owner'] } : {}) } as any)
+    .then(() => null, (e) => e);
+}
+
+describe('object-form filter entries reach the wire as an AST', () => {
+  beforeEach(() => clearSharedDiscoveryCache());
+
+  bothRoutes(
+    'translates a single rule, mapping the operator alias',
+    [{ field: 'stage', operator: 'greater_than_or_equal', value: 3 }],
+    (wire) => expect(wire).toEqual(['stage', '>=', 3]),
+  );
+
+  bothRoutes(
+    'joins several rules with `and`',
+    [
+      { field: 'stage', operator: 'eq', value: 'won' },
+      { field: 'amount', operator: 'gt', value: 100 },
+    ],
+    (wire) => expect(wire).toEqual(['and', ['stage', '=', 'won'], ['amount', '>', 100]]),
+  );
+
+  bothRoutes(
+    'accepts the `op` shorthand key',
+    [{ field: 'owner', op: 'eq', value: 'me' }],
+    (wire) => expect(wire).toEqual(['owner', '=', 'me']),
+  );
+
+  bothRoutes(
+    'passes an AST tuple through untouched',
+    ['stage', '=', 'won'],
+    (wire) => expect(wire).toEqual(['stage', '=', 'won']),
+  );
+
+  bothRoutes(
+    'passes a logical AST node through untouched',
+    ['or', ['stage', '=', 'won'], ['stage', '=', 'lost']],
+    (wire) => expect(wire).toEqual(['or', ['stage', '=', 'won'], ['stage', '=', 'lost']]),
+  );
+
+  bothRoutes('sends no filter at all for an empty array', [], (wire) => expect(wire).toBeUndefined());
+});
+
+describe('a `name`-keyed entry is not an accepted shape', () => {
+  beforeEach(() => clearSharedDiscoveryCache());
+
+  /**
+   * `objectFilterEntryToAST` read `entry.field ?? entry.name` while the shape
+   * sniff keyed on `field` alone, so the `name` half could never be reached —
+   * dead from the commit that introduced it. The spec agrees it is not a real
+   * shape: `ViewFilterRuleSchema.field` is required, so such a rule cannot be
+   * saved as view metadata. It reaches the server unchanged and is refused
+   * there (objectstack#4121) rather than being quietly half-understood here.
+   */
+  bothRoutes(
+    'is passed through rather than translated',
+    [{ name: 'stage', operator: 'eq', value: 'won' }],
+    (wire) => expect(wire).toEqual([{ name: 'stage', operator: 'eq', value: 'won' }]),
+  );
+});
+
+describe('an untranslatable entry fails instead of narrowing the filter', () => {
+  beforeEach(() => clearSharedDiscoveryCache());
+
+  for (const route of ['plain', 'expand'] as const) {
+    it(`rejects a rule with a blank field rather than dropping it (${route})`, async () => {
+      // Survives `ViewFilterRuleSchema` (`field: z.string()` admits ''), so it
+      // can be genuine stored metadata. It used to be dropped, and dropping the
+      // only rule sent no filter — the whole table came back.
+      const err = await findRejects([{ field: '', operator: 'eq', value: 'x' }], route);
+      expect(err).toBeInstanceOf(Error);
+      expect(isMalformedFilterError(err)).toBe(true);
+    });
+
+    it(`rejects a bad entry rather than silently widening the AND (${route})`, async () => {
+      const err = await findRejects(
+        [
+          { field: 'stage', operator: 'eq', value: 'won' },
+          { field: 'amount', operator: 42 as any, value: 1 },
+        ],
+        route,
+      );
+      expect(isMalformedFilterError(err)).toBe(true);
+      // Names which entry, so the author can find it in the view config.
+      expect(String((err as Error).message)).toContain('entry 1');
+    });
+  }
+
+  it('carries the status and code that classify it as a rejected request', async () => {
+    const err: any = await findRejects([{ field: '', operator: 'eq' }], 'plain');
+    // plugin-list's `classifyLoadError` reads these to pick the error panel;
+    // without them a malformed filter reads as "check your connection" (#3066).
+    expect(err.code).toBe('INVALID_FILTER');
+    expect(err.httpStatus).toBe(400);
+  });
+});
+
+describe('object-form rules nested inside a logical node are translated too', () => {
+  beforeEach(() => clearSharedDiscoveryCache());
+
+  /**
+   * This is what a list builds the moment a view with a stored filter meets a
+   * user filter from the panel — `['and', <ViewFilterRule[]>, <AST tuples>]`.
+   * Translating only the top level shipped the rules raw, and the server has no
+   * good answer for that: `isFilterAST` rejects the shape (so a server with
+   * objectstack#4121 returns 400 and the list fails to load), while
+   * `parseFilterAST` on the same array returns `{ amount: { $gt: 1 } }` — the
+   * view's own `stage = won` dropped without a word.
+   */
+  bothRoutes(
+    'translates a rule group nested under `and`',
+    ['and', [{ field: 'stage', operator: 'eq', value: 'won' }], [['amount', '>', 1]]],
+    (wire) => expect(wire).toEqual(['and', ['stage', '=', 'won'], [['amount', '>', 1]]]),
+  );
+
+  bothRoutes(
+    'translates under `or`, and through more than one level',
+    ['or', ['and', [{ field: 'stage', operator: 'not_in', value: ['lost'] }]], ['x', '=', 1]],
+    (wire) => expect(wire).toEqual(['or', ['and', ['stage', 'nin', ['lost']]], ['x', '=', 1]]),
+  );
+
+  bothRoutes(
+    'translates a group inside a legacy flat array of children',
+    [[{ field: 'stage', operator: 'eq', value: 'won' }], ['amount', '>', 1]],
+    (wire) => expect(wire).toEqual([['stage', '=', 'won'], ['amount', '>', 1]]),
+  );
+
+  bothRoutes(
+    'leaves a field literally named `and` alone',
+    ['and', '=', true],
+    (wire) => expect(wire).toEqual(['and', '=', true]),
+  );
+
+  /**
+   * A mixed array used to lose the tuple: it did not translate as a rule, so it
+   * was filtered out and the query ran on the remaining condition alone —
+   * broader than asked for. Keep both rather than dropping one or failing the
+   * whole query.
+   */
+  bothRoutes(
+    'keeps both halves of a rule/tuple mixed array',
+    [{ field: 'stage', operator: 'eq', value: 'won' }, ['amount', '>', 1]],
+    (wire) => expect(wire).toEqual(['and', ['stage', '=', 'won'], ['amount', '>', 1]]),
+  );
+
+  it('rejects a malformed rule nested under `and` as well', async () => {
+    const err = await findRejects(['and', [{ field: '', operator: 'eq', value: 1 }]], 'plain');
+    expect(isMalformedFilterError(err)).toBe(true);
+  });
+});
+
+describe('what this adapter emits passes the server’s own gate', () => {
+  beforeEach(() => clearSharedDiscoveryCache());
+
+  /**
+   * The real contract is not a literal shape, it is "the server accepts this".
+   * `isFilterAST` is the function the protocol gates on, so assert against it
+   * directly rather than restating what it happens to accept today — a filter
+   * it rejects is a 400 (objectstack#4121), and was an unfiltered query before
+   * that (objectstack#3948).
+   */
+  const TRANSLATABLE: Array<[string, unknown]> = [
+    ['a single rule', [{ field: 'stage', operator: 'eq', value: 'won' }]],
+    ['several rules', [
+      { field: 'stage', operator: 'contains', value: 'w' },
+      { field: 'amount', operator: 'less_than_or_equal', value: 9 },
+    ]],
+    ['rules under `and` beside a tuple', [
+      'and', [{ field: 'stage', operator: 'before', value: '2024-01-01' }], ['amount', '>', 1],
+    ]],
+    ['rules inside a legacy flat array', [
+      [{ field: 'stage', operator: 'is_null', value: true }], ['amount', '>', 1],
+    ]],
+    ['a mixed rule/tuple array', [{ field: 'stage', operator: 'eq', value: 'won' }, ['a', '>', 1]]],
+  ];
+
+  for (const [name, input] of TRANSLATABLE) {
+    for (const route of ['plain', 'expand'] as const) {
+      it(`${name} → accepted by isFilterAST (${route})`, async () => {
+        expect(isFilterAST(await filterOnWire(input, route))).toBe(true);
+      });
+    }
+  }
+});
+
+describe('a bare rule object directly under a logical node', () => {
+  beforeEach(() => clearSharedDiscoveryCache());
+
+  /**
+   * Produced by any caller that SPREADS a `ViewFilterRule[]` into an `and`
+   * rather than wrapping it — `['and', ...rules, ...tuples]`. The rules land as
+   * bare objects where the AST expects nodes, `isFilterAST` rejects the whole
+   * node (a 400 since objectstack#4121), and `parseFilterAST` reads the rule as
+   * a Mongo condition on columns literally named `field`/`operator`/`value`.
+   * objectui's own producer was fixed to wrap; this is the chokepoint defence.
+   */
+  bothRoutes(
+    'is translated in place',
+    ['and', { field: 'stage', operator: 'eq', value: 'won' }, ['owner', '=', 'me']],
+    (wire) => expect(wire).toEqual(['and', ['stage', '=', 'won'], ['owner', '=', 'me']]),
+  );
+
+  bothRoutes(
+    'leaves a genuine MongoDB condition child alone',
+    // No `field` key, so it is a condition on a column named `status` — not a
+    // rule. Translating it would invent a filter the caller never wrote.
+    ['and', { status: 'active' }, ['owner', '=', 'me']],
+    (wire) => expect(wire).toEqual(['and', { status: 'active' }, ['owner', '=', 'me']]),
+  );
+});
+
+describe('an OBJECT filter reaches the same predicate on both routes', () => {
+  beforeEach(() => clearSharedDiscoveryCache());
+
+  /**
+   * The array branch was single-sourced in #3072; the object branch was not.
+   * `convertQueryParams` converted a MongoDB-style filter to AST while
+   * `translateFilterToAST` returned it verbatim — so the same `$filter` went out
+   * in two formats, decided by whether the query expanded a lookup.
+   *
+   * Measured across 21 operator shapes, four diverged. `$exists` vs `$null` was
+   * a cosmetic difference the server treats identically, but the other three
+   * were not: see below.
+   */
+  bothRoutes(
+    'converts a plain equality object',
+    { status: 'active' },
+    (wire) => expect(wire).toEqual(['status', '=', 'active']),
+  );
+
+  bothRoutes(
+    'converts an operator object',
+    { age: { $gte: 18 } },
+    (wire) => expect(wire).toEqual(['age', '>=', 18]),
+  );
+
+  bothRoutes(
+    'leaves a top-level Mongo logical node alone',
+    // `mergeFilters` (dashboard scope filters) produces this. It survives as a
+    // `['$and', '=', [...]]` comparison that `parseFilterAST` reads back as a
+    // real `$and` — verified, and the reason this is NOT rewritten here.
+    { $and: [{ a: 1 }, { b: 2 }] },
+    (wire) => expect(wire).toEqual(['$and', '=', [{ a: 1 }, { b: 2 }]]),
+  );
+
+  for (const route of ['plain', 'expand'] as const) {
+    it(`refuses an unknown operator on the ${route} route`, async () => {
+      // The guard exists "to avoid silent failure" — it used to run on one
+      // route only, so a typo shipped silently whenever a lookup was expanded.
+      const err = await findRejects({ s: { $bogus: 1 } }, route);
+      expect(err).toBeInstanceOf(Error);
+      expect(String((err as Error).message)).toContain('$bogus');
+      expect(isMalformedFilterError(err)).toBe(true);
+    });
+
+    it(`refuses $regex rather than answering a different question (${route})`, async () => {
+      // Was silently rewritten to `contains`: `$regex: 'a.c'` matches "abc",
+      // `contains 'a.c'` does not. The spec has no `$regex` to translate into.
+      const err = await findRejects({ s: { $regex: 'a.c' } }, route);
+      expect(isMalformedFilterError(err)).toBe(true);
+      expect(String((err as Error).message)).toMatch(/regex/i);
+    });
+  }
+});
+
+describe('the two routes agree on shapes that are neither form', () => {
+  beforeEach(() => clearSharedDiscoveryCache());
+
+  /**
+   * The inline copy of the sniff omitted the `!== null` guard that this one
+   * had, so `[null]` threw a TypeError on the plain route and was handled on
+   * the `$expand` route — the same stored filter, decided by whether the view
+   * happened to expand a lookup.
+   */
+  bothRoutes(
+    'does not crash on a null entry',
+    [null],
+    (wire) => expect(wire).toEqual([null]),
+  );
+
+  bothRoutes(
+    'leaves a nested legacy AST alone',
+    [['stage', '=', 'won'], ['amount', '>', 1]],
+    (wire) => expect(wire).toEqual([['stage', '=', 'won'], ['amount', '>', 1]]),
+  );
+});

package/src/filter-operator-ast-parity.test.ts

@@ -0,0 +1,71 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Adapter operator table → filter-AST parity (#2901, objectstack#3948).
+ *
+ * `FILTER_OPERATOR_ALIASES` is the last translation a filter passes through
+ * before it goes on the wire, and `normalizeFilterOperator` ends in `?? op` —
+ * an unmapped operator is emitted verbatim. The server then rejects the shape
+ * at `isFilterAST()`, passes the array through unconverted, and driver-sql
+ * skips it entirely: **no WHERE clause, no error, every row returned.**
+ *
+ * So a missing row in this table is not a validation failure, it is an
+ * unfiltered query. `before`/`after` — canonical members of the spec's
+ * `VIEW_FILTER_OPERATORS` — were missing, which is exactly how a stored
+ * "close_date before X" view came back unfiltered.
+ *
+ * These tests pin the table against the spec vocabularies in both directions.
+ */
+import { describe, it, expect } from 'vitest';
+import { VALID_AST_OPERATORS } from '@objectstack/spec/data';
+import { VIEW_FILTER_OPERATORS } from '@objectstack/spec/ui';
+import { FILTER_OPERATOR_ALIASES } from './index';
+
+/**
+ * View operators this adapter is not the bridge for — the value-shape ones the
+ * view layer resolves to a null comparison before an operator is ever emitted.
+ */
+const NOT_THIS_ADAPTERS_JOB = new Set(['is_empty', 'is_not_empty']);
+
+describe('FILTER_OPERATOR_ALIASES lands inside the spec AST vocabulary', () => {
+  it('reads both vocabularies from the spec', () => {
+    expect(VIEW_FILTER_OPERATORS.length).toBeGreaterThan(0);
+    expect(VALID_AST_OPERATORS.size).toBeGreaterThan(0);
+  });
+
+  it('every alias target is an operator the AST gate accepts', () => {
+    const bad = Object.entries(FILTER_OPERATOR_ALIASES)
+      .filter(([, target]) => !VALID_AST_OPERATORS.has(String(target).toLowerCase()))
+      .map(([alias, target]) => `${alias} → ${target}`);
+    expect(
+      bad,
+      'these aliases translate to operators VALID_AST_OPERATORS rejects, so the '
+        + 'server drops the filter silently instead of erroring',
+    ).toEqual([]);
+  });
+
+  it('covers every canonical view operator the spec defines', () => {
+    const uncovered = VIEW_FILTER_OPERATORS
+      .filter((op) => !NOT_THIS_ADAPTERS_JOB.has(op))
+      .filter((op) => {
+        const target = FILTER_OPERATOR_ALIASES[op] ?? op;
+        return !VALID_AST_OPERATORS.has(String(target).toLowerCase());
+      });
+    expect(
+      uncovered,
+      'an author can declare these on a ViewFilterRule and the spec validates them, '
+        + 'but they reach the wire unmapped and the filter is silently dropped',
+    ).toEqual([]);
+  });
+
+  it('maps the date comparisons that regressed', () => {
+    expect(FILTER_OPERATOR_ALIASES.before).toBe('<');
+    expect(FILTER_OPERATOR_ALIASES.after).toBe('>');
+  });
+});