@open-mercato/core 0.6.6-develop.6330.1.a261878aa8 → 0.6.6-develop.6332.1.6e73f0f55b

package/src/modules/attachments/components/AttachmentPartitionSettings.tsx

@@ -24,6 +24,7 @@ import {
 } from '@open-mercato/ui/primitives/dialog'
 import { apiCall, readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
 import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { raiseCrudError } from '@open-mercato/ui/backend/utils/serverErrors'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
@@ -257,6 +258,7 @@ export function AttachmentPartitionSettings({ s3Enabled }: AttachmentPartitionSe
       await loadItems()
     } catch (err) {
       console.error('[attachments.partitions] save failed', err)
+      if (surfaceRecordConflict(err, t)) return
       const message =
         err instanceof Error ? err.message : t('attachments.partitions.errors.save', 'Failed to save partition.')
       setError(message)
@@ -294,6 +296,7 @@ export function AttachmentPartitionSettings({ s3Enabled }: AttachmentPartitionSe
         await loadItems()
       } catch (err) {
         console.error('[attachments.partitions] delete failed', err)
+        if (surfaceRecordConflict(err, t)) return
         flash(t('attachments.partitions.errors.delete', 'Failed to delete partition.'), 'error')
       }
     },

package/src/modules/auth/api/logout.ts

@@ -1,9 +1,8 @@
-import { NextResponse } from 'next/server'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { AuthService } from '@open-mercato/core/modules/auth/services/authService'
 import { verifyJwt } from '@open-mercato/shared/lib/auth/jwt'
-import { buildRequestOriginUrl } from '@open-mercato/core/modules/auth/lib/requestRedirect'
+import { buildSafeRedirectResponse } from '@open-mercato/core/modules/auth/lib/requestRedirect'
 
 function parseCookie(req: Request, name: string): string | null {
   const cookie = req.headers.get('cookie') || ''
@@ -39,7 +38,7 @@ export async function POST(req: Request) {
       }
     } catch {}
   }
-  const res = NextResponse.redirect(buildRequestOriginUrl(req, '/login'))
+  const res = buildSafeRedirectResponse(req, '/login')
   res.cookies.set('auth_token', '', { path: '/', maxAge: 0 })
   res.cookies.set('session_token', '', { path: '/', maxAge: 0 })
   return res

package/src/modules/auth/api/roles/acl/route.ts

@@ -5,7 +5,7 @@ import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { logCrudAccess } from '@open-mercato/shared/lib/crud/factory'
 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 { withAtomicFlush } from '@open-mercato/shared/lib/commands/flush'
 import { RoleAcl, Role } from '@open-mercato/core/modules/auth/data/entities'
 import type { EntityManager } from '@mikro-orm/postgresql'
