fix(drivers): the uncompilable-filter refusal speaks INVALID_FILTER, without the driver prefix (#4436)

Completes the WIP commit: adds the remaining sql-driver throw sites and the
regression tests for both backends.

#4209/#4029/#3948 settled the POSTURE — a filter carrying an operator the
driver cannot compile is refused instead of silently matching every row. What
was missing is the refusal's IDENTITY on the wire. The driver threw a bare
`Error`, so `mapDataError` fell through to its default branch and served a body
whose only key was `error`:

  GET /api/v1/data/showcase_task?filter={"title":{"$bogusop":"x"}}
  → 400 {"error":"[sql-driver] Unsupported filter operator \"$bogusop\" …"}

Two contract breaks in one body — no `error.code` at all on a route whose
sibling rejections all speak the ADR-0112 catalogue, and the driver-internal
`[sql-driver]` prefix on the wire, which is what the #3867 sanitiser exists to
stop.

Fixed at the throw site (PD #12), not by teaching the REST layer to guess:
both drivers now refuse through an `unsupportedFilterError` helper that stamps
`code = StandardErrorCode.enum.INVALID_FILTER` — the constant, so a catalogue
rename breaks the compile — and `status = 400`. `INVALID_FILTER` is the same
code `metadata-protocol` already emits when a filter fails to parse upstream
(`malformedFilterArrayError` / `unusableFilterError`): one condition, one wire
code, however the caller reached it. The `status` also puts the rejection on
`isExpectedQueryRejection`, so a client mistake stops being logged as an
unhandled server error.

Applied to every filter-COMPILATION refusal in both backends, not only the one
branch the issue names: unsupported operator ($-object, legacy triple),
unrecognised logical keyword, unrecognised element type, and a `between` /
`$between` operand that is not a two-element array. They are the same envelope
defect on adjacent lines, and #3948 made the two drivers agree that an
uncompilable filter is a refusal — so their refusal envelopes have to agree
too, or the cross-driver parity this repo relies on is false where it matters.

Tests: new `sql-driver-filter-refusal-envelope.test.ts` (8) and
`memory-filter-refusal-envelope.test.ts` (5) pin `code`, `status`, the absence
of the internal prefix, and that the actionable operator/field/vocabulary
detail survives. Full suites green: driver-sql 623 passed, driver-memory 286
passed.

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

Author: claude

packages/plugins/driver-memory/src/memory-filter-refusal-envelope.test.ts

@@ -0,0 +1,75 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#4436] The memory driver's filter refusals carry the SAME wire identity as
+ * driver-sql's.
+ *
+ * #3948 made the two backends agree that an uncompilable filter is a refusal
+ * rather than a silent match-everything. The refusal's ENVELOPE has to agree
+ * too, or a suite that swaps the memory driver for SQLite sees a coded 400 on
+ * one backend and a bare `{ error }` on the other — and the cross-driver parity
+ * this driver exists to provide would be false exactly where it is load-bearing.
+ *
+ * Twin of `driver-sql/src/sql-driver-filter-refusal-envelope.test.ts`; the
+ * rationale lives there.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { InMemoryDriver } from './memory-driver.js';
+import type { FilterCondition } from '@objectstack/spec/data';
+
+interface WireBearingError extends Error {
+  code?: string;
+  status?: number;
+}
+
+async function refusalOf(run: () => Promise<unknown>): Promise<WireBearingError> {
+  try {
+    await run();
+  } catch (e) {
+    return e as WireBearingError;
+  }
+  throw new Error('expected the driver to refuse this filter, but it resolved');
+}
+
+describe('[#4436] InMemoryDriver filter refusals carry INVALID_FILTER and leak no driver prefix', () => {
+  let driver: InMemoryDriver;
+
+  beforeEach(async () => {
+    driver = new InMemoryDriver();
+    await driver.syncSchema?.({
+      name: 'deal',
+      fields: {
+        id: { type: 'text', name: 'id' },
+        stage: { type: 'text', name: 'stage' },
+        amount: { type: 'number', name: 'amount' },
+      },
+    } as any);
+    await driver.create('deal', { id: '1', stage: 'won', amount: 10 });
+  });
+
+  const find = (where: unknown) =>
+    driver.find('deal', { object: 'deal', fields: ['id'], where: where as FilterCondition });
+
+  const cases: Array<[string, unknown, string]> = [
+    ['unsupported operator in a condition array', [['stage', 'sounds_like', 'won']], 'sounds_like'],
+    ['bare comparison triple', ['close_date', 'before', '2024-01-01'], 'close_date'],
+    ['filter element of the wrong type', [42], 'number'],
+    ['`between` with a bad operand', [['amount', 'between', 5]], 'between'],
+  ];
+
+  for (const [name, where, needle] of cases) {
+    it(`${name} → 400 INVALID_FILTER, no prefix`, async () => {
+      const err = await refusalOf(() => find(where));
+      expect(err.code).toBe('INVALID_FILTER');
+      expect(err.status).toBe(400);
+      expect(err.message).not.toContain('[driver-memory]');
+      expect(err.message).toContain(needle);
+    });
+  }
+
+  it('a compilable filter is unaffected', async () => {
+    const rows = await find({ stage: 'won' });
+    expect(rows.map((r: any) => r.id)).toEqual(['1']);
+  });
+});

packages/plugins/driver-sql/src/sql-driver-filter-refusal-envelope.test.ts

@@ -0,0 +1,114 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#4436] The uncompilable-filter refusal must carry an ADR-0112 wire identity.
+ *
+ * #4209/#4029/#3948 settled the POSTURE — a filter the driver cannot compile is
+ * refused instead of silently matching every row. What was still missing is the
+ * refusal's IDENTITY on the wire.
+ *
+ * The driver threw a bare `Error`, so it carried no `code` and no `status`.
+ * `@objectstack/rest`'s `mapDataError` therefore fell all the way through to its
+ * default branch — `{ status: 400, body: { error: raw } }` — and served a body
+ * whose only key was `error`:
+ *
+ * ```
+ * GET /api/v1/data/showcase_task?filter={"title":{"$bogusop":"x"}}
+ * → 400 {"error":"[sql-driver] Unsupported filter operator \"$bogusop\" …"}
+ * ```
+ *
+ * Two contract breaks in one body: no `error.code` at all, on a route whose
+ * sibling rejections all speak the catalogued vocabulary (`INVALID_FIELD`,
+ * `INVALID_FILTER`, `RECORD_NOT_FOUND`); and the driver-internal `[sql-driver]`
+ * prefix on the wire, which is precisely what the #3867 sanitiser exists to
+ * stop.
+ *
+ * These tests pin BOTH halves at the throw site, because that is where the fix
+ * lives (PD #12 — the producer declares its own refusal; the REST layer is not
+ * patched to guess).
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { SqlDriver } from '../src/index.js';
+import type { FilterCondition } from '@objectstack/spec/data';
+
+/** The shape `mapDataError` / `sendError` read off a thrown driver error. */
+interface WireBearingError extends Error {
+  code?: string;
+  status?: number;
+}
+
+async function refusalOf(run: () => Promise<unknown>): Promise<WireBearingError> {
+  try {
+    await run();
+  } catch (e) {
+    return e as WireBearingError;
+  }
+  throw new Error('expected the driver to refuse this filter, but it resolved');
+}
+
+describe('[#4436] SqlDriver filter refusals carry INVALID_FILTER and leak no driver prefix', () => {
+  let driver: SqlDriver;
+
+  beforeEach(async () => {
+    driver = new SqlDriver({
+      client: 'better-sqlite3',
+      connection: { filename: ':memory:' },
+      useNullAsDefault: true,
+    });
+    await driver.initObjects([
+      {
+        name: 'deal',
+        fields: {
+          id: { type: 'text', name: 'id' },
+          stage: { type: 'text', name: 'stage' },
+          amount: { type: 'number', name: 'amount' },
+        },
+      } as any,
+    ]);
+    await driver.create('deal', { id: '1', stage: 'won', amount: 10 });
+  });
+
+  const find = (where: unknown) =>
+    driver.find('deal', { object: 'deal', fields: ['id'], where: where as FilterCondition });
+
+  // The issue's own repro, at the layer that produces the envelope.
+  it('the $-object unsupported-operator branch — the exact shape #4436 reported', async () => {
+    const err = await refusalOf(() => find({ stage: { $bogusop: 'x' } }));
+    expect(err.code).toBe('INVALID_FILTER');
+    expect(err.status).toBe(400);
+    expect(err.message).not.toContain('[sql-driver]');
+    // The actionable half survives the sanitisation — a caller must still be
+    // able to see WHICH operator on WHICH field, and what is accepted instead.
+    expect(err.message).toContain('$bogusop');
+    expect(err.message).toContain('stage');
+    expect(err.message).toContain('$startsWith');
+  });
+
+  // Every filter-COMPILATION refusal in this driver answers the same way. They
+  // are one condition — "this filter cannot run" — and ADR-0112's rule is one
+  // condition, one wire code, however the caller reached it.
+  const cases: Array<[string, unknown, string]> = [
+    ['legacy triple, unsupported operator', [['stage', 'sounds_like', 'won']], 'sounds_like'],
+    ['bare comparison triple', ['close_date', 'before', '2024-01-01'], 'close_date'],
+    ['filter element of the wrong type', [42], 'number'],
+    ['null filter element', [null], 'null'],
+    ['legacy `between` with a bad operand', [['amount', 'between', 5]], 'between'],
+    ['$between with a bad operand', { amount: { $between: 5 } }, '$between'],
+  ];
+
+  for (const [name, where, needle] of cases) {
+    it(`${name} → 400 INVALID_FILTER, no prefix`, async () => {
+      const err = await refusalOf(() => find(where));
+      expect(err.code).toBe('INVALID_FILTER');
+      expect(err.status).toBe(400);
+      expect(err.message).not.toContain('[sql-driver]');
+      expect(err.message).toContain(needle);
+    });
+  }
+
+  it('a compilable filter is unaffected', async () => {
+    const rows = await find({ stage: 'won' });
+    expect(rows.map((r: any) => r.id)).toEqual(['1']);
+  });
+});

packages/plugins/driver-sql/src/sql-driver.ts

@@ -5115,8 +5115,8 @@ export class SqlDriver implements IDataDriver {
         // never converted it and the raw array arrived as `where`. Skipping it
         // (the old behaviour) emitted NO predicate at all: the caller asked to
         // filter and silently got every row. Fail loudly instead. #3948.
-        throw new Error(
-          `[sql-driver] Unrecognized filter operator "${item}" in a comparison triple. ` +
+        throw unsupportedFilterError(
+          `Unrecognized filter operator "${item}" in a comparison triple. ` +
             `A filter array is either a logical node (["and"|"or", …]) or nested ` +
             `conditions ([[field, op, value], …]); a bare [field, op, value] only ` +
             `reaches the driver when its operator is outside @objectstack/spec ` +
@@ -5171,8 +5171,8 @@ export class SqlDriver implements IDataDriver {
       // branches and was dropped, so a malformed element silently narrowed
       // nothing. Same reasoning as above: an unapplied filter must not look
       // like a satisfied one. #3948.
-      throw new Error(
-        `[sql-driver] Unrecognized filter element of type "${item === null ? 'null' : typeof item}" — ` +
+      throw unsupportedFilterError(
+        `Unrecognized filter element of type "${item === null ? 'null' : typeof item}" — ` +
           `expected a logical keyword ("and"/"or") or a condition array. ` +
           `Filter was: ${JSON.stringify(filters)}`,
       );
@@ -5485,7 +5485,7 @@ export class SqlDriver implements IDataDriver {
             case '$between': {
               const arr = Array.isArray(coerced) ? coerced : [];
               if (arr.length !== 2) {
-                throw new Error(`[sql-driver] operator "$between" on field "${field}" requires a [min, max] value array.`);
+                throw unsupportedFilterError(`Operator "$between" on field "${field}" requires a [min, max] value array.`);
               }
               (builder as any)[logicalOp === 'or' ? 'orWhereBetween' : 'whereBetween'](field, arr as [any, any]);
               break;