@open-mercato/core 0.6.8-develop.6993.1.3fc50f3409 → 0.6.8-develop.7000.1.0ae682bad1

package/src/modules/attachments/lib/scoped-upload-service.ts

@@ -0,0 +1,257 @@
+import { randomUUID } from 'node:crypto'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { DataEngine } from '@open-mercato/shared/lib/data/engine'
+import { emitCrudSideEffects } from '@open-mercato/shared/lib/commands/helpers'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { Attachment, AttachmentPartition } from '../data/entities'
+import { attachmentCrudEvents, attachmentCrudIndexer } from './crud'
+import type { StorageDriverFactory } from './drivers'
+import { buildAttachmentFileUrl } from './imageUrls'
+import { ensureDefaultPartitions, resolveDefaultPartitionCode } from './partitions'
+import { extractAttachmentContent } from './textExtraction'
+import { requestOcrProcessing } from './ocrQueue'
+import { OcrService, shouldUseLlmOcr } from './ocrService'
+import { assertAttachmentScopeInvariant } from './access'
+import {
+  mergeAttachmentMetadata,
+  upsertAssignment,
+  type AttachmentAssignment,
+} from './metadata'
+import {
+  detectAttachmentMimeType,
+  hasDangerousExecutableExtension,
+  isActiveContentAttachment,
+  sanitizeUploadedFileName,
+} from './security'
+import { resolveAttachmentMaxBytes } from './upload-limits'
+import type { AttachmentQuotaService } from './quota-service'
+
+const logger = createLogger('attachments')
+
+export type ScopedAttachmentUploadErrorCode =
+  | 'dangerous_executable'
+  | 'max_upload_size'
+  | 'active_content'
+  | 'partition_unavailable'
+  | 'quota_exceeded'
+  | 'quota_target_exists'
+  | 'quota_unavailable'
+  | 'quota_recovery_unsupported'
+  | 'storage_failed'
+  | 'persistence_failed'
+
+export class ScopedAttachmentUploadError extends Error {
+  constructor(
+    public readonly code: ScopedAttachmentUploadErrorCode,
+    public readonly status: number,
+  ) {
+    super(code)
+    this.name = 'ScopedAttachmentUploadError'
+  }
+}
+
+export type ScopedAttachmentUploadInput = {
+  tenantId: string
+  organizationId: string
+  entityId: string
+  recordId: string
+  fileName: string
+  declaredMimeType?: string | null
+  buffer: Buffer
+  tags?: string[]
+  assignments?: AttachmentAssignment[]
+  partitionCode?: string | null
+  maxBytes?: number
+}
+
+type QuotaRecoveryScheduler = (
+  payload: { reservationId: string; tenantId: string; organizationId: string },
+  delayMs: number,
+) => Promise<void>
+
+export class ScopedAttachmentUploadService {
+  constructor(private readonly deps: {
+    em: EntityManager
+    dataEngine?: DataEngine | null
+    storageDriverFactory: StorageDriverFactory
+    attachmentQuotaService: AttachmentQuotaService
+    attachmentQuotaRecoveryScheduler: QuotaRecoveryScheduler
+  }) {}
+
+  async upload(input: ScopedAttachmentUploadInput): Promise<Attachment> {
+    const safeName = sanitizeUploadedFileName(input.fileName)
+    if (hasDangerousExecutableExtension(safeName)) {
+      throw new ScopedAttachmentUploadError('dangerous_executable', 400)
+    }
+    if (input.buffer.length > (input.maxBytes ?? resolveAttachmentMaxBytes())) {
+      throw new ScopedAttachmentUploadError('max_upload_size', 413)
+    }
+    const mimeType = detectAttachmentMimeType(input.buffer, safeName, input.declaredMimeType ?? '')
+    if (isActiveContentAttachment(input.buffer, safeName, mimeType)) {
+      throw new ScopedAttachmentUploadError('active_content', 400)
+    }
+
+    const { em, storageDriverFactory, attachmentQuotaService, attachmentQuotaRecoveryScheduler } = this.deps
+    await ensureDefaultPartitions(em)
+    const partitionCode = input.partitionCode ?? resolveDefaultPartitionCode(input.entityId)
+    const partition = await em.findOne(AttachmentPartition, {
+      code: partitionCode,
+      $or: [
+        { tenantId: null, organizationId: null },
+        { tenantId: input.tenantId, organizationId: input.organizationId },
+      ],
+    })
+    if (!partition) throw new ScopedAttachmentUploadError('partition_unavailable', 400)
+
+    const driver = await storageDriverFactory.resolveForPartition(partition.code, {
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+    })
+    const preparedStoragePath = driver.prepareStoragePath?.({
+      partitionCode: partition.code,
+      orgId: input.organizationId,
+      tenantId: input.tenantId,
+      fileName: safeName,
+    })
+    if (!preparedStoragePath) {
+      throw new ScopedAttachmentUploadError('quota_recovery_unsupported', 500)
+    }
+
+    let reservation: { id: string; leaseToken: string; expiresAt: Date } | null = null
+    try {
+      reservation = await attachmentQuotaService.reserve({
+        tenantId: input.tenantId,
+        organizationId: input.organizationId,
+        bytes: input.buffer.length,
+        source: 'attachment',
+        storageDriver: driver.key,
+        storagePath: preparedStoragePath,
+        partitionCode: partition.code,
+      })
+      await attachmentQuotaRecoveryScheduler({
+        reservationId: reservation.id,
+        tenantId: input.tenantId,
+        organizationId: input.organizationId,
+      }, Math.max(1_000, reservation.expiresAt.getTime() - Date.now()))
+      await attachmentQuotaService.beginStorage(reservation.id, reservation.leaseToken)
+    } catch (error) {
+      if (reservation) {
+        await attachmentQuotaService.release(reservation.id, reservation.leaseToken).catch(() => undefined)
+      }
+      const code = (error as { code?: unknown })?.code
+      if (code === 'quota_exceeded') throw new ScopedAttachmentUploadError('quota_exceeded', 413)
+      if (code === 'quota_target_exists') throw new ScopedAttachmentUploadError('quota_target_exists', 409)
+      throw new ScopedAttachmentUploadError('quota_unavailable', 500)
+    }
+
+    if (!reservation) throw new ScopedAttachmentUploadError('quota_unavailable', 500)
+
+    let storedPath = preparedStoragePath
+    try {
+      const stored = await driver.store({
+        partitionCode: partition.code,
+        orgId: input.organizationId,
+        tenantId: input.tenantId,
+        fileName: safeName,
+        buffer: input.buffer,
+        storagePath: preparedStoragePath,
+      })
+      storedPath = stored.storagePath
+      await attachmentQuotaService.markStored(reservation.id, reservation.leaseToken)
+    } catch (error) {
+      await this.compensateStorage(driver, partition.code, storedPath, reservation)
+      logger.error('Scoped attachment storage failed', { err: error })
+      throw new ScopedAttachmentUploadError('storage_failed', 500)
+    }
+
+    let extractedContent: string | null = null
+    const wantsLlmOcr = partition.requiresOcr && shouldUseLlmOcr(mimeType, safeName)
+    const ocrService = wantsLlmOcr ? new OcrService() : null
+    const useLlmOcr = Boolean(wantsLlmOcr && ocrService?.available)
+    if (partition.requiresOcr && !useLlmOcr) {
+      try {
+        const { filePath, cleanup } = await driver.toLocalPath(partition.code, storedPath)
+        try {
+          extractedContent = await extractAttachmentContent({ filePath, mimeType })
+        } finally {
+          await cleanup().catch(() => undefined)
+        }
+      } catch (error) {
+        logger.error('Scoped attachment text extraction failed', { err: error })
+      }
+    }
+
+    let assignments = input.assignments?.slice() ?? []
+    assignments = upsertAssignment(assignments, { type: input.entityId, id: input.recordId })
+    const metadata = mergeAttachmentMetadata(null, {
+      assignments,
+      tags: input.tags ?? [],
+    })
+    const attachmentId = randomUUID()
+    let attachment!: Attachment
+
+    try {
+      await em.transactional(async (tx) => {
+        attachment = tx.create(Attachment, {
+          id: attachmentId,
+          entityId: input.entityId,
+          recordId: input.recordId,
+          organizationId: input.organizationId,
+          tenantId: input.tenantId,
+          fileName: safeName,
+          mimeType,
+          fileSize: input.buffer.length,
+          partitionCode: partition.code,
+          storageDriver: partition.storageDriver || 'local',
+          storagePath: storedPath,
+          url: buildAttachmentFileUrl(attachmentId),
+          content: extractedContent,
+          storageMetadata: metadata,
+        })
+        assertAttachmentScopeInvariant({ tenantId: attachment.tenantId, organizationId: attachment.organizationId })
+        await tx.persist(attachment).flush()
+        await attachmentQuotaService.completeAttachment(reservation.id, reservation.leaseToken, tx)
+      })
+    } catch (error) {
+      await this.compensateStorage(driver, partition.code, storedPath, reservation)
+      logger.error('Scoped attachment persistence failed', { err: error })
+      throw new ScopedAttachmentUploadError('persistence_failed', 500)
+    }
+
+    if (useLlmOcr) {
+      requestOcrProcessing(em, attachment, driver, storedPath).catch((error) => {
+        logger.error('Scoped attachment OCR scheduling failed', { err: error })
+      })
+    }
+    if (this.deps.dataEngine) {
+      await emitCrudSideEffects({
+        dataEngine: this.deps.dataEngine,
+        action: 'created',
+        entity: attachment,
+        identifiers: {
+          id: attachment.id,
+          organizationId: attachment.organizationId ?? null,
+          tenantId: attachment.tenantId ?? null,
+        },
+        events: attachmentCrudEvents,
+        indexer: attachmentCrudIndexer,
+      })
+      await this.deps.dataEngine.flushOrmEntityChanges()
+    }
+    return attachment
+  }
+
+  private async compensateStorage(
+    driver: Awaited<ReturnType<StorageDriverFactory['resolveForPartition']>>,
+    partitionCode: string,
+    storagePath: string,
+    reservation: { id: string; leaseToken: string },
+  ): Promise<void> {
+    try {
+      await (driver.deleteStrict?.(partitionCode, storagePath) ?? driver.delete(partitionCode, storagePath))
+      await this.deps.attachmentQuotaService.release(reservation.id, reservation.leaseToken)
+    } catch (error) {
+      logger.error('Scoped attachment compensation failed', { err: error })
+    }
+  }
+}

