wip(drivers): give the uncompilable-filter refusal an ADR-0112 code and drop the driver prefix (#4436)

IN PROGRESS — code change complete, regression test not yet written and the
real-boot curl repro not yet run.

A filter carrying an operator the driver cannot compile is already REFUSED
rather than silently matched (#4209/#4029), but the refusal had no wire
identity: the thrown `Error` carried no `code`, so `mapDataError`'s default
branch served `{"error": "[sql-driver] Unsupported filter operator …"}` — no
`error.code` at all, breaking the ADR-0112 contract every sibling rejection on
the same route already honours (`INVALID_FIELD`, `INVALID_FILTER`,
`RECORD_NOT_FOUND`), and leaking the `[sql-driver]` internal prefix that the
#3867 sanitiser exists to keep off the wire.

Both drivers now throw through a local `unsupportedFilterError` that stamps
`code = StandardErrorCode.enum.INVALID_FILTER` (the same catalogued code
`metadata-protocol` emits when a filter fails to parse upstream — one
condition, one wire code however the caller reached it) and `status = 400`,
which also puts the rejection on `isExpectedQueryRejection` so a client mistake
stops being logged as an unhandled server error. The internal prefix is gone
from the message; the actionable operator/field/vocabulary detail stays.

Applied to every filter-COMPILATION refusal in both backends, not just the one
branch the issue names — 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.

TODO: regression tests (driver-sql, driver-memory, REST envelope) + boot repro.

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-driver.ts

@@ -3,6 +3,7 @@
 import type { QueryAST, QueryInput, DriverOptions } from '@objectstack/spec/data';
 import { canonicalAstOperator } from '@objectstack/spec/data';
 import type { IDataDriver } from '@objectstack/spec/contracts';
+import { StandardErrorCode } from '@objectstack/spec/api';
 import { Logger, createLogger, nextUtcCalendarDay } from '@objectstack/core';
 import { Query, Aggregator } from 'mingo';
 import { getValueByPath } from './memory-matcher.js';
@@ -12,6 +13,24 @@ import {
   type TemporalFieldKind,
 } from './memory-temporal.js';
 
+/**
+ * [#4436] A filter this driver cannot COMPILE — see the twin in
+ * `driver-sql`'s `unsupportedFilterError`, which carries the full rationale.
+ *
+ * Kept in lockstep with driver-sql deliberately: #3948 made the two backends
+ * AGREE that an uncompilable filter is a refusal rather than a silent
+ * match-everything, and the refusal's wire envelope has to agree too. A test
+ * suite that swaps the memory driver for SQL must see the same `400
+ * INVALID_FILTER`, not a coded refusal on one backend and a bare `{error}` on
+ * the other.
+ */
+function unsupportedFilterError(message: string): Error {
+  const err = new Error(message) as Error & { code?: string; status?: number };
+  err.code = StandardErrorCode.enum.INVALID_FILTER;
+  err.status = 400;
+  return err;
+}
+
 /**
  * Persistence adapter interface.
  * Matches the PersistenceAdapterSchema contract from @objectstack/spec.
@@ -764,8 +783,8 @@ export class InMemoryDriver implements IDataDriver {
         // matches EVERY record. An unapplied filter must not look like a
         // satisfied one. #3948.
         if (lower !== 'and' && lower !== 'or') {
-          throw new Error(
-            `[driver-memory] 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 ` +
@@ -785,8 +804,8 @@ export class InMemoryDriver implements IDataDriver {
         const cond = this.convertConditionToMongo(field, operator, value, object);
         if (cond) logicGroups[logicGroups.length - 1].conditions.push(cond);
       } else {
-        throw new Error(
-          `[driver-memory] Unrecognized filter element of type ` +
+        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)}`,
         );
@@ -874,16 +893,16 @@ export class InMemoryDriver implements IDataDriver {
               : { $gte: store(value[0]), $lte: store(value[1]) },
           };
         }
-        throw new Error(
-          `[driver-memory] "between" on field "${field}" needs a two-element array, got ` +
+        throw unsupportedFilterError(
+          `"between" on field "${field}" needs a two-element array, got ` +
             `${JSON.stringify(value)}. Returning no predicate would silently match every record.`,
         );
       default:
         // Was `return null`, which the caller dropped — so an operator this
         // driver cannot express narrowed nothing instead of erroring. driver-sql
         // already threw on the same input; the two backends disagreed. #3948.
-        throw new Error(
-          `[driver-memory] Unsupported filter operator "${operator}" on field "${field}". ` +
+        throw unsupportedFilterError(
+          `Unsupported filter operator "${operator}" on field "${field}". ` +
             `Supported operators: =, !=, <, <=, >, >=, in, nin, between, contains, ` +
             `not_contains, starts_with, ends_with (see @objectstack/spec VALID_AST_OPERATORS).`,
         );

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

@@ -12,6 +12,7 @@ import { parseAutonumberFormat, renderAutonumber, missingFieldValues, isTenancyD
 import { STRUCTURED_JSON_TYPES, FILE_REFERENCE_TYPES, MULTI_OPTION_TYPES, NUMERIC_VALUE_TYPES } from '@objectstack/spec/data';
 import { canonicalAstOperator } from '@objectstack/spec/data';
 import type { IDataDriver } from '@objectstack/spec/contracts';
+import { StandardErrorCode } from '@objectstack/spec/api';
 import { StorageNameMapping } from '@objectstack/spec/system';
 import { ExternalSchemaModeViolationError } from '@objectstack/spec/shared';
 import { resolveMultiOrgEnabled } from '@objectstack/types';
@@ -378,6 +379,40 @@ function canonicalTimeOfDay(value: unknown): unknown {
  */
 const SQLITE_TIME_EXPR_REFS = 8;
 
+/**
+ * [#4436] A filter this driver cannot COMPILE — the caller sent an operator (or
+ * an operand shape) outside what the backend can express.
+ *
+ * This is a refusal the request caused, and #4209/#4029 already made it a
+ * refusal rather than a silent match-everything. What was missing is the wire
+ * IDENTITY of that refusal: the thrown `Error` carried no `code`, so
+ * `mapDataError`'s default branch served `{ "error": "<message>" }` with no
+ * `code` at all — breaking the ADR-0112 contract that `error.code` is the
+ * schema-enforced SCREAMING_SNAKE vocabulary every sibling rejection on this
+ * route already speaks (`INVALID_FIELD`, `INVALID_FILTER`, `RECORD_NOT_FOUND`).
+ *
+ * `INVALID_FILTER` is the catalogued code for the condition, and the SAME one
+ * `metadata-protocol` emits for a filter that fails to parse upstream
+ * (`malformedFilterArrayError` / `unusableFilterError`): one condition — "this
+ * filter cannot run" — has one wire code however the caller reached it.
+ *
+ * `status: 400` makes `@objectstack/rest`'s `sendError` pass the message
+ * through instead of routing it to the SQL-leak heuristic, and puts the
+ * rejection on the `isExpectedQueryRejection` list so a client mistake stops
+ * being logged as an unhandled server error.
+ *
+ * The `[sql-driver]` prefix these messages used to carry is GONE from the text:
+ * it is driver-internal wording, and shipping it to clients is exactly what the
+ * #3867 sanitiser exists to stop. The operator/field/vocabulary detail — the
+ * part a caller can act on — stays.
+ */
+function unsupportedFilterError(message: string): Error {
+  const err = new Error(message) as Error & { code?: string; status?: number };
+  err.code = StandardErrorCode.enum.INVALID_FILTER;
+  err.status = 400;
+  return err;
+}
+
 // ── Introspection Types ──────────────────────────────────────────────────────
 
 export interface IntrospectedColumn {
@@ -5259,7 +5294,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[join === 'or' ? 'orWhereBetween' : 'whereBetween'](field, arr as [any, any]);
         return;
@@ -5298,8 +5333,8 @@ export class SqlDriver implements IDataDriver {
         builder[whereNotNull](field);
         return;
       default:
-        throw new Error(
-          `[sql-driver] Unsupported filter operator "${op}" on field "${field}". Supported operators: ` +
+        throw unsupportedFilterError(
+          `Unsupported filter operator "${op}" on field "${field}". Supported operators: ` +
             `=, !=, <, <=, >, >=, in, nin, between, contains, not_contains, starts_with, ends_with, ` +
             `is_null, is_not_null (see @objectstack/spec VALID_AST_OPERATORS).`,
         );
@@ -5472,8 +5507,8 @@ export class SqlDriver implements IDataDriver {
                 : (logicalOp === 'or' ? 'orWhereNotNull' : 'whereNotNull')](field);
               break;
             default:
-              throw new Error(
-                `[sql-driver] Unsupported filter operator "${op}" on field "${field}". Supported operators: ` +
+              throw unsupportedFilterError(
+                `Unsupported filter operator "${op}" on field "${field}". Supported operators: ` +
                   `$eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $between, $contains, $notContains, ` +
                   `$startsWith, $endsWith, $regex, $null, $exists.`,
               );