@open-mercato/shared 0.6.7 → 0.6.8-develop.6874.1.982d6097d8

package/src/lib/modules/__tests__/surfaceFingerprint.test.ts

@@ -0,0 +1,122 @@
+import type { Module, BackendRouteManifestEntry } from '../../../modules/registry'
+import { getBackendRouteManifests } from '../../../modules/registry'
+import { getModules } from '../registry'
+import { getModuleSurfaceFingerprint } from '../surfaceFingerprint'
+
+jest.mock('../registry', () => ({
+  getModules: jest.fn(),
+}))
+
+jest.mock('../../../modules/registry', () => ({
+  getBackendRouteManifests: jest.fn(),
+}))
+
+const mockGetModules = jest.mocked(getModules)
+const mockGetBackendRouteManifests = jest.mocked(getBackendRouteManifests)
+
+function route(pattern: string, overrides: Partial<BackendRouteManifestEntry> = {}): BackendRouteManifestEntry {
+  return {
+    moduleId: 'auth',
+    pattern,
+    title: 'Page',
+    load: async () => null,
+    ...overrides,
+  } as BackendRouteManifestEntry
+}
+
+type ModuleSurface = string | { id: string; features: Array<{ id: string; module?: string }> }
+
+function setSurface(modules: ModuleSurface[], routes: BackendRouteManifestEntry[]): void {
+  mockGetModules.mockReturnValue(modules.map((mod) => (typeof mod === 'string' ? { id: mod } : mod) as Module))
+  mockGetBackendRouteManifests.mockReturnValue(routes)
+}
+
+describe('getModuleSurfaceFingerprint', () => {
+  afterEach(() => {
+    jest.resetAllMocks()
+  })
+
+  it('is stable for the same enabled modules and route manifest', () => {
+    setSurface(['auth', 'search'], [route('/backend/dashboard')])
+    const first = getModuleSurfaceFingerprint()
+
+    setSurface(['auth', 'search'], [route('/backend/dashboard')])
+    expect(getModuleSurfaceFingerprint()).toBe(first)
+  })
+
+  it('changes when a module is enabled — the deploy that used to serve a stale nav', () => {
+    setSurface(['auth'], [route('/backend/dashboard')])
+    const before = getModuleSurfaceFingerprint()
+
+    setSurface(['auth', 'search'], [route('/backend/dashboard')])
+    expect(getModuleSurfaceFingerprint()).not.toBe(before)
+  })
+
+  it('changes when a backend route is added', () => {
+    setSurface(['auth'], [route('/backend/dashboard')])
+    const before = getModuleSurfaceFingerprint()
+
+    setSurface(['auth'], [route('/backend/dashboard'), route('/backend/search')])
+    expect(getModuleSurfaceFingerprint()).not.toBe(before)
+  })
+
+  it('changes when only a route metadata field changes', () => {
+    setSurface(['auth'], [route('/backend/dashboard', { title: 'Dashboard' })])
+    const before = getModuleSurfaceFingerprint()
+
+    setSurface(['auth'], [route('/backend/dashboard', { title: 'Overview' })])
+    expect(getModuleSurfaceFingerprint()).not.toBe(before)
+  })
+
+  it('changes when a module declares a new feature and no route moves', () => {
+    const routes = [route('/backend/dashboard')]
+    setSurface([{ id: 'auth', features: [{ id: 'auth.view' }] }], routes)
+    const before = getModuleSurfaceFingerprint()
+
+    setSurface([{ id: 'auth', features: [{ id: 'auth.view' }, { id: 'auth.manage' }] }], routes)
+    expect(getModuleSurfaceFingerprint()).not.toBe(before)
+  })
+
+  it('changes when a feature declares a different owning module', () => {
+    const routes = [route('/backend/dashboard')]
+    setSurface([{ id: 'auth', features: [{ id: 'analytics.view' }] }], routes)
+    const before = getModuleSurfaceFingerprint()
+
+    setSurface([{ id: 'auth', features: [{ id: 'analytics.view', module: 'reporting' }] }], routes)
+    expect(getModuleSurfaceFingerprint()).not.toBe(before)
+  })
+
+  it('ignores feature ordering within a module', () => {
+    const routes = [route('/backend/dashboard')]
+    setSurface([{ id: 'auth', features: [{ id: 'auth.view' }, { id: 'auth.manage' }] }], routes)
+    const forward = getModuleSurfaceFingerprint()
+
+    setSurface([{ id: 'auth', features: [{ id: 'auth.manage' }, { id: 'auth.view' }] }], routes)
+    expect(getModuleSurfaceFingerprint()).toBe(forward)
+  })
+
+  it('ignores route manifest ordering', () => {
+    setSurface(['auth'], [route('/backend/a'), route('/backend/b')])
+    const forward = getModuleSurfaceFingerprint()
+
+    setSurface(['auth'], [route('/backend/b'), route('/backend/a')])
+    expect(getModuleSurfaceFingerprint()).toBe(forward)
+  })
+
+  it('falls back to the route manifest alone when the module registry is not populated', () => {
+    mockGetModules.mockImplementation(() => {
+      throw new Error('[Bootstrap] Modules not registered.')
+    })
+    mockGetBackendRouteManifests.mockReturnValue([route('/backend/dashboard')])
+
+    expect(getModuleSurfaceFingerprint()).toMatch(/^[0-9a-f]{12}$/)
+  })
+
+  it('degrades to a constant rather than throwing when route metadata cannot be serialized', () => {
+    const circular = route('/backend/dashboard') as BackendRouteManifestEntry & { self?: unknown }
+    circular.self = circular
+    setSurface(['auth'], [circular])
+
+    expect(getModuleSurfaceFingerprint()).toBe('unknown')
+  })
+})

