@open-mercato/shared 0.9.1-develop.7474.1.51db10479d → 0.9.1-develop.7475.1.28ca93ed97

package/src/lib/localization/translatable-fields.ts

@@ -23,3 +23,49 @@ export function getTranslatableFields(entityType: string): string[] | undefined
 export function getTranslatableFieldsRegistry(): TranslatableFieldsRegistry {
   return { ...getGlobal() }
 }
+
+export type TranslatableFieldExpansion = {
+  key: string
+  label?: string
+  baseValue?: string
+}
+
+export type TranslatableFieldExpander = (record: Record<string, unknown>) => TranslatableFieldExpansion[]
+
+type TranslatableFieldExpanderRegistry = Record<string, TranslatableFieldExpander>
+
+const EXPANDER_GLOBAL_KEY = '__openMercatoTranslatableFieldExpanders__'
+
+type ExpanderGlobalHost = { [EXPANDER_GLOBAL_KEY]?: TranslatableFieldExpanderRegistry }
+
+function getExpanderGlobal(): TranslatableFieldExpanderRegistry {
+  return (globalThis as ExpanderGlobalHost)[EXPANDER_GLOBAL_KEY] ?? {}
+}
+
+export function registerTranslatableFieldExpander(entityType: string, expander: TranslatableFieldExpander): void {
+  const host = globalThis as ExpanderGlobalHost
+  host[EXPANDER_GLOBAL_KEY] = { ...getExpanderGlobal(), [entityType]: expander }
+}
+
+export function getTranslatableFieldExpander(entityType: string): TranslatableFieldExpander | undefined {
+  return getExpanderGlobal()[entityType]
+}
+
+type TranslatableEntityListPathRegistry = Record<string, string>
+
+const LIST_PATH_GLOBAL_KEY = '__openMercatoTranslatableEntityListPaths__'
+
+type ListPathGlobalHost = { [LIST_PATH_GLOBAL_KEY]?: TranslatableEntityListPathRegistry }
+
+function getListPathGlobal(): TranslatableEntityListPathRegistry {
+  return (globalThis as ListPathGlobalHost)[LIST_PATH_GLOBAL_KEY] ?? {}
+}
+
+export function registerTranslatableEntityListPath(entityType: string, listPath: string): void {
+  const host = globalThis as ListPathGlobalHost
+  host[LIST_PATH_GLOBAL_KEY] = { ...getListPathGlobal(), [entityType]: listPath }
+}
+
+export function getTranslatableEntityListPath(entityType: string): string | undefined {
+  return getListPathGlobal()[entityType]
+}

package/src/lib/query/__tests__/overlap.test.ts

