From 917cbae75cad471179f48a10bb574e4f75c87a0f Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 31 Aug 2026 21:36:12 +0000 Subject: [PATCH 1/2] docs(objectql): correct the ADR-0061 search-expansion docblock to `$icontains` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The ADR-0061 docblock on `expandSearchOnAst` described the search expansion as a cross-field `$or` of `$contains` in two places. Both are false: the implementation one file over (`search-filter.ts`) emits `$icontains` for the source-column clauses, and its own header records the adjudication — "[#7641] The case-insensitive operator is `$icontains`, NOT `$contains`." Comment-only, zero behaviour. `search-filter.ts` is already correct and is not touched. Deliberately NOT changed: the multi-value containment passage further down `engine.ts` (`referenceProbeFilter` and its docblock), where `$contains` is the correct spelling — that paragraph is about membership over a stored array, not about ADR-0061 search expansion. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01F3jdziLbAPGeceVNmSox5L --- packages/objectql/src/engine.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/objectql/src/engine.ts b/packages/objectql/src/engine.ts index 158532ae8e..390cae032e 100644 --- a/packages/objectql/src/engine.ts +++ b/packages/objectql/src/engine.ts @@ -8644,7 +8644,7 @@ export class ObjectQL implements IObjectQLEngine { /** * ADR-0061: expand `search` into a server-resolved cross-field `$or` of - * `$contains`, AND it with any caller `where`, then strip the search keys off + * `$icontains`, AND it with any caller `where`, then strip the search keys off * the AST. * * Shared by `find` and `findOne` (#4419). It lived inline in `find` and @@ -8661,7 +8661,7 @@ export class ObjectQL implements IObjectQLEngine { * * Field resolution is server-side (declared `searchableFields` → * auto-default); the optional `searchFields` override is intersected with the - * allowed set, never widened. All drivers already execute `$or`/`$contains`, + * allowed set, never widened. All drivers already execute `$or`/`$icontains`, * so this needs no driver changes. * * The keys are deleted whether or not anything expanded — leaving them on From 24d04ba988a604ebd7726e4edce4114ec4770773 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 31 Aug 2026 22:00:13 +0000 Subject: [PATCH 2/2] chore(changeset): patch @objectstack/objectql for the ADR-0061 docblock correction Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01F3jdziLbAPGeceVNmSox5L --- .../engine-adr0061-icontains-docblock.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 .changeset/engine-adr0061-icontains-docblock.md diff --git a/.changeset/engine-adr0061-icontains-docblock.md b/.changeset/engine-adr0061-icontains-docblock.md new file mode 100644 index 0000000000..e0da1513d2 --- /dev/null +++ b/.changeset/engine-adr0061-icontains-docblock.md @@ -0,0 +1,32 @@ +--- +"@objectstack/objectql": patch +--- + +docs(objectql): correct the ADR-0061 search-expansion docblock to `$icontains` (#13744) + +Comment-only, zero behaviour. The ADR-0061 docblock on `ObjectQL`'s +`expandSearchOnAst` described the `$search` expansion as a cross-field `$or` of +`$contains` in **two** places, and both were false: + +- "expand `search` into a server-resolved cross-field `$or` of `$contains`" — + the shape of the expansion; +- "All drivers already execute `$or`/`$contains`, so this needs no driver + changes" — the easier one to miss, because it reads as a statement of fact + about driver capability rather than a description of the expansion. + +The implementation one file over (`search-filter.ts`) emits `$icontains` for the +source-column clauses and records the adjudication in its own header: +"[#7641] The case-insensitive operator is `$icontains`, NOT `$contains`." The +two files contradicted each other and the implementation was the correct one, so +the docblock is brought into line with it. `search-filter.ts` is not touched. + +Why a stale comment was worth a change at all: `engine.ts` is the file an agent +working the query engine reads first, so a docblock asserting the retired +spelling is a live invitation to re-introduce the defect #7641 paid to retire. + +Deliberately NOT changed, in the same file: the multi-value containment passage +on `referenceProbeFilter`, where `$contains` is the *correct* spelling — that +paragraph is about membership over a stored array, not about ADR-0061 search +expansion. Likewise the `__search` companion clause in `search-filter.ts`, which +stays `$contains` by design (both sides are already lowercase, so a +case-sensitive operator over two folded values is exact).