@open-mercato/enterprise 0.6.6-develop.6330.1.a261878aa8 → 0.6.6-develop.6331.1.a33b8e99b7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/enterprise",
-  "version": "0.6.6-develop.6330.1.a261878aa8",
+  "version": "0.6.6-develop.6331.1.a33b8e99b7",
   "license": "SEE LICENSE IN LICENSE.md",
   "type": "module",
   "main": "./dist/index.js",
@@ -65,8 +65,8 @@
     }
   },
   "dependencies": {
-    "@open-mercato/core": "0.6.6-develop.6330.1.a261878aa8",
-    "@open-mercato/ui": "0.6.6-develop.6330.1.a261878aa8",
+    "@open-mercato/core": "0.6.6-develop.6331.1.a33b8e99b7",
+    "@open-mercato/ui": "0.6.6-develop.6331.1.a33b8e99b7",
     "@simplewebauthn/browser": "^13.3.0",
     "@simplewebauthn/server": "^13.3.1",
     "@simplewebauthn/types": "^12.0.0",
@@ -76,12 +76,12 @@
     "qrcode": "^1.5.4"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.6.6-develop.6330.1.a261878aa8",
+    "@open-mercato/shared": "0.6.6-develop.6331.1.a33b8e99b7",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.6.6-develop.6330.1.a261878aa8",
+    "@open-mercato/shared": "0.6.6-develop.6331.1.a33b8e99b7",
     "@types/jest": "^30.0.0",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",

package/src/modules/record_locks/di.ts

@@ -4,6 +4,9 @@ import type { AppContainer } from '@open-mercato/shared/lib/di/container'
 import type { ModuleConfigService } from '@open-mercato/core/modules/configs/lib/module-config-service'
 import type { ActionLogService } from '@open-mercato/core/modules/audit_logs/services/actionLogService'
 import type { RbacService } from '@open-mercato/core/modules/auth/services/rbacService'
+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'
 import { createRecordLockService } from './lib/recordLockService'
 import type { RecordLockService } from './lib/recordLockService'
 import { createRecordLockCrudMutationGuardService } from './lib/crudMutationGuardService'
@@ -23,8 +26,31 @@ export function register(container: AppContainer) {
         rbacService: rbacService ?? null,
       }),
     ).scoped(),
-    crudMutationGuardService: asFunction((recordLockService: RecordLockService) =>
-      createRecordLockCrudMutationGuardService(recordLockService),
+    // CRUD guard decorator: chains the OSS `updated_at` floor first (built here
+    // because this DI key overrides the platform default), then adds the
+    // record_locks enrichment. record_locks can only ADD a 409, never skip the
+    // floor (S1/H2). Spec: .ai/specs/enterprise/2026-06-09-record-locks-unified-coverage.md (Phase 0)
+    crudMutationGuardService: asFunction((
+      recordLockService: RecordLockService,
+      em: EntityManager,
+    ) =>
+      createRecordLockCrudMutationGuardService(
+        recordLockService,
+        createOptimisticLockGuardService({
+          getEm: () => em,
+          readers: getAllOptimisticLockReaders(),
+        }),
+      ),
+    ).scoped(),
+    // Command guard override: lock-backed `resolveExpected` derived from
+    // authoritative server state (never requiring a client lock token, H2),
+    // awaited by `enforceCommandOptimisticLockWithGuards`. The OSS floor still
+    // runs first inside that runner.
+    commandOptimisticLockGuardService: asFunction((recordLockService: RecordLockService) =>
+      createCommandOptimisticLockGuardService({
+        resolveExpected: ({ expectedFromHeader, resourceKind }) =>
+          recordLockService.resolveExpectedVersion({ expectedFromHeader, resourceKind }),
+      }),
     ).scoped(),
   })
 }

package/src/modules/record_locks/lib/crudMutationGuardService.ts

@@ -3,50 +3,121 @@ import type {
   CrudMutationGuardValidateInput,
   CrudMutationGuardValidationResult,
 } from '@open-mercato/shared/lib/crud/mutation-guard'
+import {
+  parseOptimisticLockEnv,
+  type OptimisticLockConfig,
+} from '@open-mercato/shared/lib/crud/optimistic-lock'
+import { OPTIMISTIC_LOCK_ENV_VAR } from '@open-mercato/shared/lib/crud/optimistic-lock-headers'
 import { readRecordLockHeaders, type RecordLockService } from './recordLockService'
