feat(drivers,objectql): $regex 响亮拒收 + SQL 族 $icontains 实现 (#5702)

#4706 裁决 B 案的驱动半边。#5701 已落契约(词表 / RETIRED_FILTER_OPERATORS
处方 / 共享文本 case-set),#5710 已翻掉最后一个活体生产者(plugin-auth 的
ObjectQL 适配器,认证路径),因此拒收现在可以落地而不打断登录。

- 五个拒收点(driver-sql / driver-memory / driver-turso remote /
  driver-mongodb / objectql `having`)统一逐字打印
  `RETIRED_FILTER_OPERATORS[op].why`,并点名 `$icontains`;
- `$icontains` 在 SQL 族实现:复用 `applyLike` / `pushLike` 的 `%`/`_`/`\`
  转义与显式 ESCAPE,新增 `fold` 参数把 LOWER() 套在两侧;
- driver-mongodb 的 `default:` 裸 `new Error` 接进本文件既有的
  `INVALID_FILTER` / 400 信封;
- conformance LEDGER 五行按实测重写,剩余两半分别记为 #6518 / #6520。

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

Author: os-zhuang

.changeset/regex-retirement-icontains-drivers.md

@@ -0,0 +1,51 @@
+---
+"@objectstack/driver-sql": minor
+"@objectstack/driver-sqlite-wasm": minor
+"@objectstack/driver-turso": minor
+"@objectstack/driver-memory": minor
+"@objectstack/driver-mongodb": minor
+"@objectstack/objectql": minor
+---
+
+feat(drivers,objectql): `$regex` / `$options` are refused everywhere, and `$icontains` is implemented on the SQL family (#5702)
+
+The driver half of the #4706 ruling. #5701 landed the contract (the vocabulary,
+the `RETIRED_FILTER_OPERATORS` prescriptions, the shared text case-set) and
+#5710 flipped the last live producer — `plugin-auth`'s ObjectQL adapter, which
+emitted `$regex` on the authentication path — so the refusal can now land
+without breaking sign-in.
+
+**BREAKING for anyone writing `$regex` or `$options` in a filter.** Both are
+refused on every backend with `INVALID_FILTER` / 400 and a message that names
+the replacement. `$regex` was never a declared operator: `driver-sql` compiled
+it to a LIKE-escaped substring (so `a.b` matched only the literal `a.b`),
+`driver-memory` ran it as a real `RegExp` (so the same filter also matched
+`axb`, and an *invalid* pattern was caught and answered `false` — zero rows, in
+silence), and `objectql`'s `having` did the same. Write `$icontains` for the
+case-insensitive substring search this was almost always used for, `$contains`
+for a case-sensitive one; a pattern that genuinely needs a regex has no
+filter-level replacement.
+
+**`$icontains` now runs on the SQL family** — `driver-sql`, `driver-sqlite-wasm`,
+and both of `driver-turso`'s transports (the remote one does not go through
+knex, so it needed its own). It compiles to `LOWER(col) LIKE LOWER(?) ESCAPE ?`
+through the same `applyLike` / `pushLike` that carries the `%` / `_` / `\`
+escaping, as a `fold` parameter rather than a second emitter — a copied emitter
+is where the escape class would have been dropped, and an unescaped `%` matches
+every row. An empty or non-string comparand is refused on the validating walk
+(an empty one matches every row, which widens rather than narrows). On SQLite
+`lower()` folds ASCII only, which IS the contract (#4706 Q1 = A): `$icontains:
+'café'` does not match `CAFÉ`.
+
+`driver-mongodb`'s unknown-operator arm was throwing a bare `Error` with no
+`code` and no `status`, three lines from the helper in its own file that sets
+`INVALID_FILTER` / 400 — a 500-shaped body for a 400-class client mistake. It
+now speaks the same envelope as its three siblings.
+
+Two parts of the ruling are deliberately NOT in this change and stay tracked in
+`scripts/check-driver-conformance.mjs`'s ledger: the `$contains` family's
+case-sensitivity (#4706 Q2 = A) needs SQLite's `LIKE` replaced by a case-exact
+construct in the driver, the RLS lowering and the analytics lowering together,
+or one permission rule compiles to two row sets (#6518); and `$icontains` on the
+JS evaluation faces needs the spec vocabulary to take the operator, which cannot
+happen before `driver-memory` has an arm for it (#6520).

packages/drivers/driver-memory/src/filter-refusal.ts

@@ -30,7 +30,7 @@
  * vocabulary; it does not get to drop what falls outside it.
  */
 
-import { FILTER_OPERATORS, LOGICAL_OPERATORS } from '@objectstack/spec/data';
+import { FILTER_OPERATORS, LOGICAL_OPERATORS, RETIRED_FILTER_OPERATORS } from '@objectstack/spec/data';
 import { StandardErrorCode } from '@objectstack/spec/api';
 
 /**
@@ -148,18 +148,27 @@ export function emptyFieldConstraintError(field: string, path: string): Error {
  * `convertConditionToMongo`'s alias fold) — a list written out here would agree
  * with the spec on the day it was typed and never again.
  *
- * Two additions the spec's list does not carry, both deliberate and both
- * pre-existing behaviour rather than new capability:
+ * ## [#5702] The two additions are GONE — nothing is added any more
  *
- * - **`$regex`** — not in `FILTER_OPERATORS`, but really produced: plugin-auth's
- *   ObjectQL adapter emits `{ field: { $regex: value } }` for a `contains`
- *   search. `driver-sql` compiles it (to a substring LIKE), `objectql`'s
- *   `having` allows it, and this driver's matcher implements it. Refusing it
- *   here would break a live producer.
- * - **`$options`** — the regex-flags companion `memory-matcher` reads
- *   (`new RegExp(target, condition.$options)`) and `objectql`'s `having` skips
- *   for the same reason. It is a modifier of `$regex`, not a predicate of its
- *   own.
+ * This set used to be `[...FILTER_OPERATORS, '$regex', '$options']`. Both extra
+ * members existed for one reason, recorded here verbatim at the time: *"Refusing
+ * it here would break a live producer"* — plugin-auth's ObjectQL adapter emitted
+ * `{ field: { $regex: value } }` for better-auth's `contains` search, on the
+ * AUTHENTICATION path.
+ *
+ * That producer was flipped to `$contains` by #5710 (PR #5812), and a whole-repo
+ * scan on `origin/main` found no other: every surviving `$regex` occurrence is a
+ * consumer arm, a retirement prescription, or a refusal assertion. The reason the
+ * two members existed is therefore gone, and #4706 retired both spellings — so
+ * they are refused here like any other undeclared operator, with the spec's
+ * prescription attached (see {@link retiredFilterOperatorError}).
+ *
+ * Note what this does NOT do: it does not add `$icontains`. That name is
+ * declared by `StringOperatorSchema` but deliberately absent from
+ * `FILTER_OPERATORS` (#5701), and this set is derived, so this driver refuses it
+ * — fail-closed, an unimplemented capability rather than a silent widening. The
+ * `$icontains` implementation for the JS faces is #5499-frozen; see the
+ * `driver-memory` row of `scripts/check-driver-conformance.mjs`.
  *
  * Everything else is refused. That includes the mingo operators this driver used
  * to hand through by accident (`$elemMatch`, `$size`, `$type`, `$mod`, `$where`,
@@ -168,8 +177,6 @@ export function emptyFieldConstraintError(field: string, path: string): Error {
  */
 export const SUPPORTED_FIELD_OPERATORS: ReadonlySet<string> = new Set<string>([
   ...FILTER_OPERATORS,
-  '$regex',
-  '$options',
 ]);
 
 /** The vocabulary as it appears in a refusal message, in declaration order. */
@@ -418,24 +425,53 @@ export function nonBooleanNullComparandError(field: string, value: unknown, path
 }
 
 /**
- * [#5324] `$options` without the `$regex` it modifies.
- *
- * `$options` is in {@link SUPPORTED_FIELD_OPERATORS} as a MODIFIER, not a
- * predicate — it carries the regex flags (`memory-matcher` reads it as
- * `new RegExp(target, condition.$options)`, and objectql's `having` skips it for
- * the same reason). On its own it is not a filter at all, and the two faces
- * proved it: mingo raised `unknown query operator $options` — uncoded, the very
- * escape #5324 is about — while the matcher ignored it and matched EVERY row.
- * Allowlisting the key without requiring its partner would have left exactly one
- * operator still leaking out of the envelope.
+ * [#5702] A RETIRED filter operator in a field constraint.
+ *
+ * Distinct from {@link unknownFieldOperatorError} on purpose, and the
+ * distinction is the author's: `$sounds_like` is a name that never meant
+ * anything, while `$regex` and `$options` are names this driver ANSWERED — with
+ * a real `RegExp`, the only regex evaluator in the repo — until #4706 retired
+ * them. Handing that author the fifteen-name vocabulary list is true and
+ * useless; what they need is `$icontains`.
+ *
+ * The prescription is `RETIRED_FILTER_OPERATORS[op].why`, printed VERBATIM. The
+ * spec table exists precisely so `driver-sql`, this driver, `driver-turso`'s
+ * remote transport, `driver-mongodb` and `objectql`'s `having` stop each writing
+ * their own sentence about one retirement (#5701).
+ *
+ * This subsumes the `$options`-with-no-`$regex` refusal #5324 added
+ * (`danglingRegexOptionsError`, deleted with this change): while `$options` was
+ * an allowlisted MODIFIER, a dangling one needed its own gate; now that both
+ * spellings are refused outright there is no shape left for that gate to catch,
+ * and the message it printed — which taught the reader to write
+ * `{ "$regex": "abc", "$options": "i" }` — would be prescribing the retired form.
+ *
+ * `siblings` are the other keys of the SAME field constraint, and every retired
+ * one among them is named too — `{ $regex: '^acme', $options: 'i' }` is ONE
+ * mistake with ONE fix, and a message naming only the key iteration reached
+ * first would send its author back for a second round-trip on the other.
+ *
+ * Returns `null` when `op` is not retired, so the caller falls through to the
+ * ordinary unknown-operator refusal in one expression.
  */
-export function danglingRegexOptionsError(field: string, path: string): Error {
+export function retiredFilterOperatorError(
+  op: string,
+  field: string,
+  path: string,
+  siblings: readonly string[] = [],
+): Error | null {
+  const guidance = RETIRED_FILTER_OPERATORS[op];
+  if (!guidance) return null;
+  const replacement = guidance.to ? ` Write "${guidance.to}" instead.` : '';
+  const alsoRetired = siblings.filter((key) => key !== op && RETIRED_FILTER_OPERATORS[key]);
+  const also = alsoRetired.length
+    ? ` The same field constraint also carries the retired ` +
+      `${alsoRetired.map((key) => `"${key}"`).join(', ')} — one "${guidance.to}" replaces the whole ` +
+      `shape, so this is ONE mistake with ONE fix, not one per key.`
+    : '';
   return unsupportedFilterError(
-    `Operator "$options" on field "${field}" at ${path} has no "$regex" to modify. "$options" ` +
-      `carries the flags of a regex predicate (e.g. { "${field}": { "$regex": "abc", "$options": "i" } }); ` +
-      `it is not a predicate on its own. It is refused rather than ignored because the two ` +
-      `evaluation paths answered it differently — one raised an uncoded engine error, the other ` +
-      `matched every row (#5324).`,
+    `Filter operator "${op}" on field "${field}" at ${path} is RETIRED and is no longer evaluated ` +
+      `by this driver.${replacement} ${guidance.why}${also}`,
   );
 }
 
