@open-mercato/shared 0.10.1-develop.7576.1.21d5b50435 → 0.10.1-develop.7577.1.477f2486e5

package/src/lib/openapi/generator.ts

@@ -15,6 +15,12 @@ type PathParamInfo = {
   optional?: boolean
 }
 
+type PathVariant = {
+  path: string
+  params: PathParamInfo[]
+  omittedParam?: string
+}
+
 type ParameterLocation = 'query' | 'path' | 'header'
 
 export type JsonSchema = Record<string, unknown>
@@ -119,6 +125,20 @@ function normalizePath(path: string): { path: string; params: PathParamInfo[] }
   return { path: '/' + normalized, params }
 }
 
+function expandOptionalPathParams(normalized: { path: string; params: PathParamInfo[] }): PathVariant[] {
+  const required = normalized.params.filter((param) => !param.optional)
+  const optionalParam = normalized.params.find((param) => param.optional)
+  const fullVariant: PathVariant = {
+    path: normalized.path,
+    params: normalized.params.map((param) => ({ ...param, optional: false })),
+  }
+  if (!optionalParam) return [fullVariant]
+  const placeholder = `/{${optionalParam.name}}`
+  if (!normalized.path.endsWith(placeholder)) return [fullVariant]
+  const basePath = normalized.path.slice(0, -placeholder.length) || '/'
+  return [fullVariant, { path: basePath, params: required, omittedParam: optionalParam.name }]
+}
+
 function unwrap(schema?: ZodTypeAny): {
   schema: ZodTypeAny | undefined
   optional: boolean
@@ -681,14 +701,14 @@ function buildParameters(
 
   if (location === 'path' && pathParamNames && pathParamNames.length) {
     const merged = mergePathParamSchemas(schema, pathParamNames)
-    for (const { name, schema: paramSchema, optional } of merged) {
+    for (const { name, schema: paramSchema } of merged) {
       const jsonSchema = zodToJsonSchema(paramSchema)
       const example = generateExample(paramSchema)
       const description = extractZodDescription(paramSchema)
       params.push({
         name,
         in: 'path',
-        required: !optional,
+        required: true,
         schema: jsonSchema ?? { type: 'string' },
         example,
         ...(description ? { description } : {}),
@@ -738,7 +758,7 @@ function buildParameters(
 }
 
 function mergePathParamSchemas(schema: ZodTypeAny | undefined, params: PathParamInfo[]) {
-  const merged: Array<{ name: string; schema: ZodTypeAny | undefined; optional: boolean }> = []
+  const merged: Array<{ name: string; schema: ZodTypeAny | undefined }> = []
   const map: Record<string, ZodTypeAny> = {}
   if (schema) {
     const { schema: unwrapped } = unwrap(schema)
@@ -753,7 +773,6 @@ function mergePathParamSchemas(schema: ZodTypeAny | undefined, params: PathParam
     merged.push({
       name: param.name,
       schema: map[param.name],
-      optional: !!param.optional,
     })
   }
   return merged
@@ -1051,6 +1070,7 @@ export function buildOpenApiDocument(modules: Module[], options: OpenApiDocument
 
   const includeAccessControlMetadata = options.includeAccessControlMetadata !== false
   const tags = new Map<string, string | undefined>()
+  const derivedOperations = new Set<string>()
 
   for (const moduleEntry of modules) {
     const defaultTag = moduleEntry.info?.title ?? toTitle(moduleEntry.id)
@@ -1060,85 +1080,94 @@ export function buildOpenApiDocument(modules: Module[], options: OpenApiDocument
     for (const api of apis) {
       const routeDoc = collectRouteDoc(api, moduleEntry.id)
       const moduleTag = routeDoc?.tag ?? defaultTag
-      const normalized = normalizePath((api as any).path ?? (api as any).path ?? '')
-      const pathKey = normalized.path
-      if (!doc.paths[pathKey]) doc.paths[pathKey] = {}
       const availableMethods: HttpMethod[] =
         'handlers' in api
           ? HTTP_METHODS.filter((method) => typeof (api as ModuleApiRouteFile).handlers?.[method] === 'function')
           : [api.method as HttpMethod]
 
-      for (const method of availableMethods) {
-        const methodLower = method.toLowerCase() as Lowercase<HttpMethod>
-        const existing = doc.paths[pathKey][methodLower]
-        if (existing) continue
-
-        const metadata = 'handlers' in api ? (api as ModuleApiRouteFile).metadata?.[method] : undefined
-        const methodDoc = routeDoc?.methods?.[method]
-        const summary = methodDoc?.summary ?? routeDoc?.summary ?? `${method} ${pathKey}`
-        const baseDescription = methodDoc?.description ?? routeDoc?.description
-        const meta = metadata && typeof metadata === 'object' ? (metadata as Record<string, unknown>) : undefined
-        const requireFeatures = Array.isArray(meta?.['requireFeatures'])
-          ? (meta!['requireFeatures'] as string[])
-          : undefined
-        const requireRoles = Array.isArray(meta?.['requireRoles'])
-          ? (meta!['requireRoles'] as string[])
-          : undefined
-        const requireAuth = meta?.['requireAuth'] === true
-        const descriptionParts: string[] = []
-        if (baseDescription) descriptionParts.push(baseDescription)
-        if (includeAccessControlMetadata && Array.isArray(requireFeatures) && requireFeatures.length) {
-          descriptionParts.push(`Requires features: ${requireFeatures.join(', ')}`)
-        }
-        if (includeAccessControlMetadata && Array.isArray(requireRoles) && requireRoles.length) {
-          descriptionParts.push(`Requires roles: ${requireRoles.join(', ')}`)
-        }
+      for (const normalized of expandOptionalPathParams(normalizePath((api as any).path ?? ''))) {
+        const pathKey = normalized.path
+        if (!doc.paths[pathKey]) doc.paths[pathKey] = {}
+
+        for (const method of availableMethods) {
+          const methodLower = method.toLowerCase() as Lowercase<HttpMethod>
+          const operationKey = `${methodLower} ${pathKey}`
+          const existing = doc.paths[pathKey][methodLower]
+          if (existing && (normalized.omittedParam || !derivedOperations.has(operationKey))) continue
+          if (normalized.omittedParam) derivedOperations.add(operationKey)
+          else derivedOperations.delete(operationKey)
+
+          const metadata = 'handlers' in api ? (api as ModuleApiRouteFile).metadata?.[method] : undefined
+          const methodDoc = routeDoc?.methods?.[method]
+          const summary = methodDoc?.summary ?? routeDoc?.summary ?? `${method} ${pathKey}`
+          const baseDescription = methodDoc?.description ?? routeDoc?.description
+          const meta = metadata && typeof metadata === 'object' ? (metadata as Record<string, unknown>) : undefined
+          const requireFeatures = Array.isArray(meta?.['requireFeatures'])
+            ? (meta!['requireFeatures'] as string[])
+            : undefined
+          const requireRoles = Array.isArray(meta?.['requireRoles'])
+            ? (meta!['requireRoles'] as string[])
+            : undefined
+          const requireAuth = meta?.['requireAuth'] === true
+          const descriptionParts: string[] = []
+          if (baseDescription) descriptionParts.push(baseDescription)
+          if (includeAccessControlMetadata && Array.isArray(requireFeatures) && requireFeatures.length) {
+            descriptionParts.push(`Requires features: ${requireFeatures.join(', ')}`)
+          }
+          if (includeAccessControlMetadata && Array.isArray(requireRoles) && requireRoles.length) {
+            descriptionParts.push(`Requires roles: ${requireRoles.join(', ')}`)
+          }
 
-        const querySchema = methodDoc?.query
-        const pathSchema = methodDoc?.pathParams ?? routeDoc?.pathParams
-        const headerSchema = methodDoc?.headers
-        const requestBody = methodDoc?.requestBody
-        const examples = collectExamples(querySchema, requestBody?.schema, pathSchema, headerSchema, metadata)
-        const curlSample = buildCurlSample(
-          method,
-          pathKey,
-          normalized.params,
-          examples,
-          options.baseUrlForExamples ?? 'https://api.open-mercato.local',
-          metadata,
-          requestBody
-        )
-
-        doc.paths[pathKey][methodLower] = {
-          operationId: methodDoc?.operationId ?? resolveOperationId(moduleEntry.id, pathKey, method),
-          summary,
-          description: descriptionParts.length ? descriptionParts.join('\n\n') : undefined,
-          tags: methodDoc?.tags ?? (moduleTag ? [moduleTag] : undefined),
-          deprecated: methodDoc?.deprecated,
-          externalDocs: methodDoc?.externalDocs,
-          parameters: [
-            ...buildParameters(pathSchema, 'path', normalized.params),
-            ...buildParameters(querySchema, 'query'),
-            ...buildParameters(headerSchema, 'header'),
-          ].filter(Boolean),
-          requestBody: buildRequestBody(requestBody),
-          responses: buildResponses(method, methodDoc?.responses, methodDoc?.errors, metadata),
-          security: buildSecurity(metadata, methodDoc, options.defaultSecurity),
-          'x-codeSamples': methodDoc?.codeSamples ?? [
-            {
-              lang: 'curl',
-              label: 'cURL',
-              source: curlSample,
-            },
-          ],
-          ...(includeAccessControlMetadata && Array.isArray(requireFeatures) && requireFeatures.length
-            ? { 'x-require-features': requireFeatures }
-            : {}),
-          ...(includeAccessControlMetadata && Array.isArray(requireRoles) && requireRoles.length
-            ? { 'x-require-roles': requireRoles }
-            : {}),
-          ...(requireAuth ? { 'x-require-auth': true } : {}),
-          ...(methodDoc?.extensions ?? {}),
+          const querySchema = methodDoc?.query
+          const pathSchema = methodDoc?.pathParams ?? routeDoc?.pathParams
+          const headerSchema = methodDoc?.headers
+          const requestBody = methodDoc?.requestBody
+          const examples = collectExamples(querySchema, requestBody?.schema, pathSchema, headerSchema, metadata)
+          const curlSample = buildCurlSample(
+            method,
+            pathKey,
+            normalized.params,
+            examples,
+            options.baseUrlForExamples ?? 'https://api.open-mercato.local',
+            metadata,
+            requestBody
+          )
+
+          doc.paths[pathKey][methodLower] = {
+            operationId: methodDoc?.operationId
+              ? normalized.omittedParam
+                ? `${methodDoc.operationId}_without_${normalizeOperationIdSegment(normalized.omittedParam)}`
+                : methodDoc.operationId
+              : resolveOperationId(moduleEntry.id, pathKey, method),
+            summary,
+            description: descriptionParts.length ? descriptionParts.join('\n\n') : undefined,
+            tags: methodDoc?.tags ?? (moduleTag ? [moduleTag] : undefined),
+            deprecated: methodDoc?.deprecated,
+            externalDocs: methodDoc?.externalDocs,
+            parameters: [
+              ...buildParameters(pathSchema, 'path', normalized.params),
+              ...buildParameters(querySchema, 'query'),
+              ...buildParameters(headerSchema, 'header'),
+            ].filter(Boolean),
+            requestBody: buildRequestBody(requestBody),
+            responses: buildResponses(method, methodDoc?.responses, methodDoc?.errors, metadata),
+            security: buildSecurity(metadata, methodDoc, options.defaultSecurity),
+            'x-codeSamples': methodDoc?.codeSamples ?? [
+              {
+                lang: 'curl',
+                label: 'cURL',
+                source: curlSample,
+              },
+            ],
+            ...(includeAccessControlMetadata && Array.isArray(requireFeatures) && requireFeatures.length
+              ? { 'x-require-features': requireFeatures }
+              : {}),
+            ...(includeAccessControlMetadata && Array.isArray(requireRoles) && requireRoles.length
+              ? { 'x-require-roles': requireRoles }
+              : {}),
+            ...(requireAuth ? { 'x-require-auth': true } : {}),
+            ...(methodDoc?.extensions ?? {}),
+          }
         }
       }
     }

package/src/lib/query/__tests__/empty-ids-filter.pg.test.ts

@@ -0,0 +1,89 @@
+/**
+ * End-to-end proof for #7502 against a real PostgreSQL: a `?ids=` filter that
+ * leaves no valid id (`{ id: { $in: [] } }`, the shape `mergeIdFilter` produces
+ * for an unparseable or disjoint id list) must answer an empty page, not a
+ * 42601 syntax error from Kysely compiling `in ()`.
+ *
+ * Gated on OM_COUNT_CAP_PG_URL (a throwaway database — the suite creates and
+ * drops its own table). 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 empty-ids-filter.pg
+ */
+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_emptyids_order'
+const TABLE = 'om_emptyids_orders'
+const ID_A = '33333333-3333-4333-8333-000000000001'
+const ID_B = '33333333-3333-4333-8333-000000000002'
+
+maybe('empty $in/$nin filter against PostgreSQL', () => {
+  jest.setTimeout(30_000)
+  let db: Kysely<any>
+
+  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 }) }) })
+    await sql`drop table if exists om_emptyids_orders`.execute(db)
+    await sql`create table om_emptyids_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`insert into om_emptyids_orders (id, tenant_id, organization_id, deleted_at, status) values
+      (${ID_A}::uuid, ${TENANT}::uuid, ${ORG}::uuid, null, 'open'),
+      (${ID_B}::uuid, ${TENANT}::uuid, ${ORG}::uuid, null, 'closed')`.execute(db)
+  })
+
+  afterAll(async () => {
+    await sql`drop table if exists om_emptyids_orders`.execute(db)
+    await db.destroy()
+  })
+
+  const makeEngine = () => new BasicQueryEngine({} as any, () => db as any)
+  const baseOpts = {
+    tenantId: TENANT,
+    organizationId: ORG,
+    fields: ['id'],
+    page: { page: 1, pageSize: 10 },
+  }
+
+  test('?ids= with no valid id returns an empty page instead of a 500 (AND path)', async () => {
+    const result = await makeEngine().query(ENTITY, {
+      ...baseOpts,
+      filters: { id: { $in: [] } },
+    })
+    expect(result.items).toEqual([])
+    expect(result.total).toBe(0)
+  })
+
+  test('a disjoint ?id=&?ids= intersection inside an $or group still matches the other disjunct', async () => {
+    const result = await makeEngine().query(ENTITY, {
+      ...baseOpts,
+      filters: {
+        $or: [
+          { id: { $in: [] } },
+          { status: { $eq: 'closed' } },
+        ],
+      },
+    })
+    expect(result.items.map((row: any) => row.id)).toEqual([ID_B])
+    expect(result.total).toBe(1)
+  })
+
+  test('an empty $nin excludes nothing, matching every row', async () => {
+    const result = await makeEngine().query(ENTITY, {
+      ...baseOpts,
+      filters: { id: { $nin: [] } },
+    })
+    expect(result.total).toBe(2)
+  })
+})

package/src/lib/query/__tests__/engine.empty-in-filter.test.ts

@@ -0,0 +1,79 @@
+/**
+ * #7502: `mergeIdFilter` deliberately produces `{ $in: [] }` for a `?ids=` param
+ * that left no valid UUID (or a disjoint `?id=`+`?ids=` intersection) — the
+ * correct "match nothing" semantics. Both engine where-builders used to pass
+ * that empty array straight to Kysely's `.where(column, 'in', [])`, which
+ * compiles to invalid SQL (`in ()`) and makes Postgres answer 42601/500
+ * instead of an empty page. These tests pin the guard directly on the two
+ * private builder methods — no real SQL execution needed to prove the shape
+ * changed; `count-cap-plan.test.ts`-style Postgres-gated tests cover the
+ * end-to-end compiled-SQL behavior.
+ */
+import { BasicQueryEngine } from '../engine'
+
+describe('applyColumnOp empty $in/$nin guard (#7502)', () => {
+  const engine = new BasicQueryEngine({} as any, () => ({}) as any)
+
+  function callApplyColumnOp(op: string, value: unknown) {
+    const calls: any[] = []
+    const builder: any = {
+      where: (...args: any[]) => {
+        calls.push(args)
+        return builder
+      },
+    }
+    ;(engine as any).applyColumnOp(builder, 'id', op, value)
+    return calls
+  }
+
+  test('empty $in does not reach Kysely as an empty in-list', () => {
+    const calls = callApplyColumnOp('in', [])
+    expect(calls).toHaveLength(1)
+    // Pre-fix this called builder.where('id', 'in', []) -- three arguments, the
+    // shape Kysely compiles to invalid SQL. Post-fix it is a single predicate arg.
+    expect(calls[0]).not.toEqual(['id', 'in', []])
+    expect(calls[0]).toHaveLength(1)
+  })
+
+  test('non-empty $in keeps the original in-list predicate', () => {
+    const calls = callApplyColumnOp('in', ['a'])
+    expect(calls[0]).toEqual(['id', 'in', ['a']])
+  })
+
+  test('empty $nin does not reach Kysely as an empty not-in-list', () => {
+    const calls = callApplyColumnOp('nin', [])
+    expect(calls[0]).toHaveLength(1)
+    expect(calls[0]).not.toEqual(['id', 'not in', []])
+  })
+
+  test('non-empty $nin keeps the original not-in-list predicate', () => {
+    const calls = callApplyColumnOp('nin', ['a'])
+    expect(calls[0]).toEqual(['id', 'not in', ['a']])
+  })
+})
+
+describe('buildColumnOpExpression empty $in/$nin guard (#7502, OR-group path)', () => {
+  const engine = new BasicQueryEngine({} as any, () => ({}) as any)
+
+  function callBuildColumnOpExpression(op: string, value: unknown) {
+    const eb: any = (...args: any[]) => ({ kind: 'cmp', args })
+    eb.val = (v: any) => ({ kind: 'val', value: v })
+    return (engine as any).buildColumnOpExpression(eb, 'id', op, value)
+  }
+
+  test('empty $in compiles to a never-match literal, not an empty in-list comparison', () => {
+    expect(callBuildColumnOpExpression('in', [])).toEqual({ kind: 'val', value: false })
+  })
+
+  test('non-empty $in keeps the original in-list comparison', () => {
+    expect(callBuildColumnOpExpression('in', ['a'])).toEqual({ kind: 'cmp', args: ['id', 'in', ['a']] })
+  })
+
+  test('empty $nin compiles to an always-match literal, not an empty not-in-list comparison', () => {
+    expect(callBuildColumnOpExpression('nin', [])).toEqual({ kind: 'val', value: true })
+  })
+
+  test('non-empty $nin keeps the original not-in-list comparison', () => {
+    expect(callBuildColumnOpExpression('nin', ['a'])).toEqual({ kind: 'cmp', args: ['id', 'not in', ['a']] })
+  })
+})

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

@@ -0,0 +1,219 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import {
+  DummyDriver,
+  Kysely,
+  PostgresAdapter,
+  PostgresIntrospector,
+  PostgresQueryCompiler,
+  sql,
+  type RawBuilder,
+} from 'kysely'
+import { BasicQueryEngine } from '../engine'
+import { normalizeFilters } from '../join-utils'
+import {
+  buildArrayColumnNoOverlapPredicate,
+  buildArrayColumnOverlapPredicate,
+  buildJsonbNoOverlapPredicate,
+  buildJsonbOverlapPredicate,
+  buildScalarOverlapPredicate,
+  jsonbDocKeyExpression,
+  normalizeOverlapValues,
+} from '../overlap'
+import type { FilterOp } from '../types'
+
+function makeCompilingDb(): Kysely<any> {
+  return new Kysely<any>({
+    dialect: {
+      createAdapter: () => new PostgresAdapter(),
+      createDriver: () => new DummyDriver(),
+      createIntrospector: (db) => new PostgresIntrospector(db),
+      createQueryCompiler: () => new PostgresQueryCompiler(),
+    },
+  })
+}
+
+const db = makeCompilingDb()
+
+function compileWhere(predicate: RawBuilder<boolean>): { sql: string; parameters: readonly unknown[] } {
+  const compiled = db.selectFrom('entity_indexes as ei').select('ei.id').where(predicate).compile()
+  return { sql: compiled.sql, parameters: compiled.parameters }
+}
+
+type EngineInternals = {
+  applyColumnOp: (builder: unknown, column: string, op: string, value: unknown) => { compile: () => { sql: string; parameters: readonly unknown[] } }
+  buildColumnOpExpression: (eb: unknown, column: string, op: string, value: unknown) => RawBuilder<boolean>
+  buildIndexDocOpExpression: (eb: unknown, opts: {
+    entity: string
+    field: string
+    op: FilterOp
+    value: unknown
+    recordIdColumn: string
+    tenantId?: string | null
+    withDeleted: boolean
+  }) => RawBuilder<boolean>
+}
+
+const engine = new BasicQueryEngine({} as EntityManager, () => db) as unknown as EngineInternals
+
+describe('normalizeOverlapValues', () => {
+  it('flattens, stringifies, drops nullish and de-duplicates', () => {
+    expect(normalizeOverlapValues(['a', 'b', 'a', null, undefined, 3])).toEqual(['a', 'b', '3'])
+    expect(normalizeOverlapValues('a')).toEqual(['a'])
+    expect(normalizeOverlapValues(undefined)).toEqual([])
+    expect(normalizeOverlapValues(null)).toEqual([])
+  })
+})
+
+describe('overlap predicate builders', () => {
+  it('compiles a jsonb has-any-of with the values bound as one array parameter', () => {
+    const compiled = compileWhere(buildJsonbOverlapPredicate('ei.doc', 'scope_keys', ['cat:1', 'tag:2']))
+    expect(compiled.sql).toContain(`("ei"."doc" -> 'scope_keys') ?| $1::text[]`)
+    expect(compiled.parameters).toEqual([['cat:1', 'tag:2']])
+  })
+
+  it('never interpolates values into the SQL text', () => {
+    const hostile = "x'); drop table entity_indexes; --"
+    const compiled = compileWhere(buildJsonbOverlapPredicate('ei.doc', 'scope_keys', [hostile]))
+    expect(compiled.sql).not.toContain('drop table')
+    expect(compiled.parameters).toEqual([[hostile]])
+  })
+
+  it('binds a key that is not a plain identifier instead of inlining it', () => {
+    const key = "scope'keys"
+    const expression = db.selectFrom('entity_indexes as ei').select(jsonbDocKeyExpression('ei.doc', key).as('value')).compile()
+    expect(expression.sql).toContain('("ei"."doc" -> $1)')
+    expect(expression.parameters).toEqual([key])
+  })
+
+  it.each([
+    ['jsonb', () => buildJsonbOverlapPredicate('ei.doc', 'scope_keys', [])],
+    ['array column', () => buildArrayColumnOverlapPredicate('ei.tags', [])],
+    ['scalar', () => buildScalarOverlapPredicate(sql`ei.value`, [null, undefined])],
+  ])('compiles an empty %s value list to false (matches nothing)', (_label, build) => {
+    const compiled = compileWhere(build())
+    expect(compiled.sql).toMatch(/where false$/)
+    expect(compiled.parameters).toEqual([])
+  })
+
+  it('compiles array-column overlap to && with a bound array', () => {
+    const compiled = compileWhere(buildArrayColumnOverlapPredicate('ei.tags', ['a', 'b']))
+    expect(compiled.sql).toContain('"ei"."tags" && $1')
+    expect(compiled.parameters).toEqual([['a', 'b']])
+  })
+
+  it('compiles scalar overlap to an IN list of bound values', () => {
+    const compiled = compileWhere(buildScalarOverlapPredicate(sql`ei.value`, ['a', 'b']))
+    expect(compiled.sql).toContain('ei.value in ($1, $2)')
+    expect(compiled.parameters).toEqual(['a', 'b'])
+  })
+})
+
+describe('BasicQueryEngine overlap', () => {
+  it('normalizes $overlap from the object filter syntax', () => {
+    const filters = normalizeFilters({ scope_keys: { $overlap: ['cat:1'] } })
+    expect(filters).toEqual([expect.objectContaining({ field: 'scope_keys', op: 'overlap', value: ['cat:1'] })])
+  })
+
+  it('applies && on a base column', () => {
+    const builder = db.selectFrom('catalog_products as b').select('b.id')
+    const compiled = engine.applyColumnOp(builder, 'b.tags', 'overlap', ['x', 'y']).compile()
+    expect(compiled.sql).toContain('"b"."tags" && $1')
+    expect(compiled.parameters).toEqual([['x', 'y']])
+  })
+
+  it('compiles an index-document overlap inside the entity_indexes EXISTS', () => {
+    const compiled = db
+      .selectFrom('catalog_products as b')
+      .select('b.id')
+      .where((eb) => engine.buildIndexDocOpExpression(eb, {
+        entity: 'catalog:catalog_product',
+        field: 'scope_keys',
+        op: 'overlap',
+        value: ['cat:1'],
+        recordIdColumn: 'b.id',
+        tenantId: 'tenant-1',
+        withDeleted: false,
+      }))
+      .compile()
+    expect(compiled.sql).toMatch(/exists \(select 1 as "one" from "entity_indexes" as "ei_\d+"/)
+    expect(compiled.sql).toMatch(/\("ei_\d+"\."doc" -> 'scope_keys'\) \?\| \$\d+::text\[\]/)
+    expect(compiled.parameters).toContainEqual(['cat:1'])
+  })
+
+  it('leaves existing operators unchanged', () => {
+    const compiled = db
+      .selectFrom('catalog_products as b')
+      .select('b.id')
+      .where((eb) => eb.and([
+        engine.buildColumnOpExpression(eb, 'b.sku', 'in', ['a', 'b']),
+        engine.buildColumnOpExpression(eb, 'b.title', 'ilike', '%x%'),
+        engine.buildColumnOpExpression(eb, 'b.deleted_at', 'exists', false),
+      ]))
+      .compile()
+    expect(compiled.sql).toContain('"b"."sku" in ($1, $2)')
+    expect(compiled.sql).toContain('"b"."title" ilike $3')
+    expect(compiled.sql).toContain('"b"."deleted_at" is null')
+    expect(compiled.sql).not.toContain('&&')
+    expect(compiled.sql).not.toContain('?|')
+  })
+})
+
+describe('noverlap predicate builders', () => {
+  it('compiles a jsonb has-none-of that requires a present array', () => {
+    const compiled = compileWhere(buildJsonbNoOverlapPredicate('ei.doc', 'scope_keys', ['cat:1', 'tag:2']))
+    expect(compiled.sql).toContain(
+      `(jsonb_typeof(("ei"."doc" -> 'scope_keys')) = 'array' and not (("ei"."doc" -> 'scope_keys') ?| $1::text[]))`,
+    )
+    expect(compiled.parameters).toEqual([['cat:1', 'tag:2']])
+  })
+
+  it('keeps only the array check for an empty jsonb value list', () => {
+    const compiled = compileWhere(buildJsonbNoOverlapPredicate('ei.doc', 'scope_keys', []))
+    expect(compiled.sql).toMatch(/where jsonb_typeof\(\("ei"\."doc" -> 'scope_keys'\)\) = 'array'$/)
+    expect(compiled.parameters).toEqual([])
+  })
+
+  it('compiles array-column has-none-of to not && and an empty list to is not null', () => {
+    const compiled = compileWhere(buildArrayColumnNoOverlapPredicate('ei.tags', ['a']))
+    expect(compiled.sql).toContain('not ("ei"."tags" && $1)')
+    expect(compiled.parameters).toEqual([['a']])
+    expect(compileWhere(buildArrayColumnNoOverlapPredicate('ei.tags', [])).sql).toContain('"ei"."tags" is not null')
+  })
+})
+
+describe('BasicQueryEngine noverlap', () => {
+  it('normalizes $noverlap from the object filter syntax', () => {
+    const filters = normalizeFilters({ scope_keys: { $noverlap: ['cat:1'] } })
+    expect(filters).toEqual([expect.objectContaining({ field: 'scope_keys', op: 'noverlap', value: ['cat:1'] })])
+  })
+
+  it('compiles an index-document noverlap inside the entity_indexes EXISTS', () => {
+    const compiled = db
+      .selectFrom('catalog_products as b')
+      .select('b.id')
+      .where((eb) => engine.buildIndexDocOpExpression(eb, {
+        entity: 'catalog:catalog_product',
+        field: 'scope_keys',
+        op: 'noverlap',
+        value: ['cat:1'],
+        recordIdColumn: 'b.id',
+        tenantId: 'tenant-1',
+        withDeleted: false,
+      }))
+      .compile()
+    expect(compiled.sql).toMatch(/exists \(select 1 as "one" from "entity_indexes" as "ei_\d+"/)
+    expect(compiled.sql).toMatch(/not \(\("ei_\d+"\."doc" -> 'scope_keys'\) \?\| \$\d+::text\[\]\)/)
+  })
+
+  it('applies not && on a base column', () => {
+    const builder = db.selectFrom('catalog_products as b').select('b.id')
+    const compiled = engine.applyColumnOp(builder, 'b.tags', 'noverlap', ['x']).compile()
+    expect(compiled.sql).toContain('not ("b"."tags" && $1)')
+    const expression = db
+      .selectFrom('catalog_products as b')
+      .select('b.id')
+      .where((eb) => engine.buildColumnOpExpression(eb, 'b.tags', 'noverlap', ['x']))
+      .compile()
+    expect(expression.sql).toContain('not ("b"."tags" && $1)')
+  })
+})