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

package/src/modules/feature_toggles/api/overrides/route.ts

@@ -5,7 +5,7 @@ import type { CommandBus } from '@open-mercato/shared/lib/commands'
 import { serializeOperationMetadata } from '@open-mercato/shared/lib/commands/operationMetadata'
 import { getOverrides } from '../../lib/queries'
 import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
-import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
+import { enforceCommandOptimisticLockWithGuards } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 import {
   runCrudMutationGuardAfterSuccess,
   validateCrudMutationGuard,
@@ -100,7 +100,7 @@ export async function PUT(req: Request) {
       toggle: { id: parsed.data.toggleId },
     })
     if (existingOverride) {
-      enforceCommandOptimisticLock({
+      await enforceCommandOptimisticLockWithGuards(ctx.container, {
         resourceKind: 'feature_toggles.feature_toggle_override',
         resourceId: existingOverride.id,
         current: existingOverride.updatedAt ?? null,

package/src/modules/feature_toggles/backend/feature-toggles/global/[id]/edit/page.tsx

@@ -57,6 +57,18 @@ export default function EditFeatureTogglePage({ params }: { params?: { id?: stri
     )
   }
 
+  // record_locks scope decision (Phase 6): the global feature toggle is a
+  // NON-TENANT, superadmin-only entity. record_locks enrichment (presence,
+  // acquire/heartbeat, conflict upgrade) is tenant-scoped — its decorator skips
+  // enrichment when no tenant/resource resolves — so a global (null-tenant) record
+  // cannot participate in record_locks. This surface therefore stays OSS-floor
+  // guarded ONLY: the CrudForm auto-derives the optimistic-lock header from
+  // `optimisticLockUpdatedAt`, the route enforces it via the OSS floor, and a stale
+  // save surfaces the unified conflict bar. No `backend:record:current` presence is
+  // mounted: it would never resolve a tenant-scoped lock, and this is a
+  // single-superadmin surface with no concurrent-editor expectation. Per-tenant
+  // override values (`api/global/[id]/override`) ARE tenant-scoped and are enabled
+  // in Phase 6b.
   return (
     <Page>
       <PageBody>

package/src/modules/feature_toggles/data/entities.ts

@@ -67,7 +67,7 @@ export class FeatureToggleOverride {
   @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
   createdAt: Date = new Date()
 
-  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date() })
+  @Property({ name: 'updated_at', type: Date, onCreate: () => new Date(), onUpdate: () => new Date() })
   updatedAt: Date = new Date()
 
   @Property({ name: 'value', type: 'jsonb' })

package/src/modules/feature_toggles/data/validators.ts

@@ -104,6 +104,7 @@ export const overrideListResponseSchema = z.object({
   name: z.string(),
   category: z.string(),
   isOverride: z.boolean(),
+  updatedAt: z.string().nullable().optional(),
 });
 
 export type OverrideListResponse = z.infer<typeof overrideListResponseSchema>

package/src/modules/feature_toggles/lib/queries.ts

@@ -100,6 +100,7 @@ export async function getOverrides(
             name: toggle.name,
             category: toggle.category ?? '',
             isOverride: Boolean(override),
+            updatedAt: override?.updatedAt instanceof Date ? override.updatedAt.toISOString() : null,
         }
     })
 

package/src/modules/inbox_ops/api/settings/route.ts

@@ -2,7 +2,7 @@ import { NextResponse } from 'next/server'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { runWithCacheTenant } from '@open-mercato/cache'
 import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
-import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
+import { enforceCommandOptimisticLockWithGuards } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { InboxSettings } from '../../data/entities'
 import { updateSettingsSchema } from '../../data/validators'
@@ -104,7 +104,7 @@ export async function PATCH(req: Request) {
     // Optimistic lock: refuse a stale overwrite when two tabs edit the same inbox
     // settings record. Strictly additive — a no-op without the expected-version header.
     try {
-      enforceCommandOptimisticLock({
+      await enforceCommandOptimisticLockWithGuards(ctx.container, {
         resourceKind: 'inbox_ops.settings',
         resourceId: settings.id,
         current: settings.updatedAt ?? null,

package/src/modules/messages/api/unread-count/route.ts

@@ -1,5 +1,11 @@
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { type Kysely, sql } from 'kysely'
+import { runWithCacheTenant } from '@open-mercato/cache'
+import {
+  buildCollectionTags,
+  isCrudCacheEnabled,
+  resolveCrudCache,
+} from '@open-mercato/shared/lib/crud/cache'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi/types'
 import { resolveMessageContext } from '../../lib/routeHelpers'
 import { unreadCountResponseSchema } from '../openapi'
@@ -8,6 +14,16 @@ export const metadata = {
   GET: { requireAuth: true },
 }
 
+const UNREAD_COUNT_RESOURCE = 'messages.message'
+const UNREAD_COUNT_TTL_MS = 10_000
+
+function buildUnreadCountCacheKey(params: {
+  userId: string
+  orgId: string | null
+}): string {
+  return `messages:unread-count:u=${params.userId}:org=${params.orgId ?? 'null'}`
+}
+
 function getDb(em: EntityManager): Kysely<any> {
   return em.getKysely<any>()
 }
@@ -17,6 +33,19 @@ export async function GET(req: Request) {
   const em = ctx.container.resolve('em') as EntityManager
   const db = getDb(em) as any
 
+  const orgId = scope.organizationId ?? null
+  const cache = isCrudCacheEnabled() ? resolveCrudCache(ctx.container) : null
+  const cacheKey = cache
+    ? buildUnreadCountCacheKey({ userId: scope.userId, orgId })
+    : null
+
+  if (cache && cacheKey) {
+    const cached = await runWithCacheTenant(scope.tenantId, () => cache.get(cacheKey))
+    if (typeof cached === 'number') {
+      return Response.json({ unreadCount: cached })
+    }
+  }
+
   let query = db
     .selectFrom('message_recipients as r')
     .innerJoin('messages as m', 'm.id', 'r.message_id')
@@ -38,6 +67,17 @@ export async function GET(req: Request) {
     .executeTakeFirst() as { count: string | number } | undefined
   const count = Number(row?.count ?? 0)
 
+  if (cache && cacheKey) {
+    try {
+      await runWithCacheTenant(scope.tenantId, () =>
+        cache.set(cacheKey, count, {
+          ttl: UNREAD_COUNT_TTL_MS,
+          tags: buildCollectionTags(UNREAD_COUNT_RESOURCE, scope.tenantId, [orgId]),
+        }),
+      )
+    } catch {}
+  }
+
   return Response.json({ unreadCount: count })
 }
 

package/src/modules/query_index/components/QueryIndexesTable.tsx

@@ -11,6 +11,7 @@ import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/u
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { useConfirmDialog } from '@open-mercato/ui/backend/confirm-dialog'
 import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
+import { StatusBadge, type StatusBadgeVariant } from '@open-mercato/ui/primitives/status-badge'
 
 const MUTATION_CONTEXT_ID = 'query_index.status.list:actions'
 
@@ -127,7 +128,7 @@ function createColumns(t: Translator): ColumnDef<Row>[] {
         if (!record.vectorEnabled) return <span>—</span>
         const ok = record.vectorCount != null && record.baseCount != null && record.vectorCount === record.baseCount
         const display = formatCount(record.vectorCount)
-        const className = ok ? 'text-green-600' : 'text-orange-600'
+        const className = ok ? 'text-status-success-text' : 'text-status-warning-text'
         return <span className={className}>{display}</span>
       },
       meta: { priority: 2 },
@@ -141,7 +142,7 @@ function createColumns(t: Translator): ColumnDef<Row>[] {
         if (!record.fulltextEnabled) return <span>—</span>
         const ok = record.fulltextCount != null && record.baseCount != null && record.fulltextCount === record.baseCount
         const display = formatCount(record.fulltextCount)
-        const className = ok ? 'text-green-600' : 'text-orange-600'
+        const className = ok ? 'text-status-success-text' : 'text-status-warning-text'
         return <span className={className}>{display}</span>
       },
       meta: { priority: 2 },
@@ -159,17 +160,14 @@ function createColumns(t: Translator): ColumnDef<Row>[] {
         const label = jobProgress
           ? t('query_index.table.status.withProgress', { status: statusText, progress: jobProgress })
           : statusText
-        const className = job
-          ? job.status === 'stalled'
-            ? 'text-red-600'
-            : job.status === 'reindexing' || job.status === 'purging'
-              ? 'text-orange-600'
-              : ok
-                ? 'text-green-600'
-                : 'text-muted-foreground'
-          : ok
-            ? 'text-green-600'
-            : 'text-muted-foreground'
+        let variant: StatusBadgeVariant = 'neutral'
+        if (job) {
+          if (job.status === 'stalled') variant = 'error'
+          else if (job.status === 'reindexing' || job.status === 'purging') variant = 'warning'
+          else variant = ok ? 'success' : 'neutral'
+        } else {
+          variant = ok ? 'success' : 'neutral'
+        }
 
         const lines: string[] = []
 
@@ -203,8 +201,12 @@ function createColumns(t: Translator): ColumnDef<Row>[] {
         }
 
         return (
-          <div className="space-y-1">
-            <span className={className}>{label}</span>
+          <div className="space-y-1.5">
+            <div>
+              <StatusBadge variant={variant} dot>
+                {label}
+              </StatusBadge>
+            </div>
             {lines.length > 0 && (
               <div className="text-xs text-muted-foreground">
                 {lines.map((line, idx) => (

package/src/modules/resources/backend/resources/resource-types/[id]/edit/page.tsx

@@ -1,9 +1,10 @@
 "use client"
 
 import * as React from 'react'
-import { useRouter } from 'next/navigation'
+import { usePathname, useRouter } from 'next/navigation'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { ErrorMessage, RecordNotFoundState } from '@open-mercato/ui/backend/detail'
+import { buildRecordInjectionContext, useSetCurrentRecordInjectionContext } from '@open-mercato/ui/backend/injection/recordContext'
 import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
 import { updateCrud, deleteCrud } from '@open-mercato/ui/backend/utils/crud'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
@@ -19,6 +20,7 @@ export default function ResourcesResourceTypeEditPage({ params }: { params?: { i
   const resourceTypeId = params?.id ?? ''
   const t = useT()
   const router = useRouter()
+  const pathname = usePathname()
   const [initialValues, setInitialValues] = React.useState<ResourceTypeFormValues | null>(null)
   const [loading, setLoading] = React.useState(true)
   const [error, setError] = React.useState<string | null>(null)
@@ -108,6 +110,20 @@ export default function ResourcesResourceTypeEditPage({ params }: { params?: { i
     router.push('/backend/resources/resource-types')
   }, [resourceCount, resourceTypeId, router, t])
 
+  // Publish page-load record context to the AppShell-owned `backend:record:current`
+  // mount so the enterprise record_locks widget resolves `resources.resourceType` + id
+  // explicitly. The resourceKind mirrors the ResourceTypeCrudForm `versionHistory` so the
+  // held lock matches the save-time conflict surface for the same resource type.
+  useSetCurrentRecordInjectionContext(
+    buildRecordInjectionContext({
+      resourceKind: 'resources.resourceType',
+      resourceId: resourceTypeId || null,
+      updatedAt: initialValues?.updatedAt ?? null,
+      data: initialValues as Record<string, unknown> | null,
+      path: pathname,
+    }),
+  )
+
   if (isNotFound) {
     return (
       <Page>

package/src/modules/resources/backend/resources/resources/[id]/page.tsx

@@ -1,7 +1,7 @@
 "use client"
 
 import * as React from 'react'
-import { useRouter, useSearchParams } from 'next/navigation'
+import { usePathname, useRouter, useSearchParams } from 'next/navigation'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { FormHeader } from '@open-mercato/ui/backend/forms'
 import { Button } from '@open-mercato/ui/primitives/button'
@@ -12,6 +12,7 @@ import { createCrudFormError } from '@open-mercato/ui/backend/utils/serverErrors
 import { updateCrud, deleteCrud } from '@open-mercato/ui/backend/utils/crud'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { ActivitiesSection, NotesSection, RecordNotFoundState, type SectionAction, type TagOption } from '@open-mercato/ui/backend/detail'
+import { buildRecordInjectionContext, useSetCurrentRecordInjectionContext } from '@open-mercato/ui/backend/injection/recordContext'
 import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
 import { VersionHistoryAction } from '@open-mercato/ui/backend/version-history'
 import { SendObjectMessageDialog } from '@open-mercato/ui/backend/messages'
@@ -91,6 +92,7 @@ export default function ResourcesResourceDetailPage({ params }: { params?: { id?
   const t = useT()
   const detailTranslator = React.useMemo(() => createTranslatorWithFallback(t), [t])
   const router = useRouter()
+  const pathname = usePathname()
   const searchParams = useSearchParams()
   const [initialValues, setInitialValues] = React.useState<Record<string, unknown> | null>(null)
   const [isNotFound, setIsNotFound] = React.useState(false)
@@ -602,6 +604,20 @@ export default function ResourcesResourceDetailPage({ params }: { params?: { id?
       ? initialValues.name.trim()
       : t('resources.resources.detail.untitled', 'Unnamed resource')
 
+  // Publish page-load record context to the AppShell-owned `backend:record:current`
+  // mount so the enterprise record_locks widget resolves `resources.resource` + id
+  // explicitly. The resourceKind mirrors the VersionHistoryAction config / ResourceCrudForm
+  // `versionHistory` so the held lock matches the save-time conflict surface for the resource.
+  useSetCurrentRecordInjectionContext(
+    buildRecordInjectionContext({
+      resourceKind: 'resources.resource',
+      resourceId: resourceId || null,
+      updatedAt: typeof initialValues?.updatedAt === 'string' ? initialValues.updatedAt : null,
+      data: initialValues,
+      path: pathname,
+    }),
+  )
+
   if (isNotFound) {
     return (
       <Page>

package/src/modules/resources/components/detail/notesAdapter.ts

@@ -1,6 +1,7 @@
 "use client"
 
-import { apiCallOrThrow, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCallOrThrow, readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { mapCommentSummary, type NotesDataAdapter } from '@open-mercato/ui/backend/detail/NotesSection'
 
 type Translator = (key: string, fallback?: string, params?: Record<string, string | number>) => string
@@ -61,33 +62,43 @@ export function createResourceNotesAdapter(
       )
       return response.result ?? {}
     },
-    update: async ({ id, patch }) => {
+    update: async ({ id, patch, updatedAt }) => {
       const payload: Record<string, unknown> = { id }
       if (patch.body !== undefined) payload.body = patch.body
       if (patch.appearanceIcon !== undefined) payload.appearanceIcon = patch.appearanceIcon
       if (patch.appearanceColor !== undefined) payload.appearanceColor = patch.appearanceColor
+      // Run through the guarded-mutation runner AND send the optimistic-lock header
+      // (note's loaded updatedAt) so a stale edit fails with a 409; the shared
+      // NotesSection host surfaces it through surfaceRecordConflict instead of
+      // silently overwriting.
       await runWrite(
-        () => apiCallOrThrow(
-          '/api/resources/comments',
-          {
-            method: 'PUT',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify(payload),
-          },
-          { errorMessage: translator('resources.resources.detail.notes.updateError', 'Failed to update note.') },
+        () => withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(updatedAt ?? null),
+          () => apiCallOrThrow(
+            '/api/resources/comments',
+            {
+              method: 'PUT',
+              headers: { 'content-type': 'application/json' },
+              body: JSON.stringify(payload),
+            },
+            { errorMessage: translator('resources.resources.detail.notes.updateError', 'Failed to update note.') },
+          ),
         ),
         { operation: 'updateNote', id },
       )
     },
-    delete: async ({ id }) => {
+    delete: async ({ id, updatedAt }) => {
       await runWrite(
-        () => apiCallOrThrow(
-          `/api/resources/comments?id=${encodeURIComponent(id)}`,
-          {
-            method: 'DELETE',
-            headers: { 'content-type': 'application/json' },
-          },
-          { errorMessage: translator('resources.resources.detail.notes.deleteError', 'Failed to delete note') },
+        () => withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(updatedAt ?? null),
+          () => apiCallOrThrow(
+            `/api/resources/comments?id=${encodeURIComponent(id)}`,
+            {
+              method: 'DELETE',
+              headers: { 'content-type': 'application/json' },
+            },
+            { errorMessage: translator('resources.resources.detail.notes.deleteError', 'Failed to delete note') },
+          ),
         ),
         { operation: 'deleteNote', id },
       )

package/src/modules/sales/backend/sales/documents/[id]/page.tsx

@@ -3,7 +3,7 @@
 "use client"
 
 import * as React from 'react'
-import { useSearchParams, useRouter } from 'next/navigation'
+import { useSearchParams, useRouter, usePathname } from 'next/navigation'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import {
   CustomDataSection,
@@ -68,6 +68,7 @@ import { ICON_SUGGESTIONS } from '@open-mercato/core/modules/customers/lib/dicti
 import { readMarkdownPreferenceCookie, writeMarkdownPreferenceCookie } from '@open-mercato/core/modules/customers/lib/markdownPreference'
 import { InjectionSpot, useInjectionWidgets } from '@open-mercato/ui/backend/injection/InjectionSpot'
 import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
+import { buildRecordInjectionContext, useSetCurrentRecordInjectionContext } from '@open-mercato/ui/backend/injection/recordContext'
 
 function formatMessageAmount(amount: number | null | undefined, currency: string | null | undefined): string | null {
   if (typeof amount !== 'number' || !Number.isFinite(amount)) return null
@@ -1892,6 +1893,7 @@ export default function SalesDocumentDetailPage({
   const t = useT()
   const router = useRouter()
   const searchParams = useSearchParams()
+  const pathname = usePathname()
   const { confirm, ConfirmDialogElement } = useConfirmDialog()
   const [loading, setLoading] = React.useState(true)
   const [isNotFound, setIsNotFound] = React.useState(false)
@@ -1972,6 +1974,18 @@ export default function SalesDocumentDetailPage({
     },
     [detailInjectionContext, runMutation],
   )
+  // Publish page-load record context to the AppShell-owned `backend:record:current`
+  // mount so record_locks gets presence + the action-log base (updatedAt/data) for
+  // this order/quote. Sub-resource sections inherit this context — no second mount.
+  useSetCurrentRecordInjectionContext(
+    buildRecordInjectionContext({
+      resourceKind: `sales.${kind}`,
+      resourceId: record?.id ?? null,
+      updatedAt: record?.updatedAt ?? null,
+      data: record as Record<string, unknown> | null,
+      path: pathname,
+    }),
+  )
   const clearCustomerError = React.useCallback(() => setCustomerError(null), [])
   const { data: currencyDictionary } = useCurrencyDictionary()
   const scopeVersion = useOrganizationScopeVersion()
@@ -4244,6 +4258,7 @@ export default function SalesDocumentDetailPage({
             currencyCode={record.currencyCode ?? null}
             organizationId={(record as any)?.organizationId ?? (record as any)?.organization_id ?? null}
             tenantId={(record as any)?.tenantId ?? (record as any)?.tenant_id ?? null}
+            documentUpdatedAt={record.updatedAt ?? null}
             shippingAddressSnapshot={shippingSnapshot ?? null}
             onActionChange={handleSectionActionChange}
             onAddComment={appendShipmentComment}
@@ -4300,6 +4315,7 @@ export default function SalesDocumentDetailPage({
           currencyCode={record.currencyCode ?? null}
           organizationId={(record as any)?.organizationId ?? (record as any)?.organization_id ?? null}
           tenantId={(record as any)?.tenantId ?? (record as any)?.tenant_id ?? null}
+          documentUpdatedAt={record.updatedAt ?? null}
           onActionChange={handleSectionActionChange}
           onPaymentsChange={(payments) => setHasPayments(payments.length > 0)}
           onTotalsChange={() => {

package/src/modules/sales/commands/documents.ts

@@ -4981,7 +4981,7 @@ const updateQuoteCommand: CommandHandler<
     if (!quote)
       throw new CrudHttpError(404, { error: "Sales quote not found" });
     ensureQuoteScope(ctx, quote.organizationId, quote.tenantId);
-    enforceSalesDocumentOptimisticLock(ctx, quote, SALES_RESOURCE_KIND_QUOTE);
+    await enforceSalesDocumentOptimisticLock(ctx, quote, SALES_RESOURCE_KIND_QUOTE);
     const shouldInvalidateSentToken = (quote.status ?? null) === "sent";
     if (shouldInvalidateSentToken) {
       quote.acceptanceToken = null;
@@ -5213,6 +5213,7 @@ const updateOrderCommand: CommandHandler<
     if (!order)
       throw new CrudHttpError(404, { error: "Sales order not found" });
     ensureOrderScope(ctx, order.organizationId, order.tenantId);
+    await enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER);
     const previousStatus = normalizeStatusValue(order.status);
     let statusChangeNote: SalesNote | null = null;
     const shouldRecalculateTotals =
@@ -6055,7 +6056,7 @@ const convertQuoteToOrderCommand: CommandHandler<
           ),
         });
       ensureQuoteScope(ctx, quote.organizationId, quote.tenantId);
-      enforceSalesDocumentOptimisticLock(ctx, quote, SALES_RESOURCE_KIND_QUOTE);
+      await enforceSalesDocumentOptimisticLock(ctx, quote, SALES_RESOURCE_KIND_QUOTE);
       const snapshot = await loadQuoteSnapshot(em, payload.quoteId);
       if (!snapshot)
         throw new CrudHttpError(404, {
@@ -6545,7 +6546,7 @@ const orderLineUpsertCommand: CommandHandler<
     if (!order)
       throw new CrudHttpError(404, { error: "Sales order not found" });
     ensureOrderScope(ctx, order.organizationId, order.tenantId);
-    enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER);
+    await enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER);
 
     const [existingLines, adjustments] = await Promise.all([
       em.find(SalesOrderLine, { order }, { orderBy: { lineNumber: "asc" } }),
@@ -6866,7 +6867,7 @@ const orderLineDeleteCommand: CommandHandler<
         ),
       });
     ensureOrderScope(ctx, order.organizationId, order.tenantId);
-    enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER);
+    await enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER);
     const shipmentCount = await em.count(SalesShipmentItem, {
       orderLine: parsed.id,
       shipment: { deletedAt: null },
@@ -7037,7 +7038,7 @@ const quoteLineUpsertCommand: CommandHandler<
     if (!quote)
       throw new CrudHttpError(404, { error: "Sales quote not found" });
     ensureQuoteScope(ctx, quote.organizationId, quote.tenantId);
-    enforceSalesDocumentOptimisticLock(ctx, quote, SALES_RESOURCE_KIND_QUOTE);
+    await enforceSalesDocumentOptimisticLock(ctx, quote, SALES_RESOURCE_KIND_QUOTE);
     const [existingLines, adjustments] = await Promise.all([
       em.find(SalesQuoteLine, { quote }, { orderBy: { lineNumber: "asc" } }),
       em.find(
@@ -7349,7 +7350,7 @@ const quoteLineDeleteCommand: CommandHandler<
     if (!quote)
       throw new CrudHttpError(404, { error: "Sales quote not found" });
     ensureQuoteScope(ctx, quote.organizationId, quote.tenantId);
-    enforceSalesDocumentOptimisticLock(ctx, quote, SALES_RESOURCE_KIND_QUOTE);
+    await enforceSalesDocumentOptimisticLock(ctx, quote, SALES_RESOURCE_KIND_QUOTE);
     const existingLines = await em.find(
       SalesQuoteLine,
       { quote },
@@ -7503,7 +7504,7 @@ const orderAdjustmentUpsertCommand: CommandHandler<
     if (!order)
       throw new CrudHttpError(404, { error: "Sales order not found" });
     ensureOrderScope(ctx, order.organizationId, order.tenantId);
-    enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER);
+    await enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER);
     if (parsed.scope === "line") {
       throw new CrudHttpError(400, {
         error: "Line-scoped adjustments are not supported yet.",
@@ -7797,7 +7798,7 @@ const orderAdjustmentDeleteCommand: CommandHandler<
     if (!order)
       throw new CrudHttpError(404, { error: "Sales order not found" });
     ensureOrderScope(ctx, order.organizationId, order.tenantId);
-    enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER);
+    await enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER);
 
     const [existingLines, adjustments] = await Promise.all([
       em.find(SalesOrderLine, { order }, { orderBy: { lineNumber: "asc" } }),
@@ -7962,7 +7963,7 @@ const quoteAdjustmentUpsertCommand: CommandHandler<
     if (!quote)
       throw new CrudHttpError(404, { error: "Sales quote not found" });
     ensureQuoteScope(ctx, quote.organizationId, quote.tenantId);
-    enforceSalesDocumentOptimisticLock(ctx, quote, SALES_RESOURCE_KIND_QUOTE);
+    await enforceSalesDocumentOptimisticLock(ctx, quote, SALES_RESOURCE_KIND_QUOTE);
     if (parsed.scope === "line") {
       throw new CrudHttpError(400, {
         error: "Line-scoped adjustments are not supported yet.",
@@ -8254,7 +8255,7 @@ const quoteAdjustmentDeleteCommand: CommandHandler<
     if (!quote)
       throw new CrudHttpError(404, { error: "Sales quote not found" });
     ensureQuoteScope(ctx, quote.organizationId, quote.tenantId);
-    enforceSalesDocumentOptimisticLock(ctx, quote, SALES_RESOURCE_KIND_QUOTE);
+    await enforceSalesDocumentOptimisticLock(ctx, quote, SALES_RESOURCE_KIND_QUOTE);
 
     const [existingLines, adjustments] = await Promise.all([
       em.find(SalesQuoteLine, { quote }, { orderBy: { lineNumber: "asc" } }),

package/src/modules/sales/commands/payments.ts

@@ -30,6 +30,8 @@ import {
   ensureTenantScope,
   extractUndoPayload,
   toNumericString,
+  enforceSalesDocumentOptimisticLock,
+  SALES_RESOURCE_KIND_ORDER,
 } from './shared'
 import { resolveDictionaryEntryValue } from '../lib/dictionaries'
 import { resolveRedoSnapshot } from '@open-mercato/shared/lib/commands/redo'
@@ -343,6 +345,9 @@ const createPaymentCommand: CommandHandler<
       if (order.deletedAt) {
         throw new CrudHttpError(404, { error: 'sales.payments.order_not_found' })
       }
+      // Guard the parent order's aggregate version (Gap A): a payment mutation
+      // recalculates the order totals, so a stale parent must 409 before we touch it.
+      await enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER)
       if (
         order.currencyCode &&
         input.currencyCode &&
@@ -730,6 +735,9 @@ const updatePaymentCommand: CommandHandler<
     )
     ensureSameScope(payment, resolvedOrganizationId, resolvedTenantId)
     const previousOrder = payment.order as SalesOrder | null
+    // Guard the parent order's aggregate version (Gap A): updating a payment
+    // recalculates the order totals, so a stale parent must 409 before mutating.
+    await enforceSalesDocumentOptimisticLock(ctx, previousOrder, SALES_RESOURCE_KIND_ORDER)
     // Apply payment scalar fields, order/line status changes and the
     // allocations rebuild in one transaction so a mid-write failure cannot
     // leave the payment and its allocations partially committed (#2336).
@@ -1064,6 +1072,9 @@ const deletePaymentCommand: CommandHandler<
     )
     ensureSameScope(payment, input.organizationId, input.tenantId)
     const order = payment.order as SalesOrder | null
+    // Guard the parent order's aggregate version (Gap A): deleting a payment
+    // recalculates the order totals, so a stale parent must 409 before mutating.
+    await enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER)
     const allocations = await findWithDecryption(em, SalesPaymentAllocation, { payment }, {}, { tenantId: payment.tenantId, organizationId: payment.organizationId })
     const allocationOrders = allocations
       .map((allocation) =>

package/src/modules/sales/commands/returns.ts

@@ -615,7 +615,7 @@ const createReturnCommand: CommandHandler<ReturnCreateInput, { returnId: string
         throw new CrudHttpError(404, { error: translate('sales.returns.orderMissing', 'Order not found.') })
       }
       ensureSameScope(order, input.organizationId, input.tenantId)
-      enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER)
+      await enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER)
 
       const orderLines = await findWithDecryption(
         tx,
@@ -890,7 +890,7 @@ const updateReturnCommand: CommandHandler<ReturnUpdateInput, { returnId: string
       }
       // Lock on the return's own version — editing header fields (reason / notes /
       // returnedAt) only touches the return, not the order totals.
-      enforceSalesDocumentOptimisticLock(ctx, entity, SALES_RESOURCE_KIND_RETURN)
+      await enforceSalesDocumentOptimisticLock(ctx, entity, SALES_RESOURCE_KIND_RETURN)
 
       if (input.reason !== undefined) entity.reason = input.reason.length ? input.reason : null
       if (input.notes !== undefined) entity.notes = input.notes.length ? input.notes : null
@@ -1020,7 +1020,7 @@ const deleteReturnCommand: CommandHandler<ReturnDeleteInput, { returnId: string
     }
     ensureSameScope(header, input.organizationId, input.tenantId)
     // Lock on the return's own version, captured before any mutation.
-    enforceSalesDocumentOptimisticLock(ctx, header, SALES_RESOURCE_KIND_RETURN)
+    await enforceSalesDocumentOptimisticLock(ctx, header, SALES_RESOURCE_KIND_RETURN)
 
     await reverseReturnEffects(em, salesCalculationService, snapshot)
 

package/src/modules/sales/commands/shared.ts

@@ -2,7 +2,7 @@ import type { EntityManager } from '@mikro-orm/postgresql'
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import type { CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
-import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
+import { enforceCommandOptimisticLockWithGuards } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 export { assertFound } from '@open-mercato/shared/lib/crud/errors'
 export { ensureOrganizationScope, ensureSameScope, ensureTenantScope } from '@open-mercato/shared/lib/commands/scope'
 export { extractUndoPayload } from '@open-mercato/shared/lib/commands/undo'
@@ -28,14 +28,20 @@ export const SALES_RESOURCE_KIND_RETURN = 'sales.return'
  *
  * Strictly additive: when the client sends no header the check is a no-op, so
  * existing API consumers are unaffected. Respects `OM_OPTIMISTIC_LOCK`.
+ *
+ * Routes through the async DI-aware seam `enforceCommandOptimisticLockWithGuards`
+ * (Phase 0 / S1): the OSS `updated_at` floor runs first (identical behavior when
+ * `record_locks` is disabled — floor only), then the optional enterprise
+ * `record_locks` enrichment is awaited so the aggregate check observes the
+ * action-log diff when the resource is enabled. Callers MUST `await` it.
  */
-export function enforceSalesDocumentOptimisticLock(
+export async function enforceSalesDocumentOptimisticLock(
   ctx: CommandRuntimeContext,
   document: { id: string; updatedAt?: Date | string | null } | null | undefined,
   resourceKind: string,
-): void {
+): Promise<void> {
   if (!document) return
-  enforceCommandOptimisticLock({
+  await enforceCommandOptimisticLockWithGuards(ctx.container, {
     resourceKind,
     resourceId: document.id,
     current: document.updatedAt ?? null,