@open-mercato/shared 0.6.5-develop.5337.1.534b781eac → 0.6.5

package/src/lib/crud/__tests__/custom-fields.test.ts

@@ -243,6 +243,97 @@ describe('loadCustomFieldValues (encryption)', () => {
     })
     expect(values['rec-1'].cf_priority).toBe(42)
   })
+
+  it('decrypts rows concurrently rather than sequentially (regression: issue #2229)', async () => {
+    const deks: Record<string, string> = {
+      'tenant-1': Buffer.alloc(32, 1).toString('base64'),
+      'tenant-2': Buffer.alloc(32, 2).toString('base64'),
+      'tenant-3': Buffer.alloc(32, 3).toString('base64'),
+    }
+    const rows = [
+      { recordId: 'rec-1', tenantId: 'tenant-1', plaintext: 'note-1' },
+      { recordId: 'rec-2', tenantId: 'tenant-2', plaintext: 'note-2' },
+      { recordId: 'rec-3', tenantId: 'tenant-3', plaintext: 'note-3' },
+    ].map((row) => ({
+      ...row,
+      valueText: encryptWithAesGcm(row.plaintext, deks[row.tenantId]).value,
+    }))
+    const em = {
+      find: jest.fn().mockImplementation((_, where) => {
+        if ((where as any).recordId) {
+          return Promise.resolve(
+            rows.map((row) => ({
+              recordId: row.recordId,
+              fieldKey: 'note',
+              organizationId: null,
+              tenantId: row.tenantId,
+              valueText: row.valueText,
+              valueMultiline: null,
+              valueInt: null,
+              valueFloat: null,
+              valueBool: null,
+              deletedAt: null,
+            })),
+          )
+        }
+        return Promise.resolve([
+          { key: 'note', entityId: 'demo:entity', organizationId: null, tenantId: null, kind: 'text', configJson: { encrypted: true }, isActive: true },
+        ])
+      }),
+    }
+    let inFlight = 0
+    let maxInFlight = 0
+    const mockService = {
+      isEnabled: () => true,
+      getDek: jest.fn(async (tenantId: string) => {
+        inFlight += 1
+        maxInFlight = Math.max(maxInFlight, inFlight)
+        await new Promise((resolve) => setTimeout(resolve, 5))
+        inFlight -= 1
+        return { key: deks[tenantId] }
+      }),
+    }
+    const values = await loadCustomFieldValues({
+      em: em as any,
+      entityId: 'demo:entity',
+      recordIds: ['rec-1', 'rec-2', 'rec-3'],
+      tenantIdByRecord: { 'rec-1': 'tenant-1', 'rec-2': 'tenant-2', 'rec-3': 'tenant-3' },
+      encryptionService: mockService as any,
+    })
+    expect(values['rec-1'].cf_note).toBe('note-1')
+    expect(values['rec-2'].cf_note).toBe('note-2')
+    expect(values['rec-3'].cf_note).toBe('note-3')
+    // Sequential await-in-loop would cap concurrency at 1; batching lifts it.
+    expect(maxInFlight).toBeGreaterThan(1)
+  })
+
+  it('preserves multi-value grouping order for encrypted fields (regression: issue #2229)', async () => {
+    const dek = Buffer.alloc(32, 2).toString('base64')
+    const first = encryptWithAesGcm('alpha', dek).value
+    const second = encryptWithAesGcm('beta', dek).value
+    const em = {
+      find: jest.fn().mockImplementation((_, where) => {
+        if ((where as any).recordId) {
+          return Promise.resolve([
+            { recordId: 'rec-1', fieldKey: 'tags', organizationId: null, tenantId: 'tenant-1', valueText: first, valueMultiline: null, valueInt: null, valueFloat: null, valueBool: null, deletedAt: null },
+            { recordId: 'rec-1', fieldKey: 'tags', organizationId: null, tenantId: 'tenant-1', valueText: second, valueMultiline: null, valueInt: null, valueFloat: null, valueBool: null, deletedAt: null },
+          ])
+        }
+        return Promise.resolve([
+          { key: 'tags', entityId: 'demo:entity', organizationId: null, tenantId: 'tenant-1', kind: 'text', configJson: { encrypted: true, multi: true }, isActive: true },
+        ])
+      }),
+    }
+    const mockService = { isEnabled: () => true, getDek: async () => ({ key: dek }) }
+    const values = await loadCustomFieldValues({
+      em: em as any,
+      entityId: 'demo:entity',
+      recordIds: ['rec-1'],
+      tenantIdByRecord: { 'rec-1': 'tenant-1' },
+      encryptionService: mockService as any,
+    })
+    expect(values['rec-1'].cf_tags).toEqual(['alpha', 'beta'])
+  })
 })
 
 describe('decorateRecordWithCustomFields', () => {

package/src/lib/crud/custom-fields.ts

@@ -632,7 +632,7 @@ export async function loadCustomFieldValues(opts: {
   type Bucket = { orgId: string | null; tenantId: string | null; values: unknown[]; def?: CustomFieldDef | null; encrypted?: boolean }
   const buckets = new Map<string, Bucket>()
 
-  for (const row of cfRows) {
+  const rowInfos = cfRows.map((row) => {
     const recordId = String(row.recordId)
     const key = String(row.fieldKey)
     const bucketKey = `${recordId}::${key}`
@@ -643,26 +643,39 @@ export async function loadCustomFieldValues(opts: {
     const def = pickDefinition(key, resolvedOrgId, resolvedTenantId)
     const encrypted = Boolean(def?.configJson && (def as any).configJson?.encrypted)
     const value = valueFromRow(row)
-    const decrypted = encrypted
-      ? await decryptCustomFieldValue(
-          value,
-          resolvedTenantId ?? tenantId ?? null,
-          getEncryptionService(),
-          encryptionCache,
-          { kind: def?.kind ?? null },
-        )
-      : value
-    const existing = buckets.get(bucketKey)
+    return { bucketKey, resolvedOrgId, resolvedTenantId, tenantId, def, encrypted, value }
+  })
+
+  // Decrypt every encrypted value concurrently so a list of N rows × M encrypted
+  // fields costs the slowest single decryption rather than the sum (issue #2229).
+  // The shared encryptionCache keeps DEK lookups deduped per tenant.
+  const decryptedValues = await Promise.all(
+    rowInfos.map((info) =>
+      info.encrypted
+        ? decryptCustomFieldValue(
+            info.value,
+            info.resolvedTenantId ?? info.tenantId ?? null,
+            getEncryptionService(),
+            encryptionCache,
+            { kind: info.def?.kind ?? null },
+          )
+        : info.value,
+    ),
+  )
+
+  rowInfos.forEach((info, index) => {
+    const decrypted = decryptedValues[index]
+    const existing = buckets.get(info.bucketKey)
     if (existing) {
-      if (existing.orgId == null && resolvedOrgId) existing.orgId = resolvedOrgId
-      if (existing.tenantId == null && resolvedTenantId) existing.tenantId = resolvedTenantId
-      if (existing.def == null && def) existing.def = def
-      existing.encrypted = existing.encrypted || encrypted
+      if (existing.orgId == null && info.resolvedOrgId) existing.orgId = info.resolvedOrgId
+      if (existing.tenantId == null && info.resolvedTenantId) existing.tenantId = info.resolvedTenantId
+      if (existing.def == null && info.def) existing.def = info.def
+      existing.encrypted = existing.encrypted || info.encrypted
       existing.values.push(decrypted)
     } else {
-      buckets.set(bucketKey, { orgId: resolvedOrgId, tenantId: resolvedTenantId, values: [decrypted], def: def ?? null, encrypted })
+      buckets.set(info.bucketKey, { orgId: info.resolvedOrgId, tenantId: info.resolvedTenantId, values: [decrypted], def: info.def ?? null, encrypted: info.encrypted })
     }
-  }
+  })
 
   const result: Record<string, Record<string, unknown>> = {}
   for (const [compoundKey, bucket] of buckets.entries()) {

package/src/lib/crud/factory.ts

@@ -944,7 +944,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
 
   // OSS opt-in optimistic locking — auto-register a generic reader for every
   // CRUD entity using the factory's own ORM config (Step 13.3 of the spec at
-  // .ai/specs/2026-05-25-oss-optimistic-locking.md). Hand-wired readers
+  // .ai/specs/implemented/2026-05-25-oss-optimistic-locking.md). Hand-wired readers
   // registered earlier via module DI (customers/sales) always win because we
   // use the `IfAbsent` variant. Skipped silently when the route has no
   // resolvable resourceKind or no ORM entity class (e.g. virtual routes).

package/src/lib/crud/optimistic-lock-command.ts

@@ -24,7 +24,7 @@
  * header keep working. Respects the same `OM_OPTIMISTIC_LOCK` env contract
  * (default ON; `off` disables; allow-list scopes by `resourceKind`).
  *
- * Spec: .ai/specs/2026-05-25-oss-optimistic-locking.md (§ command-level checks)
+ * Spec: .ai/specs/implemented/2026-05-25-oss-optimistic-locking.md (§ command-level checks)
  *       .ai/specs/2026-05-28-optimistic-locking-coverage-completion.md (Phase 4)
  */
 import { CrudHttpError } from './errors'

package/src/lib/crud/optimistic-lock-headers.ts

@@ -8,7 +8,7 @@
  * many HTTP intermediaries (nginx, some fetch implementations) strip
  * underscored header names — see RFC 7230 §3.2.6.
  *
- * Spec: .ai/specs/2026-05-25-oss-optimistic-locking.md §3.2
+ * Spec: .ai/specs/implemented/2026-05-25-oss-optimistic-locking.md §3.2
  */
 export const OPTIMISTIC_LOCK_MODULE_ID = 'optimistic_lock'
 

package/src/lib/crud/optimistic-lock-store.ts

@@ -12,7 +12,7 @@
  *
  * Mirrors the `mutation-guard-store.ts` HMR-safe globalThis pattern.
  *
- * Spec: .ai/specs/2026-05-25-oss-optimistic-locking.md
+ * Spec: .ai/specs/implemented/2026-05-25-oss-optimistic-locking.md
  */
 import type { OptimisticLockCurrentReader } from './optimistic-lock'
 

package/src/lib/crud/optimistic-lock.ts

@@ -28,7 +28,7 @@
  * container / em access. Stateful checks that need to read current DB state
  * MUST go through the DI service path (this file).
  *
- * Spec: .ai/specs/2026-05-25-oss-optimistic-locking.md
+ * Spec: .ai/specs/implemented/2026-05-25-oss-optimistic-locking.md
  */
 import type { EntityManager } from '@mikro-orm/postgresql'
 import type {

package/src/lib/data/__tests__/engine.custom-entity-storage-guard.test.ts

@@ -0,0 +1,78 @@
+import { DefaultDataEngine, assertCustomEntityStorageEntityId } from '../engine'
+import { isCrudHttpError } from '../../crud/errors'
+import { registerEntityIds } from '../../encryption/entityIds'
+
+function buildEm(classTables: Record<string, string>): any {
+  return {
+    getKysely: () => {
+      throw new Error('[internal] storage must not be touched for rejected entity ids')
+    },
+    getMetadata: () => ({
+      find: (className: string) => (classTables[className] ? { tableName: classTables[className] } : undefined),
+      getAll: () => Object.values(classTables).map((tableName) => ({ tableName })),
+    }),
+  }
+}
+
+function expectSystemEntityRejection(err: unknown) {
+  expect(isCrudHttpError(err)).toBe(true)
+  const httpError = err as { status: number; body: { code?: string } }
+  expect(httpError.status).toBe(400)
+  expect(httpError.body.code).toBe('system_entity_records_blocked')
+}
+
+describe('custom-entity storage guard (#2939 hardening)', () => {
+  beforeEach(() => {
+    registerEntityIds({
+      customers: { customer_deal: 'customers:customer_deal' },
+      example: { todo: 'example:todo', calendar_entity: 'example:calendar_entity' },
+    })
+  })
+
+  afterEach(() => {
+    registerEntityIds({})
+  })
+
+  test('assertCustomEntityStorageEntityId rejects module-declared ids backed by a registered ORM table', () => {
+    const em = buildEm({ CustomerDeal: 'customer_deals' })
+    try {
+      assertCustomEntityStorageEntityId(em, 'customers:customer_deal')
+      throw new Error('[internal] expected the guard to throw')
+    } catch (err) {
+      expectSystemEntityRejection(err)
+    }
+  })
+
+  test('assertCustomEntityStorageEntityId allows module-declared ids without a registered ORM table', () => {
+    const em = buildEm({})
+    expect(() => assertCustomEntityStorageEntityId(em, 'example:calendar_entity')).not.toThrow()
+  })
+
+  test('a runtime entity whose name collides with an ORM class name is NOT classified as system', () => {
+    const em = buildEm({ Todo: 'todos' })
+    expect(() => assertCustomEntityStorageEntityId(em, 'user:todo')).not.toThrow()
+  })
+
+  test('falls back to the ORM-table check when the entity-id registry is not populated', () => {
+    registerEntityIds({})
+    const em = buildEm({ CustomerDeal: 'customer_deals' })
+    try {
+      assertCustomEntityStorageEntityId(em, 'customers:customer_deal')
+      throw new Error('[internal] expected the guard to throw')
+    } catch (err) {
+      expectSystemEntityRejection(err)
+    }
+  })
+
+  test.each([
+    ['createCustomEntityRecord', (engine: DefaultDataEngine) => engine.createCustomEntityRecord({ entityId: 'customers:customer_deal', values: {} })],
+    ['updateCustomEntityRecord', (engine: DefaultDataEngine) => engine.updateCustomEntityRecord({ entityId: 'customers:customer_deal', recordId: '11111111-1111-4111-8111-111111111111', values: {} })],
+    ['deleteCustomEntityRecord', (engine: DefaultDataEngine) => engine.deleteCustomEntityRecord({ entityId: 'customers:customer_deal', recordId: '11111111-1111-4111-8111-111111111111' })],
+  ])('%s rejects a table-backed system entity id before touching storage', async (_name, run) => {
+    const engine = new DefaultDataEngine(buildEm({ CustomerDeal: 'customer_deals' }) as any, {} as any)
+    await expect(run(engine)).rejects.toMatchObject({
+      status: 400,
+      body: { code: 'system_entity_records_blocked' },
+    })
+  })
+})

package/src/lib/data/engine.ts

@@ -13,6 +13,8 @@ import type {
   CrudEntityIdentifiers,
 } from '../crud/types'
 import { CrudHttpError } from '../crud/errors'
+import { resolveRegisteredEntityTableName } from '../query/engine'
+import { getEntityIds } from '../encryption/entityIds'
 import { normalizeCustomFieldValues } from '../custom-fields/normalize'
 import { parseBooleanToken } from '../boolean'
 import { isEventDeclared } from '../../modules/events'
@@ -136,6 +138,41 @@ export interface DataEngine {
   flushOrmEntityChanges(): Promise<void>
 }
 
+export const SYSTEM_ENTITY_RECORDS_BLOCKED_CODE = 'system_entity_records_blocked'
+
+/**
+ * A system entity for doc-storage purposes is an id that modules declare in the
+ * generated entity-id registry AND that resolves to a registered ORM table. Both
+ * conditions matter: `resolveRegisteredEntityTableName` matches class-name candidates
+ * from the entity segment alone, so a runtime-registered custom entity whose name
+ * happens to collide with some ORM class (e.g. `user:todo` vs the example module's
+ * `Todo`) must never be classified as system. When the registry is not populated
+ * (exotic bootstraps, unit harnesses) the check conservatively falls back to the
+ * ORM-table match alone so the #2939 protection never switches off.
+ */
+export function isOrmBackedSystemEntityId(em: EntityManager, entityId: string): boolean {
+  const registry = getEntityIds(false)
+  const moduleIds = Object.values(registry).flatMap((moduleEntities) => Object.values(moduleEntities ?? {}))
+  if (moduleIds.length > 0 && !moduleIds.includes(entityId)) return false
+  return resolveRegisteredEntityTableName(em, entityId) !== null
+}
+
+/**
+ * Doc storage (`custom_entities_storage`) is for custom entities only. A system
+ * entity's records live in its own module tables/APIs — writing doc rows for it
+ * poisons read-path classification (#2939) and must be rejected at the deepest
+ * seam so no caller (API, AI tool, workflow) can do it.
+ */
+export function assertCustomEntityStorageEntityId(em: EntityManager, entityId: string): void {
+  if (isOrmBackedSystemEntityId(em, entityId)) {
+    throw new CrudHttpError(400, {
+      error: 'Records are available for custom entities only',
+      code: SYSTEM_ENTITY_RECORDS_BLOCKED_CODE,
+      entityId,
+    })
+  }
+}
+
 export class DefaultDataEngine implements DataEngine {
   private pendingSideEffects = new Map<string, QueuedCrudSideEffect>()
   constructor(private em: EntityManager, private container: AwilixContainer) {}
@@ -254,6 +291,7 @@ export class DefaultDataEngine implements DataEngine {
   }
 
   async createCustomEntityRecord(opts: Parameters<DataEngine['createCustomEntityRecord']>[0]): Promise<{ id: string }> {
+    assertCustomEntityStorageEntityId(this.em, opts.entityId)
     const db = this.getKysely()
     await this.ensureStorageTableExists()
     const sanitizedValues = await sanitizeCustomFieldHtmlRichTextValuesServer(this.em, {
@@ -345,6 +383,7 @@ export class DefaultDataEngine implements DataEngine {
   }
 
   async updateCustomEntityRecord(opts: Parameters<DataEngine['updateCustomEntityRecord']>[0]): Promise<void> {
+    assertCustomEntityStorageEntityId(this.em, opts.entityId)
     const db = this.getKysely()
     const sanitizedValues = await sanitizeCustomFieldHtmlRichTextValuesServer(this.em, {
       entityId: opts.entityId,
@@ -410,6 +449,7 @@ export class DefaultDataEngine implements DataEngine {
   }
 
   async deleteCustomEntityRecord(opts: Parameters<DataEngine['deleteCustomEntityRecord']>[0]): Promise<void> {
+    assertCustomEntityStorageEntityId(this.em, opts.entityId)
     const db = this.getKysely()
     const id = String(opts.recordId)
     const orgId = opts.organizationId ?? null

package/src/lib/db/__tests__/buildIlikeTerm.test.ts

@@ -0,0 +1,40 @@
+import { buildIlikeTerm } from '../buildIlikeTerm'
+import { escapeLikePattern } from '../escapeLikePattern'
+
+describe('buildIlikeTerm', () => {
+  it('wraps the escaped term in leading and trailing wildcards by default', () => {
+    expect(buildIlikeTerm('acme')).toBe('%acme%')
+  })
+
+  it('matches the legacy inline contains pattern exactly', () => {
+    const term = 'Acme Corp'
+    expect(buildIlikeTerm(term)).toBe(`%${escapeLikePattern(term)}%`)
+    expect(buildIlikeTerm(term, 'contains')).toBe(`%${escapeLikePattern(term)}%`)
+  })
+
+  it('builds a startsWith pattern with only a trailing wildcard', () => {
+    const term = 'user@example.com'
+    expect(buildIlikeTerm(term, 'startsWith')).toBe(`${escapeLikePattern(term)}%`)
+  })
+
+  it('builds an endsWith pattern with only a leading wildcard', () => {
+    const term = 'example.com'
+    expect(buildIlikeTerm(term, 'endsWith')).toBe(`%${escapeLikePattern(term)}`)
+  })
+
+  it('escapes LIKE metacharacters so they match literally', () => {
+    expect(buildIlikeTerm('50%_off')).toBe('%50\\%\\_off%')
+    expect(buildIlikeTerm('back\\slash')).toBe('%back\\\\slash%')
+  })
+
+  it('keeps user wildcards literal across every mode', () => {
+    expect(buildIlikeTerm('a%b', 'startsWith')).toBe('a\\%b%')
+    expect(buildIlikeTerm('a_b', 'endsWith')).toBe('%a\\_b')
+  })
+
+  it('handles an empty term as a wildcard-only pattern', () => {
+    expect(buildIlikeTerm('')).toBe('%%')
+    expect(buildIlikeTerm('', 'startsWith')).toBe('%')
+    expect(buildIlikeTerm('', 'endsWith')).toBe('%')
+  })
+})

package/src/lib/db/__tests__/escapeLikePattern.test.ts

@@ -0,0 +1,123 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { dirname, join, relative, sep } from 'node:path'
+import { escapeLikePattern } from '../escapeLikePattern'
+
+describe('escapeLikePattern', () => {
+  it('escapes LIKE wildcards and the escape character', () => {
+    expect(escapeLikePattern('%')).toBe('\\%')
+    expect(escapeLikePattern('_')).toBe('\\_')
+    expect(escapeLikePattern('\\')).toBe('\\\\')
+    expect(escapeLikePattern('a%b_c')).toBe('a\\%b\\_c')
+  })
+
+  it('escapes the backslash before the wildcards so the escape itself is literal', () => {
+    expect(escapeLikePattern('100%\\_')).toBe('100\\%\\\\\\_')
+  })
+
+  it('leaves ordinary input untouched', () => {
+    expect(escapeLikePattern('hello world')).toBe('hello world')
+    expect(escapeLikePattern('')).toBe('')
+  })
+})
+
+/**
+ * Regression guard for #2932 (and the earlier #2734 fix).
+ *
+ * Every user-supplied value interpolated into a MikroORM `$ilike` pattern under
+ * any module's `api/**` tree MUST flow through `escapeLikePattern`, otherwise a
+ * caller can inject LIKE metacharacters (`%`, `_`, `\`) to broaden predicates or
+ * force pathological full scans. This scans the whole monorepo so a NEW unescaped
+ * `$ilike` interpolation in any package or app fails the build.
+ */
+function findRepoRoot(start: string): string {
+  let current = start
+  for (let depth = 0; depth < 12; depth += 1) {
+    if (existsSync(join(current, 'packages')) && existsSync(join(current, 'apps'))) {
+      return current
+    }
+    const parent = dirname(current)
+    if (parent === current) break
+    current = parent
+  }
+  throw new Error('[internal] could not locate monorepo root for $ilike guard')
+}
+
+const SKIP_DIRS = new Set(['node_modules', '__tests__', 'generated', 'dist', '.next', '.mercato'])
+
+function collectApiSourceFiles(dir: string, acc: string[]): void {
+  let entries: string[]
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return
+  }
+  for (const name of entries) {
+    const full = join(dir, name)
+    let stat
+    try {
+      stat = statSync(full)
+    } catch {
+      continue
+    }
+    if (stat.isDirectory()) {
+      if (SKIP_DIRS.has(name)) continue
+      collectApiSourceFiles(full, acc)
+    } else if (
+      (name.endsWith('.ts') || name.endsWith('.tsx')) &&
+      !name.endsWith('.test.ts') &&
+      !name.endsWith('.test.tsx') &&
+      full.split(sep).includes('api')
+    ) {
+      acc.push(full)
+    }
+  }
+}
+
+const BARE_IDENTIFIER = /^[A-Za-z_$][\w$]*$/
+
+function isPreEscapedVariable(expr: string, source: string): boolean {
+  if (!BARE_IDENTIFIER.test(expr)) return false
+  const assignedFromEscape = new RegExp(`\\b${expr}\\s*=\\s*escapeLikePattern\\(`)
+  return assignedFromEscape.test(source)
+}
+
+function findUnescapedIlikeInterpolations(source: string): string[] {
+  const ilikeTemplate = /\$ilike:\s*`([^`]*)`/g
+  const interpolation = /\$\{([^}]*)\}/g
+  const offenders: string[] = []
+  let templateMatch: RegExpExecArray | null
+  while ((templateMatch = ilikeTemplate.exec(source)) !== null) {
+    const literal = templateMatch[1]
+    let exprMatch: RegExpExecArray | null
+    while ((exprMatch = interpolation.exec(literal)) !== null) {
+      const expr = exprMatch[1].trim()
+      if (expr.startsWith('escapeLikePattern(')) continue
+      if (isPreEscapedVariable(expr, source)) continue
+      offenders.push(`\`${templateMatch[1]}\``)
+    }
+  }
+  return offenders
+}
+
+describe('$ilike user input must be escaped under api/** (#2932)', () => {
+  const repoRoot = findRepoRoot(__dirname)
+  const roots = [join(repoRoot, 'packages'), join(repoRoot, 'apps')]
+  const files: string[] = []
+  for (const root of roots) collectApiSourceFiles(root, files)
+
+  it('discovered api source files to scan', () => {
+    expect(files.length).toBeGreaterThan(20)
+  })
+
+  it('every $ilike pattern interpolating a variable uses escapeLikePattern', () => {
+    const violations: string[] = []
+    for (const full of files) {
+      const source = readFileSync(full, 'utf8')
+      const offenders = findUnescapedIlikeInterpolations(source)
+      if (offenders.length === 0) continue
+      const rel = relative(repoRoot, full).split(sep).join('/')
+      for (const offender of offenders) violations.push(`${rel}: ${offender}`)
+    }
+    expect(violations).toEqual([])
+  })
+})

package/src/lib/db/__tests__/mikro.test.ts

@@ -23,3 +23,85 @@ describe('ORM entity registry', () => {
     expect(secondLoad.getOrmEntities()).toBe(entities)
   })
 })
+
+describe('resolvePoolConfig', () => {
+  const baseEnv = (extra: Record<string, string | undefined> = {}): NodeJS.ProcessEnv =>
+    ({ ...extra }) as NodeJS.ProcessEnv
+
+  it('applies pool size defaults when env is empty', async () => {
+    const { resolvePoolConfig } = await import('../mikro')
+    const config = resolvePoolConfig(baseEnv())
+    expect(config.poolMin).toBe(2)
+    expect(config.poolMax).toBe(20)
+    expect(config.poolIdleTimeout).toBe(3000)
+    expect(config.poolAcquireTimeout).toBe(6000)
+  })
+
+  it('reads pool sizes from env overrides', async () => {
+    const { resolvePoolConfig } = await import('../mikro')
+    const config = resolvePoolConfig(
+      baseEnv({ DB_POOL_MIN: '5', DB_POOL_MAX: '50', DB_POOL_ACQUIRE_TIMEOUT: '12000' }),
+    )
+    expect(config.poolMin).toBe(5)
+    expect(config.poolMax).toBe(50)
+    expect(config.poolAcquireTimeout).toBe(12000)
+  })
+
+  it('defaults idle_in_transaction to a finite 120s in production', async () => {
+    const { resolvePoolConfig } = await import('../mikro')
+    const config = resolvePoolConfig(baseEnv({ NODE_ENV: 'production' }))
+    expect(config.idleInTransactionTimeoutMs).toBe(120_000)
+  })
+
+  it('defaults idle_in_transaction to a finite 120s in development', async () => {
+    const { resolvePoolConfig } = await import('../mikro')
+    const config = resolvePoolConfig(baseEnv({ NODE_ENV: 'development' }))
+    expect(config.idleInTransactionTimeoutMs).toBe(120_000)
+  })
+
+  it('lets idle_in_transaction be overridden, including 0 to disable', async () => {
+    const { resolvePoolConfig } = await import('../mikro')
+    expect(
+      resolvePoolConfig(baseEnv({ DB_IDLE_IN_TRANSACTION_TIMEOUT_MS: '30000' }))
+        .idleInTransactionTimeoutMs,
+    ).toBe(30000)
+    expect(
+      resolvePoolConfig(
+        baseEnv({ NODE_ENV: 'production', DB_IDLE_IN_TRANSACTION_TIMEOUT_MS: '0' }),
+      ).idleInTransactionTimeoutMs,
+    ).toBe(0)
+  })
+
+  it('keeps idle_session production-undefined / dev-600s default', async () => {
+    const { resolvePoolConfig } = await import('../mikro')
+    expect(resolvePoolConfig(baseEnv({ NODE_ENV: 'production' })).idleSessionTimeoutMs).toBeUndefined()
+    expect(resolvePoolConfig(baseEnv({ NODE_ENV: 'development' })).idleSessionTimeoutMs).toBe(600_000)
+  })
+
+  it('leaves statement/lock timeouts unset by default (no timeout)', async () => {
+    const { resolvePoolConfig } = await import('../mikro')
+    const config = resolvePoolConfig(baseEnv({ NODE_ENV: 'production' }))
+    expect(config.statementTimeoutMs).toBeUndefined()
+    expect(config.lockTimeoutMs).toBeUndefined()
+  })
+
+  it('passes through positive statement/lock timeouts when set', async () => {
+    const { resolvePoolConfig } = await import('../mikro')
+    const config = resolvePoolConfig(
+      baseEnv({ DB_STATEMENT_TIMEOUT_MS: '30000', DB_LOCK_TIMEOUT_MS: '5000' }),
+    )
+    expect(config.statementTimeoutMs).toBe(30000)
+    expect(config.lockTimeoutMs).toBe(5000)
+  })
+
+  it('ignores non-positive or non-numeric statement/lock timeouts', async () => {
+    const { resolvePoolConfig } = await import('../mikro')
+    for (const value of ['0', '-1', 'abc', '']) {
+      const config = resolvePoolConfig(
+        baseEnv({ DB_STATEMENT_TIMEOUT_MS: value, DB_LOCK_TIMEOUT_MS: value }),
+      )
+      expect(config.statementTimeoutMs).toBeUndefined()
+      expect(config.lockTimeoutMs).toBeUndefined()
+    }
+  })
+})

package/src/lib/db/buildIlikeTerm.ts

@@ -0,0 +1,16 @@
+import { escapeLikePattern } from './escapeLikePattern'
+
+export type IlikeMatchMode = 'contains' | 'startsWith' | 'endsWith'
+
+export const buildIlikeTerm = (value: string, mode: IlikeMatchMode = 'contains'): string => {
+  const escaped = escapeLikePattern(value)
+  switch (mode) {
+    case 'startsWith':
+      return `${escaped}%`
+    case 'endsWith':
+      return `%${escaped}`
+    case 'contains':
+    default:
+      return `%${escaped}%`
+  }
+}