@open-mercato/shared 0.6.6-develop.6317.1.b3be10ab84 → 0.6.6-develop.6331.1.a33b8e99b7

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

@@ -469,20 +469,31 @@ describe('createGenericOptimisticLockReader', () => {
     expect(captures[0].options).toEqual({ fields: ['modifiedAt'] })
   })
 
-  it('fails open (returns null) when findOne throws — never 500s the mutation', async () => {
+  it('fails open (returns null) AND logs loudly with the resourceKind when findOne throws', async () => {
     const reader = createGenericOptimisticLockReader({ entity: FakeEntity })
     const em = {
       async findOne() {
-        throw new Error('column "updated_at" does not exist')
+        throw new Error('column "deleted_at" does not exist')
       },
     } as never
-    const result = await reader(em, {
-      resourceKind: 'k',
-      resourceId: 'r',
-      tenantId: 't',
-      organizationId: 'o',
-    })
-    expect(result).toBeNull()
+    const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {})
+    try {
+      const result = await reader(em, {
+        resourceKind: 'customers.tag',
+        resourceId: 'r',
+        tenantId: 't',
+        organizationId: 'o',
+      })
+      // Fail-open control flow preserved: a query error must never 500 the mutation.
+      expect(result).toBeNull()
+      // ...but a misconfig must be visible, naming the affected resourceKind.
+      expect(errorSpy).toHaveBeenCalledTimes(1)
+      const [message] = errorSpy.mock.calls[0]
+      expect(String(message)).toContain('customers.tag')
+      expect(String(message)).toContain('[optimistic-lock]')
+    } finally {
+      errorSpy.mockRestore()
+    }
   })
 
   it('returns null when the projected updatedAt is missing / null / non-Date', async () => {

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

@@ -27,7 +27,8 @@
  * Spec: .ai/specs/implemented/2026-05-25-oss-optimistic-locking.md (§ command-level checks)
  *       .ai/specs/2026-05-28-optimistic-locking-coverage-completion.md (Phase 4)
  */
-import { CrudHttpError } from './errors'
+import type { AwilixContainer } from 'awilix'
+import { CrudHttpError, isCrudHttpError } from './errors'
 import {
   OPTIMISTIC_LOCK_CONFLICT_CODE,
   OPTIMISTIC_LOCK_CONFLICT_ERROR,
@@ -303,3 +304,61 @@ export function createCommandOptimisticLockGuardService(
     },
   }
 }
+
+const COMMAND_OPTIMISTIC_LOCK_GUARD_SERVICE_KEY = 'commandOptimisticLockGuardService'
+
+function resolveCommandOptimisticLockGuardService(
+  container: AwilixContainer,
+): CommandOptimisticLockGuardService | null {
+  try {
+    const service = container.resolve<CommandOptimisticLockGuardService>(
+      COMMAND_OPTIMISTIC_LOCK_GUARD_SERVICE_KEY,
+    )
+    if (!service || typeof service.enforce !== 'function') return null
+    return service
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Async, DI-aware command-level optimistic-lock runner (Phase 0 / S1). This is
+ * the additive seam command handlers migrate to so BOTH the OSS floor and the
+ * optional enterprise `record_locks` enrichment protect Command-pattern writes
+ * through one call:
+ *
+ *   1. The OSS `updated_at` floor runs **unconditionally first** via the
+ *      synchronous {@link enforceCommandOptimisticLock} — a stale write 409s
+ *      here regardless of any record-lock token / widget state (H2). The legacy
+ *      helper is reused verbatim, so the floor behaves identically to existing
+ *      direct call sites.
+ *   2. If the floor passes, the optional `commandOptimisticLockGuardService` is
+ *      resolved from the request container and awaited for enrichment.
+ *
+ * Fail-closed delegation (H3): a `record_lock_conflict`/409 from the enterprise
+ * service is rethrown (the write must be blocked), but ANY non-conflict error
+ * from a broken/unregistered enterprise guard is swallowed — the request
+ * degrades to OSS-only protection, never to "skip the guard".
+ *
+ * Strictly additive: with no enterprise service registered (OSS-only build) this
+ * is exactly the OSS compare. The synchronous {@link enforceCommandOptimisticLock}
+ * helper is left untouched for external callers.
+ */
+export async function enforceCommandOptimisticLockWithGuards(
+  container: AwilixContainer,
+  input: EnforceCommandOptimisticLockInput,
+): Promise<void> {
+  // 1. OSS floor — unconditional, synchronous, identical to direct call sites.
+  enforceCommandOptimisticLock(input)
+
+  // 2. Optional enterprise enrichment, fail-closed.
+  const guard = resolveCommandOptimisticLockGuardService(container)
+  if (!guard) return
+
+  try {
+    await guard.enforce(input)
+  } catch (error) {
+    // A real conflict must block the write; anything else degrades to OSS-only.
+    if (isCrudHttpError(error) && error.status === 409) throw error
+  }
+}

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

@@ -151,6 +151,16 @@ export type GenericOptimisticLockReaderOptions = {
  * treats as "entity already gone" and lets the CRUD path's own 404 fire.
  * We MUST NOT throw out of the reader — that would 500 every mutation on
  * the affected entity instead of opting it out of the optimistic check.
+ *
+ * Because a genuine not-found resolves to `null` *without* throwing (MikroORM's
+ * `findOne` returns `null`, it does not raise), the catch below only fires on a
+ * real query failure — most commonly a `softDeleteField`/`tenantField`/`orgField`
+ * misconfig that filters on a column the entity's table does not have. That class
+ * of bug silently disables locking for the whole entity, so the catch logs loudly
+ * with the `resourceKind` instead of swallowing the error. The control flow stays
+ * fail-open (returns `null`) to honor the no-500 contract; the durable defense is
+ * the static reader-resolution guard (`optimistic-lock-editable-entities.test.ts`)
+ * which fails the build when a route would land in this path.
  */
 export function createGenericOptimisticLockReader(
   opts: GenericOptimisticLockReaderOptions,
@@ -162,7 +172,7 @@ export function createGenericOptimisticLockReader(
   const updatedAtField = opts.updatedAtField ?? 'updatedAt'
   const extraFilter = opts.extraFilter ?? {}
 
-  return async (em, { resourceId, tenantId, organizationId }) => {
+  return async (em, { resourceKind, resourceId, tenantId, organizationId }) => {
     const filter: Record<string, unknown> = { [idField]: resourceId }
     if (tenantField) filter[tenantField] = tenantId
     if (orgField && organizationId) filter[orgField] = organizationId
@@ -178,7 +188,18 @@ export function createGenericOptimisticLockReader(
       if (value instanceof Date) return value.toISOString()
       if (typeof value === 'string' && value.length > 0) return value
       return null
-    } catch {
+    } catch (err) {
+      // A genuine not-found returns null above without throwing; reaching here
+      // means the query itself failed (most likely a softDeleteField/tenant/org
+      // misconfig filtering on a column the table lacks), which silently disables
+      // locking for `resourceKind`. Log loudly so the misconfig is visible.
+      // Control flow stays fail-open (return null) to honor the no-500 contract.
+      // eslint-disable-next-line no-console
+      console.error(
+        `[optimistic-lock] reader query failed for resourceKind="${resourceKind}" — optimistic locking is DISABLED for this entity until fixed. ` +
+          `Most likely a softDeleteField/tenantField/orgField filters on a column the table does not have.`,
+        err,
+      )
       return null
     }
   }

package/src/lib/di/container.ts

@@ -8,6 +8,7 @@ import { commandRegistry, CommandBus } from '@open-mercato/shared/lib/commands'
 import { applyDiOverridesToContainer } from '@open-mercato/shared/modules/overrides'
 import { createOptimisticLockGuardService } from '@open-mercato/shared/lib/crud/optimistic-lock'
 import { getAllOptimisticLockReaders } from '@open-mercato/shared/lib/crud/optimistic-lock-store'
+import { createCommandOptimisticLockGuardService } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 
 type DynamicCradle = Record<string, any>
 
@@ -171,6 +172,16 @@ export async function createRequestContainer(): Promise<AppContainer> {
         readers: getAllOptimisticLockReaders(),
       }),
     ).scoped(),
+    // Default OSS command-level optimistic-lock guard, awaited by
+    // `enforceCommandOptimisticLockWithGuards` for Command-pattern writes.
+    // Header/explicit-token compare only (no `resolveExpected`), so it is
+    // behaviourally identical to calling `enforceCommandOptimisticLock`
+    // directly. The enterprise `record_locks` module overrides this DI key
+    // with a lock-backed `resolveExpected` via Awilix replace semantics.
+    // Spec: .ai/specs/enterprise/2026-06-09-record-locks-unified-coverage.md (Phase 0)
+    commandOptimisticLockGuardService: asFunction(() =>
+      createCommandOptimisticLockGuardService(),
+    ).scoped(),
   })
   // Allow modules to override/extend
   for (const reg of diRegistrars) {

package/src/lib/query/__tests__/records-search-filter.test.ts

@@ -0,0 +1,58 @@
+/** @jest-environment node */
+import { normalizeFilters } from '../join-utils'
+
+/**
+ * The custom-entity records API builds a pagination-aware server-side search as a
+ * top-level `$or` of `$ilike` clauses (one per searchable field) ANDed with the
+ * tenant/org scope (#3229). This verifies the filter shape it produces normalizes
+ * into the orGroup disjuncts + lifted common clause that the query engine consumes,
+ * so the search applies before pagination instead of only on the current page.
+ */
+describe('records server-side search filter normalization', () => {
+  it('expands an $or of $ilike clauses into orGroup-tagged disjuncts', () => {
+    const filters = {
+      $or: [
+        { id: { $ilike: '%berlin%' } },
+        { title: { $ilike: '%berlin%' } },
+        { location: { $ilike: '%berlin%' } },
+      ],
+    }
+    const normalized = normalizeFilters(filters)
+    const groups = new Set(normalized.map((f) => f.orGroup))
+    expect(groups.size).toBe(3)
+    expect(normalized).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ field: 'id', op: 'ilike', value: '%berlin%' }),
+        expect.objectContaining({ field: 'title', op: 'ilike', value: '%berlin%' }),
+        expect.objectContaining({ field: 'location', op: 'ilike', value: '%berlin%' }),
+      ]),
+    )
+  })
+
+  it('lifts the ANDed org scope out of the search disjuncts as a common clause', () => {
+    const filters = {
+      organization_id: { $in: ['org-1'] },
+      $or: [
+        { title: { $ilike: '%abc%' } },
+        { location: { $ilike: '%abc%' } },
+      ],
+    }
+    const normalized = normalizeFilters(filters)
+    const common = normalized.filter((f) => !f.orGroup)
+    const disjuncts = normalized.filter((f) => f.orGroup)
+    expect(common).toEqual([
+      expect.objectContaining({ field: 'organization_id', op: 'in', value: ['org-1'] }),
+    ])
+    expect(new Set(disjuncts.map((f) => f.orGroup)).size).toBe(2)
+    expect(disjuncts.map((f) => f.field).sort()).toEqual(['location', 'title'])
+  })
+
+  it('keeps a single-field search as a plain AND clause (no orGroup)', () => {
+    const filters = { $or: [{ id: { $ilike: '%x%' } }] }
+    const normalized = normalizeFilters(filters)
+    expect(normalized).toEqual([
+      expect.objectContaining({ field: 'id', op: 'ilike', value: '%x%' }),
+    ])
+    expect(normalized.every((f) => !f.orGroup)).toBe(true)
+  })
+})