package/src/lib/modules/registry.ts

@@ -69,3 +69,13 @@ export function getModules(): Module[] {
   }
   return modules
 }
+
+/**
+ * Non-throwing counterpart of `getModules()` for call sites that have a
+ * meaningful degraded behavior when bootstrap has not run — route unit tests
+ * exercise a single handler without `registerModules()`, and a hard throw there
+ * turns an unrelated assertion into a bootstrap error.
+ */
+export function tryGetModules(): Module[] | null {
+  return getGlobalModules()
+}

package/src/lib/modules/surfaceFingerprint.ts

@@ -0,0 +1,87 @@
+/**
+ * Deploy-time fingerprint of the registered module surface.
+ *
+ * Some cached payloads are derived from state that only changes when the app
+ * is redeployed — the enabled module set and the backend route manifest. That
+ * state has no database write to hang a tag invalidation off, so a cache key
+ * that omits it keeps serving the pre-deploy payload to anyone with a warm
+ * entry (see `/api/auth/admin/nav`, whose payload embeds
+ * `filterGrantsByEnabledModules(...)` computed at write time).
+ *
+ * Mixing this fingerprint into such keys makes new processes write to new
+ * keys, so old and new pods coexist during a rolling deploy without a purge
+ * step and without any ordering constraint between purge and rollout.
+ *
+ * Covered inputs: the enabled module ids, each module's declared `features`
+ * (which drive `filterGrantsByEnabledModules`, including the `*` superadmin
+ * expansion and off-convention prefixes), and every JSON-serializable field
+ * of the backend route manifest.
+ *
+ * NOT covered: a route's `icon`. It is a React element whose `type` is a
+ * function, which `JSON.stringify` drops — two different icon components
+ * serialize identically. Swapping an icon heals on the caller's TTL, not on
+ * the fingerprint. Callers MUST therefore still pass a `ttl`.
+ */
+import { createHash } from 'node:crypto'
+import type { Module } from '../../modules/registry'
+import { getBackendRouteManifests } from '../../modules/registry'
+import { getModules } from './registry'
+
+const UNKNOWN_FINGERPRINT = 'unknown'
+
+let cachedFingerprint: string | null = null
+let cachedManifestsRef: unknown = null
+let cachedModulesRef: unknown = null
+
+function readModulesRef(): readonly Module[] | null {
+  try {
+    return getModules()
+  } catch {
+    return null
+  }
+}
+
+function byCodeUnit(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0
+}
+
+function describeModules(modules: readonly Module[] | null): string[] {
+  if (!modules) return []
+  return modules
+    .map((mod) => {
+      const features = (Array.isArray(mod.features) ? mod.features : [])
+        .filter((feature) => feature && typeof feature.id === 'string' && feature.id.length > 0)
+        .map((feature) => `${feature.id}:${feature.module || mod.id}`)
+        .sort(byCodeUnit)
+      return JSON.stringify({ id: mod.id, features })
+    })
+    .sort(byCodeUnit)
+}
+
+export function getModuleSurfaceFingerprint(): string {
+  const manifests = getBackendRouteManifests()
+  const modulesRef = readModulesRef()
+  if (cachedFingerprint !== null && cachedManifestsRef === manifests && cachedModulesRef === modulesRef) {
+    return cachedFingerprint
+  }
+  // The manifest carries third-party route metadata and module-scope React
+  // elements, so serialization is not fully under this repo's control. Every
+  // other fallible step in the nav handler degrades rather than throws, and a
+  // throw here would blank the entire admin chrome — fall back to a constant,
+  // which is exactly the pre-fingerprint behavior.
+  let fingerprint: string
+  try {
+    const modules = describeModules(modulesRef)
+    const routes = manifests.map((route) => JSON.stringify(route)).sort(byCodeUnit)
+    fingerprint = createHash('sha1')
+      .update(JSON.stringify({ modules, routes }))
+      .digest('hex')
+      .slice(0, 12)
+  } catch {
+    fingerprint = UNKNOWN_FINGERPRINT
+  }
+  cachedManifestsRef = manifests
+  cachedModulesRef = modulesRef
+  cachedFingerprint = fingerprint
+  return fingerprint
+}

