docs(spec): $icontains 实施状态改按实测重写 —— #5702 已落地,SQL 族三面应答 (#6947) (#6987)

`filter.zod.ts` 上 `StringOperatorSchema` 的「Implementation status」段自述过期条件
是「直到 #5702 落地」;#5702 已于 2026-08-08 关闭,该段现在断言的与已发布状态相反。

按 driver 逐个实测重写(不是抄 issue 上的点检表,也不是 grep case 分支 —— grep 看不见
继承编译器的那一面,会把 5 数成 2):三个应答、两个响亮拒收。

⛔ 行为零变化:`FILTER_OPERATORS` 未动,`$icontains` 仍刻意不在词表内(fail-closed)。
词表的真实闸口写明为 #6520,不再是已落地的 #5702。


Claude-Session: https://claude.ai/code/session_018ffcE95NaMJcL9XJ9VDYgk

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-project-manager

.changeset/icontains-status-post-5702.md

@@ -0,0 +1,11 @@
+---
+"@objectstack/spec": patch
+---
+
+filter: `$icontains` 的实施状态改按实测重写(#6947)
+
+`filter.zod.ts` 上 `StringOperatorSchema` 的状态段仍然写着「没有任何后端应答 `$icontains`,五个 driver 一律拒收,直到 #5702 落地」。#5702 已于 2026-08-08 关闭,该段自述的过期条件已经触发,文字与已发布的实现正好相反。
+
+按 driver 逐个实测(同一条 `{ name: { $icontains: 'acme' } }` 打到同时含 `acme corp` 与 `ACME CORP` 的样本上,而不是 grep case 分支 —— grep 看不见继承编译器的那一面,会少数一个):**五个 driver 里三个应答**(`driver-sql`;`driver-sqlite-wasm` 通过继承 `SqlDriver`,在另一套 sql.js 引擎上;`driver-turso` 的 local 与 remote 两条传输都应答),**两个响亮拒收**(`driver-memory`、`driver-mongodb`,均为 `INVALID_FILTER` / 400)。据此改写状态段,并同步 `$icontains` 的 `.describe()`(它会渲染进 `content/docs/references/data/filter.mdx`,原文同样停留在「lowerings land with #5702」)。
+
+⛔ 行为零变化:`FILTER_OPERATORS` 未动,`$icontains` 仍然刻意不在词表里 —— 该数组是运行时 allowlist,收进去会让内存 `match()` 对**不匹配**答 `true`。词表的真实闸口从此写明是 #6520(JS 求值面),不再是已经落地的 #5702。

content/docs/references/data/filter.mdx

@@ -147,7 +147,7 @@ Type: `[FilterArray](#filterarray)[]`
 | **$notContains** | `string` | optional |  |
 | **$startsWith** | `string` | optional |  |
 | **$endsWith** | `string` | optional |  |
-| **$icontains** | `string` | optional | Contains substring, ignoring case — but ONLY ASCII case (A-Z against a-z). Every other character compares literally, so "café" does NOT match "CAFÉ" and "москва" does not match "МОСКВА". The domain is ASCII because that is the one fold all five backends can deliver: SQLite (and therefore turso and sqlite-wasm) folds ASCII only, so a Unicode promise here would be a guarantee three of the five could not keep. The comparand is matched LITERALLY — "%", "_" and regex metacharacters are ordinary characters, not wildcards. Case-SENSITIVE containment is $contains. [#5701: declared by the protocol; the driver lowerings land with #5702.] |
+| **$icontains** | `string` | optional | Contains substring, ignoring case — but ONLY ASCII case (A-Z against a-z). Every other character compares literally, so "café" does NOT match "CAFÉ" and "москва" does not match "МОСКВА". The domain is ASCII because that is the one fold all five backends can deliver: SQLite (and therefore turso and sqlite-wasm) folds ASCII only, so a Unicode promise here would be a guarantee three of the five could not keep. The comparand is matched LITERALLY — "%", "_" and regex metacharacters are ordinary characters, not wildcards. Case-SENSITIVE containment is $contains. [#5701 declared it; #5702 lowered it on the SQL family (driver-sql, driver-sqlite-wasm, driver-turso on both transports). driver-memory and driver-mongodb still REFUSE it with INVALID_FILTER / 400, so a filter using it is not portable across backends yet — #6520.] |
 
 
 ---

packages/spec/src/data/filter-operator-vocabulary.test.ts

@@ -13,16 +13,19 @@
  *   gate and `service-analytics`' coverage test DERIVE from. An entry here is a
  *   claim that backends implement the operator.
  *
- * `$icontains` is declared and not yet enforced (#5701 is the contract half of
- * the #4706 ruling; #5702 writes the lowerings). Measured on the branch that
+ * `$icontains` is declared and still not enforced (#5701 is the contract half
+ * of the #4706 ruling; #5702 wrote the lowerings for the SQL family only, and
+ * #6520 is what the remaining JS faces wait on). Measured on the branch that
  * added it to `FILTER_OPERATORS` early: driver-memory's gate stopped refusing
  * it and `match({ name: 'zzz' }, { name: { $icontains: 'acme' } })` returned
  * `true` — the predicate silently dropped, every row matched. That is the
- * widening #3948 is about, so the staging is not a stylistic choice.
+ * widening #3948 is about, so the staging is not a stylistic choice, and
+ * #5702 landing did NOT clear it: the array is read by the two faces that
+ * still refuse the operator, not by the three that answer it.
  *
  * The pin below is deliberately an EQUALITY, not a subset check, so it fails in
  * both directions: a second staged operator added without recording it fails
- * here, and so does clearing `$icontains` in #5702 — which is the point. The
+ * here, and so does clearing `$icontains` in #6520 — which is the point. The
  * failure message is the instruction.
  */
 
@@ -50,8 +53,10 @@ describe('the declaration surface and the enforcement surface', () => {
         + 'add it here plus a note on FILTER_OPERATORS saying which issue implements it — an '
         + 'operator in FILTER_OPERATORS with no backend arm makes driver-memory accept it and '
         + "silently DROP the predicate (measured, #5701). If you are CLEARING one because you "
-        + 'just implemented it (#5702): remove it from this list AND delete the staging paragraph '
-        + 'on FILTER_OPERATORS, which is now describing something that is no longer true.',
+        + 'just implemented it on EVERY face (for `$icontains` that is #6520 — #5702 did the SQL '
+        + 'family and correctly left the staging in place): remove it from this list AND delete '
+        + 'the staging paragraph on FILTER_OPERATORS, which is now describing something that is '
+        + 'no longer true.',
     ).toEqual(['$icontains']);
   });
 

packages/spec/src/data/filter.zod.ts

@@ -294,23 +294,55 @@ export const RangeOperatorSchema = lazySchema(() => z.object({
  * `$contains`. An application whose users search non-ASCII text should not read
  * `$icontains` as "accent- and case-blind search" — it is not one.
  *
- * ### Implementation status — declared here, NOT yet answered by any backend
- *
- * This PR is the contract half of the #4706 ruling and deliberately ships no
- * runtime behaviour (#5701). No driver evaluates `$icontains` today; all five
- * refuse it, loudly, as an operator they do not implement — which is the
- * fail-closed direction and stays true until #5702 lands the lowerings. The
- * same issue carries the `$contains`-family alignment the ruling above
- * requires (SQLite/turso `LIKE` made case-exact, mongo's hardcoded `'i'`
- * removed). Until then the sentence above is the DECLARATION and #5702 is the
- * gap; `FILTER_TEXT_CASES` (`filter-text-conformance.ts`) is the standard that
- * measures the gap, and the driver-conformance ledger carries one DEBT row per
- * backend so the gap is counted rather than assumed.
+ * ### Implementation status — answered by the SQL family, refused by the rest
+ *
+ * #5701 shipped this declaration deliberately ahead of every runtime, and
+ * #5702 (closed 2026-08-08, retuned by #6518) landed the lowerings on the SQL
+ * family. Measured per backend, by running `{ name: { $icontains: 'acme' } }`
+ * against a fixture holding BOTH `acme corp` and `ACME CORP` — not by grepping
+ * for a case arm, which is blind to the face that inherits its compiler and so
+ * undercounts:
+ *
+ * | driver | `$icontains` | how it gets there |
+ * |---|---|---|
+ * | `driver-sql` | ANSWERS both rows | its own `case '$icontains'`, folding through the same emitter that carries the escaping |
+ * | `driver-sqlite-wasm` | ANSWERS both rows | INHERITED — `SqliteWasmDriver extends SqlDriver`; this package carries no text case arm of its own, on a different ENGINE |
+ * | `driver-turso` | ANSWERS both rows, on BOTH transports | local inherits `SqlDriver`; the remote transport compiles independently and has its own arm |
+ * | `driver-memory` | REFUSES — `INVALID_FILTER` / 400 | no arm; its `SUPPORTED_FIELD_OPERATORS` derives from {@link FILTER_OPERATORS}, which deliberately omits it |
+ * | `driver-mongodb` | REFUSES — `INVALID_FILTER` / 400 | no arm; falls to its translator's `default:` |
+ *
+ * The other JS evaluators sit on the refusing side too: objectql's `having`
+ * face records the omission in its own source, and `formula`'s `matchesFilter`
+ * has no `$icontains` arm.
+ *
+ * **So the sentence an author needs is no longer "no backend answers this".**
+ * It is: `$icontains` is EXECUTABLE on the SQL family and refused — loudly,
+ * fail-closed, never silently — everywhere else, so a filter that uses it is
+ * not portable across backends today. An app whose tests run on the in-memory
+ * double and whose production runs SQL gets two different answers from one
+ * filter: that divergence, and the remaining implementations, are #6520.
+ *
+ * **The vocabulary gate below is still closed, and #5702 is no longer what it
+ * waits for.** `$icontains` stays out of {@link FILTER_OPERATORS} on purpose —
+ * that array is a runtime allowlist, and listing an operator the in-memory
+ * `match()` cannot evaluate makes it answer `true` for a NON-match (measured;
+ * see that array's docblock). It joins when the JS faces get arms, in #6520.
+ *
+ * The `$contains`-family alignment the ruling above requires is likewise part
+ * done rather than pending: #6518 made that family case-EXACT across the SQL
+ * dialects, while `driver-memory`'s query path and `driver-mongodb` still fold
+ * the whole Unicode range — the two rows #6682 tracks.
+ *
+ * `FILTER_TEXT_CASES` (`filter-text-conformance.ts`) is the standard that
+ * measures all of the above, and the driver-conformance ledger still carries a
+ * DEBT row for each of the two backends left, so what is open stays counted
+ * rather than assumed.
  *
  * @see FILTER_TEXT_CASES — the conformance standard for every operator here.
  * @see RETIRED_FILTER_OPERATORS — why `$regex` is not in this list.
  * @see https://github.com/objectstack-ai/objectstack/issues/4706 (the ruling)
- * @see https://github.com/objectstack-ai/objectstack/issues/5702 (the backends)
+ * @see https://github.com/objectstack-ai/objectstack/issues/5702 (the SQL family — landed)
+ * @see https://github.com/objectstack-ai/objectstack/issues/6520 (the JS faces — open)
  */
 export const StringOperatorSchema = lazySchema(() => z.object({
   /** Contains substring, CASE-SENSITIVELY - SQL: LIKE %?% (case-exact) */
@@ -337,8 +369,11 @@ export const StringOperatorSchema = lazySchema(() => z.object({
     + 'sqlite-wasm) folds ASCII only, so a Unicode promise here would be a '
     + 'guarantee three of the five could not keep. The comparand is matched '
     + 'LITERALLY — "%", "_" and regex metacharacters are ordinary characters, not '
-    + 'wildcards. Case-SENSITIVE containment is $contains. [#5701: declared by the '
-    + 'protocol; the driver lowerings land with #5702.]'
+    + 'wildcards. Case-SENSITIVE containment is $contains. [#5701 declared it; #5702 '
+    + 'lowered it on the SQL family (driver-sql, driver-sqlite-wasm, driver-turso on '
+    + 'both transports). driver-memory and driver-mongodb still REFUSE it with '
+    + 'INVALID_FILTER / 400, so a filter using it is not portable across backends yet '
+    + '— #6520.]'
   ),
 }));
 
@@ -1194,10 +1229,12 @@ export const FilterArraySchema: z.ZodType<FilterArray, FilterArray> = z.lazy(()
  * reader (verified — `NormalizedFilterSchema` is their only consumer, and
  * nothing parses a filter through it at runtime), so declaring there is inert.
  * Adding it HERE would flip driver-memory from a loud refusal to the silent
- * widening measured above, before a single backend can answer the operator.
+ * widening measured above, on a face that still cannot answer the operator.
  *
- * **`$icontains` joins this array in the PR that implements it (#5702), not
- * before.** `filter-operator-vocabulary.test.ts` pins the difference between
+ * **`$icontains` joins this array in the PR that gives the JS faces an arm
+ * (#6520), not before** — #5702 implemented the SQL family and correctly did
+ * NOT add it here, because the array is read by the faces that still refuse.
+ * `filter-operator-vocabulary.test.ts` pins the difference between
  * the two surfaces at exactly `{ $icontains }`, so this staging cannot silently
  * grow a second member, and clearing it is what makes that pin fail.
  *