@open-mercato/shared 0.8.1-develop.7294.1.0ef99fc518 → 0.8.1-develop.7296.1.2111d779db

package/src/lib/query/engine.ts

@@ -20,13 +20,16 @@ import {
   type SearchTokenProbeQueryBuilder,
 } from '../search/availability'
 import { tokenizeText } from '../search/tokenize'
+import { buildContainmentPatterns } from '../search/containment'
 import { fieldNameCandidates } from './encrypted-sort'
 import { isTenantDataEncryptionEnabled } from '../encryption/toggles'
 import { runBeforeQueryPipeline, runAfterQueryPipeline, type QueryExtensionContext } from './query-extension-runner'
 import {
   buildCustomFieldDefinitionIndexFromRows,
+  normalizeDefinitionKey,
   resolveCfDefIndexOrgCandidates,
   type CustomFieldDefinitionRow,
+  type CustomFieldDefinitionSummary,
   type ResolvedCustomFieldDefinitions,
 } from '../crud/custom-field-definition-index'
 import { warnOnCiphertextLikeFallback } from './ciphertext-search-warning'
@@ -293,6 +296,25 @@ function buildFilterableCustomFieldJoins(
   })
 }
 
+/** Custom field kinds stored numerically (`custom_field_values.value_int`/`value_float`) — sort numerically, not as text (#5674). */
+const NUMERIC_CF_SORT_KINDS = new Set(['integer', 'float'])
+
+/**
+ * Pick the winning `kind` for a `cf:` sort key from an already-resolved
+ * definition list — org-scoped beats tenant-wide beats global, same
+ * precedence as the dedicated sort-kind lookup (#5674 review).
+ */
+function pickCfSortKind(defs: CustomFieldDefinitionSummary[] | undefined): string | null {
+  if (!defs || !defs.length) return null
+  let winner: { kind: string; specificity: number } | null = null
+  for (const def of defs) {
+    if (!def.kind) continue
+    const specificity = def.organizationId != null ? 2 : def.tenantId != null ? 1 : 0
+    if (!winner || specificity >= winner.specificity) winner = { kind: def.kind, specificity }
+  }
+  return winner?.kind ?? null
+}
+
 function computeCustomFieldScore(cfg: Record<string, unknown>, kind: string, entityIndex: number) {
   const listVisibleScore = cfg.listVisible === false ? 0 : 1
   const formEditableScore = cfg.formEditable === false ? 0 : 1
@@ -446,9 +468,9 @@ export class BasicQueryEngine implements QueryEngine {
       ? await this.searchAvailability().hasTokens(String(entity), opts.tenantId ?? null, orgScope)
       : false
     const searchActive = searchEnabled && hasSearchTokens
-    // Opt-in via OM_SEARCH_USE_ILIKE_FOR_NON_ENCRYPTED_FIELDS (default false: the pre-existing
-    // rewrite-everything behavior is kept). When enabled, base-column like/ilike is rerouted
-    // through search tokens ONLY for encrypted columns, where
+    // Gated on OM_SEARCH_USE_ILIKE_FOR_NON_ENCRYPTED_FIELDS (default false per #5383; set it to
+    // true to opt into the #5803 fix ahead of that follow-up). When enabled, base-column
+    // like/ilike is rerouted through search tokens ONLY for encrypted columns, where
     // ILIKE against ciphertext cannot match. On a plaintext column SQL ILIKE is exact, and the token
     // rewrite silently changes the result set: tokenization splits on non-alphanumerics and drops
     // tokens shorter than minTokenLength, so a document-number search like "ZK 1/2026" degrades to
@@ -617,6 +639,27 @@ export class BasicQueryEngine implements QueryEngine {
           })
         }
       }