+import { isRecordLockingEnabledForResource } from './config'
 
 export type RecordLockCrudMutationGuardService = {
   validateMutation: (input: CrudMutationGuardValidateInput) => Promise<CrudMutationGuardValidationResult>
   afterMutationSuccess: (input: CrudMutationGuardAfterSuccessInput) => Promise<void>
 }
 
+/** The OSS floor service this decorator chains. Same shape as the platform default. */
+export type OssCrudMutationGuardServiceLike = {
+  validateMutation: (input: CrudMutationGuardValidateInput) => Promise<CrudMutationGuardValidationResult>
+  afterMutationSuccess: (input: CrudMutationGuardAfterSuccessInput) => Promise<void>
+}
+
 function resolveRecordLockMutationMethod(operation: CrudMutationGuardValidateInput['operation']): 'PUT' | 'DELETE' {
   if (operation === 'delete') return 'DELETE'
   return 'PUT'
 }
 
+function resolveConfig(envValue: string | null | undefined): OptimisticLockConfig {
+  return parseOptimisticLockEnv(envValue !== undefined ? envValue : process.env[OPTIMISTIC_LOCK_ENV_VAR])
+}
+
+export type CreateRecordLockCrudMutationGuardServiceOptions = {
+  /** Override `OM_OPTIMISTIC_LOCK` (mostly for tests). */
+  envValue?: string | null
+}
+
+/**
+ * Enterprise CRUD mutation guard. A **decorator** over the OSS optimistic-lock
+ * floor (S1/H2): it never replaces the floor, only adds blocks.
+ *
+ * Evaluation order (matches the spec's guard-layering chain):
+ *   1. `OM_OPTIMISTIC_LOCK=off` → pure pass-through (single global kill switch;
+ *      neither floor nor enrichment runs).
+ *   2. OSS `updated_at` floor runs first (delegated to the default OSS guard the
+ *      enterprise registration overrides). A stale write 409s here regardless of
+ *      any record-lock token / widget state — so a tokenless API/CLI client is
+ *      still caught (H1/H2).
+ *   3. Only if the floor passes, AND record_locks is enabled for the resource in
+ *      settings, the enterprise `validateMutation` enrichment runs (pessimistic
+ *      lock + action-log diff). It can only ADD a 409, never relax the floor.
+ *
+ * Fail-closed (H3): if the enterprise enrichment throws, the decorator degrades
+ * to the floor result (floor-pass ⇒ allow), never to "skip the guard".
+ */
 export function createRecordLockCrudMutationGuardService(
   recordLockService: RecordLockService,
+  ossFloorGuardService: OssCrudMutationGuardServiceLike,
+  options: CreateRecordLockCrudMutationGuardServiceOptions = {},
 ): RecordLockCrudMutationGuardService {
+  async function isRecordLockEnrichmentEnabled(resourceKind: string): Promise<boolean> {
+    try {
+      const settings = await recordLockService.getSettings()
+      return isRecordLockingEnabledForResource(settings, resourceKind)
+    } catch {
+      return false
+    }
+  }
+
   return {
     async validateMutation(input) {
-      const result = await recordLockService.validateMutation({
-        tenantId: input.tenantId,
-        organizationId: input.organizationId ?? null,
-        userId: input.userId,
-        resourceKind: input.resourceKind,
-        resourceId: input.resourceId,
-        method: resolveRecordLockMutationMethod(input.operation),
-        headers: readRecordLockHeaders(input.requestHeaders),
-        mutationPayload: input.mutationPayload ?? null,
-      })
+      const config = resolveConfig(options.envValue)
+      if (config.mode === 'off') {
+        // Single global kill switch: neither floor nor enrichment runs.
+        return { ok: true, shouldRunAfterSuccess: false, metadata: null }
+      }
+
+      // 1. OSS floor — always runs first, independent of any client lock token.
+      const floorResult = await ossFloorGuardService.validateMutation(input)
+      if (!floorResult.ok) return floorResult
+
+      // 2. Enterprise enrichment — only when the resource is enabled in settings.
+      if (!(await isRecordLockEnrichmentEnabled(input.resourceKind))) {
+        return { ok: true, shouldRunAfterSuccess: false, metadata: null }
+      }
+
+      // 3. Fail-closed: a throwing enrichment degrades to the (passed) floor.
+      let enrichmentResult: Awaited<ReturnType<RecordLockService['validateMutation']>>
+      try {
+        enrichmentResult = await recordLockService.validateMutation({
+          tenantId: input.tenantId,
+          organizationId: input.organizationId ?? null,
+          userId: input.userId,
+          resourceKind: input.resourceKind,
+          resourceId: input.resourceId,
+          method: resolveRecordLockMutationMethod(input.operation),
+          headers: readRecordLockHeaders(input.requestHeaders),
+          mutationPayload: input.mutationPayload ?? null,
+        })
+      } catch {
+        return { ok: true, shouldRunAfterSuccess: false, metadata: null }
+      }
 
-      if (result.ok) {
+      if (enrichmentResult.ok) {
         return {
           ok: true,
-          shouldRunAfterSuccess: result.resourceEnabled,
+          shouldRunAfterSuccess: enrichmentResult.resourceEnabled,
           metadata: null,
         }
       }
 
       return {
         ok: false,
-        status: result.status,
+        status: enrichmentResult.status,
         body: {
-          error: result.error,
-          code: result.code,
-          lock: result.lock ?? null,
-          conflict: result.conflict ?? null,
+          error: enrichmentResult.error,
+          code: enrichmentResult.code,
+          lock: enrichmentResult.lock ?? null,
+          conflict: enrichmentResult.conflict ?? null,
         },
       }
     },

package/src/modules/record_locks/lib/recordLockService.ts

@@ -491,6 +491,31 @@ export class RecordLockService {
     return settings // NOSONAR — both paths return settings by design; the branch controls persistence
   }
 
+  /**
+   * Command-guard `resolveExpected` seam (Phase 0 / S1). Derives the expected
+   * version token the OSS command floor compares against the record's current
+   * server-side `updated_at`.
+   *
+   * The compare is server-authoritative: the command handler already loaded the
+   * record from the DB and passes its `updated_at` as `current`, so a stale
+   * write is detected from the version header alone — NEVER requiring a client
+   * record-lock token (H2). When record_locks is not enabled for the resource
+   * (settings off), this returns the header token unchanged so the floor still
+   * runs (pure floor behavior). The richer pessimistic/action-log conflict
+   * detection runs through `validateMutation` at the CRUD layer.
+   */
+  async resolveExpectedVersion(input: {
+    resourceKind: string
+    expectedFromHeader: string | null
+  }): Promise<string | null> {
+    // Enabled or not, the server-authoritative floor compares the header token
+    // against the DB `updated_at`, so resolution is unconditionally the header
+    // value. Gating (record_locks settings) only changes whether the richer
+    // CRUD-layer conflict enrichment runs in `validateMutation` — it never
+    // affects the version floor here.
+    return input.expectedFromHeader
+  }
+
   async acquire(input: RecordLockAcquireInput): Promise<RecordLockAcquireResult | RecordLockAcquireFailure> {
     this.scheduleCleanup(input.tenantId)
     const settings = await this.getSettings()

package/src/modules/record_locks/widgets/injection/record-locking/widget.client.tsx

@@ -10,6 +10,7 @@ import { Alert, AlertDescription } from '@open-mercato/ui/primitives/alert'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import type { InjectionWidgetComponentProps } from '@open-mercato/shared/modules/widgets/injection'
 import { BACKEND_MUTATION_ERROR_EVENT } from '@open-mercato/ui/backend/injection/mutationEvents'
+import { registerRecordLockConflictHandler } from '@open-mercato/ui/backend/conflicts'
 import { useSearchParams } from 'next/navigation'
 import { Mail } from 'lucide-react'
 import {
@@ -32,7 +33,7 @@ import {
   type RecordLockUiView,
 } from '@open-mercato/enterprise/modules/record_locks/lib/clientLockStore'
 import { isUuid, resolveConflictId, runAcceptIncoming } from './conflictResolution'
-import { classifyUnmatchedSaveError } from '@open-mercato/enterprise/modules/record_locks/lib/optimisticLockFloor'
+import { isOptimisticLockFloorConflict } from '@open-mercato/enterprise/modules/record_locks/lib/optimisticLockFloor'
 
 type CrudInjectionContext = {
   formId?: string
@@ -295,6 +296,74 @@ function isRecordDeletedError(error: unknown): boolean {
   return false
 }
 
+/**
+ * Action the record-lock widget takes when a CrudForm / guarded-mutation save
+ * error event (`om:crud-save-error` / backend-mutation-error) fires. Extracted
+ * as a pure function so the single-conflict-surface (S3) decision is unit-testable
+ * without rendering the widget:
+ *
+ *  - `ignore`          — event is for a different form/record, there is no
+ *                        actionable mounted record, OR the error is a plain OSS
+ *                        `optimistic_lock_conflict` 409 already owned by the OSS
+ *                        conflict bar via `surfaceRecordConflict` (opening the
+ *                        dialog too would render TWO surfaces — #3504/#3505).
+ *  - `record-deleted`  — the record was deleted by another user.
+ *  - `apply-conflict`  — a genuine enterprise `record_lock_conflict` payload;
+ *                        open the field-level merge dialog with it.
+ *  - `fallback-dialog` — an unrecognized 409 (neither record-lock nor OSS
+ *                        optimistic-lock) for the mounted record; open the
+ *                        degraded fallback dialog (legacy behavior).
+ */
+export type RecordLockSaveErrorDecision =
+  | { action: 'ignore' }
+  | { action: 'record-deleted' }
+  | {
+      action: 'apply-conflict'
+      payload: {
+        conflict: RecordLockUiConflict
+        lock?: RecordLockUiView | null
+        latestActionLogId?: string | null
+      }
+    }
+  | { action: 'fallback-dialog' }
+
+export function resolveRecordLockSaveErrorDecision(args: {
+  error: unknown
+  eventContextId: string | null | undefined
+  formId: string
+  currentState: { resourceKind?: string | null; resourceId?: string | null } | null | undefined
+}): RecordLockSaveErrorDecision {
+  const { error, eventContextId, formId, currentState } = args
+  const payload = extractRecordLockConflictPayload(error)
+  const eventTargetsCurrentForm = !eventContextId || eventContextId === formId
+  if (!eventTargetsCurrentForm) {
+    if (!payload || !currentState?.resourceKind || !currentState?.resourceId) return { action: 'ignore' }
+    const payloadResourceKind = payload.conflict.resourceKind?.trim() ?? ''
+    const payloadResourceId = payload.conflict.resourceId?.trim() ?? ''
+    if (!payloadResourceKind || !payloadResourceId) return { action: 'ignore' }
+    if (payloadResourceKind !== currentState.resourceKind || payloadResourceId !== currentState.resourceId) {
+      return { action: 'ignore' }
+    }
+  }
+  if (!payload) {
+    if (!currentState?.resourceKind || !currentState?.resourceId) return { action: 'ignore' }
+    if (isRecordDeletedError(error)) return { action: 'record-deleted' }
+    // A plain OSS `optimistic_lock_conflict` 409 (the shape `makeCrudRoute` /
+    // `CrudForm` returns on a stale write) is already surfaced by the OSS conflict
+    // bar via `surfaceRecordConflict`. Defer to it instead of opening the degraded
+    // fallback merge dialog — otherwise both surfaces render at once (#3504) and the
+    // dialog has no field diff and a no-op "Accept incoming" (#3505). The rich merge
+    // dialog stays reserved for genuine `record_lock_conflict` payloads (handled
+    // above) whose conflict carries field changes + resolution options. Delegates to
+    // the shared `optimisticLockFloor` detector so this arbitration stays identical to
+    // the conflict bar's ownership decision (single source of truth).
+    if (isOptimisticLockFloorConflict(error)) return { action: 'ignore' }
+    if (extractErrorStatus(error) === 409) return { action: 'fallback-dialog' }
+    return { action: 'ignore' }
+  }
+  return { action: 'apply-conflict', payload }
+}
+
 function clearIncomingChangesQueryFlag() {
   if (typeof window === 'undefined') return
   try {
@@ -1019,41 +1088,33 @@ export default function RecordLockingWidget({
       const detail = (event as CustomEvent<CrudSaveErrorEventDetail>).detail
       if (!detail) return
       const eventContextId = detail.contextId ?? detail.formId
-      let payload = extractRecordLockConflictPayload(detail.error)
       const currentState = getRecordLockFormState(formId)
-      const eventTargetsCurrentForm = !eventContextId || eventContextId === formId
-      if (!eventTargetsCurrentForm) {
-        if (!payload || !currentState?.resourceKind || !currentState?.resourceId) return
-        const payloadResourceKind = payload.conflict.resourceKind?.trim() ?? ''
-        const payloadResourceId = payload.conflict.resourceId?.trim() ?? ''
-        if (!payloadResourceKind || !payloadResourceId) return
-        if (payloadResourceKind !== currentState.resourceKind || payloadResourceId !== currentState.resourceId) return
+      const decision = resolveRecordLockSaveErrorDecision({
+        error: detail.error,
+        eventContextId,
+        formId,
+        currentState,
+      })
+      if (decision.action === 'ignore') return
+      if (decision.action === 'record-deleted') {
+        setIsConflictDialogOpen(true)
+        setRecordLockFormState(formId, {
+          recordDeleted: true,
+          acquired: false,
+          lock: null,
+          conflict: null,
+          pendingConflictId: null,
+          pendingResolution: 'normal',
+          pendingResolutionArmed: false,
+        })
+        return
       }
-        if (!payload) {
-        if (!currentState?.resourceKind || !currentState?.resourceId) return
-        if (isRecordDeletedError(detail.error)) {
-          setIsConflictDialogOpen(true)
-          setRecordLockFormState(formId, {
-            recordDeleted: true,
-            acquired: false,
-            lock: null,
-            conflict: null,
-            pendingConflictId: null,
-            pendingResolution: 'normal',
-            pendingResolutionArmed: false,
-          })
-          return
-        }
-        // Single-surface arbitration (issue #3504 / S3): an OSS optimistic-lock-floor
-        // 409 is already owned by the shared conflict bar, so defer to it instead of
-        // opening a second, degraded merge dialog. Other 409s keep the fallback dialog.
-        if (classifyUnmatchedSaveError(detail.error, extractErrorStatus(detail.error)) === 'fallback-merge-dialog') {
-          applyConflictPayload(buildFallbackConflict(currentState))
-        }
+      if (decision.action === 'fallback-dialog') {
+        if (currentState) applyConflictPayload(buildFallbackConflict(currentState))
         return
       }
 
-      applyConflictPayload(payload)
+      applyConflictPayload(decision.payload)
     }
 
     window.addEventListener(BACKEND_MUTATION_ERROR_EVENT, onCrudSaveError)
@@ -1064,6 +1125,33 @@ export default function RecordLockingWidget({
     }
   }, [formId, isPrimaryInstance])
 
+  // Single conflict surface (S3): own the surface for record_lock_conflict 409s
+  // routed through `surfaceRecordConflict` (command/raw-write paths that don't
+  // emit the crud-save-error event). Opening the dialog here is idempotent with
+  // the listener above; returning true tells the core helper to suppress the OSS
+  // bar (so we never render both). Decline (false) for a different record so the
+  // bar still renders there — a conflict is never swallowed.
+  React.useEffect(() => {
+    if (!isPrimaryInstance) return
+    if (!resourceKind || !resourceId) return
+    const unregister = registerRecordLockConflictHandler((_conflict, error) => {
+      const payload = extractRecordLockConflictPayload(error)
+      if (!payload) return false
+      const payloadKind = payload.conflict.resourceKind?.trim() ?? ''
+      const payloadId = payload.conflict.resourceId?.trim() ?? ''
+      if (payloadKind && payloadId && (payloadKind !== resourceKind || payloadId !== resourceId)) return false
+      setIsConflictDialogOpen(true)
+      setRecordLockFormState(formId, {
+        conflict: payload.conflict,
+        pendingConflictId: payload.conflict.id,
+        pendingResolution: 'normal',
+        pendingResolutionArmed: false,
+      })
+      return true
+    })
+    return unregister
+  }, [formId, isPrimaryInstance, resourceKind, resourceId])
+
   const handleTakeOver = React.useCallback(async () => {
     keepMineRetryVersionRef.current += 1
     if (!state?.resourceKind || !state?.resourceId) return