@@ -0,0 +1,219 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import {
+  DummyDriver,
+  Kysely,
+  PostgresAdapter,
+  PostgresIntrospector,
+  PostgresQueryCompiler,
+  sql,
+  type RawBuilder,
+} from 'kysely'
+import { BasicQueryEngine } from '../engine'
+import { normalizeFilters } from '../join-utils'
+import {
+  buildArrayColumnNoOverlapPredicate,
+  buildArrayColumnOverlapPredicate,
+  buildJsonbNoOverlapPredicate,
+  buildJsonbOverlapPredicate,
+  buildScalarOverlapPredicate,
+  jsonbDocKeyExpression,
+  normalizeOverlapValues,
+} from '../overlap'
+import type { FilterOp } from '../types'
+
+function makeCompilingDb(): Kysely<any> {
+  return new Kysely<any>({
+    dialect: {
+      createAdapter: () => new PostgresAdapter(),
+      createDriver: () => new DummyDriver(),
+      createIntrospector: (db) => new PostgresIntrospector(db),
+      createQueryCompiler: () => new PostgresQueryCompiler(),
+    },
+  })
+}
+
+const db = makeCompilingDb()
+
+function compileWhere(predicate: RawBuilder<boolean>): { sql: string; parameters: readonly unknown[] } {
+  const compiled = db.selectFrom('entity_indexes as ei').select('ei.id').where(predicate).compile()
+  return { sql: compiled.sql, parameters: compiled.parameters }
+}
+
+type EngineInternals = {
+  applyColumnOp: (builder: unknown, column: string, op: string, value: unknown) => { compile: () => { sql: string; parameters: readonly unknown[] } }
+  buildColumnOpExpression: (eb: unknown, column: string, op: string, value: unknown) => RawBuilder<boolean>
+  buildIndexDocOpExpression: (eb: unknown, opts: {
+    entity: string
+    field: string
+    op: FilterOp
+    value: unknown
+    recordIdColumn: string
+    tenantId?: string | null
+    withDeleted: boolean
+  }) => RawBuilder<boolean>
+}
+
+const engine = new BasicQueryEngine({} as EntityManager, () => db) as unknown as EngineInternals
+
+describe('normalizeOverlapValues', () => {
+  it('flattens, stringifies, drops nullish and de-duplicates', () => {
+    expect(normalizeOverlapValues(['a', 'b', 'a', null, undefined, 3])).toEqual(['a', 'b', '3'])
+    expect(normalizeOverlapValues('a')).toEqual(['a'])
+    expect(normalizeOverlapValues(undefined)).toEqual([])
+    expect(normalizeOverlapValues(null)).toEqual([])
+  })
+})
+
+describe('overlap predicate builders', () => {
+  it('compiles a jsonb has-any-of with the values bound as one array parameter', () => {
+    const compiled = compileWhere(buildJsonbOverlapPredicate('ei.doc', 'scope_keys', ['cat:1', 'tag:2']))
+    expect(compiled.sql).toContain(`("ei"."doc" -> 'scope_keys') ?| $1::text[]`)
+    expect(compiled.parameters).toEqual([['cat:1', 'tag:2']])
+  })
+
+  it('never interpolates values into the SQL text', () => {
+    const hostile = "x'); drop table entity_indexes; --"
+    const compiled = compileWhere(buildJsonbOverlapPredicate('ei.doc', 'scope_keys', [hostile]))
+    expect(compiled.sql).not.toContain('drop table')
+    expect(compiled.parameters).toEqual([[hostile]])
+  })
+
+  it('binds a key that is not a plain identifier instead of inlining it', () => {
+    const key = "scope'keys"
+    const expression = db.selectFrom('entity_indexes as ei').select(jsonbDocKeyExpression('ei.doc', key).as('value')).compile()
+    expect(expression.sql).toContain('("ei"."doc" -> $1)')
+    expect(expression.parameters).toEqual([key])
+  })
+
+  it.each([
+    ['jsonb', () => buildJsonbOverlapPredicate('ei.doc', 'scope_keys', [])],
+    ['array column', () => buildArrayColumnOverlapPredicate('ei.tags', [])],
+    ['scalar', () => buildScalarOverlapPredicate(sql`ei.value`, [null, undefined])],
+  ])('compiles an empty %s value list to false (matches nothing)', (_label, build) => {
+    const compiled = compileWhere(build())
+    expect(compiled.sql).toMatch(/where false$/)
+    expect(compiled.parameters).toEqual([])
+  })
+
+  it('compiles array-column overlap to && with a bound array', () => {
+    const compiled = compileWhere(buildArrayColumnOverlapPredicate('ei.tags', ['a', 'b']))
+    expect(compiled.sql).toContain('"ei"."tags" && $1')
+    expect(compiled.parameters).toEqual([['a', 'b']])
+  })
+
+  it('compiles scalar overlap to an IN list of bound values', () => {
+    const compiled = compileWhere(buildScalarOverlapPredicate(sql`ei.value`, ['a', 'b']))
+    expect(compiled.sql).toContain('ei.value in ($1, $2)')
+    expect(compiled.parameters).toEqual(['a', 'b'])
+  })
+})
+
+describe('BasicQueryEngine overlap', () => {
+  it('normalizes $overlap from the object filter syntax', () => {
+    const filters = normalizeFilters({ scope_keys: { $overlap: ['cat:1'] } })
+    expect(filters).toEqual([expect.objectContaining({ field: 'scope_keys', op: 'overlap', value: ['cat:1'] })])
+  })
+
+  it('applies && on a base column', () => {
+    const builder = db.selectFrom('catalog_products as b').select('b.id')
+    const compiled = engine.applyColumnOp(builder, 'b.tags', 'overlap', ['x', 'y']).compile()
+    expect(compiled.sql).toContain('"b"."tags" && $1')
+    expect(compiled.parameters).toEqual([['x', 'y']])
+  })
+
+  it('compiles an index-document overlap inside the entity_indexes EXISTS', () => {
+    const compiled = db
+      .selectFrom('catalog_products as b')
+      .select('b.id')
+      .where((eb) => engine.buildIndexDocOpExpression(eb, {
+        entity: 'catalog:catalog_product',
+        field: 'scope_keys',
+        op: 'overlap',
+        value: ['cat:1'],
+        recordIdColumn: 'b.id',
+        tenantId: 'tenant-1',
+        withDeleted: false,
+      }))
+      .compile()
+    expect(compiled.sql).toMatch(/exists \(select 1 as "one" from "entity_indexes" as "ei_\d+"/)
+    expect(compiled.sql).toMatch(/\("ei_\d+"\."doc" -> 'scope_keys'\) \?\| \$\d+::text\[\]/)
+    expect(compiled.parameters).toContainEqual(['cat:1'])
+  })
+
+  it('leaves existing operators unchanged', () => {
+    const compiled = db
+      .selectFrom('catalog_products as b')
+      .select('b.id')
+      .where((eb) => eb.and([
+        engine.buildColumnOpExpression(eb, 'b.sku', 'in', ['a', 'b']),
+        engine.buildColumnOpExpression(eb, 'b.title', 'ilike', '%x%'),
+        engine.buildColumnOpExpression(eb, 'b.deleted_at', 'exists', false),
+      ]))
+      .compile()
+    expect(compiled.sql).toContain('"b"."sku" in ($1, $2)')
+    expect(compiled.sql).toContain('"b"."title" ilike $3')
+    expect(compiled.sql).toContain('"b"."deleted_at" is null')
+    expect(compiled.sql).not.toContain('&&')
+    expect(compiled.sql).not.toContain('?|')
+  })
+})
+
+describe('noverlap predicate builders', () => {
+  it('compiles a jsonb has-none-of that requires a present array', () => {
+    const compiled = compileWhere(buildJsonbNoOverlapPredicate('ei.doc', 'scope_keys', ['cat:1', 'tag:2']))
+    expect(compiled.sql).toContain(
+      `(jsonb_typeof(("ei"."doc" -> 'scope_keys')) = 'array' and not (("ei"."doc" -> 'scope_keys') ?| $1::text[]))`,
+    )
+    expect(compiled.parameters).toEqual([['cat:1', 'tag:2']])
+  })
+
+  it('keeps only the array check for an empty jsonb value list', () => {
+    const compiled = compileWhere(buildJsonbNoOverlapPredicate('ei.doc', 'scope_keys', []))
+    expect(compiled.sql).toMatch(/where jsonb_typeof\(\("ei"\."doc" -> 'scope_keys'\)\) = 'array'$/)
+    expect(compiled.parameters).toEqual([])
+  })
+
+  it('compiles array-column has-none-of to not && and an empty list to is not null', () => {
+    const compiled = compileWhere(buildArrayColumnNoOverlapPredicate('ei.tags', ['a']))
+    expect(compiled.sql).toContain('not ("ei"."tags" && $1)')
+    expect(compiled.parameters).toEqual([['a']])
+    expect(compileWhere(buildArrayColumnNoOverlapPredicate('ei.tags', [])).sql).toContain('"ei"."tags" is not null')
+  })
+})
+
+describe('BasicQueryEngine noverlap', () => {
+  it('normalizes $noverlap from the object filter syntax', () => {
+    const filters = normalizeFilters({ scope_keys: { $noverlap: ['cat:1'] } })
+    expect(filters).toEqual([expect.objectContaining({ field: 'scope_keys', op: 'noverlap', value: ['cat:1'] })])
+  })
+
+  it('compiles an index-document noverlap inside the entity_indexes EXISTS', () => {
+    const compiled = db
+      .selectFrom('catalog_products as b')
+      .select('b.id')
+      .where((eb) => engine.buildIndexDocOpExpression(eb, {
+        entity: 'catalog:catalog_product',
+        field: 'scope_keys',
+        op: 'noverlap',
+        value: ['cat:1'],
+        recordIdColumn: 'b.id',
+        tenantId: 'tenant-1',
+        withDeleted: false,
+      }))
+      .compile()
+    expect(compiled.sql).toMatch(/exists \(select 1 as "one" from "entity_indexes" as "ei_\d+"/)
+    expect(compiled.sql).toMatch(/not \(\("ei_\d+"\."doc" -> 'scope_keys'\) \?\| \$\d+::text\[\]\)/)
+  })
+
+  it('applies not && on a base column', () => {
+    const builder = db.selectFrom('catalog_products as b').select('b.id')
+    const compiled = engine.applyColumnOp(builder, 'b.tags', 'noverlap', ['x']).compile()
+    expect(compiled.sql).toContain('not ("b"."tags" && $1)')
+    const expression = db
+      .selectFrom('catalog_products as b')
+      .select('b.id')
+      .where((eb) => engine.buildColumnOpExpression(eb, 'b.tags', 'noverlap', ['x']))
+      .compile()
+    expect(expression.sql).toContain('not ("b"."tags" && $1)')
+  })
+})

package/src/lib/query/engine.ts

@@ -38,6 +38,13 @@ import { resolveListCountCap } from './count-cap'
 import { mapWithConcurrency } from './bounded-decrypt'
 import { parseNumberWithDefault } from '../number'
 import { createLogger } from '../logger'
+import {
+  buildArrayColumnNoOverlapPredicate,
+  buildArrayColumnOverlapPredicate,
+  buildJsonbNoOverlapPredicate,
+  buildJsonbOverlapPredicate,
+  buildScalarOverlapPredicate,
+} from './overlap'
 
 const logger = createLogger('shared').child({ component: 'query' })
 
@@ -1216,7 +1223,11 @@ export class BasicQueryEngine implements QueryEngine {
           })
           continue
         }