package/src/modules/attachments/lib/target-access-service.ts

@@ -0,0 +1,57 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { AuthContext } from '@open-mercato/shared/lib/auth/server'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { Attachment, AttachmentPartition } from '../data/entities'
+import { checkAttachmentAccess } from './access'
+import { readAttachmentMetadata } from './metadata'
+
+export type AttachmentRecordTarget = {
+  entityId: string
+  recordId: string
+}
+
+export type AttachmentTargetAccessInput = {
+  attachmentId: string
+  tenantId: string
+  organizationId: string
+  auth: Exclude<AuthContext, null>
+  targets: AttachmentRecordTarget[]
+}
+
+export class AttachmentTargetAccessService {
+  constructor(private readonly em: EntityManager) {}
+
+  async canAccessLinkedTarget(input: AttachmentTargetAccessInput): Promise<boolean> {
+    if (!input.targets.length) return false
+    const attachment = await findOneWithDecryption(
+      this.em,
+      Attachment,
+      {
+        id: input.attachmentId,
+        tenantId: input.tenantId,
+        organizationId: input.organizationId,
+      },
+      {},
+      { tenantId: input.tenantId, organizationId: input.organizationId },
+    )
+    if (!attachment) return false
+
+    const partition = await this.em.findOne(AttachmentPartition, {
+      code: attachment.partitionCode,
+      $or: [
+        { tenantId: null, organizationId: null },
+        { tenantId: input.tenantId, organizationId: input.organizationId },
+      ],
+    })
+    if (!partition) return false
+    if (!checkAttachmentAccess(input.auth, attachment, partition, { requireAuthForPublic: true }).ok) return false
+
+    const metadata = readAttachmentMetadata(attachment.storageMetadata)
+    return input.targets.some((target) => (
+      (attachment.entityId === target.entityId && attachment.recordId === target.recordId)
+      || metadata.assignments?.some((assignment) => (
+        assignment.type === target.entityId && assignment.id === target.recordId
+      )) === true
+    ))
+  }
+}

