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

package/src/lib/db/mikro.ts

@@ -35,6 +35,47 @@ export function getOrmEntities(): any[] {
   return entities
 }
 
+export type ResolvedPoolConfig = {
+  poolMin: number
+  poolMax: number
+  poolIdleTimeout: number
+  poolAcquireTimeout: number
+  idleSessionTimeoutMs: number | undefined
+  idleInTransactionTimeoutMs: number | undefined
+  statementTimeoutMs: number | undefined
+  lockTimeoutMs: number | undefined
+}
+
+// Parse an optional positive-millisecond env var. Returns undefined when unset,
+// non-numeric, or non-positive so callers treat "no value" as "no timeout".
+function parsePositiveIntEnv(raw: string | undefined): number | undefined {
+  const parsed = parseInt(raw || '')
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined
+}
+
+export function resolvePoolConfig(env: NodeJS.ProcessEnv = process.env): ResolvedPoolConfig {
+  const idleSessionTimeoutEnv = parseInt(env.DB_IDLE_SESSION_TIMEOUT_MS || '')
+  const idleInTxTimeoutEnv = parseInt(env.DB_IDLE_IN_TRANSACTION_TIMEOUT_MS || '')
+  return {
+    poolMin: parseInt(env.DB_POOL_MIN || '2'),
+    poolMax: parseInt(env.DB_POOL_MAX || '20'),
+    poolIdleTimeout: parseInt(env.DB_POOL_IDLE_TIMEOUT || '3000'),
+    poolAcquireTimeout: parseInt(env.DB_POOL_ACQUIRE_TIMEOUT || '6000'),
+    idleSessionTimeoutMs: Number.isFinite(idleSessionTimeoutEnv)
+      ? idleSessionTimeoutEnv
+      : env.NODE_ENV === 'production'
+        ? undefined
+        : 600_000,
+    // Finite default in every environment (including production) so a leaked or idle
+    // open transaction cannot pin a pool connection indefinitely and exhaust the pool.
+    // Mirrors the long-standing dev value; override (incl. 0 to disable) via env.
+    idleInTransactionTimeoutMs: Number.isFinite(idleInTxTimeoutEnv) ? idleInTxTimeoutEnv : 120_000,
+    // Opt-in guards against runaway statements and lock waits. No timeout when unset.
+    statementTimeoutMs: parsePositiveIntEnv(env.DB_STATEMENT_TIMEOUT_MS),
+    lockTimeoutMs: parsePositiveIntEnv(env.DB_LOCK_TIMEOUT_MS),
+  }
+}
+
 export async function getOrm() {
   if (ormInstance) {
     return ormInstance
@@ -47,22 +88,16 @@ export async function getOrm() {
   }
 
   // Parse connection pool settings from environment
-  const poolMin = parseInt(process.env.DB_POOL_MIN || '2')
-  const poolMax = parseInt(process.env.DB_POOL_MAX || '20')
-  const poolIdleTimeout = parseInt(process.env.DB_POOL_IDLE_TIMEOUT || '3000')
-  const poolAcquireTimeout = parseInt(process.env.DB_POOL_ACQUIRE_TIMEOUT || '6000')
-  const idleSessionTimeoutEnv = parseInt(process.env.DB_IDLE_SESSION_TIMEOUT_MS || '')
-  const idleInTxTimeoutEnv = parseInt(process.env.DB_IDLE_IN_TRANSACTION_TIMEOUT_MS || '')
-  const idleSessionTimeoutMs = Number.isFinite(idleSessionTimeoutEnv)
-    ? idleSessionTimeoutEnv
-    : process.env.NODE_ENV === 'production'
-      ? undefined
-      : 600_000
-  const idleInTransactionTimeoutMs = Number.isFinite(idleInTxTimeoutEnv)
-    ? idleInTxTimeoutEnv
-    : process.env.NODE_ENV === 'production'
-      ? undefined
-      : 120_000
+  const {
+    poolMin,
+    poolMax,
+    poolIdleTimeout,
+    poolAcquireTimeout,
+    idleSessionTimeoutMs,
+    idleInTransactionTimeoutMs,
+    statementTimeoutMs,
+    lockTimeoutMs,
+  } = resolvePoolConfig()
   const connectionOptions =
     idleSessionTimeoutMs && idleSessionTimeoutMs > 0
       ? `-c idle_session_timeout=${idleSessionTimeoutMs}`
@@ -78,6 +113,8 @@ export async function getOrm() {
       poolAcquireTimeout,
       idleSessionTimeoutMs,
       idleInTransactionTimeoutMs,
+      statementTimeoutMs,
+      lockTimeoutMs,
       nodeEnv: process.env.NODE_ENV,
     })
   }