@@ -183,7 +183,7 @@ export async function PUT(req: Request) {
   // no prior version to conflict with).
   if (acl) {
     try {
-      enforceCommandOptimisticLock({
+      await enforceCommandOptimisticLockWithGuards(container, {
         resourceKind: 'auth.role_acl',
         resourceId: acl.id,
         current: acl.updatedAt ?? null,

package/src/modules/auth/api/session/refresh.ts

@@ -6,9 +6,8 @@ import { signJwt } from '@open-mercato/shared/lib/auth/jwt'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { refreshSessionRequestSchema } from '@open-mercato/core/modules/auth/data/validators'
 import { checkAuthRateLimit } from '@open-mercato/core/modules/auth/lib/rateLimitCheck'
-import { buildRequestOriginUrl } from '@open-mercato/core/modules/auth/lib/requestRedirect'
+import { buildSafeRedirectResponse, resolveTrustedRedirectBase } from '@open-mercato/core/modules/auth/lib/requestRedirect'
 import { sanitizeRedirectPath } from '@open-mercato/core/modules/auth/lib/safeRedirect'
-import { getAppBaseUrl } from '@open-mercato/shared/lib/url'
 import { readEndpointRateLimitConfig } from '@open-mercato/shared/lib/ratelimit/config'
 import { rateLimitErrorSchema } from '@open-mercato/shared/lib/ratelimit/helpers'
 import { z } from 'zod'
@@ -46,12 +45,12 @@ function clearStaffAuthCookies(response: NextResponse) {
 
 export async function GET(req: Request) {
   const url = new URL(req.url)
-  const baseUrl = getAppBaseUrl(req)
+  const baseUrl = resolveTrustedRedirectBase(req) ?? url.origin
   const redirectTo = sanitizeRedirectPath(url.searchParams.get('redirect'), baseUrl, '/')
   const token = parseCookie(req, 'session_token')
   if (!token) {
     return clearStaffAuthCookies(
-      NextResponse.redirect(buildRequestOriginUrl(req, '/login?redirect=' + encodeURIComponent(redirectTo)))
+      buildSafeRedirectResponse(req, '/login?redirect=' + encodeURIComponent(redirectTo))
     )
   }
   const c = await createRequestContainer()
@@ -59,12 +58,12 @@ export async function GET(req: Request) {
   const ctx = await auth.refreshFromSessionToken(token)
   if (!ctx) {
     return clearStaffAuthCookies(
-      NextResponse.redirect(buildRequestOriginUrl(req, '/login?redirect=' + encodeURIComponent(redirectTo)))
+      buildSafeRedirectResponse(req, '/login?redirect=' + encodeURIComponent(redirectTo))
     )
   }
   const { user, roles, session } = ctx
   const jwt = signJwt({ sub: String(user.id), sid: session ? String(session.id) : undefined, tenantId: String(user.tenantId), orgId: String(user.organizationId), email: user.email, roles })
-  const res = NextResponse.redirect(buildRequestOriginUrl(req, redirectTo))
+  const res = buildSafeRedirectResponse(req, redirectTo)
   res.cookies.set('auth_token', jwt, { httpOnly: true, path: '/', sameSite: 'lax', secure: process.env.NODE_ENV === 'production', maxAge: 60 * 60 * 8 })
   return res
 }

package/src/modules/auth/api/users/acl/route.ts

@@ -5,7 +5,7 @@ import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { logCrudAccess } from '@open-mercato/shared/lib/crud/factory'
 import { forbidden, 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 { withAtomicFlush } from '@open-mercato/shared/lib/commands/flush'
 import { UserAcl } from '@open-mercato/core/modules/auth/data/entities'
 import {
@@ -159,7 +159,7 @@ export async function PUT(req: Request) {
   // the client sends no expected-version header; skipped when no ACL row exists.
   if (acl) {
     try {
-      enforceCommandOptimisticLock({
+      await enforceCommandOptimisticLockWithGuards(container, {
         resourceKind: 'auth.user_acl',
         resourceId: acl.id,
         current: acl.updatedAt ?? null,

package/src/modules/auth/backend/roles/[id]/edit/page.tsx

@@ -1,8 +1,10 @@
 "use client"
 import * as React from 'react'
+import { usePathname } from 'next/navigation'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { CrudForm, type CrudField, type CrudFormGroup } from '@open-mercato/ui/backend/CrudForm'
 import { apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildRecordInjectionContext, useSetCurrentRecordInjectionContext } from '@open-mercato/ui/backend/injection/recordContext'
 import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { deleteCrud, updateCrud } from '@open-mercato/ui/backend/utils/crud'
 import { collectCustomFieldValues } from '@open-mercato/ui/backend/utils/customFieldValues'
@@ -37,6 +39,7 @@ type RoleListResponse = {
 export default function EditRolePage({ params }: { params?: { id?: string } }) {
   const id = params?.id
   const t = useT()
+  const pathname = usePathname()
   const [initial, setInitial] = React.useState<RoleRecord | null>(null)
   const [loading, setLoading] = React.useState(true)
   const [aclData, setAclData] = React.useState<AclData>({ isSuperAdmin: false, features: [], organizations: null })
@@ -189,6 +192,20 @@ export default function EditRolePage({ params }: { params?: { id?: string } }) {
     },
   ]), [aclData, actorIsSuperAdmin, detailFieldIds, id, initial, loading, selectedTenantId, t])
 
+  // Publish page-load record context to the AppShell-owned `backend:record:current`
+  // mount so the enterprise record_locks widget resolves `auth.role` + id explicitly.
+  // The resourceKind mirrors the CrudForm `versionHistory` so the held lock matches
+  // the save-time conflict surface for the same role.
+  useSetCurrentRecordInjectionContext(
+    buildRecordInjectionContext({
+      resourceKind: 'auth.role',
+      resourceId: id || null,
+      updatedAt: initial?.updatedAt ?? null,
+      data: initial as Record<string, unknown> | null,
+      path: pathname,
+    }),
+  )
+
   if (!id) return null
   return (
     <Page>

package/src/modules/auth/backend/users/[id]/edit/page.tsx

@@ -1,5 +1,6 @@
 "use client"
 import * as React from 'react'
+import { usePathname } from 'next/navigation'
 import { E } from '#generated/entities.ids.generated'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { CrudForm, type CrudField, type CrudFormGroup, type CrudFieldOption } from '@open-mercato/ui/backend/CrudForm'
@@ -19,6 +20,7 @@ import { extractCustomFieldEntries } from '@open-mercato/shared/lib/crud/custom-
 import { formatPasswordRequirements, getPasswordPolicy } from '@open-mercato/shared/lib/auth/passwordPolicy'
 import { UserConsentsPanel } from '@open-mercato/core/modules/auth/components/UserConsentsPanel'
 import { RecordNotFoundState, ErrorMessage } from '@open-mercato/ui/backend/detail'
+import { buildRecordInjectionContext, useSetCurrentRecordInjectionContext } from '@open-mercato/ui/backend/injection/recordContext'
 import { normalizeDisplayNameInput } from '@open-mercato/core/modules/auth/lib/displayName'
 
 type EditUserFormValues = {
@@ -123,6 +125,7 @@ function TenantAwareOrganizationSelectInput({
 export default function EditUserPage({ params }: { params?: { id?: string } }) {
   const id = params?.id
   const t = useT()
+  const pathname = usePathname()
   const tRef = React.useRef(t)
   tRef.current = t
   const [initialUser, setInitialUser] = React.useState<LoadedUser | null>(null)
@@ -473,6 +476,20 @@ export default function EditUserPage({ params }: { params?: { id?: string } }) {
     }
   }, [initialUser, customFieldValues, selectedTenantId])
 
+  // Publish page-load record context to the AppShell-owned `backend:record:current`
+  // mount so the enterprise record_locks widget resolves `auth.user` + id explicitly.
+  // The resourceKind mirrors the CrudForm `versionHistory` so the held lock matches
+  // the save-time conflict surface for the same user.
+  useSetCurrentRecordInjectionContext(
+    buildRecordInjectionContext({
+      resourceKind: 'auth.user',
+      resourceId: id || null,
+      updatedAt: initialUser?.updatedAt ?? null,
+      data: initialUser as Record<string, unknown> | null,
+      path: pathname,
+    }),
+  )
+
   if (isNotFound) {
     return (
       <Page>

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

@@ -273,7 +273,7 @@ export class RoleAcl {
   @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
   createdAt: Date = new Date()
 
-  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date(), nullable: true })
+  @Property({ name: 'updated_at', type: Date, onCreate: () => new Date(), onUpdate: () => new Date(), nullable: true })
   updatedAt?: Date
 
   @Property({ name: 'deleted_at', type: Date, nullable: true })
@@ -308,7 +308,7 @@ export class UserAcl {
   @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
   createdAt: Date = new Date()
 
-  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date(), nullable: true })
+  @Property({ name: 'updated_at', type: Date, onCreate: () => new Date(), onUpdate: () => new Date(), nullable: true })
   updatedAt?: Date
 
   @Property({ name: 'deleted_at', type: Date, nullable: true })

package/src/modules/auth/lib/requestRedirect.ts

@@ -1,5 +1,47 @@
-import { resolveRequestOrigin } from '@open-mercato/shared/lib/url'
+import { NextResponse } from 'next/server'
+import { getSecurityEmailBaseUrl } from '@open-mercato/shared/lib/url'
 
+function toRelativeRedirectPath(path: string): string {
+  // Strip any scheme/authority so the value is always treated as a path on the
+  // current origin. Both `new URL(path, base)` and the browser would otherwise
+  // honour a protocol-relative (`//host`) or backslash-smuggled value as a
+  // cross-origin target supplied by a spoofed Host / X-Forwarded-Host.
+  const withoutBackslashes = path.replace(/\\/g, '/')
+  const rooted = withoutBackslashes.startsWith('/') ? withoutBackslashes : `/${withoutBackslashes}`
+  return rooted.replace(/^\/+/, '/')
+}
+
+export function resolveTrustedRedirectBase(req: Request): string | null {
+  try {
+    return getSecurityEmailBaseUrl(req)
+  } catch {
+    return null
+  }
+}
+
+export function resolveSafeRedirectLocation(req: Request, path: string): string {
+  const safePath = toRelativeRedirectPath(path)
+  const base = resolveTrustedRedirectBase(req)
+  if (base) return new URL(safePath, base).toString()
+  return safePath
+}
+
+export function buildSafeRedirectResponse(req: Request, path: string, status: number = 307): NextResponse {
+  return new NextResponse(null, {
+    status,
+    headers: { Location: resolveSafeRedirectLocation(req, path) },
+  })
+}
+
+/**
+ * @deprecated Use {@link buildSafeRedirectResponse} or {@link resolveSafeRedirectLocation}.
+ * Previously derived the redirect origin from raw request headers, which
+ * allowed open redirects via a spoofed Host / X-Forwarded-Host. It now returns
+ * an allowlist-validated app origin when the request origin is trusted, and a
+ * host-relative path otherwise — the latter may be a relative URL, so callers
+ * MUST NOT pass the result to `NextResponse.redirect` (use
+ * {@link buildSafeRedirectResponse} instead).
+ */
 export function buildRequestOriginUrl(req: Request, path: string): string {
-  return new URL(path, resolveRequestOrigin(req)).toString()
+  return resolveSafeRedirectLocation(req, path)
 }

package/src/modules/business_rules/api/rules/route.ts

@@ -5,7 +5,7 @@ import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 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 { BusinessRule } from '../../data/entities'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { escapeLikePattern } from '@open-mercato/shared/lib/db/escapeLikePattern'
@@ -280,7 +280,7 @@ export async function PUT(req: Request) {
   }
 
   try {
-    enforceCommandOptimisticLock({
+    await enforceCommandOptimisticLockWithGuards(container, {
       resourceKind: 'business_rules.rule',
       resourceId: rule.id,
       current: rule.updatedAt ?? null,
@@ -338,7 +338,7 @@ export async function DELETE(req: Request) {
   }
 
   try {
-    enforceCommandOptimisticLock({
+    await enforceCommandOptimisticLockWithGuards(container, {
       resourceKind: 'business_rules.rule',
       resourceId: rule.id,
       current: rule.updatedAt ?? null,

package/src/modules/business_rules/api/sets/route.ts

@@ -4,7 +4,7 @@ import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 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 { RuleSet } from '../../data/entities'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { escapeLikePattern } from '@open-mercato/shared/lib/db/escapeLikePattern'
@@ -224,7 +224,7 @@ export async function PUT(req: Request) {
   }
 
   try {
-    enforceCommandOptimisticLock({
+    await enforceCommandOptimisticLockWithGuards(container, {
       resourceKind: 'business_rules.ruleSet',
       resourceId: ruleSet.id,
       current: ruleSet.updatedAt ?? null,
@@ -271,7 +271,7 @@ export async function DELETE(req: Request) {
   }
 
   try {
-    enforceCommandOptimisticLock({
+    await enforceCommandOptimisticLockWithGuards(container, {
       resourceKind: 'business_rules.ruleSet',
       resourceId: ruleSet.id,
       current: ruleSet.updatedAt ?? null,

package/src/modules/business_rules/backend/rules/[id]/page.tsx

@@ -2,7 +2,7 @@
 
 import * as React from 'react'
 import Link from 'next/link'
-import { useRouter, useParams } from 'next/navigation'
+import { useRouter, useParams, usePathname } from 'next/navigation'
 import { useQuery } from '@tanstack/react-query'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { CrudForm } from '@open-mercato/ui/backend/CrudForm'
@@ -10,6 +10,7 @@ import { Spinner } from '@open-mercato/ui/primitives/spinner'
 import { Button } from '@open-mercato/ui/primitives/button'
 import { apiFetch, withScopedApiHeaders } from '@open-mercato/ui/backend/utils/api'
 import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { buildRecordInjectionContext, useSetCurrentRecordInjectionContext } from '@open-mercato/ui/backend/injection/recordContext'
 import { readJsonSafe } from '@open-mercato/ui/backend/utils/serverErrors'
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
@@ -27,6 +28,7 @@ import { buildRulePayload, parseRuleToFormValues } from '../../../components/uti
 export default function EditBusinessRulePage() {
   const router = useRouter()
   const params = useParams()
+  const pathname = usePathname()
 
   // Handle catch-all route: params.slug = ['rules', 'uuid']
   let ruleId: string | undefined
@@ -103,6 +105,20 @@ export default function EditBusinessRulePage() {
     [t]
   )
 
+  // Publish page-load record context to the AppShell-owned `backend:record:current`
+  // mount so the enterprise record_locks widget resolves `business_rules.rule` + id
+  // explicitly. The resourceKind mirrors the route's `enforceCommandOptimisticLock`
+  // call so the held lock matches the save-time conflict surface for the same rule.
+  useSetCurrentRecordInjectionContext(
+    buildRecordInjectionContext({
+      resourceKind: 'business_rules.rule',
+      resourceId: ruleId ?? null,
+      updatedAt: rule?.updatedAt ?? rule?.updated_at ?? null,
+      data: (rule ?? null) as Record<string, unknown> | null,
+      path: pathname,
+    }),
+  )
+
   if (isLoading) {
     return (
       <Page>

package/src/modules/business_rules/backend/sets/[id]/page.tsx

@@ -2,7 +2,7 @@
 
 import * as React from 'react'
 import Link from 'next/link'
-import { useRouter, useParams } from 'next/navigation'
+import { useRouter, useParams, usePathname } from 'next/navigation'
 import { useQuery, useQueryClient } from '@tanstack/react-query'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { CrudForm } from '@open-mercato/ui/backend/CrudForm'
@@ -12,6 +12,7 @@ import { Button } from '@open-mercato/ui/primitives/button'
 import { apiFetch, withScopedApiHeaders } from '@open-mercato/ui/backend/utils/api'
 import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
 import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { buildRecordInjectionContext, useSetCurrentRecordInjectionContext } from '@open-mercato/ui/backend/injection/recordContext'
 import { readJsonSafe } from '@open-mercato/ui/backend/utils/serverErrors'
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
@@ -55,6 +56,7 @@ type RuleSetDetail = {
 export default function EditRuleSetPage() {
   const router = useRouter()
   const params = useParams()
+  const pathname = usePathname()
 
   // Handle catch-all route: params.slug = ['sets', 'uuid']
   let setId: string | undefined
@@ -237,6 +239,21 @@ export default function EditRuleSetPage() {
     ]
   }, [t, ruleSet, handleAddMember, handleUpdateMember, handleRemoveMember])
 
+  // Publish page-load record context to the AppShell-owned `backend:record:current`
+  // mount so the enterprise record_locks widget resolves the rule set + id
+  // explicitly. The resourceKind mirrors the route's `enforceCommandOptimisticLock`
+  // call (`business_rules.ruleSet`) so the held lock matches the save-time conflict
+  // surface for the same rule set.
+  useSetCurrentRecordInjectionContext(
+    buildRecordInjectionContext({
+      resourceKind: 'business_rules.ruleSet',
+      resourceId: setId ?? null,
+      updatedAt: ruleSet?.updatedAt ?? null,
+      data: (ruleSet ?? null) as Record<string, unknown> | null,
+      path: pathname,
+    }),
+  )
+
   if (isLoading) {
     return (
       <Page>

package/src/modules/catalog/api/product-media/route.ts

@@ -10,6 +10,10 @@ import { CatalogProduct } from '../../data/entities'
 import { E } from '#generated/entities.ids.generated'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 
+// record_locks decision: this route is read-only (GET only) and projects the
+// attachment side-table for a product. It is EXEMPT from the optimistic-lock /
+// record-lock guard (Phase 4) — there is no mutating method here, and media
+// uploads/deletes are owned by the attachments module's own write paths.
 export const metadata = {
   GET: { requireAuth: true, requireFeatures: ['catalog.products.view'] },
 }

package/src/modules/catalog/backend/catalog/categories/[id]/edit/page.tsx

@@ -1,6 +1,7 @@
 "use client"
 
 import * as React from 'react'
+import { usePathname } from 'next/navigation'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { CrudForm, type CrudField, type CrudFormGroup } from '@open-mercato/ui/backend/CrudForm'
 import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
@@ -8,6 +9,7 @@ import { updateCrud, deleteCrud } from '@open-mercato/ui/backend/utils/crud'
 import { createCrudFormError } from '@open-mercato/ui/backend/utils/serverErrors'
 import { collectCustomFieldValues } from '@open-mercato/ui/backend/utils/customFieldValues'
 import { ErrorMessage, RecordNotFoundState } from '@open-mercato/ui/backend/detail'
+import { buildRecordInjectionContext, useSetCurrentRecordInjectionContext } from '@open-mercato/ui/backend/injection/recordContext'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { extractCustomFieldEntries } from '@open-mercato/shared/lib/crud/custom-fields-client'
 import { E } from '#generated/entities.ids.generated'
@@ -81,6 +83,7 @@ async function submitCategoryUpdate(
 export default function EditCatalogCategoryPage({ params }: { params?: { id?: string } }) {
   const categoryId = params?.id ?? ''
   const t = useT()
+  const pathname = usePathname()
   const [initialValues, setInitialValues] = React.useState<CategoryFormValues | null>(null)
   const [pathLabel, setPathLabel] = React.useState<string>('')
   const [loading, setLoading] = React.useState<boolean>(true)
@@ -195,6 +198,20 @@ export default function EditCatalogCategoryPage({ params }: { params?: { id?: st
     },
   ], [t])
 
+  // Publish page-load record context to the AppShell-owned `backend:record:current`
+  // mount so the enterprise record_locks widget resolves `catalog.category` + id
+  // explicitly. The resourceKind mirrors the CrudForm `versionHistory` so the held
+  // lock matches the save-time conflict surface for the same category.
+  useSetCurrentRecordInjectionContext(
+    buildRecordInjectionContext({
+      resourceKind: 'catalog.category',
+      resourceId: categoryId || null,
+      updatedAt: initialValues?.updatedAt ?? null,
+      data: initialValues as Record<string, unknown> | null,
+      path: pathname,
+    }),
+  )
+
   if (!categoryId) {
     return (
       <Page>

package/src/modules/catalog/backend/catalog/products/[id]/page.tsx

@@ -2,6 +2,7 @@
 
 import * as React from "react";
 import Link from "next/link";
+import { usePathname } from "next/navigation";
 import { Page, PageBody } from "@open-mercato/ui/backend/Page";
 import { ErrorMessage, RecordNotFoundState } from "@open-mercato/ui/backend/detail";
 import {
@@ -41,6 +42,10 @@ import {
 } from "@open-mercato/ui/backend/utils/apiCall";
 import { buildOptimisticLockHeader } from "@open-mercato/ui/backend/utils/optimisticLock";
 import { surfaceRecordConflict } from "@open-mercato/ui/backend/conflicts";
+import {
+  buildRecordInjectionContext,
+  useSetCurrentRecordInjectionContext,
+} from "@open-mercato/ui/backend/injection/recordContext";
 import { useT } from "@open-mercato/shared/lib/i18n/context";
 import { useConfirmDialog } from "@open-mercato/ui/backend/confirm-dialog";
 import { E } from "#generated/entities.ids.generated";
@@ -314,6 +319,7 @@ export default function EditCatalogProductPage({
 }) {
   const productId = params?.id ? String(params.id) : null;
   const t = useT();
+  const pathname = usePathname();
   const productSubpathPrefix = productId
     ? `/backend/catalog/products/${productId}/`
     : null;
@@ -835,6 +841,21 @@ export default function EditCatalogProductPage({
     el.scrollIntoView({ behavior: 'smooth', block: 'start' })
   })
 
+  // Publish page-load record context to the AppShell-owned `backend:record:current`
+  // mount so the enterprise record_locks widget resolves `catalog.product` + id
+  // explicitly (presence/acquire/heartbeat on load; cleared on unmount). The
+  // resourceKind mirrors the CrudForm `versionHistory` so the held lock matches
+  // the save-time conflict surface for the same product.
+  useSetCurrentRecordInjectionContext(
+    buildRecordInjectionContext({
+      resourceKind: "catalog.product",
+      resourceId: productId,
+      updatedAt: initialValues?.updatedAt ?? null,
+      data: initialValues as Record<string, unknown> | null,
+      path: pathname,
+    }),
+  );
+
   const handleVariantDeleted = React.useCallback((variantId: string) => {
     setVariants((prev) => prev.filter((variant) => variant.id !== variantId));
   }, []);

package/src/modules/catalog/backend/catalog/products/[productId]/variants/[variantId]/page.tsx

@@ -1,7 +1,7 @@
 "use client"
 
 import * as React from 'react'
-import { useRouter } from 'next/navigation'
+import { useRouter, usePathname } from 'next/navigation'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { CrudForm, type CrudFormGroup } from '@open-mercato/ui/backend/CrudForm'
 import { createCrud, updateCrud, deleteCrud } from '@open-mercato/ui/backend/utils/crud'
@@ -10,6 +10,7 @@ import { collectCustomFieldValues } from '@open-mercato/ui/backend/utils/customF
 import { apiCall, readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
 import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
+import { buildRecordInjectionContext, useSetCurrentRecordInjectionContext } from '@open-mercato/ui/backend/injection/recordContext'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { ErrorMessage, RecordNotFoundState } from '@open-mercato/ui/backend/detail'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
@@ -100,6 +101,7 @@ function resolveVariantPriceLabel(prices: Record<string, VariantPriceDraft> | un
 export default function EditVariantPage({ params }: { params?: { productId?: string; variantId?: string } }) {
   const router = useRouter()
   const t = useT()
+  const pathname = usePathname()
   const productId = params?.productId ? String(params.productId) : null
   const variantId = params?.variantId ? String(params.variantId) : null
   const isCreateSentinel = variantId === 'create'
@@ -476,6 +478,19 @@ export default function EditVariantPage({ params }: { params?: { productId?: str
     return list
   }, [optionDefinitions, priceKinds, t, taxRates])
 
+  // Publish page-load record context to the AppShell-owned `backend:record:current`
+  // mount so the enterprise record_locks widget resolves `catalog.variant` + id
+  // explicitly. Skipped on the create-delegation path (no record to lock).
+  useSetCurrentRecordInjectionContext(
+    buildRecordInjectionContext({
+      resourceKind: 'catalog.variant',
+      resourceId: isCreateSentinel ? null : variantId,
+      updatedAt: initialValues?.updatedAt ?? null,
+      data: initialValues as Record<string, unknown> | null,
+      path: pathname,
+    }),
+  )
+
   if (isCreateSentinel) {
     if (!productId) {
       return (

package/src/modules/catalog/components/PriceKindSettings.tsx

@@ -18,7 +18,8 @@ import {
 } from '@open-mercato/ui/primitives/dialog'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { apiCall, readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
-import { buildOptimisticLockHeader, extractOptimisticLockConflict } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
 import { raiseCrudError } from '@open-mercato/ui/backend/utils/serverErrors'
 import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
@@ -236,9 +237,15 @@ export function PriceKindSettings() {
       await loadItems()
     } catch (err) {
       console.error('catalog.price-kinds.save failed', err)
-      const message = extractOptimisticLockConflict(err)
-        ? t('ui.forms.flash.recordModified', 'This record was modified by someone else. Refresh and try again.')
-        : err instanceof Error ? err.message : t('catalog.priceKinds.errors.save', 'Failed to save price kind.')
+      // Route a concurrent-edit 409 through the single conflict surface (unified
+      // conflict bar, or the enterprise merge dialog when its handler is mounted)
+      // and close the editor so that surface owns the resolution. Other errors
+      // stay inline in the dialog so the user can correct and resubmit.
+      if (surfaceRecordConflict(err, t, { onRefresh: () => { void loadItems() } })) {
+        closeDialog()
+        return
+      }
+      const message = err instanceof Error ? err.message : t('catalog.priceKinds.errors.save', 'Failed to save price kind.')
       setError(message)
     } finally {
       setSubmitting(false)
@@ -270,9 +277,10 @@ export function PriceKindSettings() {
         await loadItems()
       } catch (err) {
         console.error('catalog.price-kinds.delete failed', err)
-        const message = extractOptimisticLockConflict(err)
-          ? t('ui.forms.flash.recordModified', 'This record was modified by someone else. Refresh and try again.')
-          : err instanceof Error ? err.message : t('catalog.priceKinds.errors.delete', 'Failed to delete price kind.')
+        // Route a concurrent-edit 409 through the single conflict surface; fall
+        // back to a flash for any other delete failure.
+        if (surfaceRecordConflict(err, t, { onRefresh: () => { void loadItems() } })) return
+        const message = err instanceof Error ? err.message : t('catalog.priceKinds.errors.delete', 'Failed to delete price kind.')
         flash(message, 'error')
       }
     },

package/src/modules/catalog/lib/bulkDelete.ts

@@ -82,6 +82,12 @@ export async function deleteCatalogProductsWithProgress(params: {
   let affectedCount = 0
   const deletedIds = new Set<string>()
 
+  // record_locks decision: bulk product delete is EXEMPT from the optimistic-lock
+  // / record-lock guard (Phase 4). It is an explicit destructive operation over a
+  // multi-selection, not a collaborative field edit, and the queued job has no
+  // per-row expected `updated_at` to compare against — mirroring the customers
+  // bulk pattern from Phase 2. Single-product delete on the detail screen still
+  // rides the CRUD mutation-guard decorator with the version header.
   for (const [index, id] of ids.entries()) {
     await commandBus.execute<{ body?: Record<string, unknown> }, { productId: string }>('catalog.products.delete', {
       input: { body: { id } },