package/src/lib/query/__tests__/ciphertext-search-warning.test.ts

@@ -0,0 +1,178 @@
+import {
+  normalizeColumnName,
+  resetCiphertextLikeWarnCache,
+  warnOnCiphertextLikeFallback,
+} from '../ciphertext-search-warning'
+import { createLogger } from '../../logger'
+
+jest.mock('../../logger', () => {
+  const warn = jest.fn()
+  const debug = jest.fn()
+  const child = jest.fn(() => ({ warn, debug }))
+  return { createLogger: jest.fn(() => ({ child })), __warn: warn, __debug: debug }
+})
+
+const loggerModule = jest.requireMock('../../logger') as { __warn: jest.Mock; __debug: jest.Mock }
+
+function createService(encryptedFields: string[], overrides: Record<string, unknown> = {}) {
+  return {
+    isEnabled: () => true,
+    getEncryptedFieldNames: jest.fn(async () => encryptedFields),
+    ...overrides,
+  }
+}
+
+describe('warnOnCiphertextLikeFallback', () => {
+  beforeEach(() => {
+    resetCiphertextLikeWarnCache()
+    loggerModule.__warn.mockClear()
+    loggerModule.__debug.mockClear()
+  })
+
+  it('warns when the filtered column is covered by an encryption map', async () => {
+    const service = createService(['email', 'display_name'])
+    await warnOnCiphertextLikeFallback({
+      entity: 'customers:customer_entity',
+      fields: ['display_name'],
+      tenantId: 'tenant-1',
+      reason: 'no-search-tokens',
+      service,
+    })
+
+    expect(loggerModule.__warn).toHaveBeenCalledTimes(1)
+    const [message, payload] = loggerModule.__warn.mock.calls[0]
+    expect(message).toBe('Text search filter cannot match an encrypted column')
+    expect(payload).toMatchObject({
+      entity: 'customers:customer_entity',
+      field: 'display_name',
+      reason: 'no-search-tokens',
+    })
+  })
+
+  it('stays quiet for columns outside the encryption map', async () => {
+    await warnOnCiphertextLikeFallback({
+      entity: 'currencies:currency',
+      fields: ['code', 'symbol'],
+      tenantId: 'tenant-1',
+      reason: 'no-search-tokens',
+      service: createService(['unrelated']),
+    })
+    expect(loggerModule.__warn).not.toHaveBeenCalled()
+  })
+
+  it('does not cache a non-encrypted lookup as already warned', async () => {
+    await warnOnCiphertextLikeFallback({
+      entity: 'auth:user', fields: ['email'], tenantId: 'tenant-1', reason: 'no-search-tokens', service: createService([]),
+    })
+    await warnOnCiphertextLikeFallback({
+      entity: 'auth:user', fields: ['email'], tenantId: 'tenant-1', reason: 'no-search-tokens', service: createService(['email']),
+    })
+    expect(loggerModule.__warn).toHaveBeenCalledTimes(1)
+  })
+
+  it('matches camelCase filter fields against snake_case map entries', async () => {
+    await warnOnCiphertextLikeFallback({
+      entity: 'checkout:checkout_transaction',
+      fields: ['firstName'],
+      tenantId: null,
+      reason: 'no-search-tokens',
+      service: createService(['first_name']),
+    })
+    expect(loggerModule.__warn).toHaveBeenCalledTimes(1)
+    expect(loggerModule.__warn.mock.calls[0][1]).toMatchObject({ field: 'first_name' })
+  })
+
+  it('warns once per entity, tenant and field', async () => {
+    const service = createService(['email'])
+    const params = {
+      entity: 'auth:user',
+      fields: ['email'],
+      tenantId: 'tenant-1',
+      reason: 'no-search-tokens' as const,
+      service,
+    }
+    await warnOnCiphertextLikeFallback(params)
+    await warnOnCiphertextLikeFallback(params)
+    await warnOnCiphertextLikeFallback(params)
+
+    expect(loggerModule.__warn).toHaveBeenCalledTimes(1)
+    expect(service.getEncryptedFieldNames).toHaveBeenCalledTimes(1)
+  })
+
+  it('warns separately for a different tenant', async () => {
+    const service = createService(['email'])
+    await warnOnCiphertextLikeFallback({
+      entity: 'auth:user', fields: ['email'], tenantId: 'tenant-1', reason: 'no-search-tokens', service,
+    })
+    await warnOnCiphertextLikeFallback({
+      entity: 'auth:user', fields: ['email'], tenantId: 'tenant-2', reason: 'no-search-tokens', service,
+    })
+    expect(loggerModule.__warn).toHaveBeenCalledTimes(2)
+  })
+
+  it('does nothing when encryption is unavailable or disabled', async () => {
+    await warnOnCiphertextLikeFallback({
+      entity: 'auth:user', fields: ['email'], tenantId: null, reason: 'no-search-tokens', service: null,
+    })
+    await warnOnCiphertextLikeFallback({
+      entity: 'auth:user',
+      fields: ['email'],
+      tenantId: null,
+      reason: 'no-search-tokens',
+      service: createService(['email'], { isEnabled: () => false }),
+    })
+    expect(loggerModule.__warn).not.toHaveBeenCalled()
+  })
+
+  it('ignores custom-field filters', async () => {
+    const service = createService(['cf:secret_note'])
+    await warnOnCiphertextLikeFallback({
+      entity: 'example:todo', fields: ['cf:secret_note'], tenantId: null, reason: 'no-search-tokens', service,
+    })
+    expect(service.getEncryptedFieldNames).not.toHaveBeenCalled()
+    expect(loggerModule.__warn).not.toHaveBeenCalled()
+  })
+
+  it('reports the disabled-search reason with its own hint', async () => {
+    await warnOnCiphertextLikeFallback({
+      entity: 'auth:user', fields: ['email'], tenantId: null, reason: 'search-disabled', service: createService(['email']),
+    })
+    expect(loggerModule.__warn.mock.calls[0][1]).toMatchObject({ reason: 'search-disabled' })
+    expect(loggerModule.__warn.mock.calls[0][1].hint).toContain('OM_SEARCH_ENABLED')
+  })
+
+  it('reports values that are too short to tokenize', async () => {
+    await warnOnCiphertextLikeFallback({
+      entity: 'auth:user', fields: ['email'], tenantId: null, reason: 'no-indexable-tokens', service: createService(['email']),
+    })
+    expect(loggerModule.__warn.mock.calls[0][1]).toMatchObject({ reason: 'no-indexable-tokens' })
+    expect(loggerModule.__warn.mock.calls[0][1].hint).toContain('OM_SEARCH_MIN_LEN')
+  })
+
+  it('never rethrows when the encryption lookup fails', async () => {
+    const service = {
+      isEnabled: () => true,
+      getEncryptedFieldNames: jest.fn(async () => { throw new Error('kms down') }),
+    }
+    await expect(warnOnCiphertextLikeFallback({
+      entity: 'auth:user', fields: ['email'], tenantId: null, reason: 'no-search-tokens', service,
+    })).resolves.toBeUndefined()
+    expect(loggerModule.__warn).not.toHaveBeenCalled()
+    expect(loggerModule.__debug).toHaveBeenCalled()
+  })
+})
+
+describe('normalizeColumnName', () => {
+  it('converts camelCase to snake_case and lowercases', () => {
+    expect(normalizeColumnName('firstName')).toBe('first_name')
+    expect(normalizeColumnName('primaryEmail')).toBe('primary_email')
+    expect(normalizeColumnName('display_name')).toBe('display_name')
+    expect(normalizeColumnName('Email')).toBe('email')
+  })
+})
+
+describe('logger wiring', () => {
+  it('uses the shared query logger namespace', () => {
+    expect(createLogger).toHaveBeenCalledWith('shared')
+  })
+})

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