package/src/lib/query/engine.ts

@@ -518,18 +518,21 @@ export class BasicQueryEngine implements QueryEngine {
           group.push(f)
           groups.set(f.orGroup!, group)
         }
-        const resolvedGroupFilters: Array<Array<{ qualified: string; op: string; value: unknown; fieldName: string }>> = []
+        type ResolvedOrClause =
+          | { kind: 'column'; qualified: string; op: NormalizedFilter['op']; value: unknown }
+          | { kind: 'doc'; field: string; op: NormalizedFilter['op']; value: unknown }
+        const resolvedGroupFilters: ResolvedOrClause[][] = []
         for (const [, groupFilters] of groups) {
-          const resolved: Array<{ qualified: string; op: string; value: unknown; fieldName: string }> = []
+          const resolved: ResolvedOrClause[] = []
           for (const filter of groupFilters) {
             const column = await this.resolveBaseColumn(table, String(filter.field))
             if (column) {
-              resolved.push({
-                qualified: qualify(column),
-                op: filter.op,
-                value: filter.value,
-                fieldName: String(filter.field),
-              })
+              resolved.push({ kind: 'column', qualified: qualify(column), op: filter.op, value: filter.value })
+            } else {
+              // Field is not a base column — for custom-entity records it lives in
+              // entity_indexes.doc. Build an EXISTS sub-filter so `$or` searches
+              // across doc fields resolve instead of being silently dropped (#3229).
+              resolved.push({ kind: 'doc', field: String(filter.field), op: filter.op, value: filter.value })
             }
           }
           if (resolved.length > 0) resolvedGroupFilters.push(resolved)
@@ -537,7 +540,18 @@ export class BasicQueryEngine implements QueryEngine {
         if (resolvedGroupFilters.length > 0) {
           q = q.where((eb: any) => eb.or(
             resolvedGroupFilters.map((group) => {
-              const parts = group.map((rf) => this.buildColumnOpExpression(eb, rf.qualified, rf.op, rf.value))
+              const parts = group.map((rf) => rf.kind === 'column'
+                ? this.buildColumnOpExpression(eb, rf.qualified, rf.op, rf.value)
+                : this.buildIndexDocOpExpression(eb, {
+                    entity: String(entity),
+                    field: rf.field,
+                    op: rf.op,
+                    value: rf.value,
+                    recordIdColumn,
+                    tenantId: opts.tenantId ?? null,
+                    organizationScope: orgScope,
+                    withDeleted: opts.withDeleted === true,
+                  }))
               return parts.length === 1 ? parts[0] : eb.and(parts)
             })
           ))
@@ -1276,9 +1290,29 @@ export class BasicQueryEngine implements QueryEngine {
       return q
     }
 
+    return q.where((eb: any) => this.buildIndexDocOpExpression(eb, opts))
+  }
+
+  // Builds the entity_indexes EXISTS expression for a single doc-field operator,
+  // shared by the regular doc-filter path (applyIndexDocFilter) and the OR-group
+  // path so `$or` queries over custom-entity doc fields resolve instead of being
+  // silently dropped (#3229).
+  private buildIndexDocOpExpression(
+    eb: any,
+    opts: {
+      entity: string
+      field: string
+      op: NormalizedFilter['op']
+      value: unknown
+      recordIdColumn: string
+      tenantId?: string | null
+      organizationScope?: { ids: string[]; includeNull: boolean } | null
+      withDeleted: boolean
+    }
+  ): any {
     const alias = `ei_${this.searchAliasSeq++}`
     const engine = this
-    return q.where((eb: any) => eb.exists((() => {
+    return eb.exists((() => {
       let sub: AnyBuilder = eb
         .selectFrom(`entity_indexes as ${alias}`)
         .select(sql<number>`1`.as('one'))
@@ -1331,7 +1365,7 @@ export class BasicQueryEngine implements QueryEngine {
           break
       }
       return sub
-    })()))
+    })())
   }
 
   private configureCustomFieldSources(