@@ -564,7 +600,13 @@ function assertFieldConstraintShape(
   const keys = Object.keys(spec);
   if (!keys.some((key) => key.startsWith('$'))) return;
   for (const op of keys) {
-    if (!SUPPORTED_FIELD_OPERATORS.has(op)) throw unknownFieldOperatorError(op, field, path);
+    if (!SUPPORTED_FIELD_OPERATORS.has(op)) {
+      // [#5702] A RETIRED spelling gets the prescription; anything else gets
+      // the vocabulary. Checked in this order because `$regex` satisfies both
+      // descriptions ("not supported" and "retired") and only the second one
+      // tells its author what to write.
+      throw retiredFilterOperatorError(op, field, path, keys) ?? unknownFieldOperatorError(op, field, path);
+    }
     // [#5345] Declared, but not by THIS face. Checked before the comparand-shape
     // rules below so a `$between` a face cannot compile is reported as
     // unsupported-here rather than as a malformed range the face would refuse
@@ -583,9 +625,12 @@ function assertFieldConstraintShape(
       throw nonBooleanNullComparandError(field, spec[op], `${path}.$null`);
     }
   }
-  // `$options` is the one entry in the vocabulary that is a modifier rather than
-  // a predicate, so it is the one that needs a companion.
-  if (keys.includes('$options') && !keys.includes('$regex')) throw danglingRegexOptionsError(field, path);
+  // [#5702] The `$options`-without-`$regex` companion check that stood here is
+  // GONE. It was needed while `$options` was an allowlisted MODIFIER — a key the
+  // vocabulary accepted but which is not a predicate on its own. Both spellings
+  // are retired now, so the loop above refuses either of them on sight and there
+  // is no surviving shape for a companion rule to judge. See
+  // {@link retiredFilterOperatorError}.
 }
 
 /**

packages/drivers/driver-memory/src/memory-analytics-filter-refusal.test.ts

@@ -141,7 +141,6 @@ describe('[#5345] MemoryAnalyticsService — filters it cannot compile are refus
     { op: '$startsWith', where: { name: { $startsWith: 'al' } } },
     { op: '$endsWith', where: { name: { $endsWith: 'ta' } } },
     { op: '$null', where: { closed_at: { $null: true } } },
-    { op: '$regex', where: { name: { $regex: '^al' } } },
   ];
 
   for (const { op, where } of UNCOMPILABLE) {
@@ -153,6 +152,34 @@ describe('[#5345] MemoryAnalyticsService — filters it cannot compile are refus
     });
   }
 
+  /**
+   * [#5702] `$regex` was the sixth row of the table above until this change, and
+   * it was in the WRONG table: its assertion read "declared by the Filter
+   * Protocol, not compilable by this face", and `$regex` was never declared by
+   * the Filter Protocol at all — it was an undeclared spelling this package
+   * evaluated. #4706 retired it outright, so it is no longer a
+   * declared-but-uncompilable operator on this face; it is a refused one on
+   * every face, with a prescription attached.
+   *
+   * Kept as its own case rather than deleted, because the analytics face is a
+   * SECOND door into the same walk and "the query path refuses it" is not
+   * evidence that this one does — the two faces answering one filter differently
+   * is the divergence class this whole file exists over (#5345).
+   */
+  for (const op of ['$regex', '$options'] as const) {
+    it(`refuses the retired ${op} on the analytics face too, naming $icontains`, async () => {
+      const err = await expectRefusal(() => count({ name: { [op]: '^al' } } as FilterCondition), op);
+      expect(err.message).toContain('RETIRED');
+      expect(err.message).toContain('$icontains');
+      // NOT the uncompilable-on-this-face sentence. Asserted against that
+      // message's own distinctive phrase rather than against "declared by the
+      // Filter Protocol", which the spec's prescription also contains — in the
+      // NEGATED form ("was never declared by the Filter Protocol"), so a
+      // substring test on it passes for both messages and pins nothing.
+      expect(err.message).not.toContain('Supported operators on this surface');
+    });
+  }
+
   it('refuses an unmapped operator reached through the nested-relation branch', async () => {
     // `{profile: {verified: …}}` is re-entered as a synthesised `{'profile.verified': …}`
     // node the up-front gate never walked — the one path where the lowering's own

packages/drivers/driver-memory/src/memory-driver.test.ts

@@ -509,12 +509,30 @@ describe('InMemoryDriver', () => {
       expect(results.map((r: any) => r.name).sort()).toEqual(['Bob', 'Diana']);
     });
 
-    it('should filter with $regex operator', async () => {
-      const results = await driver.find(testTable, {
-        where: { name: { $regex: /^[AB]/ } },
-      });
-      expect(results).toHaveLength(2);
-      expect(results.map((r: any) => r.name).sort()).toEqual(['Alice', 'Bob']);
+    // [#5702] REPLACED WHOLESALE, not re-spelled. This case used to read
+    // `should filter with $regex operator` and asserted that
+    // `{ name: { $regex: /^[AB]/ } }` returned Alice and Bob — i.e. it pinned
+    // the real `RegExp` evaluation that made this driver the only backend in
+    // the repo answering `$regex` as a pattern while every SQL backend answered
+    // it as a literal substring. That divergence is what #4706 retired the
+    // operator over, so the limb is gone and its fixture cannot be re-spelled
+    // into the new world: there is no `$regex` answer left to assert.
+    //
+    // What replaces it pins the retirement instead — and pins `code`/`status`,
+    // not merely that something threw, because a bare `toThrow()` here would
+    // stay green against any error at all, including the uncoded engine errors
+    // #5324 spent a whole issue routing back into the ADR-0112 envelope.
+    it('refuses the retired $regex operator, in the ADR-0112 envelope', async () => {
+      const err = await driver
+        .find(testTable, { where: { name: { $regex: '^[AB]' } } })
+        .then(() => null, (e: any) => e);
+      expect(err).toBeInstanceOf(Error);
+      expect(err.code).toBe('INVALID_FILTER');
+      expect(err.status).toBe(400);
+      expect(err.message).toContain('$regex');
+      // The prescription, not just the verdict: an author who wrote `$regex`
+      // needs the name of what replaces it.
+      expect(err.message).toContain('$icontains');
     });
 
     it('should count with complex filter', async () => {

packages/drivers/driver-memory/src/memory-driver.ts

@@ -1002,9 +1002,16 @@ export class InMemoryDriver implements IDataDriver {
           result[op] = store(val);
           break;
         // Evaluated by mingo under the same name. `$exists` is a presence
-        // predicate, `$regex`/`$options` a pattern and its flags — none of them
-        // is a comparand, so none takes the field's storage form (#4047).
-        case '$exists': case '$regex': case '$options':
+        // predicate, not a comparand, so it does not take the field's storage
+        // form (#4047).
+        //
+        // [#5702] `$regex` and `$options` were passed through here too, on the
+        // same line, for the same "not a comparand" reason. Both are RETIRED
+        // (#4706) and refused by the shape gate before this method runs, so the
+        // arm is gone rather than left as an unreachable third name — an
+        // evaluation arm for a refused operator is exactly what let this
+        // driver's two faces answer one `$regex` differently for so long.
+        case '$exists':
           result[op] = val;
           break;
         default: