@open-mercato/shared 0.6.8-develop.7091.1.15ffbe30ce → 0.6.8-develop.7093.1.700c5c8d96

package/dist/lib/version.js

@@ -1,4 +1,4 @@
-const APP_VERSION = "0.6.8-develop.7091.1.15ffbe30ce";
+const APP_VERSION = "0.6.8-develop.7093.1.700c5c8d96";
 const appVersion = APP_VERSION;
 export {
   APP_VERSION,

package/dist/lib/version.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/version.ts"],
-  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.6.8-develop.7091.1.15ffbe30ce';\nexport const appVersion = APP_VERSION;\n"],
+  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.6.8-develop.7093.1.700c5c8d96';\nexport const appVersion = APP_VERSION;\n"],
   "mappings": "AACO,MAAM,cAAc;AACpB,MAAM,aAAa;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/shared",
-  "version": "0.6.8-develop.7091.1.15ffbe30ce",
+  "version": "0.6.8-develop.7093.1.700c5c8d96",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -109,7 +109,7 @@
     "@mikro-orm/core": "^7.1.8",
     "@mikro-orm/decorators": "^7.1.8",
     "@mikro-orm/postgresql": "^7.1.8",
-    "@open-mercato/cache": "0.6.8-develop.7091.1.15ffbe30ce",
+    "@open-mercato/cache": "0.6.8-develop.7093.1.700c5c8d96",
     "@types/html-to-text": "^9.0.4",
     "@types/sanitize-html": "^2.16.1",
     "dotenv": "^17.4.2",

package/src/lib/crud/__tests__/crud-factory.test.ts

@@ -12,6 +12,16 @@ import {
 import { loadCustomFieldDefinitionIndex } from '@open-mercato/shared/lib/crud/custom-fields'
 import { registerMutationGuards } from '@open-mercato/shared/lib/crud/mutation-guard-store'
 import { CommandInterceptorError } from '@open-mercato/shared/lib/commands/errors'
+import {
+  registerLoggerExtension,
+  resetLoggerExtension,
+  type LoggerExtensionRecord,
+} from '@open-mercato/shared/lib/logger'
+import {
+  registerTelemetryRuntime,
+  resetTelemetryRuntime,
+  type TelemetryRuntime,
+} from '@open-mercato/shared/lib/telemetry/runtime'
 import { z } from 'zod'
 
 // Keep the real custom-field helpers but spy on the definition loader so we can
@@ -1076,6 +1086,7 @@ describe('CRUD Factory', () => {
     await expect(res.json()).resolves.toEqual({
       error: 'Internal server error',
       message: 'Something went wrong. Please try again later.',
+      requestId: expect.any(String),
     })
   })
 
@@ -1114,6 +1125,138 @@ describe('CRUD Factory', () => {
     await expect(res.json()).resolves.toEqual({
       error: 'Internal server error',
       message: 'Something went wrong. Please try again later.',
+      requestId: expect.any(String),
+    })
+  })
+
+  // Issue #5608 — a generic 500 must carry a requestId the client/support can cite, and
+  // that same id must appear on the server log line so the two can be correlated.
+  describe('generic 500 requestId correlation', () => {
+    const logRecords: LoggerExtensionRecord[] = []
+    const reportError = jest.fn()
+
+    const postWithRequestId = (requestId: string) => interceptorErrorRoute().POST(
+      new Request('http://x/api/example/todos/command', {
+        method: 'POST',
+        body: JSON.stringify({ title: 'A' }),
+        headers: { 'content-type': 'application/json', 'x-request-id': requestId },
+      }),
+    )
+
+    beforeEach(() => {
+      logRecords.length = 0
+      reportError.mockClear()
+      registerLoggerExtension({ emit: (record) => logRecords.push(record) })
+      registerTelemetryRuntime({
+        canUseGlobalTracePropagation: () => false,
+        captureTraceContext: () => ({}),
+        continueTrace: (_carrier, _name, fn) => fn(),
+        recordHttpDuration: () => {},
+        reportError,
+        shutdown: async () => {},
+      } satisfies TelemetryRuntime)
+    })
+
+    afterEach(() => {
+      resetLoggerExtension()
+      resetTelemetryRuntime()
+    })
+
+    it('includes a requestId in the body that matches the server log line', async () => {
+      commandBus.execute.mockRejectedValue(new Error('boom'))
+
+      const res = await postInterceptorErrorRequest(interceptorErrorRoute())
+      const body = await res.json()
+
+      expect(res.status).toBe(500)
+      expect(typeof body.requestId).toBe('string')
+      expect(body.requestId.length).toBeGreaterThan(0)
+
+      const logRecord = logRecords.find((record) => record.message === 'Unexpected CRUD error')
+      expect(logRecord?.fields.requestId).toBe(body.requestId)
+    })
+
+    it('echoes the requestId on an x-request-id response header', async () => {
+      commandBus.execute.mockRejectedValue(new Error('boom'))
+
+      const res = await postInterceptorErrorRequest(interceptorErrorRoute())
+      const body = await res.json()
+
+      expect(res.headers.get('x-request-id')).toBe(body.requestId)
+    })
+
+    it('reuses an inbound x-request-id header instead of generating a new one', async () => {
+      commandBus.execute.mockRejectedValue(new Error('boom'))
+
+      const res = await postWithRequestId('req-fixed-123')
+      const body = await res.json()
+
+      expect(res.status).toBe(500)
+      expect(body.requestId).toBe('req-fixed-123')
+      const logRecord = logRecords.find((record) => record.message === 'Unexpected CRUD error')
+      expect(logRecord?.fields.requestId).toBe('req-fixed-123')
+    })
+
+    // `Headers.get()` returns '' for an empty or whitespace-only header, which a plain
+    // `?? randomUUID()` would hand straight through as a blank correlation id.
+    it.each([
+      ['an empty inbound header', ''],
+      ['a whitespace-only inbound header', '   '],
+    ])('generates a fresh id for %s', async (_label, inbound) => {
+      commandBus.execute.mockRejectedValue(new Error('boom'))
+
+      const res = await postWithRequestId(inbound)
+      const body = await res.json()
+
+      expect(res.status).toBe(500)
+      expect(typeof body.requestId).toBe('string')
+      expect(body.requestId.length).toBeGreaterThan(0)
+      const logRecord = logRecords.find((record) => record.message === 'Unexpected CRUD error')
+      expect(logRecord?.fields.requestId).toBe(body.requestId)
+    })
+
+    // A caller-controlled id lands verbatim in the unquoted `key=value` log line, so an
+    // over-long one or one carrying spaces/`=` is discarded rather than echoed.
+    it.each([
+      ['a value carrying log-field separators', 'a=1 tenantId=victim'],
+      ['an over-long value', 'x'.repeat(129)],
+    ])('discards %s in favor of a generated id', async (_label, inbound) => {
+      commandBus.execute.mockRejectedValue(new Error('boom'))
+
+      const res = await postWithRequestId(inbound)
+      const body = await res.json()
+
+      expect(res.status).toBe(500)
+      expect(body.requestId).not.toBe(inbound)
+      expect(body.requestId).toMatch(/^[A-Za-z0-9-]{36}$/)
+    })
+
+    it('reports the error to telemetry with the same requestId', async () => {
+      commandBus.execute.mockRejectedValue(new Error('boom'))
+
+      const res = await postWithRequestId('req-fixed-123')
+      const body = await res.json()
+
+      expect(body.requestId).toBe('req-fixed-123')
+      expect(reportError).toHaveBeenCalledTimes(1)
+      expect(reportError).toHaveBeenCalledWith(
+        expect.any(Error),
+        { module: 'crud', attributes: { requestId: 'req-fixed-123', errorName: 'Error' } },
+      )
+    })
+
+    // The 503/422 branches deliberately stay outside this change (issue #5608) — lock that
+    // in so a later refactor cannot quietly widen the correlation id across every branch.
+    it('leaves the interceptor-rejection branch without a requestId', async () => {
+      commandBus.execute.mockRejectedValue(
+        new CommandInterceptorError('Missing required fields: VAT id', { status: 422 }),
+      )
+
+      const res = await postWithRequestId('req-fixed-123')
+
+      expect(res.status).toBe(422)
+      await expect(res.json()).resolves.toEqual({ error: 'Missing required fields: VAT id' })
+      expect(res.headers.get('x-request-id')).toBeNull()
     })
   })
 

package/src/lib/crud/factory.ts

@@ -75,6 +75,8 @@ import { createGenericOptimisticLockReader } from './optimistic-lock'
 import { registerOptimisticLockReaderIfAbsent } from './optimistic-lock-store'
 import { createLogger } from '../logger'
 import { isTransientDbError } from '../db/pg-errors'
+import { getTelemetryRuntime } from '../telemetry/runtime'
+import { randomUUID } from 'node:crypto'
 
 type RbacServiceLike = {
   getGrantedFeatures: (userId: string, opts: { tenantId: string | null; organizationId: string | null }) => Promise<string[]>
@@ -594,7 +596,19 @@ function attachOperationHeader(res: Response, logEntry: any) {
   return res
 }
 
-function handleError(err: unknown): Response {
+// An inbound `x-request-id` is caller-controlled, so it is only reused when it still
+// looks like an id. `Headers.get()` yields '' for an empty or whitespace-only header —
+// which `??` would not replace — and an unbounded value carrying spaces or `=` would
+// forge fields in the unquoted `key=value` log line this id exists to be read from.
+const INBOUND_REQUEST_ID_PATTERN = /^[A-Za-z0-9._-]{1,128}$/
+
+function resolveRequestId(request?: Request): string {
+  const inbound = request?.headers.get('x-request-id')?.trim()
+  if (inbound && INBOUND_REQUEST_ID_PATTERN.test(inbound)) return inbound
+  return randomUUID()
+}
+
+function handleError(err: unknown, request?: Request): Response {
   if (err instanceof Response) return err
   if (isCrudHttpError(err)) return json(err.body, { status: err.status })
   // A command interceptor that blocked with an explicit status is a deliberate business
@@ -618,14 +632,25 @@ function handleError(err: unknown): Response {
     )
   }
 
+  // Unexpected exceptions still collapse into a generic 500 for the client (no internal
+  // detail leaked), but a requestId ties that response to this log line and to whatever
+  // reaches APM, so a client/support ticket citing it can be correlated with server-side
+  // detail (issue #5608).
   const message = err instanceof Error ? err.message : undefined
   const stack = err instanceof Error ? err.stack : undefined
-  logger.error('Unexpected CRUD error', { message, stack, err })
+  const errorName = err instanceof Error ? err.name : undefined
+  const requestId = resolveRequestId(request)
+  logger.error('Unexpected CRUD error', { message, stack, err, requestId })
+  getTelemetryRuntime()?.reportError(err, {
+    module: 'crud',
+    attributes: { requestId, errorName },
+  })
   const body: Record<string, unknown> = {
     error: 'Internal server error',
     message: 'Something went wrong. Please try again later.',
+    requestId,
   }
-  return json(body, { status: 500 })
+  return json(body, { status: 500, headers: { 'x-request-id': requestId } })
 }
 
 const LIFECYCLE_ACTION_MAP: Record<string, { before: string; after: string }> = {
@@ -2163,7 +2188,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
       return response
     } catch (e) {
       finishProfile({ result: 'error' })
-      return handleError(e)
+      return handleError(e, request)
     }
   }
 
@@ -2477,7 +2502,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
       payload = await enrichSingleRecord(payload, ctx)
       return json(payload, { status: 201 })
     } catch (e) {
-      return handleError(e)
+      return handleError(e, request)
     }
   }
 
@@ -2815,7 +2840,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
       }
       return json(payload)
     } catch (e) {
-      return handleError(e)
+      return handleError(e, request)
     }
   }
 
@@ -3104,7 +3129,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
       }
       return json(payload)
     } catch (e) {
-      return handleError(e)
+      return handleError(e, request)
     }
   }
 

package/src/lib/query/__tests__/engine.count-distinct.test.ts

@@ -1,6 +1,13 @@
-import { BasicQueryEngine } from '../engine'
+import { BasicQueryEngine, clearColumnExistsCache } from '../engine'
 import { registerModules } from '../../i18n/server'
 
+// The column-existence answer is memoized on the module, not the instance (#5605), so
+// the per-test fake schemas below would otherwise inherit whatever the first test
+// probed for the same table names.
+beforeEach(() => {
+  clearColumnExistsCache()
+})
+
 // One entity extension on auth:user so includeExtensions exercises the joined-aggregate path.
 registerModules([
   { id: 'auth', entityExtensions: [{ base: 'auth:user', extension: 'my_module:user_profile', join: { baseKey: 'id', extensionKey: 'user_id' } }] },

package/src/lib/query/__tests__/engine.scope-and-or.test.ts

@@ -1,6 +1,16 @@
-import { BasicQueryEngine } from '../engine'
+import { BasicQueryEngine, clearColumnExistsCache } from '../engine'
 import { normalizeFilters } from '../join-utils'
 
+// The column-existence answer is memoized on the module, not the instance (#5605), and
+// the fixtures below declare mutually contradictory `information_schema.columns` shapes
+// for the same `scheduled_jobs` table. Without this clear, whichever test ran first
+// decides the scoping every later test sees — the automatic tenant/organization guard
+// would silently drop out of a query and the assertion for it would still be reading a
+// stale `false`.
+beforeEach(() => {
+  clearColumnExistsCache()
+})
+
 type FakeData = Record<string, any[]>
 
 function cloneRows(rows: any[] | undefined): any[] {

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

@@ -2,13 +2,14 @@ import { BasicQueryEngine } from '../engine'
 import { SortDir } from '../types'
 import { registerModules } from '../../i18n/server'
 import { clearSearchTokenPresenceCache } from '../../search/availability'
-import { clearEncryptedLikeFieldsCache } from '../engine'
+import { clearEncryptedLikeFieldsCache, clearColumnExistsCache, columnExistsCacheSize } from '../engine'
 
 // 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()
   clearEncryptedLikeFieldsCache()
+  clearColumnExistsCache()
 })
 
 // Mock modules with one entity extension
@@ -1415,3 +1416,159 @@ describe('BasicQueryEngine like/ilike routing by column encryption', () => {
       })
   })
 })
+
+describe('module-scoped column-existence cache (#5605)', () => {
+  const columnProbes = (fakeDb: any) =>
+    fakeDb._calls.filter((b: any) => b._ops.table === 'information_schema.columns')
+
+  const columnProbesFor = (fakeDb: any, column: string) =>
+    columnProbes(fakeDb).filter((b: any) =>
+      b._ops.wheres.some((w: any) => Array.isArray(w) && w[0] === 'column_name' && w[1] === '=' && w[2] === column)
+    )
+
+  const hasTenantGuard = (fakeDb: any) => {
+    const baseCall = fakeDb._calls.find((b: any) => b._ops.table === 'customer_entities')
+    return !!baseCall?._ops.wheres.some(
+      (w: any) => Array.isArray(w) && w[0] === 'customer_entities.tenant_id' && w[1] === '=' && w[2] === 't1',
+    )
+  }
+
+  const originalTtl = process.env.OM_QUERY_COLUMN_EXISTS_CACHE_MS
+  const originalMaxEntries = process.env.OM_QUERY_COLUMN_EXISTS_CACHE_MAX_ENTRIES
+
+  afterEach(() => {
+    if (originalTtl === undefined) delete process.env.OM_QUERY_COLUMN_EXISTS_CACHE_MS
+    else process.env.OM_QUERY_COLUMN_EXISTS_CACHE_MS = originalTtl
+    if (originalMaxEntries === undefined) delete process.env.OM_QUERY_COLUMN_EXISTS_CACHE_MAX_ENTRIES
+    else process.env.OM_QUERY_COLUMN_EXISTS_CACHE_MAX_ENTRIES = originalMaxEntries
+    jest.restoreAllMocks()
+  })
+
+  test('the column-existence cache is shared across separate engine instances', async () => {
+    // `createRequestContainer()` builds a fresh `BasicQueryEngine` per HTTP request.
+    // The cache must live on the module, not the instance, so a later "request" (a
+    // second engine here) reuses the first request's answer instead of re-probing
+    // `information_schema.columns`.
+    const fakeDb = createFakeKysely({
+      customer_entities: [],
+      'information_schema.columns': [
+        { table_name: 'customer_entities', column_name: 'tenant_id' },
+      ],
+    })
+    const queryOpts = { tenantId: 't1', fields: ['id'], page: { page: 1, pageSize: 10 } }
+
+    const engine1 = new BasicQueryEngine({} as any, () => fakeDb as any)
+    await engine1.query('customers:customer_entity', queryOpts)
+    const probesAfterFirstEngine = columnProbes(fakeDb).length
+    expect(probesAfterFirstEngine).toBeGreaterThan(0)
+
+    const engine2 = new BasicQueryEngine({} as any, () => fakeDb as any)
+    await engine2.query('customers:customer_entity', queryOpts)
+    expect(columnProbes(fakeDb).length).toBe(probesAfterFirstEngine)
+  })
+
+  test('a missing column is remembered as false instead of being re-queried on every call', async () => {
+    // Before the fix, `columnExists` deleted a `false` result instead of caching it,
+    // so `organization_id` (absent here) was re-queried once per query projection
+    // ('full' and 'count') within a single `.query()` call.
+    const fakeDb = createFakeKysely({
+      customer_entities: [],
+      'information_schema.columns': [],
+    })
+    const engine = new BasicQueryEngine({} as any, () => fakeDb as any)
+
+    await engine.query('customers:customer_entity', {
+      tenantId: 't1',
+      organizationId: 'org1',
+      fields: ['id'],
+      page: { page: 1, pageSize: 10 },
+    })
+
+    expect(columnProbesFor(fakeDb, 'organization_id').length).toBe(1)
+  })
+
+  test('a cached negative expires, so a migrated-in scope column is picked up without a process restart', async () => {
+    // A cached `false` is consumed where the tenant/organization/soft-delete predicates
+    // are applied, so a stale one does not merely slow a query down — it silently drops
+    // a scope guard. The TTL bounds that window: a migration applied against a running
+    // process (`yarn dev`, or pods not recycled by a separate migration release step)
+    // converges once the entry expires instead of never.
+    const now = 1_700_000_000_000
+    const nowSpy = jest.spyOn(Date, 'now').mockReturnValue(now)
+
+    const beforeMigration = createFakeKysely({
+      customer_entities: [],
+      'information_schema.columns': [],
+    })
+    const queryOpts = { tenantId: 't1', fields: ['id'], page: { page: 1, pageSize: 10 } }
+    await new BasicQueryEngine({} as any, () => beforeMigration as any).query('customers:customer_entity', queryOpts)
+    expect(columnProbesFor(beforeMigration, 'tenant_id').length).toBe(1)
+    expect(hasTenantGuard(beforeMigration)).toBe(false)
+
+    // Same process, same cache — a second request while the entry is still fresh reuses
+    // the negative and does not re-probe, even though the column now exists.
+    const afterMigration = createFakeKysely({
+      customer_entities: [],
+      'information_schema.columns': [
+        { table_name: 'customer_entities', column_name: 'tenant_id' },
+      ],
+    })
+    await new BasicQueryEngine({} as any, () => afterMigration as any).query('customers:customer_entity', queryOpts)
+    expect(columnProbesFor(afterMigration, 'tenant_id').length).toBe(0)
+    expect(hasTenantGuard(afterMigration)).toBe(false)
+
+    nowSpy.mockReturnValue(now + 300_001)
+
+    const afterTtl = createFakeKysely({
+      customer_entities: [],
+      'information_schema.columns': [
+        { table_name: 'customer_entities', column_name: 'tenant_id' },
+      ],
+    })
+    await new BasicQueryEngine({} as any, () => afterTtl as any).query('customers:customer_entity', queryOpts)
+    expect(columnProbesFor(afterTtl, 'tenant_id').length).toBe(1)
+    expect(hasTenantGuard(afterTtl)).toBe(true)
+  })
+
+  test('the cache is bounded, so caller-supplied sort fields cannot grow it without limit', async () => {
+    // `columnExists` is reached with raw request input through `resolveBaseColumn` —
+    // `sortField` arrives from the query string and many list schemas type it as a plain
+    // string. Without a cap, one distinct name per request would be retained for the
+    // lifetime of the process.
+    process.env.OM_QUERY_COLUMN_EXISTS_CACHE_MAX_ENTRIES = '4'
+    const fakeDb = createFakeKysely({
+      customer_entities: [],
+      'information_schema.columns': [],
+    })
+    const engine = new BasicQueryEngine({} as any, () => fakeDb as any)
+
+    for (let index = 0; index < 20; index += 1) {
+      await engine.query('customers:customer_entity', {
+        tenantId: 't1',
+        fields: ['id'],
+        sort: [{ field: `attacker_supplied_${index}`, dir: SortDir.Asc }],
+        page: { page: 1, pageSize: 10 },
+      })
+      expect(columnExistsCacheSize()).toBeLessThanOrEqual(4)
+    }
+  })
+
+  test('OM_QUERY_COLUMN_EXISTS_CACHE_MS=0 disables the memo and probes per request again', async () => {
+    process.env.OM_QUERY_COLUMN_EXISTS_CACHE_MS = '0'
+    const fakeDb = createFakeKysely({
+      customer_entities: [],
+      'information_schema.columns': [
+        { table_name: 'customer_entities', column_name: 'tenant_id' },
+      ],
+    })
+    const queryOpts = { tenantId: 't1', fields: ['id'], page: { page: 1, pageSize: 10 } }
+
+    await new BasicQueryEngine({} as any, () => fakeDb as any).query('customers:customer_entity', queryOpts)
+    const probesAfterFirstEngine = columnProbesFor(fakeDb, 'tenant_id').length
+    expect(probesAfterFirstEngine).toBeGreaterThan(0)
+    expect(columnExistsCacheSize()).toBe(0)
+
+    await new BasicQueryEngine({} as any, () => fakeDb as any).query('customers:customer_entity', queryOpts)
+    expect(columnProbesFor(fakeDb, 'tenant_id').length).toBeGreaterThan(probesAfterFirstEngine)
+  })
+})

package/src/lib/query/engine.ts

@@ -33,6 +33,7 @@ import { warnOnCiphertextLikeFallback } from './ciphertext-search-warning'
 import { resolveEncryptedSortFields, resolveEncryptedSortMaxRows, sortRowsInMemory } from './encrypted-sort'
 import { resolveListCountCap } from './count-cap'
 import { mapWithConcurrency } from './bounded-decrypt'
+import { parseNumberWithDefault } from '../number'
 import { createLogger } from '../logger'
 
 const logger = createLogger('shared').child({ component: 'query' })
@@ -89,6 +90,58 @@ export function clearEncryptedLikeFieldsCache(): void {
   encryptedLikeFieldsCache.clear()
 }
 
+// Module-scoped on purpose: `createRequestContainer` builds a fresh `BasicQueryEngine`
+// per request, so an instance field alone re-pays the `information_schema` probe on
+// every request (#5605). Schema shape (does a table have this column?) is not
+// per-request state — unlike `tenantEncryptionService` — so sharing the answer across
+// requests is safe. One map per module instance rather than a true process singleton:
+// standalone builds can duplicate this package, which for a memo is harmless (two
+// caches, both correct), so nothing may be built on top of singleton semantics here.
+//
+// Bounded and TTL'd for two reasons. `columnExists` is reached with caller-supplied
+// field names via `resolveBaseColumn` (sort fields and base filter keys arrive raw from
+// the HTTP layer), so an unbounded map would grow monotonically on request input. And a
+// cached `false` is consumed where the tenant/organization/soft-delete predicates are
+// applied, so a schema change that adds one of those columns must not stay invisible
+// until the process restarts — a migration applied against a running `yarn dev` or
+// not-yet-recycled pods converges within the TTL instead. The TTL still removes
+// essentially all of the traffic: a hot column is probed twelve times an hour rather
+// than tens of thousands. Set OM_QUERY_COLUMN_EXISTS_CACHE_MS=0 to disable and probe
+// per request again; OM_QUERY_COLUMN_EXISTS_CACHE_MAX_ENTRIES tunes the bound.
+const COLUMN_EXISTS_CACHE_DEFAULT_TTL_MS = 300_000
+const COLUMN_EXISTS_CACHE_DEFAULT_MAX_ENTRIES = 10_000
+const columnExistsCache = new Map<string, { value: boolean; expiresAt: number }>()
+
+function resolveColumnExistsCacheTtlMs(): number {
+  return parseNumberWithDefault(process.env.OM_QUERY_COLUMN_EXISTS_CACHE_MS, COLUMN_EXISTS_CACHE_DEFAULT_TTL_MS, { integer: true, min: 0 })
+}
+
+function resolveColumnExistsCacheMaxEntries(): number {
+  return parseNumberWithDefault(process.env.OM_QUERY_COLUMN_EXISTS_CACHE_MAX_ENTRIES, COLUMN_EXISTS_CACHE_DEFAULT_MAX_ENTRIES, { integer: true, min: 1 })
+}
+
+function storeColumnExists(key: string, value: boolean, ttlMs: number): void {
+  const maxEntries = resolveColumnExistsCacheMaxEntries()
+  if (columnExistsCache.size >= maxEntries) {
+    const now = Date.now()
+    for (const [entryKey, entry] of columnExistsCache) {
+      if (entry.expiresAt <= now) columnExistsCache.delete(entryKey)
+    }
+    if (columnExistsCache.size >= maxEntries) columnExistsCache.clear()
+  }
+  columnExistsCache.set(key, { value, expiresAt: Date.now() + ttlMs })
+}
+
+/** Test-only: the module-scoped memo would otherwise leak state across specs. */
+export function clearColumnExistsCache(): void {
+  columnExistsCache.clear()
+}
+
+/** Test-only: entry count of the column-existence memo, for the cap regression test. */
+export function columnExistsCacheSize(): number {
+  return columnExistsCache.size
+}
+
 type ResolvedCustomFieldSource = {
   entityId: EntityId
   alias: string
@@ -271,7 +324,6 @@ function computeCustomFieldScore(cfg: Record<string, unknown>, kind: string, ent
  * {@link HybridQueryEngine} when the query index is unavailable or incomplete.
  */
 export class BasicQueryEngine implements QueryEngine {
-  private columnCache = new Map<string, boolean>()
   private searchAliasSeq = 0
   private searchAvailabilityInstance: SearchTokenAvailability | null = null
 
@@ -661,7 +713,8 @@ export class BasicQueryEngine implements QueryEngine {
     // and cf filters are expressed as correlated EXISTS semi-joins, so nothing can
     // multiply base rows and a LIMIT above the query is an enforceable bound.
     // Re-running the WHERE/JOIN logic per projection is cheap: every `columnExists`
-    // check is memoized on `this.columnCache`, so later passes hit no extra DB calls.
+    // check is memoized on the module-scoped `columnExistsCache`, so later passes
+    // hit no extra DB calls.
     const buildQuery = async (projection: 'full' | 'sortKeys' | 'count'): Promise<BuiltQuery> => {
       const isSortKeysProjection = projection === 'sortKeys'
       const isCountProjection = projection === 'count'
@@ -1545,11 +1598,9 @@ export class BasicQueryEngine implements QueryEngine {
 
   private async columnExists(table: string, column: string): Promise<boolean> {
     const key = `${table}.${column}`
-    if (this.columnCache.has(key)) {
-      const cached = this.columnCache.get(key)
-      if (cached === true) return true
-      this.columnCache.delete(key)
-    }
+    const ttlMs = resolveColumnExistsCacheTtlMs()
+    const cached = columnExistsCache.get(key)
+    if (cached && cached.expiresAt > Date.now()) return cached.value
     const db = this.getDb()
     const exists = await db
       .selectFrom('information_schema.columns' as any)
@@ -1559,8 +1610,7 @@ export class BasicQueryEngine implements QueryEngine {
       .limit(1)
       .executeTakeFirst()
     const present = !!exists
-    if (present) this.columnCache.set(key, true)
-    else this.columnCache.delete(key)
+    if (ttlMs > 0) storeColumnExists(key, present, ttlMs)
     return present
   }