@open-mercato/shared 0.7.0 → 0.7.1-develop.7102.1.b41f7e3e51

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

@@ -2,11 +2,14 @@ import { BasicQueryEngine } from '../engine'
 import { SortDir } from '../types'
 import { registerModules } from '../../i18n/server'
 import { clearSearchTokenPresenceCache } from '../../search/availability'
+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
@@ -176,6 +179,13 @@ function createFakeKysely(overrides?: FakeData) {
           return infoRows.find((row: any) => !targetTable || row.table_name === targetTable)
         }
         if (localOps.selects.some((s: any) => s && typeof s === 'object' && (s.__isCount || String(s?.alias || '') === 'count'))) {
+          // An aggregate over a recorded subquery (the capped-count probe) counts
+          // the subquery's source rows bounded by its LIMIT, mirroring Postgres.
+          if (localOps.subquery) {
+            const sourceRows = (data[localOps.subquery.table] || []).length
+            const innerLimit = localOps.subquery.limits
+            return { count: String(innerLimit ? Math.min(sourceRows, innerLimit) : sourceRows) }
+          }
           return { count: String((data[localOps.table] || []).length) }
         }
         const rows = data[localOps.table] || []
@@ -188,6 +198,22 @@ function createFakeKysely(overrides?: FakeData) {
   }
 
   function builderFor(tableArg: any): any {
+    if (tableArg && typeof tableArg === 'object' && tableArg._ops) {
+      // selectFrom(subquery.as(alias)) — the capped-count probe shape.
+      const ops = {
+        table: '__subquery__',
+        alias: tableArg._ops.alias ?? null,
+        subquery: tableArg._ops,
+        wheres: [] as any[],
+        joins: [] as any[],
+        selects: [] as any[],
+        orderBys: [] as any[],
+        groups: [] as any[],
+        limits: 0,
+        offsets: 0,
+      }
+      return makeBuilder(ops, true)
+    }
     const parsed = parseTableSpec(tableArg)
     const ops = {
       table: parsed.table,
@@ -693,10 +719,10 @@ describe('BasicQueryEngine (Kysely)', () => {
 
     expect(result.items.map((item: any) => item.display_name)).toEqual(['Charlie', 'Dave'])
     const baseCalls = fakeDb._calls.filter((call: any) => call._ops.table === 'customer_entities')
-    expect(baseCalls.length).toBe(2)
-    // qFull ('full' projection) is built first (used for count + phase 2);
-    // qSort ('sortKeys' projection) is built second (phase 1).
-    const [phase2Call, phase1Call] = baseCalls
+    expect(baseCalls.length).toBe(3)
+    // qFull ('full' projection) is built first (used for phase 2), then the
+    // 'count' projection (the bounded count probe), then 'sortKeys' (phase 1).
+    const [phase2Call, , phase1Call] = baseCalls
     // Phase 1 (slim id+sort-column scan): no SQL order/limit — the full candidate
     // set is fetched, decrypted, and sorted in memory.
     expect(phase1Call._ops.orderBys).toEqual([])
@@ -878,7 +904,7 @@ describe('BasicQueryEngine (Kysely)', () => {
         page: { page: 1, pageSize: 2 },
       })
       expect(result.meta?.encryptedSortRowCapWarning).toBeUndefined()
-      const [, phase1Call] = fakeDb._calls.filter((call: any) => call._ops.table === 'customer_entities')
+      const [, , phase1Call] = fakeDb._calls.filter((call: any) => call._ops.table === 'customer_entities')
       expect(phase1Call._ops.limits).toBe(0)
     })
 
@@ -912,10 +938,37 @@ describe('BasicQueryEngine (Kysely)', () => {
         maxRows: 3,
         totalMatched: 5,
       })
-      const [, phase1Call] = fakeDb._calls.filter((call: any) => call._ops.table === 'customer_entities')
-      expect(phase1Call._ops.limits).toBe(3)
+      const [, , phase1Call] = fakeDb._calls.filter((call: any) => call._ops.table === 'customer_entities')
+      // cap + 1 probe: truncation is detected from the candidate scan itself,
+      // not by comparing against a (possibly capped) total.
+      expect(phase1Call._ops.limits).toBe(4)
       expect(phase1Call._ops.orderBys).toEqual([['customer_entities.id', 'asc']])
     })