+      // A PLAINTEXT base column the gate above kept off the token path: apply the declared
+      // containment once per word so the token subquery's word-order-independent matching survives
+      // the reroute (#5803 / TC-RESO-009). Chained `where`s ARE the AND the token
+      // `having count(distinct)` did. `fieldName` is required, so this never fires for a JOINed
+      // column — `applyJoinFilters` calls `applyFilterOp` without it (below), and that predicate
+      // keeps its pre-existing literal-containment behavior unchanged.
+      if (
+        (op === 'like' || op === 'ilike') &&
+        typeof value === 'string' &&
+        searchActive &&
+        fieldName &&
+        encryptedLikeFields !== null &&
+        !isEncryptedLikeField(encryptedLikeFields, fieldName)
+      ) {
+        const patterns = buildContainmentPatterns(value)
+        if (patterns.length > 1) {
+          let next = builder
+          for (const pattern of patterns) next = this.applyColumnOp(next, column, op, pattern)
+          return next
+        }
+      }
       return this.applyColumnOp(builder, column, op, value)
     }
 
@@ -703,6 +746,7 @@ export class BasicQueryEngine implements QueryEngine {
       hasJoinedAggregates: boolean
       cfJsonAliases: Set<string>
       cfMultiAliasByAlias: Map<string, string>
+      cfSortAliases: string[]
       resolvedCustomFieldDefinitions: ResolvedCustomFieldDefinitions | undefined
     }
 
@@ -994,10 +1038,70 @@ export class BasicQueryEngine implements QueryEngine {
         }
       }
 
+      // A `cf:` sort needs to know the field's declared `kind` so the ORDER BY
+      // expression can cast numeric kinds instead of ordering by jsonb text
+      // (#5674). Org-scoped beats tenant-wide beats global for the same key —
+      // a same-key definition from an unrelated organization in the tenant
+      // never gets to decide the kind (#5674 review).
+      const cfSortKeys = Array.from(new Set(
+        resolvedSorts.filter((sort) => sort.field.startsWith('cf:')).map((sort) => sort.field.slice(3))
+      ))
+      const cfSortKinds = new Map<string, string>()
+      if (cfSortKeys.length > 0) {
+        // `includeCustomFields === true` already resolved every definition for
+        // these entities into `resolvedCustomFieldDefinitions` above — reuse it
+        // instead of a second `custom_field_defs` round trip (#5674 review).
+        const keysNeedingQuery: string[] = []
+        for (const key of cfSortKeys) {
+          const kind = resolvedCustomFieldDefinitions
+            ? pickCfSortKind(resolvedCustomFieldDefinitions.index.get(normalizeDefinitionKey(key)))
+            : null
+          if (kind) cfSortKinds.set(key, kind)
+          else keysNeedingQuery.push(key)
+        }
+        if (keysNeedingQuery.length > 0) {
+          const sortEntityIds = Array.from(new Set(
+            keysNeedingQuery
+              .map((key) => keySource.get(key)?.entityId)
+              .filter((id): id is EntityId => Boolean(id))
+              .map((id) => String(id))
+          ))
+          if (sortEntityIds.length > 0) {
+            const cfSortOrgCandidates = resolveCfDefIndexOrgCandidates(opts.organizationIds, opts.organizationId ?? null)
+            const kindRows = await db
+              .selectFrom('custom_field_defs' as any)
+              .select(['key' as any, 'kind' as any, 'organization_id' as any, 'tenant_id' as any])
+              .where('entity_id' as any, 'in', sortEntityIds)
+              .where('key' as any, 'in', keysNeedingQuery)
+              .where('is_active' as any, '=', true)
+              .where((eb: any) => eb.or([
+                eb('tenant_id' as any, '=', tenantId),
+                eb('tenant_id' as any, 'is', null),
+              ]))
+              .where((eb: any) => cfSortOrgCandidates.length
+                ? eb.or([
+                    eb('organization_id' as any, 'is', null),
+                    eb('organization_id' as any, 'in', cfSortOrgCandidates),
+                  ])
+                : eb('organization_id' as any, 'is', null))
+              .execute() as Array<{ key: string; kind: string | null; organization_id: string | null; tenant_id: string | null }>
+            const winners = new Map<string, { kind: string; specificity: number }>()
+            for (const row of kindRows) {
+              if (!row.kind) continue
+              const specificity = row.organization_id != null ? 2 : row.tenant_id != null ? 1 : 0
+              const existing = winners.get(row.key)
+              if (!existing || specificity >= existing.specificity) winners.set(row.key, { kind: row.kind, specificity })
+            }
+            for (const [key, entry] of winners) cfSortKinds.set(key, entry.kind)
+          }
+        }
+      }
+
       const cfValueExprByKey: Record<string, RawBuilder<string | null>> = {}
       const cfSelectedAliases: string[] = []
       const cfJsonAliases = new Set<string>()
       const cfMultiAliasByAlias = new Map<string, string>()