@@ -107,6 +144,8 @@ export async function getOrm() {
     driverOptions: {
       connectionTimeoutMillis: poolAcquireTimeout,
       idle_in_transaction_session_timeout: idleInTransactionTimeoutMs,
+      statement_timeout: statementTimeoutMs,
+      lock_timeout: lockTimeoutMs,
       options: connectionOptions,
       ssl: sslConfig,
       onPoolCreated: (pool: any) => {

package/src/lib/di/container.ts

@@ -164,7 +164,7 @@ export async function createRequestContainer(): Promise<AppContainer> {
     // sent) it short-circuits at validateMutation. Module-level di.ts
     // registrations override this default via Awilix replace semantics —
     // see the enterprise `record_locks` module for the canonical override.
-    // Spec: .ai/specs/2026-05-25-oss-optimistic-locking.md
+    // Spec: .ai/specs/implemented/2026-05-25-oss-optimistic-locking.md
     crudMutationGuardService: asFunction(({ em: scopedEm }: { em: EntityManager }) =>
       createOptimisticLockGuardService({
         getEm: () => scopedEm,

package/src/lib/encryption/__tests__/kms.test.ts

@@ -126,3 +126,83 @@ describe('kms timeout handling', () => {
     expect(dek?.key).toBeTruthy()
   })
 })
+
+describe('kms self-healing circuit breaker (#2661)', () => {
+  const vaultAddr = 'http://vault.test'
+  const vaultToken = 'token'
+
+  afterEach(() => {
+    process.env = { ...originalEnv }
+    jest.restoreAllMocks()
+  })
+
+  it('re-probes Vault and recovers after the cooldown window instead of staying unhealthy forever', async () => {
+    let clock = 1_000_000
+    jest.spyOn(Date, 'now').mockImplementation(() => clock)
+
+    let calls = 0
+    const fetchMock = jest.fn(() => {
+      calls += 1
+      if (calls === 1) {
+        // First read hits a transient 5xx (Vault hiccup) → breaker opens.
+        return Promise.resolve({ ok: false, status: 503, json: async () => ({}) })
+      }
+      // Vault is back: subsequent reads succeed.
+      return Promise.resolve({ ok: true, status: 200, json: async () => ({ data: { data: { key: 'recovered-key' } } }) })
+    })
+    ;(globalThis as { fetch?: typeof fetch }).fetch = fetchMock as typeof fetch
+
+    const service = new HashicorpVaultKmsService({ vaultAddr, vaultToken, recoveryCooldownMs: 5_000 })
+
+    // Transient failure flips the instance unhealthy.
+    await expect(service.getTenantDek('tenant-1')).resolves.toBeNull()
+    expect(service.isHealthy()).toBe(false)
+
+    // Still within the cooldown: the breaker stays open.
+    clock += 4_000
+    expect(service.isHealthy()).toBe(false)
+
+    // Past the cooldown: half-open — report healthy so the next call re-probes.
+    clock += 2_000
+    expect(service.isHealthy()).toBe(true)
+
+    // The re-probe succeeds and the breaker fully closes (the never-recover bug).
+    const dek = await service.getTenantDek('tenant-1')
+    expect(dek?.key).toBe('recovered-key')
+    expect(service.isHealthy()).toBe(true)
+  })
+
+  it('treats missing VAULT_ADDR/VAULT_TOKEN as a terminal failure that never self-heals', () => {
+    let clock = 2_000_000
+    jest.spyOn(Date, 'now').mockImplementation(() => clock)
+
+    const service = new HashicorpVaultKmsService({ vaultAddr: '', vaultToken: '', recoveryCooldownMs: 5_000 })
+    expect(service.isHealthy()).toBe(false)
+
+    // No cooldown re-probe should ever revive a misconfigured instance.
+    clock += 10_000_000
+    expect(service.isHealthy()).toBe(false)
+  })
+
+  it('keeps Vault healthy on a 404 read so read-before-write DEK creation can proceed', async () => {
+    jest.spyOn(Date, 'now').mockReturnValue(3_000_000)
+
+    const fetchMock = jest.fn((_url: string, init?: RequestInit) => {
+      const method = (init?.method || 'GET').toUpperCase()
+      if (method === 'GET') {
+        // KV v2 returns 404 for a not-yet-created tenant key — Vault is reachable.
+        return Promise.resolve({ ok: false, status: 404, json: async () => ({}) })
+      }
+      return Promise.resolve({ ok: true, status: 200, json: async () => ({}) })
+    })
+    ;(globalThis as { fetch?: typeof fetch }).fetch = fetchMock as typeof fetch
+
+    const service = new HashicorpVaultKmsService({ vaultAddr, vaultToken })
+
+    const dek = await service.createTenantDek('tenant-2')
+    expect(typeof dek?.key).toBe('string')
+    expect(dek?.key).toBeTruthy()
+    expect(service.isHealthy()).toBe(true)
+    expect(fetchMock).toHaveBeenCalledTimes(2) // 404 read probe + the write
+  })
+})

package/src/lib/encryption/kms.ts

@@ -5,6 +5,7 @@ import { parseBooleanToken } from '../boolean'
 import { fetchWithTimeout, resolveTimeoutMs } from '../http/fetchWithTimeout'
 
 const DEFAULT_VAULT_REQUEST_TIMEOUT_MS = 1_000
+const DEFAULT_VAULT_RECOVERY_COOLDOWN_MS = 30_000
 
 function resolveVaultRequestTimeoutMs(): number {
   const raw = process.env.VAULT_REQUEST_TIMEOUT_MS
@@ -12,6 +13,12 @@ function resolveVaultRequestTimeoutMs(): number {
   return resolveTimeoutMs(parsed, DEFAULT_VAULT_REQUEST_TIMEOUT_MS)
 }
 
+function resolveVaultRecoveryCooldownMs(): number {
+  const raw = process.env.VAULT_RECOVERY_COOLDOWN_MS
+  const parsed = raw ? Number.parseInt(raw, 10) : undefined
+  return resolveTimeoutMs(parsed, DEFAULT_VAULT_RECOVERY_COOLDOWN_MS)
+}
+
 export type TenantDek = {
   tenantId: string
   key: string // base64
@@ -90,6 +97,7 @@ type VaultClientOpts = {
   mountPath?: string
   ttlMs?: number
   requestTimeoutMs?: number
+  recoveryCooldownMs?: number
 }
 
 type VaultReadResponse = {
@@ -166,7 +174,16 @@ export class HashicorpVaultKmsService implements KmsService {
   private readonly mountPath: string
   private readonly ttlMs: number
   private readonly requestTimeoutMs: number
+  private readonly recoveryCooldownMs: number
   private healthy = true
+  // Sticky terminal failure (missing VAULT_ADDR/VAULT_TOKEN): no amount of
+  // re-probing fixes a misconfiguration, so this never self-heals — only a
+  // restart with corrected config does.
+  private misconfigured = false
+  // Timestamp of the last transient failure (timeout / network blip / 5xx).
+  // Drives the half-open circuit breaker in isHealthy(): after the cooldown the
+  // instance reports healthy again so the next call re-probes Vault.
+  private lastTransientFailureAt: number | null = null
   private readonly debugEnabled: boolean
   private static loggedInit = false
 
@@ -176,9 +193,11 @@ export class HashicorpVaultKmsService implements KmsService {
     this.mountPath = (opts.mountPath || process.env.VAULT_KV_PATH || 'secret/data').replace(/\/+$/, '')
     this.ttlMs = opts.ttlMs ?? 15 * 60 * 1000
     this.requestTimeoutMs = resolveTimeoutMs(opts.requestTimeoutMs, resolveVaultRequestTimeoutMs())
+    this.recoveryCooldownMs = resolveTimeoutMs(opts.recoveryCooldownMs, resolveVaultRecoveryCooldownMs())
     this.debugEnabled = isEncryptionDebugEnabled()
     if (!this.vaultAddr || !this.vaultToken) {
       this.healthy = false
+      this.misconfigured = true
       if (this.debugEnabled) {
         console.warn('⚠️ [encryption][kms] Vault misconfigured (missing VAULT_ADDR or VAULT_TOKEN)')
       }
@@ -192,13 +211,34 @@ export class HashicorpVaultKmsService implements KmsService {
   }
 
   isHealthy(): boolean {
-    return this.healthy
+    // A missing-config failure is terminal — never report healthy again.
+    if (this.misconfigured) return false
+    if (this.healthy) return true
+    // Half-open circuit breaker: once the cooldown since the last transient
+    // failure has elapsed, report healthy so the next read/write re-probes
+    // Vault. A successful probe flips `healthy` back on; a failing one records a
+    // fresh failure timestamp and re-opens the breaker for another cooldown.
+    if (this.lastTransientFailureAt === null) return false
+    return this.now() - this.lastTransientFailureAt >= this.recoveryCooldownMs
   }
 
   private now(): number {
     return Date.now()
   }
 
+  // Vault responded successfully (or is provably reachable): close the breaker.
+  private markHealthy(): void {
+    this.healthy = true
+    this.lastTransientFailureAt = null
+  }
+
+  // Transient infra failure (timeout / network blip / 5xx): open the breaker and
+  // start the recovery cooldown so a later call can re-probe and self-heal.
+  private markTransientFailure(): void {
+    this.healthy = false
+    this.lastTransientFailureAt = this.now()
+  }
+
   private cacheHit(tenantId: string): TenantDek | null {
     const entry = this.cache.get(tenantId)
     if (!entry) return null
@@ -212,6 +252,7 @@ export class HashicorpVaultKmsService implements KmsService {
   private async readVault(path: string): Promise<VaultReadResponse | null> {
     if (!this.vaultAddr || !this.vaultToken) {
       this.healthy = false
+      this.misconfigured = true
       return null
     }
     try {
@@ -221,16 +262,21 @@ export class HashicorpVaultKmsService implements KmsService {
         timeoutMs: this.requestTimeoutMs,
       })
       if (!res.ok) {
-        this.healthy = res.status < 500
+        // 5xx = Vault down/erroring (transient). <500 (auth/not-found/etc.) means
+        // Vault is reachable and answered, so keep it healthy — a 404 for a
+        // not-yet-created tenant DEK is the normal read-before-write path.
+        if (res.status >= 500) this.markTransientFailure()
+        else this.markHealthy()
         console.warn('⚠️ [encryption][kms] Vault read failed', { path, status: res.status })
         return null
       }
+      this.markHealthy()
       if (this.debugEnabled) {
         console.info('🔍 [encryption][kms] Vault read ok', { path })
       }
       return (await res.json()) as VaultReadResponse
     } catch (err) {
-      this.healthy = false
+      this.markTransientFailure()
       console.warn('⚠️ [encryption][kms] Vault read error', {
         path,
         error: (err as Error)?.message || String(err),
@@ -243,6 +289,7 @@ export class HashicorpVaultKmsService implements KmsService {
   private async writeVault(path: string, key: string, opts?: { cas?: number }): Promise<VaultWriteOutcome> {
     if (!this.vaultAddr || !this.vaultToken) {
       this.healthy = false
+      this.misconfigured = true
       return 'error'
     }
     const body: { data: { key: string }; options?: { cas: number } } = { data: { key } }
@@ -258,21 +305,22 @@ export class HashicorpVaultKmsService implements KmsService {
         timeoutMs: this.requestTimeoutMs,
       })
       if (res.ok) {
-        this.healthy = true
+        this.markHealthy()
         return 'ok'
       }
       // KV v2 returns 400 when a check-and-set write loses to a concurrent
       // writer (path already at a newer version). That is a normal race outcome,
-      // not an unhealthy Vault — don't flip `healthy`.
+      // not an unhealthy Vault — Vault is reachable, so close the breaker.
       if (typeof opts?.cas === 'number' && res.status === 400) {
+        this.markHealthy()
         console.warn('⚠️ [encryption][kms] Vault write CAS conflict (concurrent DEK create)', { path, status: res.status })
         return 'conflict'
       }
-      this.healthy = false
+      this.markTransientFailure()
       console.warn('⚠️ [encryption][kms] Vault write failed', { path, status: res.status })
       return 'error'
     } catch (err) {
-      this.healthy = false
+      this.markTransientFailure()
       console.warn('⚠️ [encryption][kms] Vault write error', {
         path,
         error: (err as Error)?.message || String(err),

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

@@ -0,0 +1,229 @@
+import { BasicQueryEngine } from '../engine'
+import { registerModules } from '../../i18n/server'
+
+// 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' } }] },
+] as any)
+
+type FakeData = Record<string, any[]>
+
+function cloneRows(rows: any[] | undefined): any[] {
+  if (!rows) return []
+  return rows.map((row) => ({ ...row }))
+}
+
+// Reads the SQL text of a Kysely raw/aliased expression by walking its operation node.
+function rawSqlText(expr: any): string {
+  const node = typeof expr?.toOperationNode === 'function' ? expr.toOperationNode() : expr
+  const inner = node?.node ?? node
+  const fragments = inner?.sqlFragments
+  return Array.isArray(fragments) ? fragments.join(' ? ') : ''
+}
+
+function aliasName(expr: any): string | undefined {
+  const node = typeof expr?.toOperationNode === 'function' ? expr.toOperationNode() : expr
+  const alias = node?.alias
+  return alias?.name ?? alias?.column?.name
+}
+
+function createFakeKysely(selectsSink: any[], overrides?: FakeData) {
+  const calls: any[] = []
+  const defaultData: FakeData = { custom_field_defs: [], custom_field_values: [] }
+  const sourceData = { ...defaultData, ...(overrides || {}) }
+  const data: FakeData = Object.fromEntries(
+    Object.entries(sourceData).map(([table, rows]) => [table, cloneRows(rows)]),
+  )
+
+  function parseTableSpec(spec: unknown): { table: string; alias: string | null } {
+    if (typeof spec !== 'string') return { table: String(spec || ''), alias: null }
+    const asMatch = /^(.+?)\s+as\s+(.+)$/i.exec(spec)
+    if (asMatch) return { table: asMatch[1].trim(), alias: asMatch[2].trim() }
+    return { table: spec, alias: null }
+  }
+
+  function createExpressionBuilder() {
+    const eb: any = (column: any, op: any, value: any) => ({ kind: 'cmp', column, op, value })
+    eb.and = (parts: any[]) => ({ kind: 'and', parts })
+    eb.or = (parts: any[]) => ({ kind: 'or', parts })
+    eb.not = (part: any) => ({ kind: 'not', part })
+    eb.exists = (sub: any) => ({ kind: 'exists', sub })
+    eb.val = (value: any) => ({ kind: 'val', value })
+    eb.ref = (name: string) => ({ kind: 'ref', name })
+    eb.selectFrom = (spec: any) => builderFor(spec)
+    return eb
+  }
+
+  function normalizeWhereArgs(args: any[]): any[] {
+    if (args.length === 1 && typeof args[0] === 'function') {
+      const produced = args[0](createExpressionBuilder())
+      if (produced && produced.kind === 'or') return ['or', produced.parts]
+      if (produced && produced.kind === 'and') return ['and', produced.parts]
+      if (produced && produced.kind === 'exists') return ['exists', produced.sub]
+      if (produced && produced.kind === 'not' && produced.part?.kind === 'exists') return ['notExists', produced.part.sub]
+      return ['expr', produced]
+    }
+    return args
+  }
+
+  function recordJoin(ops: any, type: 'left' | 'inner', spec: any, fn: Function) {
+    const parsed = parseTableSpec(spec)
+    const aliasObj = parsed.alias ? { [parsed.alias]: parsed.table } : { [parsed.table]: parsed.table }
+    const entry: any = { type, aliasObj, conditions: [] as any[] }
+    const ctx: any = {}
+    ctx.on = (left: any, op?: any, right?: any) => {
+      if (typeof left === 'function') entry.conditions.push({ method: 'on', expr: left(createExpressionBuilder()) })
+      else entry.conditions.push({ method: 'on', args: [left, op, right] })
+      return ctx
+    }
+    ctx.onRef = (left: any, op: any, right: any) => {
+      entry.conditions.push({ method: 'on', args: [left, op, right] })
+      return ctx
+    }
+    fn(ctx)
+    ops.joins.push(entry)
+  }
+
+  function makeBuilder(ops: any, record: boolean): any {
+    const b: any = {
+      _ops: ops,
+      select(this: any, ...cols: any[]) {
+        const flat = cols.length === 1 && Array.isArray(cols[0]) ? cols[0] : cols
+        this._ops.selects.push(...flat)
+        selectsSink.push(...flat)
+        return this
+      },
+      distinct(this: any) { return this },
+      where(this: any, ...args: any[]) { this._ops.wheres.push(normalizeWhereArgs(args)); return this },
+      whereRef(this: any, left: any, op: any, right: any) { this._ops.wheres.push(['ref', left, op, right]); return this },
+      leftJoin(this: any, spec: any, fn: Function) { recordJoin(this._ops, 'left', spec, fn); return this },
+      innerJoin(this: any, spec: any, fn: Function) { recordJoin(this._ops, 'inner', spec, fn); return this },
+      groupBy(this: any, arg: any) {
+        if (Array.isArray(arg)) this._ops.groups.push(...arg)
+        else this._ops.groups.push(arg)
+        return this
+      },
+      having(this: any) { return this },
+      orderBy(this: any, col: any, dir?: any) { this._ops.orderBys.push([col, dir]); return this },
+      limit(this: any, n: number) { this._ops.limits = n; return this },
+      offset(this: any, n: number) { this._ops.offsets = n; return this },
+      clearSelect(this: any) { return makeBuilder({ ...this._ops, selects: [] }, false) },
+      clearOrderBy(this: any) { return makeBuilder({ ...this._ops, orderBys: [] }, false) },
+      clearGroupBy(this: any) { return makeBuilder({ ...this._ops, groups: [] }, false) },
+      as(this: any, alias: string) { this._ops.alias = alias; return this },
+      async execute(this: any) { return cloneRows(data[this._ops.table]) },
+      async executeTakeFirst(this: any) {
+        const localOps = this._ops
+        if (localOps.table === 'information_schema.columns') {
+          const infoRows = data['information_schema.columns']
+          if (!Array.isArray(infoRows)) return undefined
+          const targetTable = extractEqValue(localOps.wheres, 'table_name')
+          const targetColumn = extractEqValue(localOps.wheres, 'column_name')
+          return infoRows.find((row: any) =>
+            (!targetTable || row.table_name === targetTable) && (!targetColumn || row.column_name === targetColumn))
+        }
+        if (localOps.table === 'information_schema.tables') {
+          const infoRows = data['information_schema.tables']
+          if (!Array.isArray(infoRows)) return undefined
+          const targetTable = extractEqValue(localOps.wheres, 'table_name')
+          return infoRows.find((row: any) => !targetTable || row.table_name === targetTable)
+        }
+        if (localOps.selects.some((s: any) => aliasName(s) === 'count')) return { count: '0' }
+        const rows = data[localOps.table] || []
+        if (rows.length === 0) return { count: '0' }
+        return rows[0]
+      },
+    }
+    if (record) calls.push(b)
+    return b
+  }
+
+  function builderFor(tableArg: any): any {
+    const parsed = parseTableSpec(tableArg)
+    const ops = {
+      table: parsed.table,
+      alias: parsed.alias,
+      wheres: [] as any[],
+      joins: [] as any[],
+      selects: [] as any[],
+      orderBys: [] as any[],
+      groups: [] as any[],
+      limits: 0,
+      offsets: 0,
+    }
+    return makeBuilder(ops, true)
+  }
+
+  function extractEqValue(wheres: any[], column: string): any {
+    for (const entry of wheres) {
+      if (!Array.isArray(entry)) continue
+      if (entry[0] === column && entry[1] === '=') return entry[2]
+    }
+    return undefined
+  }
+
+  const db: any = { selectFrom(spec: any) { return builderFor(spec) } }
+  db._calls = calls
+  return db
+}
+
+function findCountSql(selectsSink: any[]): string {
+  const countExprs = selectsSink.filter((s) => aliasName(s) === 'count')
+  expect(countExprs.length).toBeGreaterThan(0)
+  return rawSqlText(countExprs[countExprs.length - 1]).toLowerCase()
+}
+
+describe('BasicQueryEngine — list COUNT query (issue #2227)', () => {
+  test('uses count(*) and no group-by when no joins can multiply base rows', async () => {
+    const selects: any[] = []
+    const fakeDb = createFakeKysely(selects)
+    const engine = new BasicQueryEngine({} as any, () => fakeDb as any)
+    await engine.query('scheduler:scheduled_job', { tenantId: 't1', fields: ['id'], page: { page: 1, pageSize: 20 } })
+
+    const countSql = findCountSql(selects)
+    expect(countSql).toContain('count(*)')
+    expect(countSql).not.toContain('distinct')
+
+    const baseCall = fakeDb._calls.find((b: any) => b._ops.table === 'scheduled_jobs')
+    expect(baseCall._ops.groups.length).toBe(0)
+  })
+
+  test('keeps count(distinct base.id) with group-by when extensions are joined', async () => {
+    const selects: any[] = []
+    const fakeDb = createFakeKysely(selects)
+    const engine = new BasicQueryEngine({} as any, () => fakeDb as any)
+    await engine.query('auth:user', {
+      tenantId: 't1',
+      organizationId: '1',
+      fields: ['id'],
+      includeExtensions: true,
+      page: { page: 1, pageSize: 20 },
+    })
+
+    const countSql = findCountSql(selects)
+    expect(countSql).toContain('count(distinct')
+    expect(countSql).not.toContain('count(*)')
+
+    const baseCall = fakeDb._calls.find((b: any) => b._ops.table === 'users')
+    expect(baseCall._ops.groups.length).toBeGreaterThan(0)
+  })
+
+  test('keeps count(distinct base.id) without group-by when an explicit relation join is configured', async () => {
+    const selects: any[] = []
+    const fakeDb = createFakeKysely(selects)
+    const engine = new BasicQueryEngine({} as any, () => fakeDb as any)
+    await engine.query('scheduler:scheduled_job', {
+      tenantId: 't1',
+      fields: ['id'],
+      joins: [{ alias: 'owner', table: 'users', from: { field: 'owner_id' }, to: { field: 'id' } }],
+      page: { page: 1, pageSize: 20 },
+    })
+
+    const countSql = findCountSql(selects)
+    expect(countSql).toContain('count(distinct')
+    expect(countSql).not.toContain('count(*)')
+
+    const baseCall = fakeDb._calls.find((b: any) => b._ops.table === 'scheduled_jobs')
+    expect(baseCall._ops.groups.length).toBe(0)
+  })
+})

package/src/lib/query/advanced-filter-tree.ts

@@ -1,7 +1,7 @@
 // packages/shared/src/lib/query/advanced-filter-tree.ts
 import type { FilterOperator } from './advanced-filter'
 import { isValuelessOperator } from './advanced-filter'
-import { escapeLikePattern } from '../db/escapeLikePattern'
+import { buildIlikeTerm } from '../db/buildIlikeTerm'
 
 export type FilterCombinator = 'and' | 'or'
 
@@ -102,22 +102,22 @@ function compileRule(rule: FilterRule): Record<string, unknown> | null {
     case 'contains': {
       const v = normalizeSingleValue(rule.value)
       if (v === null) return null
-      filter[rule.field] = { $ilike: `%${escapeLikePattern(String(v))}%` }; break
+      filter[rule.field] = { $ilike: buildIlikeTerm(String(v)) }; break
     }
     case 'does_not_contain': {
       const v = normalizeSingleValue(rule.value)
       if (v === null) return null
-      filter[rule.field] = { $not: { $ilike: `%${escapeLikePattern(String(v))}%` } }; break
+      filter[rule.field] = { $not: { $ilike: buildIlikeTerm(String(v)) } }; break
     }
     case 'starts_with': {
       const v = normalizeSingleValue(rule.value)
       if (v === null) return null
-      filter[rule.field] = { $ilike: `${escapeLikePattern(String(v))}%` }; break
+      filter[rule.field] = { $ilike: buildIlikeTerm(String(v), 'startsWith') }; break
     }
     case 'ends_with': {
       const v = normalizeSingleValue(rule.value)
       if (v === null) return null
-      filter[rule.field] = { $ilike: `%${escapeLikePattern(String(v))}` }; break
+      filter[rule.field] = { $ilike: buildIlikeTerm(String(v), 'endsWith') }; break
     }
     case 'is_empty': filter[rule.field] = { $exists: false }; break
     case 'is_not_empty': filter[rule.field] = { $exists: true }; break

package/src/lib/query/advanced-filter.ts

@@ -1,4 +1,4 @@
-import { escapeLikePattern } from '../db/escapeLikePattern'
+import { buildIlikeTerm } from '../db/buildIlikeTerm'
 
 export type FilterOperator =
   | 'is' | 'is_not' | 'contains' | 'does_not_contain' | 'starts_with' | 'ends_with' | 'is_empty' | 'is_not_empty'
@@ -190,19 +190,19 @@ function buildConditionFilter(condition: FilterCondition): Record<string, unknow
       break
     case 'contains':
       if (normalizeSingleValue(condition.value) === null) return null
-      filter[condition.field] = { $ilike: `%${escapeLikePattern(String(normalizeSingleValue(condition.value)))}%` }
+      filter[condition.field] = { $ilike: buildIlikeTerm(String(normalizeSingleValue(condition.value))) }
       break
     case 'does_not_contain':
       if (normalizeSingleValue(condition.value) === null) return null
-      filter[condition.field] = { $not: { $ilike: `%${escapeLikePattern(String(normalizeSingleValue(condition.value)))}%` } }
+      filter[condition.field] = { $not: { $ilike: buildIlikeTerm(String(normalizeSingleValue(condition.value))) } }
       break
     case 'starts_with':
       if (normalizeSingleValue(condition.value) === null) return null
-      filter[condition.field] = { $ilike: `${escapeLikePattern(String(normalizeSingleValue(condition.value)))}%` }
+      filter[condition.field] = { $ilike: buildIlikeTerm(String(normalizeSingleValue(condition.value)), 'startsWith') }
       break
     case 'ends_with':
       if (normalizeSingleValue(condition.value) === null) return null
-      filter[condition.field] = { $ilike: `%${escapeLikePattern(String(normalizeSingleValue(condition.value)))}` }
+      filter[condition.field] = { $ilike: buildIlikeTerm(String(normalizeSingleValue(condition.value)), 'endsWith') }
       break
     case 'is_empty':
       filter[condition.field] = { $exists: false }

package/src/lib/query/engine.ts

@@ -844,9 +844,20 @@ export class BasicQueryEngine implements QueryEngine {
     if (hasJoinedAggregates) {
       q = q.groupBy(`${table}.id`)
     }
+    // `count(distinct base.id)` is only required when a join can multiply base rows
+    // (CF/extension aggregates, explicit relation joins, or custom-field sources).
+    // Without such joins base.id is the unique PK, so `count(*)` is equivalent and
+    // lets Postgres skip the redundant DISTINCT sort/hash for an index-only count (#2227).
+    const mayMultiplyBaseRows =
+      hasJoinedAggregates ||
+      (Array.isArray(opts.joins) && opts.joins.length > 0) ||
+      (Array.isArray(opts.customFieldSources) && opts.customFieldSources.length > 0)
+    const countExpr = mayMultiplyBaseRows
+      ? sql<string>`count(distinct ${sql.ref(`${table}.id`)})`
+      : sql<string>`count(*)`
     const countBuilder = hasJoinedAggregates
-      ? q.clearSelect().clearOrderBy().clearGroupBy().select(sql<string>`count(distinct ${sql.ref(`${table}.id`)})`.as('count'))
-      : q.clearSelect().clearOrderBy().select(sql<string>`count(distinct ${sql.ref(`${table}.id`)})`.as('count'))
+      ? q.clearSelect().clearOrderBy().clearGroupBy().select(countExpr.as('count'))
+      : q.clearSelect().clearOrderBy().select(countExpr.as('count'))
     const countRow = await countBuilder.executeTakeFirst() as { count: unknown } | undefined
     const total = Number((countRow as any)?.count ?? 0)
     const dataQuery = requiresPlaintextSort