+
+    test('still warns when the list count itself is capped below the matched set', async () => {
+      // The old detection compared `total > sortCap`; with OM_LIST_COUNT_CAP at or
+      // below the sort cap that comparison can never fire. The probe must warn anyway.
+      process.env.OM_ENCRYPTED_SORT_MAX_ROWS = '3'
+      process.env.OM_LIST_COUNT_CAP = '3'
+      try {
+        const { engine } = buildFixture()
+        const result = await engine.query('customers:customer_entity', {
+          tenantId: 't1',
+          organizationId: 'org1',
+          fields: ['id', 'display_name'],
+          sort: [{ field: 'display_name', dir: SortDir.Asc }],
+          page: { page: 1, pageSize: 2 },
+        })
+        expect(result.total).toBe(3)
+        expect(result.meta?.listCountCapWarning).toEqual({ entity: 'customers:customer_entity', cap: 3 })
+        expect(result.meta?.encryptedSortRowCapWarning).toMatchObject({
+          entity: 'customers:customer_entity',
+          maxRows: 3,
+        })
+      } finally {
+        delete process.env.OM_LIST_COUNT_CAP
+      }
+    })
   })
 
   test('keeps SQL ordering and pagination for unencrypted base fields', async () => {
@@ -954,6 +1007,80 @@ describe('BasicQueryEngine (Kysely)', () => {
     expect(baseCall._ops.offsets).toBe(10)
   })
 
+  describe('OM_LIST_COUNT_CAP boundary', () => {
+    const originalCap = process.env.OM_LIST_COUNT_CAP
+    afterEach(() => {
+      if (originalCap === undefined) delete process.env.OM_LIST_COUNT_CAP
+      else process.env.OM_LIST_COUNT_CAP = originalCap
+    })
+
+    function buildFixture(rowCount: number) {
+      const rows = Array.from({ length: rowCount }, (_, i) => ({
+        id: String(i + 1), tenant_id: 't1', organization_id: 'org1', display_name: `Row ${i + 1}`,
+      }))
+      const fakeDb = createFakeKysely({
+        customer_entities: rows,
+        'information_schema.columns': [
+          { table_name: 'customer_entities', column_name: 'id' },
+          { table_name: 'customer_entities', column_name: 'tenant_id' },
+          { table_name: 'customer_entities', column_name: 'organization_id' },
+          { table_name: 'customer_entities', column_name: 'deleted_at' },
+          { table_name: 'customer_entities', column_name: 'display_name' },
+        ],
+      })
+      const engine = new BasicQueryEngine({} as any, () => fakeDb as any)
+      return { fakeDb, engine }
+    }
+
+    const query = (engine: BasicQueryEngine) => engine.query('customers:customer_entity', {
+      tenantId: 't1',
+      organizationId: 'org1',
+      fields: ['id'],
+      page: { page: 1, pageSize: 2 },
+    })
+
+    test('cap - 1 matching rows: exact total, no flag', async () => {
+      process.env.OM_LIST_COUNT_CAP = '5'
+      const { engine } = buildFixture(4)
+      const result = await query(engine)
+      expect(result.total).toBe(4)
+      expect(result.meta?.listCountCapWarning).toBeUndefined()
+    })
+
+    test('exactly cap matching rows: exact total, no flag — a genuine total of cap is not mislabeled', async () => {
+      process.env.OM_LIST_COUNT_CAP = '5'
+      const { engine } = buildFixture(5)
+      const result = await query(engine)
+      expect(result.total).toBe(5)
+      expect(result.meta?.listCountCapWarning).toBeUndefined()
+    })
+
+    test('cap + 1 matching rows: total reports cap (not the probe value) with the warning', async () => {
+      process.env.OM_LIST_COUNT_CAP = '5'
+      const { engine } = buildFixture(6)
+      const result = await query(engine)
+      expect(result.total).toBe(5)
+      expect(result.meta?.listCountCapWarning).toEqual({ entity: 'customers:customer_entity', cap: 5 })
+    })
+
+    test('OM_LIST_COUNT_CAP=0: exact totals however large the set', async () => {
+      process.env.OM_LIST_COUNT_CAP = '0'
+      const { engine } = buildFixture(7)
+      const result = await query(engine)
+      expect(result.total).toBe(7)
+      expect(result.meta?.listCountCapWarning).toBeUndefined()
+    })
+
+    test('unparseable value falls back to the default cap rather than disabling it', async () => {
+      process.env.OM_LIST_COUNT_CAP = 'not-a-number'
+      const { fakeDb, engine } = buildFixture(3)
+      const result = await query(engine)
+      expect(result.total).toBe(3)
+      const outer = fakeDb._calls.find((call: any) => call._ops.table === '__subquery__')
+      expect(outer._ops.subquery.limits).toBe(10_001)
+    })
+  })
+
   // A tiebreak sort is only worth configuring if the engine actually emits it.
   // `list.tiebreakSortField` (used by the sales line routes to keep lines with an
   // equal `line_number` in a repeatable order) is the first caller to pass more
@@ -1134,3 +1261,314 @@ describe('BasicQueryEngine entity-extension joins', () => {
     expect(join.aliasObj).toEqual({ ext_example_session_note: 'example_session_notes' })
   })
 })
