@open-mercato/shared 0.6.8-develop.7030.1.b84302d973 → 0.6.8-develop.7032.1.70d74d4bfe

package/dist/lib/query/types.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/lib/query/types.ts"],
-  "sourcesContent": ["import type { EntityId } from '@open-mercato/shared/modules/entities'\nimport type { Profiler } from '../profiler'\nimport type { ResolvedCustomFieldDefinitions } from '../crud/custom-field-definition-index'\n\nexport type FilterOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'like' | 'ilike' | 'exists'\n\nexport enum SortDir {\n  Asc = 'asc',\n  Desc = 'desc',\n}\n\nexport type FieldSelector = string // base field or custom field key (prefixed with 'cf:')\n\nexport type Filter = {\n  field: FieldSelector\n  op: FilterOp\n  value?: any\n}\n\nexport type Sort = { field: FieldSelector; dir?: SortDir }\n\nexport type Page = { page?: number; pageSize?: number }\n\n// Mongo/Medusa-style filter operators (typed)\nexport type WhereOps<T> = {\n  $eq?: T\n  $ne?: T | null\n  $gt?: T extends number | Date ? T : never\n  $gte?: T extends number | Date ? T : never\n  $lt?: T extends number | Date ? T : never\n  $lte?: T extends number | Date ? T : never\n  $in?: T[]\n  $nin?: T[]\n  $like?: T extends string ? string : never\n  $ilike?: T extends string ? string : never\n  $exists?: boolean\n}\n\n// A field filter can be a direct value (equals) or ops object\nexport type WhereValue<T = any> = T | WhereOps<T>\n\n// Generic shape for object filters. If you have a typed map of field\u2192type,\n// pass it as the generic to get end-to-end typing.\n// Example: Where<{\n//   id: string; title: string; created_at: Date; 'cf:severity': number\n// }>\nexport type Where<Fields extends Record<string, any> = Record<string, any>> =\n  Partial<{ [K in keyof Fields]: WhereValue<Fields[K]> }> & Record<string, WhereValue>\n\nexport type QueryCustomFieldJoin = {\n  fromField: string\n  toField: string\n  type?: 'left' | 'inner'\n}\n\nexport type QueryCustomFieldSource = {\n  entityId: EntityId\n  table?: string\n  alias?: string\n  recordIdColumn?: string\n  join?: QueryCustomFieldJoin\n  tenantField?: string\n  organizationField?: string\n}\n\nexport type QueryJoinEdge = {\n  alias: string\n  table?: string\n  entityId?: EntityId\n  from: {\n    alias?: string\n    field: string\n  }\n  to: {\n    field: string\n  }\n  type?: 'left' | 'inner'\n}\n\n/**\n * Optional context for query-level UMES extensions.\n * When provided, the query engine will execute sync lifecycle events\n * (querying/queried) and apply query-enabled enrichers.\n */\nexport type QueryExtensionsConfig = {\n  userId?: string\n  container?: unknown\n  userFeatures?: string[]\n  resolve?: <T = unknown>(name: string) => T\n}\n\nexport type QueryOptions = {\n  fields?: FieldSelector[] // base fields and/or 'cf:<key>' for custom fields\n  includeExtensions?: boolean | string[] // include all registered extensions or only specific ones by entity id\n  includeCustomFields?: boolean | string[] // include all CFs or specific keys\n  // Accept classic array syntax or Mongo-style object syntax\n  filters?: Filter[] | Where\n  sort?: Sort[]\n  page?: Page\n  organizationId?: string // enforce multi-tenant scope\n  tenantId?: string // enforce tenant scope\n  // Optional list of organization ids to scope results. Takes precedence over organizationId.\n  organizationIds?: string[]\n  /**\n   * When true, the engine does not apply default `organization_id` / `tenant_id` equality guards.\n   *\n   * Callers MUST encode full visibility in `filters` (for example with `$or` of scoped branches)\n   * and MUST fail closed when the authenticated principal lacks a resolvable tenant/org, otherwise\n   * queries return cross-tenant rows.\n   *\n   * When this flag is set, the hybrid query engine delegates to the basic engine. The basic engine\n   * still applies `cf:*` filters/sorts, but `search_tokens` fulltext filtering, the JSONB index read\n   * path, and the vector-search branch are BYPASSED. Only use this on entities whose scoping does\n   * not match the standard `organization_id = X AND tenant_id = Y` shape.\n   */\n  omitAutomaticTenantOrgScope?: boolean\n  // Soft-delete behavior: when false (default), rows with non-null deleted_at\n  // are excluded if the base table has that column. Set true to include them.\n  withDeleted?: boolean\n  customFieldSources?: QueryCustomFieldSource[]\n  joins?: QueryJoinEdge[]\n  profiler?: Profiler\n  // When true, suppress automatic reindex scheduling triggered by coverage gap detection.\n  // Used by the search indexing pipeline to prevent feedback loops where indexing triggers\n  // re-indexing indefinitely.\n  skipAutoReindex?: boolean\n  /**\n   * Force routing this query to custom-entity doc storage (`custom_entities_storage`)\n   * instead of classifying the entity automatically. Automatic classification routes\n   * ids backed by a registered ORM table to that base table, so surfaces that manage\n   * doc records for ids that are ALSO table-backed (e.g. the entities records browser\n   * reading a module-declared custom entity such as `example:todo`) must set this flag.\n   * Honored by the hybrid query engine only; `BasicQueryEngine` has no doc-storage\n   * reader and ignores it.\n   */\n  forceCustomEntityStorage?: boolean\n  // Optional UMES query extensions context. When provided, the engine will\n  // emit sync lifecycle events and apply query-level enrichers.\n  extensions?: QueryExtensionsConfig\n}\n\nexport type PartialIndexWarning = {\n  entity: EntityId\n  entityLabel?: string | null\n  baseCount?: number | null\n  indexedCount?: number | null\n  scope?: 'scoped' | 'global'\n}\n\nexport type EncryptedSortRowCapWarning = {\n  entity: EntityId\n  sortFields: string[]\n  maxRows: number\n  totalMatched: number\n}\n\nexport type QueryResultMeta = {\n  partialIndexWarning?: PartialIndexWarning\n  encryptedSortRowCapWarning?: EncryptedSortRowCapWarning\n}\n\nexport type QueryResult<T = any> = {\n  items: T[]\n  page: number\n  pageSize: number\n  total: number\n  meta?: QueryResultMeta\n  /**\n   * Custom-field definitions the engine resolved while building this result\n   * (only present when `includeCustomFields: true`). Lets the CRUD factory\n   * decorate list rows without reloading definitions from the DB (issue #2133).\n   * Internal contract \u2014 additive and optional; callers must treat absence as a\n   * cue to load definitions themselves.\n   */\n  customFieldDefinitions?: ResolvedCustomFieldDefinitions\n}\n\nexport interface QueryEngine {\n  query<T = any>(entity: EntityId, opts?: QueryOptions): Promise<QueryResult<T>>\n}\n"],
+  "sourcesContent": ["import type { EntityId } from '@open-mercato/shared/modules/entities'\nimport type { Profiler } from '../profiler'\nimport type { ResolvedCustomFieldDefinitions } from '../crud/custom-field-definition-index'\n\nexport type FilterOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'like' | 'ilike' | 'exists'\n\nexport enum SortDir {\n  Asc = 'asc',\n  Desc = 'desc',\n}\n\nexport type FieldSelector = string // base field or custom field key (prefixed with 'cf:')\n\nexport type Filter = {\n  field: FieldSelector\n  op: FilterOp\n  value?: any\n}\n\nexport type Sort = { field: FieldSelector; dir?: SortDir }\n\nexport type Page = { page?: number; pageSize?: number }\n\n// Mongo/Medusa-style filter operators (typed)\nexport type WhereOps<T> = {\n  $eq?: T\n  $ne?: T | null\n  $gt?: T extends number | Date ? T : never\n  $gte?: T extends number | Date ? T : never\n  $lt?: T extends number | Date ? T : never\n  $lte?: T extends number | Date ? T : never\n  $in?: T[]\n  $nin?: T[]\n  $like?: T extends string ? string : never\n  $ilike?: T extends string ? string : never\n  $exists?: boolean\n}\n\n// A field filter can be a direct value (equals) or ops object\nexport type WhereValue<T = any> = T | WhereOps<T>\n\n// Generic shape for object filters. If you have a typed map of field\u2192type,\n// pass it as the generic to get end-to-end typing.\n// Example: Where<{\n//   id: string; title: string; created_at: Date; 'cf:severity': number\n// }>\nexport type Where<Fields extends Record<string, any> = Record<string, any>> =\n  Partial<{ [K in keyof Fields]: WhereValue<Fields[K]> }> & Record<string, WhereValue>\n\nexport type QueryCustomFieldJoin = {\n  fromField: string\n  toField: string\n  type?: 'left' | 'inner'\n}\n\nexport type QueryCustomFieldSource = {\n  entityId: EntityId\n  table?: string\n  alias?: string\n  recordIdColumn?: string\n  join?: QueryCustomFieldJoin\n  tenantField?: string\n  organizationField?: string\n}\n\nexport type QueryJoinEdge = {\n  alias: string\n  table?: string\n  entityId?: EntityId\n  from: {\n    alias?: string\n    field: string\n  }\n  to: {\n    field: string\n  }\n  type?: 'left' | 'inner'\n}\n\n/**\n * Optional context for query-level UMES extensions.\n * When provided, the query engine will execute sync lifecycle events\n * (querying/queried) and apply query-enabled enrichers.\n */\nexport type QueryExtensionsConfig = {\n  userId?: string\n  container?: unknown\n  userFeatures?: string[]\n  resolve?: <T = unknown>(name: string) => T\n}\n\nexport type QueryOptions = {\n  fields?: FieldSelector[] // base fields and/or 'cf:<key>' for custom fields\n  includeExtensions?: boolean | string[] // include all registered extensions or only specific ones by entity id\n  includeCustomFields?: boolean | string[] // include all CFs or specific keys\n  // Accept classic array syntax or Mongo-style object syntax\n  filters?: Filter[] | Where\n  sort?: Sort[]\n  page?: Page\n  organizationId?: string // enforce multi-tenant scope\n  tenantId?: string // enforce tenant scope\n  // Optional list of organization ids to scope results. Takes precedence over organizationId.\n  organizationIds?: string[]\n  /**\n   * When true, the engine does not apply default `organization_id` / `tenant_id` equality guards.\n   *\n   * Callers MUST encode full visibility in `filters` (for example with `$or` of scoped branches)\n   * and MUST fail closed when the authenticated principal lacks a resolvable tenant/org, otherwise\n   * queries return cross-tenant rows.\n   *\n   * When this flag is set, the hybrid query engine delegates to the basic engine. The basic engine\n   * still applies `cf:*` filters/sorts, but `search_tokens` fulltext filtering, the JSONB index read\n   * path, and the vector-search branch are BYPASSED. Only use this on entities whose scoping does\n   * not match the standard `organization_id = X AND tenant_id = Y` shape.\n   */\n  omitAutomaticTenantOrgScope?: boolean\n  // Soft-delete behavior: when false (default), rows with non-null deleted_at\n  // are excluded if the base table has that column. Set true to include them.\n  withDeleted?: boolean\n  customFieldSources?: QueryCustomFieldSource[]\n  joins?: QueryJoinEdge[]\n  profiler?: Profiler\n  // When true, suppress automatic reindex scheduling triggered by coverage gap detection.\n  // Used by the search indexing pipeline to prevent feedback loops where indexing triggers\n  // re-indexing indefinitely.\n  skipAutoReindex?: boolean\n  /**\n   * Force routing this query to custom-entity doc storage (`custom_entities_storage`)\n   * instead of classifying the entity automatically. Automatic classification routes\n   * ids backed by a registered ORM table to that base table, so surfaces that manage\n   * doc records for ids that are ALSO table-backed (e.g. the entities records browser\n   * reading a module-declared custom entity such as `example:todo`) must set this flag.\n   * Honored by the hybrid query engine only; `BasicQueryEngine` has no doc-storage\n   * reader and ignores it.\n   */\n  forceCustomEntityStorage?: boolean\n  // Optional UMES query extensions context. When provided, the engine will\n  // emit sync lifecycle events and apply query-level enrichers.\n  extensions?: QueryExtensionsConfig\n}\n\nexport type PartialIndexWarning = {\n  entity: EntityId\n  entityLabel?: string | null\n  baseCount?: number | null\n  indexedCount?: number | null\n  scope?: 'scoped' | 'global'\n}\n\nexport type EncryptedSortRowCapWarning = {\n  entity: EntityId\n  sortFields: string[]\n  maxRows: number\n  /**\n   * Exact when `meta.listCountCapWarning` is absent; a floor when it is\n   * present (the list total itself was bounded at the cap).\n   */\n  totalMatched: number\n}\n\n/**\n * Present when the list COUNT was bounded at `cap` matching rows\n * (`OM_LIST_COUNT_CAP`): `total` is a floor, not an exact value. Surfaced on\n * CRUD list payloads as `totalIsCapped: true`.\n */\nexport type ListCountCapWarning = {\n  entity: EntityId\n  cap: number\n}\n\nexport type QueryResultMeta = {\n  partialIndexWarning?: PartialIndexWarning\n  encryptedSortRowCapWarning?: EncryptedSortRowCapWarning\n  listCountCapWarning?: ListCountCapWarning\n}\n\nexport type QueryResult<T = any> = {\n  items: T[]\n  page: number\n  pageSize: number\n  total: number\n  meta?: QueryResultMeta\n  /**\n   * Custom-field definitions the engine resolved while building this result\n   * (only present when `includeCustomFields: true`). Lets the CRUD factory\n   * decorate list rows without reloading definitions from the DB (issue #2133).\n   * Internal contract \u2014 additive and optional; callers must treat absence as a\n   * cue to load definitions themselves.\n   */\n  customFieldDefinitions?: ResolvedCustomFieldDefinitions\n}\n\nexport interface QueryEngine {\n  query<T = any>(entity: EntityId, opts?: QueryOptions): Promise<QueryResult<T>>\n}\n"],
   "mappings": "AAMO,IAAK,UAAL,kBAAKA,aAAL;AACL,EAAAA,SAAA,SAAM;AACN,EAAAA,SAAA,UAAO;AAFG,SAAAA;AAAA,GAAA;",
   "names": ["SortDir"]
 }