@@ -1,6 +1,13 @@
 import { BasicQueryEngine } from '../engine'
 import { SortDir } from '../types'
 import { registerModules } from '../../i18n/server'
+import { clearSearchTokenPresenceCache } from '../../search/availability'
+
+// The token-presence answer is cached process-wide (TTL); without clearing it,
+// probe-count assertions would observe hits from earlier tests in this file.
+beforeEach(() => {
+  clearSearchTokenPresenceCache()
+})
 
 // Mock modules with one entity extension
 const mockModules = [
@@ -355,6 +362,8 @@ describe('BasicQueryEngine (Kysely)', () => {
     const fakeDb = createFakeKysely({
       customer_entities: [],
       customer_people: [],
+      search_tokens: [{ one: 1 }],
+      'information_schema.tables': [{ table_name: 'search_tokens' }],
       'information_schema.columns': [
         { table_name: 'customer_entities', column_name: 'tenant_id' },
         { table_name: 'customer_people', column_name: 'id' },
@@ -362,8 +371,6 @@ describe('BasicQueryEngine (Kysely)', () => {
       ],
     })
     const engine = new BasicQueryEngine({} as any, () => fakeDb as any)
-    jest.spyOn(engine as any, 'tableExists').mockResolvedValue(true)
-    jest.spyOn(engine as any, 'hasSearchTokens').mockResolvedValue(true)
     const applySearchTokensSpy = jest.spyOn(engine as any, 'applySearchTokens')
 
     await engine.query('customers:customer_entity', {
@@ -409,7 +416,6 @@ describe('BasicQueryEngine (Kysely)', () => {
       ],
     })
     const engine = new BasicQueryEngine({} as any, () => fakeDb as any)
-    jest.spyOn(engine as any, 'tableExists').mockResolvedValue(false)
     const applySearchTokensSpy = jest.spyOn(engine as any, 'applySearchTokens')
 
     await engine.query('customers:customer_entity', {
@@ -445,10 +451,10 @@ describe('BasicQueryEngine (Kysely)', () => {
   test('uses search tokens for index document fields on base entities', async () => {
     const fakeDb = createFakeKysely({
       todos: [],
+      search_tokens: [{ one: 1 }],
+      'information_schema.tables': [{ table_name: 'search_tokens' }],
     })
     const engine = new BasicQueryEngine({} as any, () => fakeDb as any)
-    const tableExistsSpy = jest.spyOn(engine as any, 'tableExists').mockResolvedValue(true)
-    const hasSearchTokensSpy = jest.spyOn(engine as any, 'hasSearchTokens').mockResolvedValue(true)
     const applySearchTokensSpy = jest.spyOn(engine as any, 'applySearchTokens')
 
     await engine.query('example:todo', {
@@ -461,12 +467,15 @@ describe('BasicQueryEngine (Kysely)', () => {
       page: { page: 1, pageSize: 10 },
     })
 
-    expect(tableExistsSpy).toHaveBeenCalledWith('search_tokens')
-    expect(hasSearchTokensSpy).toHaveBeenCalledWith(
-      'example:todo',
-      't1',
-      expect.objectContaining({ ids: ['org1'] }),
-    )
+    const calls = fakeDb._calls as Array<{ _ops: { table: string; wheres: unknown[][] } }>
+    const tableProbe = calls.find((call) =>
+      call._ops.table === 'information_schema.tables' &&
+      call._ops.wheres.some((where) => where[0] === 'table_name' && where[2] === 'search_tokens'))
+    expect(tableProbe).toBeTruthy()
+    const tokenProbe = calls.find((call) =>
+      call._ops.table === 'search_tokens' &&
+      call._ops.wheres.some((where) => where[0] === 'entity_type' && where[2] === 'example:todo'))
+    expect(tokenProbe).toBeTruthy()
     expect(applySearchTokensSpy).toHaveBeenCalledWith(
       expect.anything(),
       expect.objectContaining({
@@ -488,7 +497,6 @@ describe('BasicQueryEngine (Kysely)', () => {
       ],
     })
     const engine = new BasicQueryEngine({} as any, () => fakeDb as any)
-    const hasSearchTokensSpy = jest.spyOn(engine as any, 'hasSearchTokens').mockResolvedValue(true)
     const applySearchTokensSpy = jest.spyOn(engine as any, 'applySearchTokens')
 
     await engine.query('example:todo', {
@@ -501,7 +509,8 @@ describe('BasicQueryEngine (Kysely)', () => {
       page: { page: 1, pageSize: 10 },
     })
 
-    expect(hasSearchTokensSpy).not.toHaveBeenCalled()
+    const calls = fakeDb._calls as Array<{ _ops: { table: string } }>
+    expect(calls.some((call) => call._ops.table === 'search_tokens')).toBe(false)
     expect(applySearchTokensSpy).not.toHaveBeenCalled()
     const baseCall = fakeDb._calls.find((builder: any) => builder._ops.table === 'todos')
     expect(baseCall?._ops.wheres).toContainEqual(['todos.search_text', 'ilike', '%avision%'])
@@ -933,4 +942,47 @@ describe('BasicQueryEngine (Kysely)', () => {
     expect(baseCall._ops.limits).toBe(10)
     expect(baseCall._ops.offsets).toBe(10)
   })
+
+  describe('search_tokens coverage probe (#4723 parity)', () => {
+    type ProbeDbLog = { _calls: Array<{ _ops: { table: string } }> }
+
+    const countProbes = (fakeDb: ProbeDbLog): number =>
+      fakeDb._calls.filter((call) => call._ops.table === 'search_tokens').length
+
+    const buildEngine = (fakeDb: unknown): BasicQueryEngine => new BasicQueryEngine(
+      {} as ConstructorParameters<typeof BasicQueryEngine>[0],
+      (() => fakeDb) as unknown as NonNullable<ConstructorParameters<typeof BasicQueryEngine>[1]>,
+    )
+
+    const buildDb = () => createFakeKysely({
+      users: [],
+      'information_schema.tables': [{ table_name: 'search_tokens' }],
+    })
+
+    test('is skipped when the query carries no like/ilike filter', async () => {
+      const fakeDb = buildDb()
+      const engine = buildEngine(fakeDb)
+
+      await engine.query('auth:user', {
+        tenantId: 't1',
+        organizationId: 'org1',
+        filters: { is_active: { $eq: true } },
+      })
+
+      expect(countProbes(fakeDb)).toBe(0)
+    })
+
+    test('still runs when the query actually searches', async () => {
+      const fakeDb = buildDb()
+      const engine = buildEngine(fakeDb)
+
+      await engine.query('auth:user', {
+        tenantId: 't1',
+        organizationId: 'org1',
+        filters: { email: { $ilike: '%abc%' } },
+      })
+
+      expect(countProbes(fakeDb)).toBeGreaterThan(0)
+    })
+  })
 })

package/src/lib/query/ciphertext-search-warning.ts

@@ -0,0 +1,95 @@
+import { createLogger } from '../logger'
+import type { EntityId } from '../../modules/entities'
+
+const logger = createLogger('shared').child({ component: 'query' })
+
+/**
+ * Minimal slice of `TenantDataEncryptionService` needed to decide whether a
+ * text filter targets an encrypted column.
+ */
+export type CiphertextWarningEncryptionService = {
+  getEncryptedFieldNames?: (
+    entityId: EntityId,
+    tenantId?: string | null,
+    organizationId?: string | null,
+  ) => Promise<readonly string[]>
+  isEnabled?: () => boolean
+} | null | undefined
+
+export type CiphertextLikeFallbackReason = 'no-indexable-tokens' | 'no-search-tokens' | 'search-disabled'
+
+// One warning per entity/tenant/field per process — the fallback repeats on
+// every request, and an operator only needs to learn about it once.
+const WARN_CACHE_CAP = 5000
+const warned = new Set<string>()
+
+const warnKey = (entity: string, tenantId: string | null, field: string): string =>
+  `${entity}|${tenantId ?? 'null'}|${field}`
+
+export const normalizeColumnName = (value: string): string =>
+  value.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase()
+
+/** Test seam: the warn-once cache is process-global by design. */
+export function resetCiphertextLikeWarnCache(): void {
+  warned.clear()
+}
+
+/**
+ * Warn when a `like`/`ilike` filter is about to run against a column that an
+ * encryption map covers while the token index is unavailable.
+ *
+ * Without this the query degrades silently: the predicate compares a plaintext
+ * pattern against ciphertext, matches nothing, and the endpoint returns an
+ * empty page that is indistinguishable from a genuine no-result. Issue #2990.
+ *
+ * Never throws and never blocks the query — a failure here is logged at debug
+ * level and the caller proceeds unchanged.
+ */
+export async function warnOnCiphertextLikeFallback(params: {
+  entity: string
+  fields: readonly string[]
+  tenantId: string | null
+  reason: CiphertextLikeFallbackReason
+  service: CiphertextWarningEncryptionService
+}): Promise<void> {
+  const { entity, tenantId, reason, service } = params
+  if (!service || service.isEnabled?.() === false) return
+  if (typeof service.getEncryptedFieldNames !== 'function') return
+
+  const candidates = params.fields
+    .filter((field) => typeof field === 'string' && !field.startsWith('cf:'))
+    .map((field) => normalizeColumnName(field))
+    .filter((field, index, all) => field.length > 0 && all.indexOf(field) === index)
+    .filter((field) => !warned.has(warnKey(entity, tenantId, field)))
+  if (!candidates.length) return
+
+  try {
+    // `organizationId: null` resolves the global map plus every per-organization
+    // override, so a field encrypted for any organization is reported.
+    const encrypted = new Set(
+      (await service.getEncryptedFieldNames(entity, tenantId, null)).map((field) =>
+        normalizeColumnName(String(field)),
+      ),
+    )
+    for (const field of candidates) {
+      if (!encrypted.has(field)) continue
+      if (warned.size >= WARN_CACHE_CAP) warned.clear()
+      warned.add(warnKey(entity, tenantId, field))
+      logger.warn('Text search filter cannot match an encrypted column', {
+        entity,
+        field,
+        reason,
+        hint: reason === 'search-disabled'
+          ? 'OM_SEARCH_ENABLED is off, so the filter runs as ILIKE against ciphertext and matches nothing.'
+          : reason === 'no-indexable-tokens'
+            ? 'The filter value produced no search tokens, so it runs as ILIKE against ciphertext and matches nothing. Use at least OM_SEARCH_MIN_LEN indexable characters, or filter on the deterministic hash column.'
+            : 'No search_tokens exist for this entity and scope, so the filter runs as ILIKE against ciphertext and matches nothing. Index the entity through query_index and reindex, or filter on the deterministic hash column.',
+      })
+    }
+  } catch (err) {
+    logger.debug('Ciphertext search warning check failed', {
+      entity,
+      err: err instanceof Error ? err.message : String(err),
+    })
+  }
+}