+
+describe('BasicQueryEngine like/ilike routing by column encryption', () => {
+  // The gate is opt-in: OM_SEARCH_USE_ILIKE_FOR_NON_ENCRYPTED_FIELDS defaults to false and the
+  // legacy rewrite-everything behavior stays. These cases flip it on; the last one pins the
+  // default off.
+  beforeEach(() => {
+    process.env.OM_SEARCH_USE_ILIKE_FOR_NON_ENCRYPTED_FIELDS = 'true'
+  })
+  afterEach(() => {
+    delete process.env.OM_SEARCH_USE_ILIKE_FOR_NON_ENCRYPTED_FIELDS
+  })
+
+  // The token rewrite exists because ILIKE against ciphertext cannot match. On a plaintext
+  // column SQL ILIKE is exact, and the rewrite silently changes the result set: tokenization
+  // splits on non-alphanumerics and drops tokens shorter than minTokenLength, so a
+  // document-number search like "ZK 1/2026" degrades to the tokens {202, 2026} and matches
+  // every record from that year instead of the one document.
+  const fakeDbWithTokens = () => createFakeKysely({
+    customer_entities: [],
+    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_entities', column_name: 'display_name' },
+    ],
+  })
+
+  test('a plaintext base column keeps exact SQL ILIKE even when tokens are available', async () => {
+    const fakeDb = fakeDbWithTokens()
+    const engine = new BasicQueryEngine(
+      {} as any,
+      () => fakeDb as any,
+      () => ({ getEncryptedFieldNames: async () => [] }) as any,
+    )
+    const applySearchTokensSpy = jest.spyOn(engine as any, 'applySearchTokens')
+
+    await engine.query('customers:customer_entity', {
+      tenantId: 't1',
+      fields: ['id'],
+      filters: { display_name: { $ilike: '%ZK 1/2026%' } },
+      page: { page: 1, pageSize: 10 },
+    })
+
+    expect(applySearchTokensSpy).not.toHaveBeenCalled()
+    const baseCall = fakeDb._calls.find((b: any) => b._ops.table === 'customer_entities')
+    expect(baseCall).toBeTruthy()
+    const ilikeWhere = baseCall._ops.wheres.some(
+      (w: any) => Array.isArray(w) && String(w[0]).includes('display_name') && w[1] === 'ilike' && w[2] === '%ZK 1/2026%',
+    )
+    expect(ilikeWhere).toBe(true)
+  })
+
+  test('an encrypted base column still routes through search tokens', async () => {
+    const engine = new BasicQueryEngine(
+      {} as any,
+      () => fakeDbWithTokens() as any,
+      () => ({ getEncryptedFieldNames: async () => ['display_name'] }) as any,
+    )
+    const applySearchTokensSpy = jest.spyOn(engine as any, 'applySearchTokens')
+
+    await engine.query('customers:customer_entity', {
+      tenantId: 't1',
+      fields: ['id'],
+      filters: { display_name: { $ilike: '%avision%' } },
+      page: { page: 1, pageSize: 10 },
+    })
+
+    expect(applySearchTokensSpy).toHaveBeenCalled()
+  })
+
+  test('no service + encryption disabled: nothing is ciphertext, ILIKE stays exact', async () => {
+    process.env.TENANT_DATA_ENCRYPTION = 'no'
+    try {
+      const fakeDb = fakeDbWithTokens()
+      const engine = new BasicQueryEngine({} as any, () => fakeDb as any)
+      const applySearchTokensSpy = jest.spyOn(engine as any, 'applySearchTokens')
+
+      await engine.query('customers:customer_entity', {
+        tenantId: 't1',
+        fields: ['id'],
+        filters: { display_name: { $ilike: '%avision%' } },
+        page: { page: 1, pageSize: 10 },
+      })
+
+      expect(applySearchTokensSpy).not.toHaveBeenCalled()
+      const baseCall = fakeDb._calls.find((b: any) => b._ops.table === 'customer_entities')
+      const ilikeWhere = baseCall._ops.wheres.some(
+        (w: any) => Array.isArray(w) && String(w[0]).includes('display_name') && w[1] === 'ilike' && w[2] === '%avision%',
+      )
+      expect(ilikeWhere).toBe(true)
+    } finally {
+      delete process.env.TENANT_DATA_ENCRYPTION
+    }
+  })
+
+  test('no service + encryption enabled: the map is unknown, the token rewrite is kept', async () => {
+    // A swallowed DI failure looks exactly like "no service". Guessing "plaintext" here would
+    // run ILIKE against ciphertext (zero rows, silently) -- so the gate stays inert instead.
+    const engine = new BasicQueryEngine({} as any, () => fakeDbWithTokens() as any)
+    const applySearchTokensSpy = jest.spyOn(engine as any, 'applySearchTokens')
+
+    await engine.query('customers:customer_entity', {
+      tenantId: 't1',
+      fields: ['id'],
+      filters: { display_name: { $ilike: '%avision%' } },
+      page: { page: 1, pageSize: 10 },
+    })
+
+    expect(applySearchTokensSpy).toHaveBeenCalled()
+  })
+
+  test('a camelCase encryption-map entry still routes its column through tokens', async () => {
+    // Encryption maps may declare `displayName` while the filter carries the column name
+    // `display_name` (TenantDataEncryptionService resolves both). A raw name comparison would
+    // misread that ciphertext column as plaintext and run ILIKE against ciphertext -- zero rows,
+    // silently. The gate must match across name shapes.
+    const engine = new BasicQueryEngine(
+      {} as any,
+      () => fakeDbWithTokens() as any,
+      () => ({ getEncryptedFieldNames: async () => ['displayName'] }) as any,
+    )
+    const applySearchTokensSpy = jest.spyOn(engine as any, 'applySearchTokens')
+
+    await engine.query('customers:customer_entity', {
+      tenantId: 't1',
+      fields: ['id'],
+      filters: { display_name: { $ilike: '%avision%' } },
+      page: { page: 1, pageSize: 10 },
+    })
+
+    expect(applySearchTokensSpy).toHaveBeenCalled()
+  })
+
+  test('with the flag off (default) the token rewrite is kept even for plaintext columns', () => {
+    delete process.env.OM_SEARCH_USE_ILIKE_FOR_NON_ENCRYPTED_FIELDS
+    const fakeDb = fakeDbWithTokens()
+    const engine = new BasicQueryEngine(
+      {} as any,
+      () => fakeDb as any,
+      () => ({ getEncryptedFieldNames: async () => [] }) as any,
+    )
+    const applySearchTokensSpy = jest.spyOn(engine as any, 'applySearchTokens')
+
+    return engine
+      .query('customers:customer_entity', {
+        tenantId: 't1',
+        fields: ['id'],
+        filters: { display_name: { $ilike: '%avision%' } },
+        page: { page: 1, pageSize: 10 },
+      })
+      .then(() => {
+        expect(applySearchTokensSpy).toHaveBeenCalled()
+      })
+  })
+})
+
+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/count-cap.ts

@@ -0,0 +1,19 @@
+import { parseNumberWithDefault } from '../number'
+
+export const DEFAULT_LIST_COUNT_CAP = 10_000
+
+/**
+ * Cap on how many matching rows a list COUNT may visit before reporting
+ * `total: cap` with `meta.listCountCapWarning` (surfaced to clients as
+ * `totalIsCapped`). Returns the cap as a number, or `null` when capping is
+ * disabled.
+ *
+ * Resolution of `OM_LIST_COUNT_CAP`:
+ * - unset / blank / unparseable → `DEFAULT_LIST_COUNT_CAP` (the cap is on by
+ *   default, and bad input must not silently disable it)
+ * - `0` (or negative) → `null` — capping disabled, exact counts everywhere
+ */
+export function resolveListCountCap(): number | null {
+  const parsed = parseNumberWithDefault(process.env.OM_LIST_COUNT_CAP, DEFAULT_LIST_COUNT_CAP, { integer: true })
+  return parsed <= 0 ? null : parsed
+}