package/src/modules/auth/api/sidebar/preferences/route.ts

@@ -9,9 +9,9 @@ import {
   sidebarPreferencesScopeSchema,
 } from '../../../data/validators'
 import {
+  findSidebarPreference,
   loadRoleSidebarPreferenceUpdatedAt,
   loadRoleSidebarPreferences,
-  loadSidebarPreference,
   loadSidebarPreferenceUpdatedAt,
   saveRoleSidebarPreference,
   saveSidebarPreference,
@@ -204,7 +204,7 @@ export async function GET(req: Request) {
   // For API key auth, use userId (the actual user) if available
   const effectiveUserId = auth.isApiKey ? auth.userId : auth.sub
   const settings = effectiveUserId
-    ? await loadSidebarPreference(em, {
+    ? await findSidebarPreference(em, {
         userId: effectiveUserId,
         tenantId: auth.tenantId ?? null,
         organizationId: auth.orgId ?? null,

package/src/modules/auth/lib/backendChrome.tsx

@@ -33,8 +33,8 @@ import { Role } from '@open-mercato/core/modules/auth/data/entities'
 import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import {
   applySidebarPreference,
+  findSidebarPreference,
   loadFirstRoleSidebarPreference,
-  loadSidebarPreference,
 } from '@open-mercato/core/modules/auth/services/sidebarPreferencesService'
 import type { SidebarPreferencesSettings } from '@open-mercato/shared/modules/navigation/sidebarPreferences'
 
@@ -436,7 +436,7 @@ export async function resolveBackendChromePayload({
 
   const effectiveUserId = auth.isApiKey ? auth.userId : auth.sub
   if (effectiveUserId) {
-    userPreference = await loadSidebarPreference(em, {
+    userPreference = await findSidebarPreference(em, {
       userId: effectiveUserId,
       tenantId: scopedTenantId,
       organizationId: scopedOrganizationId,

package/src/modules/auth/services/sidebarPreferencesService.ts

@@ -37,10 +37,10 @@ export type SidebarGroupLike<T = Record<string, unknown>> = {
   weight?: number
 } & T
 
-export async function loadSidebarPreference(
+export async function findSidebarPreference(
   em: EntityManager,
   scope: SidebarPreferenceScope,
-): Promise<SidebarPreferencesSettings> {
+): Promise<SidebarPreferencesSettings | null> {
   // Cross-locale: variants & preferences are scoped per (user, tenant, org) only.
   // The `locale` field on the row is kept for audit / when the row was created.
   const { userId, tenantId, organizationId } = normalizeScope(scope)
@@ -51,7 +51,26 @@ export async function loadSidebarPreference(
     undefined,
     { tenantId, organizationId },
   )
-  return normalizeSidebarSettings(existing?.settingsJson as SidebarPreferencesSettings | undefined)
+  // `null` means "no saved preference" and is distinct from "a preference exists but is empty":
+  // callers layer role defaults beneath the user layout and must skip the user pass entirely,
+  // because applying empty settings overwrites the role state instead of merging with it.
+  if (!existing) return null
+  return normalizeSidebarSettings(existing.settingsJson as SidebarPreferencesSettings | null | undefined)
+}
+
+/**
+ * @deprecated Since 0.7.1, slated for removal in 0.9.0. Use `findSidebarPreference` and handle
+ * `null`. This function fabricates a default settings object for a user with no saved row, which
+ * is indistinguishable from a saved-but-empty preference — applying that result erases any role
+ * layer underneath it, because `applySidebarPreference` overwrites `hidden` rather than merging.
+ * Migration: `(await findSidebarPreference(em, scope)) ?? normalizeSidebarSettings(null)`
+ * reproduces this exact return value if you genuinely want the defaults.
+ */
+export async function loadSidebarPreference(
+  em: EntityManager,
+  scope: SidebarPreferenceScope,
+): Promise<SidebarPreferencesSettings> {
+  return (await findSidebarPreference(em, scope)) ?? normalizeSidebarSettings(null)
 }
 
 export async function loadSidebarPreferenceUpdatedAt(

package/src/modules/customers/api/companies/route.ts

@@ -91,6 +91,7 @@ const crud = makeCrudRoute({
     tenantField: 'tenantId',
     softDeleteField: 'deletedAt',
   },
+  enrichers: { entityId: 'customers.company' },
   indexer: {
     entityType: E.customers.customer_entity,
   },

package/src/modules/customers/backend/customers/companies-v2/[id]/page.tsx

@@ -305,7 +305,9 @@ export default function CompanyDetailV2Page({ params }: { params?: { id?: string
         .filter((widget) => (widget.placement?.kind ?? 'tab') === 'tab')
         .map((widget) => {
           const tabId = widget.placement?.groupId ?? widget.widgetId
-          const label = widget.placement?.groupLabel ?? widget.module.metadata.title ?? tabId
+          const label = widget.placement?.groupLabel
+            ? t(widget.placement.groupLabel, widget.placement.groupLabel)
+            : widget.module.metadata.title ?? tabId
           const priority = typeof widget.placement?.priority === 'number' ? widget.placement.priority : 0
           const render = () => (
             <widget.module.Widget
@@ -317,7 +319,7 @@ export default function CompanyDetailV2Page({ params }: { params?: { id?: string
           return { id: tabId, label, priority, render }
         })
         .sort((a, b) => b.priority - a.priority),
-    [data, injectedTabWidgets, injectionContext],
+    [data, injectedTabWidgets, injectionContext, t],
   )
 
   const injectedTabMap = React.useMemo(() => new Map(injectedTabs.map((tab) => [tab.id, tab.render])), [injectedTabs])

package/src/modules/customers/backend/customers/people-v2/[id]/page.tsx

@@ -308,7 +308,9 @@ export default function PersonDetailV2Page({ params }: { params?: { id?: string
         .filter((widget) => (widget.placement?.kind ?? 'tab') === 'tab')
         .map((widget) => {
           const tabId = widget.placement?.groupId ?? widget.widgetId
-          const label = widget.placement?.groupLabel ?? widget.module.metadata.title ?? tabId
+          const label = widget.placement?.groupLabel
+            ? t(widget.placement.groupLabel, widget.placement.groupLabel)
+            : widget.module.metadata.title ?? tabId
           const priority = typeof widget.placement?.priority === 'number' ? widget.placement.priority : 0
           const render = () => (
             <widget.module.Widget
@@ -320,7 +322,7 @@ export default function PersonDetailV2Page({ params }: { params?: { id?: string
           return { id: tabId, label, priority, render }
         })
         .sort((a, b) => b.priority - a.priority),
-    [data, injectedTabWidgets, injectionContext],
+    [data, injectedTabWidgets, injectionContext, t],
   )
 
   const injectedTabMap = React.useMemo(() => new Map(injectedTabs.map((tab) => [tab.id, tab.render])), [injectedTabs])

package/src/modules/customers/components/detail/assignableStaff.ts

@@ -1,177 +1,14 @@
-import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
-import type { FilterOption } from '@open-mercato/shared/lib/query/advanced-filter'
-
-export type AssignableStaffMember = {
-  teamMemberId: string
-  userId: string
-  displayName: string
-  email: string | null
-  teamName: string | null
-}
-
-type AssignableStaffResponse = {
-  items?: Array<Record<string, unknown>>
-  total?: number
-  page?: number
-  pageSize?: number
-}
-
-export type AssignableStaffMembersPage = {
-  items: AssignableStaffMember[]
-  /**
-   * How many rows the server served for this page, before the dedupe below.
-   * "Load more" guards must measure this rather than `items.length`: a deduped
-   * length shorter than the served page reads as a short page and terminates
-   * the sequence early, stranding the rest of the roster.
-   */
-  servedCount: number
-  total: number
-  page: number
-  pageSize: number
-}
-
-// The assignable-staff roster is owned by the optional, ejectable `staff` module.
-// When that module is disabled, its `/api/staff/team-members/assignable` endpoint is
-// absent and the request resolves to 404. Customers UI (deals / people / companies
-// owner filters, role-assignment dialogs) is core and always enabled, so it must not
-// break in that case — a missing staff module simply means there is no roster to
-// offer. Treat the 404 as an empty page and let any other failure propagate.
-function isAssignableEndpointMissing(error: unknown): boolean {
-  return (
-    typeof error === 'object' &&
-    error !== null &&
-    (error as { status?: unknown }).status === 404
-  )
-}
-
-export async function fetchAssignableStaffMembersPage(
-  query: string,
-  options?: { page?: number; pageSize?: number; signal?: AbortSignal },
-): Promise<AssignableStaffMembersPage> {
-  const page = options?.page ?? 1
-  const pageSize = options?.pageSize ?? 24
-  const params = new URLSearchParams()
-  params.set('page', String(page))
-  params.set('pageSize', String(pageSize))
-  const normalizedQuery = query.trim()
-  if (normalizedQuery.length > 0) {
-    params.set('search', normalizedQuery)
-  }
-
-  let data: AssignableStaffResponse
-  try {
-    data = await readApiResultOrThrow<AssignableStaffResponse>(
-      `/api/staff/team-members/assignable?${params.toString()}`,
-      options?.signal ? { signal: options.signal } : undefined,
-    )
-  } catch (error) {
-    if (isAssignableEndpointMissing(error)) {
-      return { items: [], servedCount: 0, total: 0, page, pageSize }
-    }
-    throw error
-  }
-
-  const rawItems = Array.isArray(data?.items) ? data.items : []
-  const deduped = new Map<string, AssignableStaffMember>()
-
-  for (const item of rawItems) {
-    const userId =
-      typeof item?.userId === 'string'
-        ? item.userId
-        : typeof item?.user_id === 'string'
-          ? item.user_id
-          : null
-    if (!userId || deduped.has(userId)) continue
-
-    const user =
-      item?.user && typeof item.user === 'object'
-        ? (item.user as Record<string, unknown>)
-        : null
-    const team =
-      item?.team && typeof item.team === 'object'
-        ? (item.team as Record<string, unknown>)
-        : null
-
-    const displayName =
-      typeof item?.displayName === 'string' && item.displayName.trim().length > 0
-        ? item.displayName.trim()
-        : typeof item?.display_name === 'string' && item.display_name.trim().length > 0
-          ? item.display_name.trim()
-          : null
-    const email =
-      user && typeof user.email === 'string' && user.email.trim().length > 0
-        ? user.email.trim()
-        : typeof item?.email === 'string' && item.email.trim().length > 0
-          ? item.email.trim()
-          : null
-    const teamName =
-      typeof item?.teamName === 'string' && item.teamName.trim().length > 0
-        ? item.teamName.trim()
-        : typeof item?.team_name === 'string' && item.team_name.trim().length > 0
-          ? item.team_name.trim()
-          : team && typeof team.name === 'string' && team.name.trim().length > 0
-            ? team.name.trim()
-            : null
-    const teamMemberId =
-      typeof item?.teamMemberId === 'string'
-        ? item.teamMemberId
-        : typeof item?.team_member_id === 'string'
-          ? item.team_member_id
-          : typeof item?.id === 'string'
-            ? item.id
-            : userId
-
-    deduped.set(userId, {
-      teamMemberId,
-      userId,
-      displayName: displayName ?? email ?? userId,
-      email,
-      teamName,
-    })
-  }
-
-  return {
-    items: Array.from(deduped.values()),
-    servedCount: rawItems.length,
-    total:
-      typeof data?.total === 'number' && Number.isFinite(data.total)
-        ? data.total
-        : deduped.size,
-    page:
-      typeof data?.page === 'number' && Number.isFinite(data.page)
-        ? data.page
-        : page,
-    pageSize:
-      typeof data?.pageSize === 'number' && Number.isFinite(data.pageSize)
-        ? data.pageSize
-        : pageSize,
-  }
-}
-
-export async function fetchAssignableStaffMembers(
-  query: string,
-  options?: { pageSize?: number; signal?: AbortSignal },
-): Promise<AssignableStaffMember[]> {
-  const result = await fetchAssignableStaffMembersPage(query, options)
-  return result.items
-}
-
-export function mapAssignableStaffToFilterOptions(items: AssignableStaffMember[]): FilterOption[] {
-  return items.map((item) => ({
-    value: item.userId,
-    label: item.email && item.email !== item.displayName
-      ? `${item.displayName} (${item.email})`
-      : item.displayName,
-    tone: 'neutral',
-  }))
-}
-
-export function ensureCurrentUserFilterOption(
-  options: FilterOption[],
-  currentUserId: string,
-  fallbackLabel: string,
-): FilterOption[] {
-  const trimmed = currentUserId.trim()
-  if (!trimmed || options.some((option) => option.value === trimmed)) return options
-  return [{ value: trimmed, label: fallbackLabel, tone: 'neutral' }, ...options]
-}
+/**
+ * @deprecated Import from `@open-mercato/core/modules/customers/lib/assignableStaff` instead.
+ * This path is a compatibility bridge kept for one minor version after 0.6.7; it will be
+ * removed in 0.7.0. The implementation moved to `../../lib/assignableStaff` so non-component
+ * callers (API routes, commands) can use it without importing from a `components/` path.
+ */
+export {
+  fetchAssignableStaffMembersPage,
+  fetchAssignableStaffMembers,
+  mapAssignableStaffToFilterOptions,
+  ensureCurrentUserFilterOption,
+  type AssignableStaffMember,
+  type AssignableStaffMembersPage,
+} from '../../lib/assignableStaff'