-        q = this.applyColumnOp(q, expr, f.op, f.value)
+        q = f.op === 'overlap'
+          ? q.where(buildScalarOverlapPredicate(expr, f.value))
+          : f.op === 'noverlap'
+            ? q.where(sql<boolean>`false`)
+            : this.applyColumnOp(q, expr, f.op, f.value)
       }
 
       // OR groups are applied here, after the cf:* value expressions exist, so a
@@ -1263,7 +1274,10 @@ export class BasicQueryEngine implements QueryEngine {
                     value: rf.value,
                   })
                 }
-                return this.buildColumnOpExpression(eb, cfValueExprByKey[rf.key], rf.op, rf.value)
+                if (rf.op === 'noverlap') return sql<boolean>`false`
+                return rf.op === 'overlap'
+                  ? buildScalarOverlapPredicate(cfValueExprByKey[rf.key], rf.value)
+                  : this.buildColumnOpExpression(eb, cfValueExprByKey[rf.key], rf.op, rf.value)
               }
               return this.buildIndexDocOpExpression(eb, {
                 entity: String(entity),
@@ -1601,6 +1615,10 @@ export class BasicQueryEngine implements QueryEngine {
         return value
           ? builder.where(column as any, 'is not', null)
           : builder.where(column as any, 'is', null)
+      case 'overlap':
+        return builder.where(buildArrayColumnOverlapPredicate(column, value))
+      case 'noverlap':
+        return builder.where(buildArrayColumnNoOverlapPredicate(column, value))
       default:
         return builder
     }
@@ -1734,6 +1752,11 @@ export class BasicQueryEngine implements QueryEngine {
       case 'exists':
         predicate = sql<boolean>`${caseExpr} is not null`
         break
+      case 'overlap':
+        predicate = buildScalarOverlapPredicate(caseExpr, value)
+        break
+      case 'noverlap':
+        return sql<boolean>`false`
       default:
         // Mirrors buildColumnOpExpression's unknown-op fallback: a neutral
         // predicate, so full and count shapes drop the same leaves.
@@ -1756,6 +1779,8 @@ export class BasicQueryEngine implements QueryEngine {
       case 'like': return eb(column, 'like', value)
       case 'ilike': return eb(column, 'ilike', value)
       case 'exists': return value ? eb(column, 'is not', null) : eb(column, 'is', null)
+      case 'overlap': return buildArrayColumnOverlapPredicate(column, value)
+      case 'noverlap': return buildArrayColumnNoOverlapPredicate(column, value)
       default: return eb.val(true)
     }
   }
@@ -1973,6 +1998,12 @@ export class BasicQueryEngine implements QueryEngine {
             ? sub.where(sql<boolean>`${textExpr} is not null`)
             : sub.where(sql<boolean>`${textExpr} is null`)
           break
+        case 'overlap':
+          sub = sub.where(buildJsonbOverlapPredicate(`${alias}.doc`, opts.field, opts.value))
+          break
+        case 'noverlap':
+          sub = sub.where(buildJsonbNoOverlapPredicate(`${alias}.doc`, opts.field, opts.value))
+          break
         default:
           break
       }

package/src/lib/query/join-utils.ts

@@ -7,7 +7,7 @@ type AnyBuilder = any
 
 export type NormalizedFilter = { field: string; op: FilterOp; value?: unknown; orGroup?: string; qualified?: string | null }
 
-const VALID_OPS = ['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'nin', 'like', 'ilike', 'exists'] as const
+const VALID_OPS = ['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'nin', 'like', 'ilike', 'exists', 'overlap', 'noverlap'] as const
 
 const normalizeField = (key: string) => (key.startsWith('cf_') ? `cf:${key.slice(3)}` : key)
 

package/src/lib/query/overlap.ts

@@ -0,0 +1,106 @@
+import { sql, type RawBuilder } from 'kysely'
+
+const LITERAL_SAFE_DOC_KEY = /^[A-Za-z0-9_:.-]{1,128}$/
+
+/**
+ * Normalizes the right-hand side of an `overlap` filter into a de-duplicated list of strings.
+ *
+ * `null`/`undefined` entries are dropped; a scalar is treated as a one-element list. An empty
+ * result means the filter matches nothing — every `overlap` builder compiles it to `false`
+ * rather than dropping the predicate, so a caller that computes an empty inclusion set can
+ * never widen a query by accident.
+ */
+export function normalizeOverlapValues(value: unknown): string[] {
+  const list: readonly unknown[] = Array.isArray(value)
+    ? value
+    : value === undefined || value === null
+      ? []
+      : [value]
+  const out: string[] = []
+  const seen = new Set<string>()
+  for (const entry of list) {
+    if (entry === undefined || entry === null) continue
+    const normalized = String(entry)
+    if (seen.has(normalized)) continue
+    seen.add(normalized)
+    out.push(normalized)
+  }
+  return out
+}
+
+/**
+ * `(<docColumn> -> '<key>')` — the jsonb sub-document of an index document.
+ *
+ * The key is emitted as an escaped SQL literal when it is a plain identifier so the expression is
+ * textually identical to a GIN expression index such as `((doc -> 'scope_keys'))` and the planner
+ * can match it. Any other key falls back to a bound parameter (still correct, just not indexable).
+ */
+export function jsonbDocKeyExpression(docColumnRef: string, key: string): RawBuilder<unknown> {
+  const keyExpr = LITERAL_SAFE_DOC_KEY.test(key) ? sql.lit(key) : sql`${key}`
+  return sql`(${sql.ref(docColumnRef)} -> ${keyExpr})`
+}
+
+/**
+ * jsonb "has any of" over a string-array key of an index document:
+ * `(<docColumn> -> '<key>') ?| $n::text[]`. The values are bound as one array parameter.
+ * A missing key or a JSON `null` evaluates to SQL NULL, i.e. the row does not match.
+ */
+export function buildJsonbOverlapPredicate(docColumnRef: string, key: string, value: unknown): RawBuilder<boolean> {
+  const values = normalizeOverlapValues(value)
+  if (!values.length) return sql<boolean>`false`
+  return sql<boolean>`${jsonbDocKeyExpression(docColumnRef, key)} ?| ${values}::text[]`
+}
+
+/**
+ * jsonb "has none of" over a string-array key of an index document (`noverlap`):
+ * `(jsonb_typeof(<expr>) = 'array' and not (<expr> ?| $n::text[]))`.
+ *
+ * Only a document whose key holds a JSON array can match: a missing key, a JSON `null` or a
+ * scalar never satisfies it, so an unindexed document can never slip through an exclusion.
+ * An empty value list excludes nothing (only the array check remains).
+ */
+export function buildJsonbNoOverlapPredicate(docColumnRef: string, key: string, value: unknown): RawBuilder<boolean> {
+  const values = normalizeOverlapValues(value)
+  const keyExpr = jsonbDocKeyExpression(docColumnRef, key)
+  const isArray = sql<boolean>`jsonb_typeof(${keyExpr}) = 'array'`
+  if (!values.length) return isArray
+  return sql<boolean>`(${isArray} and not (${keyExpr} ?| ${values}::text[]))`
+}
+
+/**
+ * Postgres array overlap for array-typed columns: `<column> && $n`. The bound array takes its
+ * element type from the column, so `text[]`, `varchar[]` and `uuid[]` columns all work.
+ */
+export function buildArrayColumnOverlapPredicate(
+  column: string | RawBuilder<unknown>,
+  value: unknown,
+): RawBuilder<boolean> {
+  const values = normalizeOverlapValues(value)
+  if (!values.length) return sql<boolean>`false`
+  const columnExpr = typeof column === 'string' ? sql.ref(column) : column
+  return sql<boolean>`${columnExpr} && ${values}`
+}
+
+/**
+ * Postgres array "has none of" for array-typed columns (`noverlap`): `not (<column> && $n)`.
+ * A NULL column never matches; an empty value list excludes nothing (`<column> is not null`).
+ */
+export function buildArrayColumnNoOverlapPredicate(
+  column: string | RawBuilder<unknown>,
+  value: unknown,
+): RawBuilder<boolean> {
+  const values = normalizeOverlapValues(value)
+  const columnExpr = typeof column === 'string' ? sql.ref(column) : column
+  if (!values.length) return sql<boolean>`${columnExpr} is not null`
+  return sql<boolean>`not (${columnExpr} && ${values})`
+}
+
+/**
+ * `overlap` over a scalar expression evaluated once per stored value (custom-field value rows):
+ * the record matches when any of its values is one of the requested ones — `<expr> in (...)`.
+ */
+export function buildScalarOverlapPredicate(expression: RawBuilder<unknown>, value: unknown): RawBuilder<boolean> {
+  const values = normalizeOverlapValues(value)
+  if (!values.length) return sql<boolean>`false`
+  return sql<boolean>`${expression} in (${sql.join(values.map((entry) => sql`${entry}`), sql`, `)})`
+}

package/src/lib/query/types.ts

@@ -2,7 +2,17 @@ import type { EntityId } from '@open-mercato/shared/modules/entities'
 import type { Profiler } from '../profiler'
 import type { ResolvedCustomFieldDefinitions } from '../crud/custom-field-definition-index'
 
-export type FilterOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'like' | 'ilike' | 'exists'
+/**
+ * `overlap` (additive, 2026-10-05): "has any of" over a multi-valued field. An index-document
+ * string array compiles to jsonb `?|`, a `cf:*` key to any-value-in-set, and an array-typed base
+ * column to `&&`. An empty value list matches nothing.
+ *
+ * `noverlap` (additive, 2026-10-05): "has none of" — the negation of `overlap` on an index-document
+ * string array or an array-typed base column. Only a present array can match (a missing/null key or
+ * NULL column never does); an empty value list excludes nothing. Unsupported on `cf:*` keys, where
+ * it compiles to `false`.
+ */
+export type FilterOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'like' | 'ilike' | 'exists' | 'overlap' | 'noverlap'
 
 export enum SortDir {
   Asc = 'asc',
@@ -34,6 +44,8 @@ export type WhereOps<T> = {
   $like?: T extends string ? string : never
   $ilike?: T extends string ? string : never
   $exists?: boolean
+  $overlap?: T extends readonly (infer Element)[] ? Element[] : T[]
+  $noverlap?: T extends readonly (infer Element)[] ? Element[] : T[]
 }
 
 // A field filter can be a direct value (equals) or ops object

package/src/modules/search.ts

@@ -94,6 +94,39 @@ export type SearchOptions = {
   offset?: number
   /** How to combine results: 'or' merges all, 'and' requires match in all strategies */
   combineMode?: 'or' | 'and'
+  /**
+   * Restricts results to records whose query-index row (`entity_indexes`) matches this predicate,
+   * evaluated inside the strategy's ranking query so a restrictive filter never starves the result
+   * set (additive, 2026-10-06). Only strategies with `supportsIndexDocFilter: true` receive a
+   * filtered search; any other strategy returns no results for it rather than unfiltered ones.
+   */
+  indexDocFilter?: SearchIndexDocFilter
+}
+
+/**
+ * One condition over a record's query-index document (`entity_indexes.doc`), with the query
+ * engine's index-document semantics:
+ * - `exists`: the key is present and not JSON `null`;
+ * - `eq`: the key's text value equals `value` (booleans and numbers compare by their JSON text);
+ * - `overlap`: the key holds an array sharing at least one entry with `values`; empty `values`
+ *   matches nothing;
+ * - `noverlap`: the key holds an array sharing no entry with `values`; a missing key never matches;
+ * - `recordIdNotIn`: the record id is none of `values`.
+ */
+export type SearchIndexDocCondition =
+  | { op: 'exists'; key: string }
+  | { op: 'eq'; key: string; value: string | number | boolean }
+  | { op: 'overlap'; key: string; values: string[] }
+  | { op: 'noverlap'; key: string; values: string[] }
+  | { op: 'recordIdNotIn'; values: string[] }
+
+/**
+ * A predicate over a record's `entity_indexes` row in disjunctive normal form: the record matches
+ * when its index row is not deleted and every condition of at least one `anyOf` branch holds.
+ * An empty `anyOf` matches nothing; an empty branch matches every indexed record.
+ */
+export type SearchIndexDocFilter = {
+  anyOf: SearchIndexDocCondition[][]
 }
 
 // =============================================================================
@@ -144,6 +177,12 @@ export interface SearchStrategy {
   /** Priority for result merging (higher = more prominent in results) */
   readonly priority: number
 
+  /**
+   * Whether `search()` applies `SearchOptions.indexDocFilter` inside its ranking query. Absent or
+   * `false` means the strategy is skipped for filtered searches (fail closed).
+   */
+  readonly supportsIndexDocFilter?: boolean
+
   /** Check if strategy is available and configured */
   isAvailable(): Promise<boolean>