docs(spec): search-fields docblock says $icontains, the operator the engine emits (#17572)

* docs(spec): search-fields docblock says $icontains, the operator the engine emits

The module docblock claimed `expandSearchToFilter` expands a `$search` term
into an `$or` of `$contains` clauses. It has compiled to `$icontains` since
#7641; `packages/objectql/src/search-filter.ts:23` carries the ruling and both
return paths of `fieldClausesForTerm` (:109, :111) emit `$icontains`.

The distinction matters to a reader of this module because `$contains` is
contractually case-SENSITIVE (#4706 Q2 = A): anyone who built an ingress gate,
a test or a driver against the old sentence built one STRICTER than the
platform — a false refusal, not a leak. That is now stated in one clause.

The sibling INGRESS sentence two lines below was measured and is unchanged.

Claude-Session: https://claude.ai/code/session_01MkQhmuuJAVDjmeWNixwDDH
Co-authored-by: Claude <noreply@anthropic.com>

* chore(changeset): declare the search-fields docblock correction as a spec patch

`@objectstack/spec`'s published `files[]` ships `dist`, and this TSDoc is
emitted into `dist/data/index.d.ts` and `dist/data/index.d.mts` -- measured on
the built artifact, so published content moves and `skip-changeset` is not
available.

Claude-Session: https://claude.ai/code/session_01MkQhmuuJAVDjmeWNixwDDH
Co-authored-by: Claude <noreply@anthropic.com>

---------

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

Author: os-bill

.changeset/15052-search-fields-docblock-icontains.md

@@ -0,0 +1,38 @@
+---
+'@objectstack/spec': patch
+---
+
+`search-fields.ts`'s module docblock says `$search` expands to an `$or` of `$icontains`, the operator the engine actually emits
+
+The docblock's ENGINE bullet claimed `@objectstack/objectql`'s
+`expandSearchToFilter` expands a `$search` term into an `$or` of **`$contains`**
+clauses. It has compiled to `$icontains` since objectstack#7641:
+`packages/objectql/src/search-filter.ts:23` carries the ruling verbatim — *"The
+case-insensitive operator is `$icontains`, NOT `$contains`. `$contains` is
+contractually case-SENSITIVE (#4706 Q2 = A)"* — and both return paths of
+`fieldClausesForTerm` (`:109`, `:111`) emit `$icontains`.
+
+**Why the distinction is worth a clause rather than a word swap.** `$contains`
+is contractually case-SENSITIVE, so a reader who trusted the old sentence built
+an ingress gate, a test or a driver **stricter** than the platform is — a false
+refusal, not a leak. The corrected bullet now says that in one clause, so the
+next reader of this module does not have to reconstruct it from two other
+packages.
+
+⛔ No behaviour changes. This is a module docblock; the engine has been right
+since #7641 and no accept set, authorable key or published behaviour moves.
+
+**This is shipped, which is why it carries a changeset rather than
+`skip-changeset`.** `@objectstack/spec`'s published `files[]` ships `dist`, and
+this TSDoc is emitted into `dist/data/index.d.ts` and `dist/data/index.d.mts` —
+measured on the built artifact, with the old spelling absent from all 216 built
+files afterwards and the docblock's own neighbouring sentence present at 2 as
+the lit control. `src/data/search-fields.ts` is not a `.zod.ts`, so it is not
+shipped as source; the emitted declarations are the whole of its published
+reach, and they change.
+
+The sibling INGRESS sentence two lines below — `@objectstack/metadata-protocol`
+`findData` refusing a `$searchFields` override the resolved set does not admit
+(#4254) — was measured on the same tip and is unchanged: `findData` still calls
+`assertSearchFieldsAreSearchable`, which resolves through this module's own
+`resolveSearchFieldResolution` rather than re-implementing the rule.

packages/spec/src/data/search-fields.ts

@@ -6,7 +6,10 @@
  * ONE resolution shared by the two layers that must agree on it:
  *
  * - the ENGINE (`@objectstack/objectql` `expandSearchToFilter`), which expands
- *   a `$search` term into a `$or` of `$contains` clauses over exactly this set;
+ *   a `$search` term into a `$or` of `$icontains` clauses over exactly this set
+ *   — `$icontains` since #7641, NOT `$contains`, which is contractually
+ *   case-SENSITIVE (#4706 Q2 = A): a gate, test or driver written to the old
+ *   sentence is STRICTER than the platform — a false refusal, not a leak;
  * - the INGRESS gate (`@objectstack/metadata-protocol` `findData`), which
  *   refuses a `$searchFields` override naming a field this set does not admit
  *   (#4254), instead of letting the engine drop it silently.