package/dist/lib/version.js

@@ -1,4 +1,4 @@
-const APP_VERSION = "0.6.8-develop.7030.1.b84302d973";
+const APP_VERSION = "0.6.8-develop.7032.1.70d74d4bfe";
 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.7030.1.b84302d973';\nexport const appVersion = APP_VERSION;\n"],
+  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.6.8-develop.7032.1.70d74d4bfe';\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.7030.1.b84302d973",
+  "version": "0.6.8-develop.7032.1.70d74d4bfe",
   "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.7030.1.b84302d973",
+    "@open-mercato/cache": "0.6.8-develop.7032.1.70d74d4bfe",
     "@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

@@ -268,6 +268,28 @@ describe('CRUD Factory', () => {
     }))
   })
 
+  it('GET spreads totalIsCapped only when the engine reports a capped count', async () => {
+    queryEngine.query.mockResolvedValueOnce({
+      items: [{ id: 'id-1', title: 'A', is_done: false }],
+      total: 10_000,
+      page: 1,
+      pageSize: 10,
+      meta: { listCountCapWarning: { entity: 'example.todo', cap: 10_000 } },
+    })
+    const res = await route.GET(new Request('http://x/api/example/todos?page=1&pageSize=10&sortField=id&sortDir=asc'))
+    expect(res.status).toBe(200)
+    const body = await res.json()
+    expect(body.total).toBe(10_000)
+    expect(body.totalIsCapped).toBe(true)
+    expect(body.meta.listCountCapWarning).toEqual({ entity: 'example.todo', cap: 10_000 })
+  })
+
+  it('GET omits totalIsCapped entirely for exact totals', async () => {
+    const res = await route.GET(new Request('http://x/api/example/todos?page=1&pageSize=10&sortField=id&sortDir=asc'))
+    const body = await res.json()
+    expect('totalIsCapped' in body).toBe(false)
+  })
+
   const makeDecoratedRoute = () => makeCrudRoute({
     metadata: { GET: { requireAuth: true } },
     orm: { entity: Todo, idField: 'id', orgField: 'organizationId', tenantField: 'tenantId', softDeleteField: 'deletedAt' },

package/src/lib/crud/factory.ts

@@ -1941,6 +1941,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
           page: page.page || requestedPage,
           pageSize: page.pageSize || requestedPageSize,
           totalPages: Math.ceil(res.total / (Number(page.pageSize) || 1)),
+          ...(res.meta?.listCountCapWarning ? { totalIsCapped: true } : {}),
           ...(res.meta ? { meta: res.meta } : {}),
         }
         await opts.hooks?.afterList?.(payload, { ...ctx, query: validated as any })

package/src/lib/openapi/crud.ts

@@ -17,6 +17,9 @@ export function createPagedListResponseSchema(itemSchema: ZodTypeAny, options: P
     page: paginationMetaOptional ? z.number().optional() : z.number(),
     pageSize: paginationMetaOptional ? z.number().optional() : z.number(),
     totalPages: z.number(),
+    // Present (true) only when the list count was bounded at OM_LIST_COUNT_CAP:
+    // `total` is then a floor, not an exact value.
+    totalIsCapped: z.boolean().optional(),
   })
 }
 

package/src/lib/query/__tests__/count-cap-plan.test.ts

@@ -0,0 +1,240 @@
+/**
+ * Plan-level guard for the capped list COUNT (#4552 Phase 2), run against a real
+ * PostgreSQL. This is the only test that fails if a future refactor reintroduces
+ * a blocking node (Aggregate/Sort/Unique) between the probe `Limit` and the base
+ * scan — a mocked total cannot catch a bound that does not bind. It doubles as
+ * the count-parity check: with the cap disabled, the rebuilt count must equal
+ * ground truth across the cf-filter / or-group / plain matrices.
+ *
+ * Gated on OM_COUNT_CAP_PG_URL (a throwaway database — the suite creates and
+ * drops its own tables). Example:
+ *   docker run --rm -d -p 54329:5432 -e POSTGRES_PASSWORD=t postgres:16
+ *   OM_COUNT_CAP_PG_URL=postgres://postgres:t@localhost:54329/postgres yarn jest count-cap-plan
+ */
+import { Kysely, PostgresDialect, sql } from 'kysely'
+import { BasicQueryEngine } from '../engine'
+
+const PG_URL = process.env.OM_COUNT_CAP_PG_URL
+const maybe = PG_URL ? describe : describe.skip
+
+const TENANT = '11111111-1111-4111-8111-111111111111'
+const ORG = '22222222-2222-4222-8222-222222222222'
+const ENTITY = 'capcheck:om_capcheck_order'
+const TABLE = 'om_capcheck_orders'
+const ROWS = 120
+const RED_ROWS = 30
+
+maybe('capped list COUNT against PostgreSQL', () => {
+  jest.setTimeout(60_000)
+  let db: Kysely<any>
+  let sqlLog: string[] = []
+  let paramLog: unknown[][] = []
+  const originalCap = process.env.OM_LIST_COUNT_CAP
+
+  beforeAll(async () => {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { Pool } = require('pg')
+    db = new Kysely<any>({
+      dialect: new PostgresDialect({ pool: new Pool({ connectionString: PG_URL }) }),
+      log(event) {
+        if (event.level === 'query' || event.level === 'error') {
+          sqlLog.push(event.query.sql)
+          paramLog.push([...event.query.parameters])
+        }
+      },
+    })
+    await sql`drop table if exists om_capcheck_orders`.execute(db)
+    await sql`create table om_capcheck_orders (
+      id uuid primary key,
+      tenant_id uuid not null,
+      organization_id uuid not null,
+      deleted_at timestamptz,
+      status text not null
+    )`.execute(db)
+    await sql`create table if not exists custom_field_defs (
+      id serial primary key,
+      key text not null,
+      entity_id text not null,
+      kind text,
+      config_json jsonb,
+      is_active boolean not null default true,
+      organization_id uuid,
+      tenant_id uuid,
+      updated_at timestamptz,
+      deleted_at timestamptz
+    )`.execute(db)
+    await sql`create table if not exists custom_field_values (
+      id serial primary key,
+      entity_id text not null,
+      field_key text not null,
+      record_id text not null,
+      value_text text,
+      value_multiline text,
+      value_int int,
+      value_float float,
+      value_bool boolean,
+      organization_id uuid,
+      tenant_id uuid
+    )`.execute(db)
+    await sql`delete from custom_field_defs where entity_id = ${ENTITY}`.execute(db)
+    await sql`delete from custom_field_values where entity_id = ${ENTITY}`.execute(db)
+    await sql`insert into custom_field_defs (key, entity_id, kind, is_active, tenant_id)
+      values ('color', ${ENTITY}, 'text', true, null)`.execute(db)
+    for (let i = 0; i < ROWS; i++) {
+      const id = `33333333-3333-4333-8333-${String(i).padStart(12, '0')}`
+      await sql`insert into om_capcheck_orders (id, tenant_id, organization_id, deleted_at, status)
+        values (${id}::uuid, ${TENANT}::uuid, ${ORG}::uuid, null, ${i % 2 === 0 ? 'open' : 'closed'})`.execute(db)
+      if (i < RED_ROWS) {
+        await sql`insert into custom_field_values (entity_id, field_key, record_id, value_text, tenant_id)
+          values (${ENTITY}, 'color', ${id}, 'red', ${TENANT}::uuid)`.execute(db)
+      }
+    }
+  })
+
+  afterAll(async () => {
+    await sql`drop table if exists om_capcheck_orders`.execute(db)
+    await sql`delete from custom_field_defs where entity_id = ${ENTITY}`.execute(db)
+    await sql`delete from custom_field_values where entity_id = ${ENTITY}`.execute(db)
+    await db.destroy()
+  })
+
+  afterEach(() => {
+    if (originalCap === undefined) delete process.env.OM_LIST_COUNT_CAP
+    else process.env.OM_LIST_COUNT_CAP = originalCap
+  })
+
+  const makeEngine = () => new BasicQueryEngine({} as any, () => db as any)
+  const baseOpts = {
+    tenantId: TENANT,
+    organizationId: ORG,
+    fields: ['id'],
+    page: { page: 1, pageSize: 10 },
+  }
+
+  function lastCountSql(): { text: string; params: unknown[] } {
+    for (let i = sqlLog.length - 1; i >= 0; i--) {
+      if (/count\(\*\)/i.test(sqlLog[i])) return { text: sqlLog[i], params: paramLog[i] }
+    }
+    throw new Error('no count SQL captured')
+  }
+
+  function collectNodes(node: any, out: any[] = []): any[] {
+    if (!node) return out
+    out.push(node)
+    for (const child of node.Plans ?? []) collectNodes(child, out)
+    return out
+  }
+
+  test('probe plan: no blocking node between the Limit and the base scan (cf-filtered)', async () => {
+    process.env.OM_LIST_COUNT_CAP = '50'
+    sqlLog = []; paramLog = []
+    const result = await makeEngine().query(ENTITY, {
+      ...baseOpts,
+      filters: { status: { $eq: 'open' } },
+    })
+    expect(result.total).toBe(50)
+    expect(result.meta?.listCountCapWarning).toEqual({ entity: ENTITY, cap: 50 })
+
+    const { text, params } = lastCountSql()
+    expect(text.toLowerCase()).toContain('limit')
+    const explained = await sql
+      .raw(`explain (format json) ${text.replace(/\$(\d+)/g, (_, n) => {
+        const value = params[Number(n) - 1]
+        return typeof value === 'number' ? String(value) : `'${String(value).replace(/'/g, "''")}'`
+      })}`)
+      .execute(db)
+    const plan = (explained.rows[0] as any)['QUERY PLAN'][0].Plan
+    const all = collectNodes(plan)
+    const limitNode = all.find((n) => n['Node Type'] === 'Limit')
+    expect(limitNode).toBeTruthy()
+    // Below the Limit: only row-producing nodes down to the scan. An Aggregate,
+    // Sort, or Unique here means the bound does not bind.
+    const belowLimit = collectNodes(limitNode).slice(1)
+    const blocking = belowLimit.filter((n) => /Aggregate|Sort|Unique/.test(String(n['Node Type'])))
+    expect(blocking).toEqual([])
+    // The base scan is inside the Limit subtree.
+    expect(belowLimit.some((n) => n['Relation Name'] === TABLE)).toBe(true)
+  })
+
+  test('cf filter compiles to EXISTS and stays cappable', async () => {
+    process.env.OM_LIST_COUNT_CAP = '10'
+    sqlLog = []; paramLog = []
+    const result = await makeEngine().query(ENTITY, {
+      ...baseOpts,
+      filters: { cf_color: { $eq: 'red' } },
+    })
+    expect(result.total).toBe(10)
+    expect(result.meta?.listCountCapWarning).toEqual({ entity: ENTITY, cap: 10 })
+    const { text } = lastCountSql()
+    expect(text.toLowerCase()).toContain('exists')
+    expect(text.toLowerCase()).not.toContain('group by')
+  })
+
+  test('parity with the cap disabled: rebuilt count matches the display query across the filter matrix', async () => {
+    process.env.OM_LIST_COUNT_CAP = '0'
+    const engine = makeEngine()
+    const wide = { page: { page: 1, pageSize: 1000 } }
+
+    // Each case asserts the rebuilt count against ground truth where the filter
+    // semantics are well-defined, and always against the display query's own
+    // row set — the regression guard for "count rebuild changing a total".
+    const expectParity = async (filters: any, expectedTotal?: number) => {
+      const result = await engine.query(ENTITY, { ...baseOpts, ...wide, filters })
+      expect(result.total).toBe(result.items.length)
+      if (expectedTotal !== undefined) expect(result.total).toBe(expectedTotal)
+      expect(result.meta?.listCountCapWarning).toBeUndefined()
+      return result
+    }
+
+    await expectParity(undefined, ROWS)
+    await expectParity({ status: { $eq: 'open' } }, ROWS / 2)
+    await expectParity({ cf_color: { $eq: 'red' } }, RED_ROWS)
+    await expectParity({ $and: [{ status: { $eq: 'open' } }, { cf_color: { $eq: 'red' } }] }, RED_ROWS / 2)
+    // Base-column-only $or exercises the or-group path in the count shape.
+    await expectParity({ $or: [{ status: { $eq: 'open' } }, { status: { $eq: 'closed' } }] }, ROWS)
+    // Mixed base + cf disjunction (#5039): the count shape must compile the cf
+    // leaf to an EXISTS rather than dropping it — a dropped leaf narrows the OR
+    // and undercounts. closed (60) ∪ red (30, half of which are closed) = 75.
+    await expectParity({ $or: [{ status: { $eq: 'closed' } }, { cf_color: { $eq: 'red' } }] }, ROWS / 2 + RED_ROWS / 2)
+    // cf-only disjunction: red (30) ∪ blue (0) = 30.
+    await expectParity({ $or: [{ cf_color: { $eq: 'red' } }, { cf_color: { $eq: 'blue' } }] }, RED_ROWS)
+    await expectParity({ cf_color: { $eq: 'blue' } }, 0)
+    await expectParity({ cf_color: { $eq: null } }, ROWS - RED_ROWS)
+    await expectParity({ cf_color: { $ne: 'red' } }, 0)
+    await expectParity({ cf_color: { $in: ['red', 'blue'] } }, RED_ROWS)
+  })
+
+  test('kill switch (cap=0): the cf-filtered count still plans set-oriented, not per-row', async () => {
+    // OM_LIST_COUNT_CAP=0 restores exact totals but runs them through the
+    // rebuilt shape. The documented escape hatch must not be slower than the
+    // problem: the uncapped EXISTS should plan as a semi-join or a hashed
+    // subplan, never an un-hashed per-row subplan re-executed for every row.
+    process.env.OM_LIST_COUNT_CAP = '0'
+    sqlLog = []; paramLog = []
+    const result = await makeEngine().query(ENTITY, {
+      ...baseOpts,
+      filters: { cf_color: { $eq: 'red' } },
+    })
+    expect(result.total).toBe(RED_ROWS)
+
+    const { text, params } = lastCountSql()
+    const explained = await sql
+      .raw(`explain (format json) ${text.replace(/\$(\d+)/g, (_, n) => {
+        const value = params[Number(n) - 1]
+        return typeof value === 'number' ? String(value) : `'${String(value).replace(/'/g, "''")}'`
+      })}`)
+      .execute(db)
+    const plan = (explained.rows[0] as any)['QUERY PLAN'][0].Plan
+    const all = collectNodes(plan)
+    const semiJoin = all.some((n) => /Semi/.test(String(n['Join Type'] ?? '')))
+    const hashedSubplan = all.some((n) => /hashed/i.test(String(n['Subplan Name'] ?? '')))
+    expect(semiJoin || hashedSubplan).toBe(true)
+  })
+
+  test('sub-cap totals stay exact with the cap active', async () => {
+    process.env.OM_LIST_COUNT_CAP = '1000'
+    const result = await makeEngine().query(ENTITY, { ...baseOpts, filters: { cf_color: { $eq: 'red' } } })
+    expect(result.total).toBe(RED_ROWS)
+    expect(result.meta?.listCountCapWarning).toBeUndefined()
+  })
+})

package/src/lib/query/__tests__/count-cap.test.ts

@@ -0,0 +1,41 @@
+import { resolveListCountCap, DEFAULT_LIST_COUNT_CAP } from '../count-cap'
+
+describe('resolveListCountCap', () => {
+  const original = process.env.OM_LIST_COUNT_CAP
+  afterEach(() => {
+    if (original === undefined) delete process.env.OM_LIST_COUNT_CAP
+    else process.env.OM_LIST_COUNT_CAP = original
+  })
+
+  test('unset: the default cap — the cap is on by default', () => {
+    delete process.env.OM_LIST_COUNT_CAP
+    expect(resolveListCountCap()).toBe(DEFAULT_LIST_COUNT_CAP)
+  })
+
+  test('blank: the default cap', () => {
+    process.env.OM_LIST_COUNT_CAP = '  '
+    expect(resolveListCountCap()).toBe(DEFAULT_LIST_COUNT_CAP)
+  })
+
+  test('0 disables capping', () => {
+    process.env.OM_LIST_COUNT_CAP = '0'
+    expect(resolveListCountCap()).toBeNull()
+  })
+
+  test('negative values disable capping like 0', () => {
+    process.env.OM_LIST_COUNT_CAP = '-5'
+    expect(resolveListCountCap()).toBeNull()
+  })
+
+  test('a positive integer is used as-is; floats floor', () => {
+    process.env.OM_LIST_COUNT_CAP = '500'
+    expect(resolveListCountCap()).toBe(500)
+    process.env.OM_LIST_COUNT_CAP = '500.9'
+    expect(resolveListCountCap()).toBe(500)
+  })
+
+  test('unparseable input falls back to the default — bad input must not silently disable the cap', () => {
+    process.env.OM_LIST_COUNT_CAP = 'unbounded'
+    expect(resolveListCountCap()).toBe(DEFAULT_LIST_COUNT_CAP)
+  })
+})

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

@@ -139,6 +139,22 @@ function createFakeKysely(selectsSink: any[], 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,
@@ -173,8 +189,28 @@ function findCountSql(selectsSink: any[]): string {
   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 () => {
+// The count query is rebuilt from scope + filters only (#4552 Phase 2): cf
+// filters compile to correlated EXISTS semi-joins, projection joins are
+// dropped, so the count never needs DISTINCT or GROUP BY — completing the
+// direction #2227 started — and the LIMIT cap+1 probe actually bounds the scan.
+describe('BasicQueryEngine — rebuilt list COUNT query (#4552 Phase 2)', () => {
+  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
+  })
+
+  // The count-shape builder is the base-table call carrying the probe LIMIT
+  // (cap + 1); with the cap disabled it is the base call whose recorded select
+  // is the bare count aggregate.
+  function findCountShapeCall(fakeDb: any, table: string) {
+    const baseCalls = fakeDb._calls.filter((b: any) => b._ops.table === table)
+    const probed = baseCalls.find((b: any) => b._ops.limits === 10_001)
+    if (probed) return probed
+    return baseCalls.find((b: any) => b._ops.selects.some((s: any) => aliasName(s) === 'count'))
+  }
+
+  test('uses count(*) with no DISTINCT and no GROUP BY when nothing joins', async () => {
     const selects: any[] = []
     const fakeDb = createFakeKysely(selects)
     const engine = new BasicQueryEngine({} as any, () => fakeDb as any)
@@ -184,11 +220,11 @@ describe('BasicQueryEngine — list COUNT query (issue #2227)', () => {
     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)
+    const countCall = findCountShapeCall(fakeDb, 'scheduled_jobs')
+    expect(countCall._ops.groups.length).toBe(0)
   })
 
-  test('keeps count(distinct base.id) with group-by when extensions are joined', async () => {
+  test('drops extension projection joins from the count: count(*) over the bare base table', async () => {
     const selects: any[] = []
     const fakeDb = createFakeKysely(selects)
     const engine = new BasicQueryEngine({} as any, () => fakeDb as any)
@@ -201,14 +237,20 @@ describe('BasicQueryEngine — list COUNT query (issue #2227)', () => {
     })
 
     const countSql = findCountSql(selects)
-    expect(countSql).toContain('count(distinct')
-    expect(countSql).not.toContain('count(*)')
+    expect(countSql).toContain('count(*)')
+    expect(countSql).not.toContain('distinct')
 
-    const baseCall = fakeDb._calls.find((b: any) => b._ops.table === 'users')
-    expect(baseCall._ops.groups.length).toBeGreaterThan(0)
+    // The display query keeps the extension join + GROUP BY …
+    const dataCall = fakeDb._calls.find((b: any) => b._ops.table === 'users' && b._ops.joins.length > 0)
+    expect(dataCall._ops.groups.length).toBeGreaterThan(0)
+    // … while the count shape carries neither: no join can multiply base rows,
+    // so no barrier sits between the probe LIMIT and the scan.
+    const countCall = findCountShapeCall(fakeDb, 'users')
+    expect(countCall._ops.joins.length).toBe(0)
+    expect(countCall._ops.groups.length).toBe(0)
   })
 
-  test('keeps count(distinct base.id) without group-by when an explicit relation join is configured', async () => {
+  test('explicit relation joins never reach the count: count(*), join filters stay EXISTS', async () => {
     const selects: any[] = []
     const fakeDb = createFakeKysely(selects)
     const engine = new BasicQueryEngine({} as any, () => fakeDb as any)
@@ -216,14 +258,112 @@ describe('BasicQueryEngine — list COUNT query (issue #2227)', () => {
       tenantId: 't1',
       fields: ['id'],
       joins: [{ alias: 'owner', table: 'users', from: { field: 'owner_id' }, to: { field: 'id' } }],
+      filters: { 'owner.email': { $eq: 'a@b.c' } },
+      page: { page: 1, pageSize: 20 },
+    })
+
+    const countSql = findCountSql(selects)
+    expect(countSql).toContain('count(*)')
+    expect(countSql).not.toContain('distinct')
+
+    const countCall = findCountShapeCall(fakeDb, 'scheduled_jobs')
+    expect(countCall._ops.groups.length).toBe(0)
+    expect(countCall._ops.joins.length).toBe(0)
+    // The join filter is a semi-join on the count shape, not a join.
+    expect(countCall._ops.wheres.some((w: any) => Array.isArray(w) && w[0] === 'exists')).toBe(true)
+  })
+
+  test('cf filters compile to EXISTS over custom_field_values on the count shape', async () => {
+    const selects: any[] = []
+    const fakeDb = createFakeKysely(selects, {
+      custom_field_defs: [
+        { key: 'color', entity_id: 'scheduler:scheduled_job', is_active: true, tenant_id: null, kind: 'text', config_json: '{}' },
+      ],
+    })
+    const engine = new BasicQueryEngine({} as any, () => fakeDb as any)
+    await engine.query('scheduler:scheduled_job', {
+      tenantId: 't1',
+      fields: ['id'],
+      filters: { cf_color: { $eq: 'red' } },
+      page: { page: 1, pageSize: 20 },
+    })
+
+    const countSql = findCountSql(selects)
+    expect(countSql).toContain('count(*)')
+    expect(countSql).not.toContain('distinct')
+
+    const countCall = findCountShapeCall(fakeDb, 'scheduled_jobs')
+    expect(countCall._ops.groups.length).toBe(0)
+    // No custom_field_values join on the count shape — the filter is an EXISTS
+    // whose subquery selects from custom_field_values.
+    expect(countCall._ops.joins.length).toBe(0)
+    const existsEntries = countCall._ops.wheres.filter((w: any) => Array.isArray(w) && w[0] === 'exists')
+    expect(existsEntries.length).toBeGreaterThan(0)
+    const existsSub = existsEntries[0][1]
+    expect(existsSub._ops.table).toBe('custom_field_values')
+    // The display query still resolves the same filter through its value join.
+    const dataCall = fakeDb._calls.find((b: any) =>
+      b._ops.table === 'scheduled_jobs' &&
+      b._ops.joins.some((j: any) => Object.values(j.aliasObj).includes('custom_field_values')))
+    expect(dataCall).toBeTruthy()
+  })
+
+  test('a cf leaf inside $or compiles to EXISTS on the count shape instead of being dropped (#5039)', async () => {
+    const selects: any[] = []
+    const fakeDb = createFakeKysely(selects, {
+      custom_field_defs: [
+        { key: 'color', entity_id: 'scheduler:scheduled_job', is_active: true, tenant_id: null, kind: 'text', config_json: '{}' },
+      ],
+      'information_schema.columns': [
+        { table_name: 'scheduled_jobs', column_name: 'id' },
+        { table_name: 'scheduled_jobs', column_name: 'tenant_id' },
+        { table_name: 'scheduled_jobs', column_name: 'status' },
+      ],
+    })
+    const engine = new BasicQueryEngine({} as any, () => fakeDb as any)
+    await engine.query('scheduler:scheduled_job', {
+      tenantId: 't1',
+      fields: ['id'],
+      filters: { $or: [{ status: { $eq: 'closed' } }, { cf_color: { $eq: 'red' } }] },
       page: { page: 1, pageSize: 20 },
     })
 
+    const countCall = findCountShapeCall(fakeDb, 'scheduled_jobs')
+    expect(countCall._ops.joins.length).toBe(0)
+    // The whole disjunction lands in one OR where-entry whose parts include an
+    // EXISTS (the cf leaf) — dropping it would narrow the OR and undercount.
+    const orEntries = countCall._ops.wheres.filter((w: any) => Array.isArray(w) && w[0] === 'or')
+    expect(orEntries.length).toBeGreaterThan(0)
+    const hasExistsPart = orEntries.some((entry: any) =>
+      (entry[1] ?? []).some((part: any) => part?.kind === 'exists' || (part?.kind === 'and' && part.parts?.some((p: any) => p?.kind === 'exists'))))
+    expect(hasExistsPart).toBe(true)
+  })
+
+  test('the probe LIMIT is cap + 1 on the row-producing inner query, counted by an outer aggregate', async () => {
+    process.env.OM_LIST_COUNT_CAP = '100'
+    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 outer = fakeDb._calls.find((b: any) => b._ops.table === '__subquery__')
+    expect(outer).toBeTruthy()
+    expect(outer._ops.subquery.limits).toBe(101)
+    expect(outer._ops.subquery.groups.length).toBe(0)
     const countSql = findCountSql(selects)
-    expect(countSql).toContain('count(distinct')
-    expect(countSql).not.toContain('count(*)')
+    expect(countSql).toContain('count(*)')
+  })
 
-    const baseCall = fakeDb._calls.find((b: any) => b._ops.table === 'scheduled_jobs')
-    expect(baseCall._ops.groups.length).toBe(0)
+  test('OM_LIST_COUNT_CAP=0 disables the probe: a direct unbounded count(*)', async () => {
+    process.env.OM_LIST_COUNT_CAP = '0'
+    const selects: any[] = []
+    const fakeDb = createFakeKysely(selects)
+    const engine = new BasicQueryEngine({} as any, () => fakeDb as any)
+    const result = await engine.query('scheduler:scheduled_job', { tenantId: 't1', fields: ['id'], page: { page: 1, pageSize: 20 } })
+
+    expect(fakeDb._calls.some((b: any) => b._ops.table === '__subquery__')).toBe(false)
+    const countSql = findCountSql(selects)
+    expect(countSql).toContain('count(*)')
+    expect(result.meta?.listCountCapWarning).toBeUndefined()
   })
 })