+      const cfSortAliases: string[] = []
       for (const key of cfKeys) {
         const source = keySource.get(key)
         if (!source) continue
@@ -1127,6 +1231,12 @@ export class BasicQueryEngine implements QueryEngine {
       // field covered by an encryption map such a leaf therefore compares against
       // ciphertext and will not match.
       //
+      // This also means the #5803 plaintext-containment split (lib/search/containment) does not
+      // apply here: `buildColumnOpExpression` below keeps a multi-word `like`/`ilike` leaf as one
+      // literal pattern, so an OR-grouped search (e.g. `customers/api/people`'s multi-field
+      // fallback) loses word-order independence on Basic while the Hybrid engine's OR groups
+      // apply the split. Pre-existing divergence between the two engines; not tracked by an issue.
+      //
       // The count shape never populates cfValueExprByKey (it joins no cf tables), so
       // its applicability test is key resolution itself — the same condition that
       // gates the full shape's expression map — and a cf leaf compiles to a
@@ -1200,30 +1310,57 @@ export class BasicQueryEngine implements QueryEngine {
         }
       }
 
-      // Sorting: base fields and cf:* (use aggregated alias for cf)
+      // Sorting: base fields and cf:* (a dedicated scalar alias, never the jsonb
+      // projection alias — ordering by `to_jsonb(...)` compares arrays after every
+      // scalar string regardless of contents, and a numeric kind must cast to
+      // numeric instead of ordering the text CASE expression lexicographically (#5674)).
+      let lastEmittedSortField: string | null = null
       for (const s of isCountProjection ? [] : resolvedSorts) {
         if (s.field.startsWith('cf:')) {
           const key = s.field.slice(3)
-          const alias = sanitize(`cf:${key}`)
-          // Ensure included in projection to sort by
-          if (!cfSelectedAliases.includes(alias)) {
-            const expr = cfValueExprByKey[key]
-            if (expr) {
-              q = q.select(sql<string | null>`max(${expr})`.as(alias))
-              cfSelectedAliases.push(alias)
+          const sortAlias = sanitize(`cf:${key}__sort`)
+          if (!cfSortAliases.includes(sortAlias)) {
+            const source = keySource.get(key)
+            const kind = cfSortKinds.get(key)
+            let sortExpr: RawBuilder<unknown> | null = null
+            if (source && kind && NUMERIC_CF_SORT_KINDS.has(kind)) {
+              const sourceAliasSafe = sanitize(source.alias || 'src')
+              const keyAliasSafe = sanitize(key)
+              const valAlias = `cfv_${sourceAliasSafe}_${keyAliasSafe}`
+              const numericColumn = kind === 'integer' ? 'value_int' : 'value_float'
+              sortExpr = sql<string | null>`max((${sql.ref(`${valAlias}.${numericColumn}`)})::numeric)`
+            } else {
+              const expr = cfValueExprByKey[key]
+              if (expr) sortExpr = sql<string | null>`max(${expr})`
+            }
+            if (sortExpr) {
+              q = q.select(sortExpr.as(sortAlias))
+              cfSortAliases.push(sortAlias)
             }
           }
-          // Only order by an alias the projection actually carries. A key that
-          // resolved to no expression is dropped rather than emitted as an
-          // unselected alias, which is what the base-column branch above already
-          // does when `resolveBaseColumn` returns null.
-          if (!requiresPlaintextSort && cfSelectedAliases.includes(alias)) {
-            q = q.orderBy(alias, (s.dir ?? 'asc') as any)
+          // Only order by an alias the query actually selects. A key that resolved
+          // to no expression is dropped rather than emitted as an unselected alias,
+          // which is what the base-column branch below already does when
+          // `resolveBaseColumn` returns null.
+          if (!requiresPlaintextSort && cfSortAliases.includes(sortAlias)) {
+            const direction = sql.raw((s.dir ?? 'asc') === 'desc' ? 'desc' : 'asc')
+            q = q.orderBy(sql`${sql.ref(sortAlias)} ${direction} NULLS LAST`)
+            lastEmittedSortField = s.field
           }
         } else {
-          if (!requiresPlaintextSort) q = q.orderBy(qualify(s.field), (s.dir ?? 'asc') as any)
+          if (!requiresPlaintextSort) {
+            q = q.orderBy(qualify(s.field), (s.dir ?? 'asc') as any)
+            lastEmittedSortField = s.field
+          }
         }
       }
+      // Stable tiebreak so ties (or NULLs) don't reorder arbitrarily across pages
+      // (#5674). Only appended when a sort term actually made it into the ORDER
+      // BY — an entirely unresolved cf sort must stay a no-op, not gain an
+      // incidental `id` ordering the caller never asked for.
+      if (!isCountProjection && lastEmittedSortField !== null && lastEmittedSortField !== 'id') {
+        q = q.orderBy(qualify('id'), 'asc' as any)
+      }
 
       // Deduplicate if we joined CFs or extensions by grouping on base id. The count
       // shape has neither, and must stay barrier-free for its LIMIT to bind.
@@ -1235,7 +1372,7 @@ export class BasicQueryEngine implements QueryEngine {
         q = q.groupBy(`${table}.id`)
       }
 
-      return { builder: q, hasJoinedAggregates, cfJsonAliases, cfMultiAliasByAlias, resolvedCustomFieldDefinitions }
+      return { builder: q, hasJoinedAggregates, cfJsonAliases, cfMultiAliasByAlias, cfSortAliases, resolvedCustomFieldDefinitions }
     }
 
     // Pagination
@@ -1247,6 +1384,7 @@ export class BasicQueryEngine implements QueryEngine {
       hasJoinedAggregates,
       cfJsonAliases,
       cfMultiAliasByAlias,
+      cfSortAliases,
       resolvedCustomFieldDefinitions,
     } = await buildQuery('full')
 
@@ -1330,6 +1468,19 @@ export class BasicQueryEngine implements QueryEngine {
       }
     }
 
+    // The `cf:<key>__sort` alias exists only to give a `cf:` sort's ORDER BY
+    // something to reference (and, for a numeric kind, to host the cast) — it
+    // is never a requested output field. Strip it before rows leave this
+    // function so it doesn't leak into API responses as a phantom custom field
+    // `<key>__sort` (unlike `__is_multi`, which `normalizeCfJsonAliases`
+    // already deletes) (#5674 review).
+    const stripCfSortAliases = (rows: ResultRow[]) => {
+      if (cfSortAliases.length === 0) return
+      for (const row of rows) {
+        for (const alias of cfSortAliases) delete row[alias]
+      }
+    }
+
     let pagedItems: ResultRow[]
     let encryptedSortRowCapWarning: EncryptedSortRowCapWarning | undefined
 
@@ -1372,6 +1523,7 @@ export class BasicQueryEngine implements QueryEngine {
       } else {
         const pageRows = await qFull.where(qualify('id'), 'in', pageIds).execute() as ResultRow[]
         normalizeCfJsonAliases(pageRows)
+        stripCfSortAliases(pageRows)
         const decryptedPageRows = decryptPayload
           ? await mapWithConcurrency(pageRows, DECRYPT_CONCURRENCY, decryptRow)
           : pageRows
@@ -1384,6 +1536,7 @@ export class BasicQueryEngine implements QueryEngine {
       const dataQuery = qFull.limit(pageSize).offset((page - 1) * pageSize)
       const items = await dataQuery.execute() as ResultRow[]
       normalizeCfJsonAliases(items)
+      stripCfSortAliases(items)
       pagedItems = decryptPayload
         ? await mapWithConcurrency(items, DECRYPT_CONCURRENCY, decryptRow)
         : items

package/src/lib/search/__tests__/config.test.ts

@@ -113,6 +113,33 @@ describe('OM_SEARCH_FIELD_BLOCKLIST parsing', () => {
   })
 })
 
+describe('OM_SEARCH_USE_ILIKE_FOR_NON_ENCRYPTED_FIELDS', () => {
+  const originalValue = process.env.OM_SEARCH_USE_ILIKE_FOR_NON_ENCRYPTED_FIELDS
+
+  afterEach(() => {
+    if (originalValue === undefined) {
+      delete process.env.OM_SEARCH_USE_ILIKE_FOR_NON_ENCRYPTED_FIELDS
+    } else {
+      process.env.OM_SEARCH_USE_ILIKE_FOR_NON_ENCRYPTED_FIELDS = originalValue
+    }
+  })
+
+  // #5383: the switch stays off by default until tokenization is made ILIKE-equivalent, so the
+  // rewrite-everything behavior is unchanged for a deployment that does not opt in. #5803 is the
+  // correctness gap this switch closes when a deployment opts in ahead of that follow-up.
+  it('defaults to off so the legacy rewrite is unchanged for every column', () => {
+    delete process.env.OM_SEARCH_USE_ILIKE_FOR_NON_ENCRYPTED_FIELDS
+
+    expect(resolveSearchConfig().useIlikeForNonEncryptedFields).toBe(false)
+  })
+
+  it('can be switched on to apply a declared ilike on a plaintext column as written', () => {
+    process.env.OM_SEARCH_USE_ILIKE_FOR_NON_ENCRYPTED_FIELDS = 'true'
+
+    expect(resolveSearchConfig().useIlikeForNonEncryptedFields).toBe(true)
+  })
+})
+
 describe('search token limits', () => {
   const variableNames = [
     'OM_SEARCH_MAX_FIELD_CHARS',

package/src/lib/search/__tests__/containment.test.ts

@@ -0,0 +1,61 @@
+import { buildContainmentPatterns, MAX_CONTAINMENT_WORDS } from '../containment'
+
+describe('buildContainmentPatterns (#5803)', () => {
+  test('splits a multi-word contains pattern into one pattern per word', () => {
+    // The token subquery matched every token in any order with anything between them. Reproducing
+    // that on SQL means ANDing per word, which is what TC-RESO-009 exercises through the API:
+    // `?search=Warehouse <stamp>` has to keep matching `Warehouse A <stamp>`.
+    expect(buildContainmentPatterns('%Warehouse 1757%')).toEqual(['%Warehouse%', '%1757%'])
+  })
+
+  test('collapses runs of whitespace rather than emitting empty patterns', () => {
+    expect(buildContainmentPatterns('%John   Smith%')).toEqual(['%John%', '%Smith%'])
+  })
+
+  test('leaves a single-word pattern exactly as the caller declared it', () => {
+    // The reported #5803 case: the distinguishing fragment must reach SQL untouched, or the exact
+    // row cannot come back at all.
+    expect(buildContainmentPatterns('%2026-08%')).toEqual(['%2026-08%'])
+  })
+
+  test('leaves a term too short to tokenize alone', () => {
+    expect(buildContainmentPatterns('%08%')).toEqual(['%08%'])
+  })
+
+  test('keeps escaped wildcards attached to their word', () => {
+    // escapeLikePattern turns a literal `%` into `\%`; splitting must not treat it as a wildcard
+    // and must not tear the escape off its word.
+    expect(buildContainmentPatterns('%50\\% off%')).toEqual(['%50\\%%', '%off%'])
+  })
+
+  test('does not split a structured pattern carrying its own wildcards', () => {
+    // A caller that hand-built `%a% b%` asked for that exact shape; re-splitting it would silently
+    // rewrite a predicate this helper has no business reinterpreting.
+    expect(buildContainmentPatterns('%a% b%')).toEqual(['%a% b%'])
+  })
+
+  test('does not split an anchored pattern', () => {
+    // `startsWith` / `endsWith` terms are anchored on purpose; per-word ANDing would drop the
+    // anchor and widen the match.
+    expect(buildContainmentPatterns('John Smith%')).toEqual(['John Smith%'])
+    expect(buildContainmentPatterns('%John Smith')).toEqual(['%John Smith'])
+  })
+
+  test('treats a trailing escaped percent as a literal, not as the closing wildcard', () => {
+    expect(buildContainmentPatterns('%John Smith\\%')).toEqual(['%John Smith\\%'])
+  })
+
+  test('splits a term at the word cap', () => {
+    const words = Array.from({ length: MAX_CONTAINMENT_WORDS }, (_, index) => `w${index}`)
+    expect(buildContainmentPatterns(`%${words.join(' ')}%`)).toEqual(words.map((word) => `%${word}%`))
+  })
+
+  test('falls back to the single verbatim pattern above the word cap', () => {
+    // Most list routes declare `search` as an unbounded string and this repo ships no trigram
+    // index, so an unbounded per-word AND would let one request compile into an unbounded number
+    // of sequential-scan predicates. Past the cap, this returns to the pre-split behavior instead.
+    const words = Array.from({ length: MAX_CONTAINMENT_WORDS + 1 }, (_, index) => `w${index}`)
+    const pattern = `%${words.join(' ')}%`
+    expect(buildContainmentPatterns(pattern)).toEqual([pattern])
+  })
+})

package/src/lib/search/config.ts

@@ -9,12 +9,34 @@ export type SearchConfig = {
   hashAlgorithm: 'sha256' | 'sha1' | 'md5'
   storeRawTokens: boolean
   /**
-   * When true, a like/ilike on a PLAINTEXT base column runs as exact SQL ILIKE instead of being
-   * rewritten into an approximate search-token match; encrypted columns always keep the token
-   * path (ILIKE against ciphertext cannot match). Off by default: token matching can be faster
-   * than an unanchored ILIKE, which may need a full scan without a trigram index — but it is
-   * approximate (fragments under minTokenLength vanish, so `ZK 1/2026` degrades to its year and
-   * an all-short term drops the predicate). Flip it on when list search must be exact.
+   * When true, a like/ilike on a PLAINTEXT base column runs as SQL ILIKE — one containment
+   * predicate per word of the term, ANDed — instead of being rewritten into an approximate
+   * search-token match; encrypted columns always keep the token path (ILIKE against ciphertext
+   * cannot match).
+   *
+   * Off by default, per #5383: the token store is expected to become faster than ILIKE once
+   * tokenization is made semantically equivalent to it, so the plan there is to keep this switch
+   * off until that follow-up lands rather than trade performance for correctness by default. #5803
+   * documents the correctness gap this switch closes when enabled: the token rewrite is lossy in a
+   * way that silently returns the WRONG record rather than merely extra ones (tokenization splits
+   * on non-alphanumerics and drops fragments under minTokenLength, so `2026-08` and `2026-01` both
+   * reduce to {202, 2026} and a picker offers the neighbouring period; a term that tokenizes to
+   * nothing (`08`) drops the predicate entirely and matches every row) — a deployment that hits
+   * that gap before #5383 lands can opt in here.
+   *
+   * Per-word ANDing (see lib/search/containment) is a trade-off, not a strict improvement, over
+   * the single-literal ILIKE #4622 originally introduced: the token subquery matched a value
+   * carrying every token in any order with anything between them, so `?search=Warehouse 1757`
+   * must keep matching `Warehouse A 1757` — a single verbatim `ILIKE '%Warehouse 1757%'` would
+   * not, and TC-RESO-009 pins that as required behavior. The same word-order independence also
+   * widens multi-word document-number searches: `?search=ZK 1/2026` now also matches
+   * `ZK 11/2026` and `1/2026 ZK`, where the old single-literal ILIKE matched neither.
+   *
+   * Set `OM_SEARCH_USE_ILIKE_FOR_NON_ENCRYPTED_FIELDS=true` to opt into declared-column ILIKE
+   * ahead of #5383 — worth doing when the #5803 wrong-record symptom is hit in practice. Leaving it
+   * unset keeps the legacy rewrite-everything behavior, including the token index's prefix matching
+   * (`?search=ware` matching `Warehouse` when `enablePartials` is on, which literal containment
+   * gives only where the fragment really is a substring).
    */
   useIlikeForNonEncryptedFields?: boolean
   blocklistedFields: string[]

package/src/lib/search/containment.ts

@@ -0,0 +1,66 @@
+/**
+ * Splits a `contains` like/ilike pattern into one pattern per whitespace-separated word, so a
+ * plaintext column taken off the hashed-token path keeps the word-order-independent matching the
+ * token index provided.
+ *
+ * The token path matches a value when it carries EVERY token of the term, in any order and with
+ * anything in between: `?search=Warehouse 1757` matches `Warehouse A 1757`. A single verbatim
+ * `name ILIKE '%Warehouse 1757%'` is literal substring containment, so the `A ` sitting between the
+ * two words defeats it — that is a capability every list grid has today, and #5803's fix must not
+ * take it away (`TC-RESO-009` pins it).
+ *
+ * ANDing one containment predicate per word reproduces the token semantics exactly on a column the
+ * engine can read, without the token path's two lossy steps: nothing is dropped for being shorter
+ * than `minTokenLength` (`?search=08` filters instead of matching every row) and nothing is split on
+ * non-alphanumerics (`?search=2026-08` no longer collapses onto `2026-01`).
+ *
+ * Splitting is deliberately narrow — a pattern is only split when it is unambiguously the
+ * `%term%` shape `buildIlikeTerm(value, 'contains')` produces:
+ *
+ * - it opens and closes with a wildcard `%` (a trailing `\%` is an escaped literal, not a wildcard);
+ * - the term between them carries no unescaped `%` or `_`, so a hand-built structured pattern such
+ *   as `%a% b%` is left exactly as the caller wrote it;
+ * - the term holds at least two words.
+ *
+ * Anything else returns the input unchanged as a single pattern, which is the caller's existing
+ * behavior.
+ *
+ * The split is also capped at {@link MAX_CONTAINMENT_WORDS} words. Most list routes declare
+ * `search` as an unbounded string, this repository ships no trigram index for the resulting
+ * `ILIKE`, and the hybrid engine's `$or` groups multiply the split across every leaf — so an
+ * attacker-controlled term with thousands of words would otherwise compile into thousands of
+ * sequential-scan predicates from one request. A term at or under the cap keeps the per-word AND
+ * semantics; over the cap it falls back to the single verbatim pattern, which is bounded and was
+ * this helper's own behavior before the split existed.
+ */
+export const MAX_CONTAINMENT_WORDS = 10
+
+export function buildContainmentPatterns(pattern: string): string[] {
+  if (!isWrappedContainsPattern(pattern)) return [pattern]
+  const term = pattern.slice(1, -1)
+  if (hasUnescapedWildcard(term)) return [pattern]
+  const words = term.split(/\s+/).filter((word) => word.length > 0)
+  if (words.length < 2 || words.length > MAX_CONTAINMENT_WORDS) return [pattern]
+  return words.map((word) => `%${word}%`)
+}
+
+function isWrappedContainsPattern(pattern: string): boolean {
+  if (pattern.length < 2) return false
+  if (!pattern.startsWith('%') || !pattern.endsWith('%')) return false
+  return countTrailingBackslashes(pattern, pattern.length - 2) % 2 === 0
+}
+
+function hasUnescapedWildcard(term: string): boolean {
+  for (let index = 0; index < term.length; index += 1) {
+    const char = term[index]
+    if (char !== '%' && char !== '_') continue
+    if (countTrailingBackslashes(term, index - 1) % 2 === 0) return true
+  }
+  return false
+}
+
+function countTrailingBackslashes(value: string, fromIndex: number): number {
+  let count = 0
+  for (let index = fromIndex; index >= 0 && value[index] === '\\'; index -= 1) count += 1
+  return count
+}