@open-mercato/core 0.8.1-develop.7296.1.2111d779db → 0.8.1-develop.7441.1.b42958b98c

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

@@ -0,0 +1,176 @@
+export const DEFAULT_CHECKPOINT_INTERVAL = 20
+
+/**
+ * Upper bound on the failure detail carried in `ProgressJob.meta`. `meta` is rewritten on every
+ * checkpoint and is part of every broadcast job payload, so an uncapped list would grow the
+ * persisted row (and the SSE frame every subscribed progress bar receives) with the batch.
+ * `checkpointSummary.failedCount` stays exact regardless of the cap.
+ */
+export const MAX_CHECKPOINTED_FAILURES = 200
+
+const BITS_PER_BYTE = 8
+
+export type BulkCreateCheckpoint<TFailure> = {
+  lastCompletedRowIndex: number
+  createdCount: number
+  failedCount: number
+  createdIds: string[]
+  failedItems: TFailure[]
+  /**
+   * The rows whose natural key already existed in the database when this job's first attempt
+   * started, or `null` for a job checkpointed before this field existed. A resumed attempt uses it
+   * to tell a record a previous attempt of this job created from one that was there all along;
+   * without it no such classification is possible and every existing key is a genuine conflict.
+   */
+  priorKeyRows: ReadonlySet<number> | null
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function readStringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : []
+}
+
+/**
+ * Encodes the snapshot as a base64 bitset over row indices rather than the natural keys
+ * themselves. `ProgressJob.meta` is rewritten on every checkpoint and rides every broadcast
+ * frame, so the snapshot's size is paid ~`items.length / checkpointInterval` times over: a key
+ * list costs the summed length of every conflicting key (hundreds of KB for a large re-import),
+ * while one bit per row costs `items.length / 8` bytes whatever the keys look like. The snapshot
+ * cannot be capped — a partial one would let a row claim a record it merely conflicts with — so
+ * it is made small instead.
+ */
+export function encodePriorKeyRows(rowIndices: Iterable<number>, rowCount: number): string {
+  const bytes = new Uint8Array(Math.ceil(Math.max(rowCount, 0) / BITS_PER_BYTE))
+  for (const rowIndex of rowIndices) {
+    if (!Number.isInteger(rowIndex) || rowIndex < 0 || rowIndex >= rowCount) continue
+    bytes[Math.floor(rowIndex / BITS_PER_BYTE)] |= 1 << (rowIndex % BITS_PER_BYTE)
+  }
+  return Buffer.from(bytes).toString('base64')
+}
+
+export function decodePriorKeyRows(value: unknown): ReadonlySet<number> | null {
+  if (typeof value !== 'string') return null
+  const bytes = Buffer.from(value, 'base64')
+  const rowIndices = new Set<number>()
+  bytes.forEach((byte, byteIndex) => {
+    for (let bit = 0; bit < BITS_PER_BYTE; bit += 1) {
+      if (byte & (1 << bit)) rowIndices.add(byteIndex * BITS_PER_BYTE + bit)
+    }
+  })
+  return rowIndices
+}
+
+export function readCheckpointInterval(meta: Record<string, unknown> | null | undefined): number {
+  const raw = isRecord(meta) ? meta.checkpointInterval : undefined
+  if (typeof raw !== 'number' || !Number.isInteger(raw) || raw < 1) return DEFAULT_CHECKPOINT_INTERVAL
+  return raw
+}
+
+/**
+ * Restores the accumulated batch state a previous attempt persisted, so a resumed run reports
+ * a summary covering the whole batch instead of only the rows after the checkpoint. Every field
+ * is validated independently: a job whose meta predates this shape, or was hand-edited, resumes
+ * from whatever it can prove rather than throwing.
+ */
+export function readCheckpoint<TFailure>(
+  meta: Record<string, unknown> | null | undefined,
+): BulkCreateCheckpoint<TFailure> {
+  const empty: BulkCreateCheckpoint<TFailure> = {
+    lastCompletedRowIndex: -1,
+    createdCount: 0,
+    failedCount: 0,
+    createdIds: [],
+    failedItems: [],
+    priorKeyRows: null,
+  }
+  if (!isRecord(meta)) return empty
+
+  const priorKeyRows = decodePriorKeyRows(meta.priorKeyRows)
+
+  const lastCompletedRowIndex = typeof meta.lastCompletedRowIndex === 'number' && Number.isInteger(meta.lastCompletedRowIndex)
+    ? meta.lastCompletedRowIndex
+    : -1
+  if (lastCompletedRowIndex < 0) return { ...empty, priorKeyRows }
+
+  const summary = isRecord(meta.checkpointSummary) ? meta.checkpointSummary : null
+  if (!summary) return { ...empty, lastCompletedRowIndex, priorKeyRows }
+
+  // `createdIds` is no longer checkpointed (it grew with the batch and was rewritten on every
+  // checkpoint), but a job enqueued before that change can still be mid-flight, so keep reading it.
+  const createdIds = readStringArray(summary.createdIds)
+  const failedItems = Array.isArray(summary.failedItems)
+    ? (summary.failedItems.filter(isRecord) as TFailure[])
+    : []
+  const createdCount = typeof summary.createdCount === 'number' && Number.isInteger(summary.createdCount)
+    ? summary.createdCount
+    : createdIds.length
+  const failedCount = typeof summary.failedCount === 'number' && Number.isInteger(summary.failedCount)
+    ? summary.failedCount
+    : failedItems.length
+
+  return { lastCompletedRowIndex, createdCount, failedCount, createdIds, failedItems, priorKeyRows }
+}
+
+export type ResumeIndex = {
+  priorKeyRows: ReadonlySet<number> | null
+  existingKeyIds: ReadonlyMap<string, string>
+  firstRowIndexByKey: ReadonlyMap<string, number>
+}
+
+/**
+ * Maps each natural key to the first row in the batch that carries it, so a resumed attempt can
+ * tell the row that created a record from a later row that merely repeats its key. Every key a
+ * row could be identified by is registered, not just the one it is reclaimed under: a record
+ * created for a row's SKU is also reachable by that row's handle, and leaving the handle
+ * unregistered would let a later handle-only row claim it.
+ */
+export function buildFirstRowIndexByKey<TRow>(
+  items: readonly TRow[],
+  naturalKeysOf: (row: TRow) => readonly string[],
+): Map<string, number> {
+  const firstRowIndexByKey = new Map<string, number>()
+  items.forEach((item, index) => {
+    for (const key of naturalKeysOf(item)) {
+      if (!firstRowIndexByKey.has(key)) firstRowIndexByKey.set(key, index)
+    }
+  })
+  return firstRowIndexByKey
+}
+
+/**
+ * Returns the id of the record a previous attempt of this job created for `rowIndex`, or `null`
+ * when nothing can be proven and the row must go through the normal creation path.
+ *
+ * The classification is deliberately conservative — it never infers one row's outcome from
+ * another's, because a row that failed mid-batch leaves nothing behind and would poison any
+ * ordering assumption:
+ *
+ * - Only a resumed attempt reclaims rows at all. The signal is the presence of the snapshot the
+ *   first attempt recorded, not the checkpoint cursor: an attempt can persist the snapshot and
+ *   then die before any checkpoint lands, and the rows it created in between still have to be
+ *   reclaimable.
+ * - Only a genuinely unique natural key counts. A row identified by title or name could match an
+ *   unrelated record, and skipping it would drop it from the batch entirely.
+ * - A row whose key already existed before the first attempt points at somebody else's record: it
+ *   is a real conflict and must be reported as one rather than counted as created.
+ * - Only the first row carrying a key can claim the record; a later row repeating it is an
+ *   intra-batch duplicate and belongs in the conflict path.
+ * - A record an earlier row of this batch already claimed is never handed to a second row, so two
+ *   rows can never both count the same id as their own creation.
+ */
+export function findRecordCreatedByPreviousAttempt(
+  index: ResumeIndex,
+  rowIndex: number,
+  naturalKey: string | null,
+  alreadyReclaimedIds: ReadonlySet<string>,
+): string | null {
+  if (naturalKey === null || index.priorKeyRows === null) return null
+  if (index.priorKeyRows.has(rowIndex)) return null
+  if (index.firstRowIndexByKey.get(naturalKey) !== rowIndex) return null
+  const recordId = index.existingKeyIds.get(naturalKey)
+  if (recordId === undefined || alreadyReclaimedIds.has(recordId)) return null
+  return recordId
+}

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

@@ -0,0 +1,62 @@
+import { getAllMutationGuardInstances } from '@open-mercato/shared/lib/crud/mutation-guard-store'
+import {
+  bridgeLegacyGuard,
+  runMutationGuards,
+} from '@open-mercato/shared/lib/crud/mutation-guard-registry'
+import type { AwilixContainer } from 'awilix'
+
+export type BulkCreateGuardDecision =
+  | { ok: true }
+  | { ok: false; body: Record<string, unknown>; status: number }
+
+function resolveUserFeatures(auth: unknown): string[] {
+  const features = (auth as { features?: unknown })?.features
+  if (!Array.isArray(features)) return []
+  return features.filter((value): value is string => typeof value === 'string')
+}
+
+/**
+ * Runs the registered mutation guards for a bulk-create request before the batch is enqueued,
+ * so a guard that would block a single `create` blocks the batch version of the same write.
+ *
+ * The guarded unit is the batch envelope, not the individual rows: the rows are created later,
+ * by a queue worker, from a context that has no request headers and no resource ids to offer a
+ * guard. For the same reason `afterSuccess` callbacks are not invoked here — there is no created
+ * record to report at enqueue time, and the request is gone by the time there is one. A guard
+ * that needs per-record post-processing has to subscribe to `catalog.product.created` /
+ * `catalog.category.created` instead.
+ */
+export async function runBulkCreateMutationGuards(params: {
+  container: AwilixContainer
+  auth: unknown
+  request: Request
+  tenantId: string
+  organizationId: string
+  userId: string
+  resourceKind: string
+  itemCount: number
+}): Promise<BulkCreateGuardDecision> {
+  const legacyGuard = bridgeLegacyGuard(params.container)
+  const guards = [...getAllMutationGuardInstances(), ...(legacyGuard ? [legacyGuard] : [])]
+  const result = await runMutationGuards(
+    guards,
+    {
+      tenantId: params.tenantId,
+      organizationId: params.organizationId,
+      userId: params.userId,
+      resourceKind: params.resourceKind,
+      resourceId: null,
+      operation: 'create',
+      requestMethod: params.request.method,
+      requestHeaders: params.request.headers,
+      mutationPayload: { bulk: true, itemCount: params.itemCount },
+    },
+    { userFeatures: resolveUserFeatures(params.auth) },
+  )
+  if (result.ok) return { ok: true }
+  return {
+    ok: false,
+    body: result.errorBody ?? { error: '[internal] Bulk create blocked by a mutation guard.' },
+    status: result.errorStatus ?? 422,
+  }
+}

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

@@ -0,0 +1,340 @@
+import type { AwilixContainer } from 'awilix'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { CommandBus, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { CatalogProduct } from '../data/entities'
+import type { ProductBulkCreateRow } from '../data/validators'
+import type { ProgressService, ProgressServiceContext } from '../../progress/lib/progressService'
+import {
+  MAX_CHECKPOINTED_FAILURES,
+  buildFirstRowIndexByKey,
+  encodePriorKeyRows,
+  findRecordCreatedByPreviousAttempt,
+  readCheckpoint,
+  readCheckpointInterval,
+} from './bulkCreateCheckpoint'
+
+export const CATALOG_PRODUCT_BULK_CREATE_QUEUE = 'catalog-product-bulk-create'
+
+export { getCatalogQueue } from './catalogQueue'
+
+export type CatalogProductBulkCreateFailureCode = 'sku_taken' | 'handle_taken' | 'command_failed'
+
+export type CatalogProductBulkCreateScope = {
+  organizationId: string
+  tenantId: string
+  userId?: string | null
+}
+
+export type CatalogProductBulkCreateJobPayload = {
+  progressJobId: string
+  items: ProductBulkCreateRow[]
+  scope: CatalogProductBulkCreateScope
+}
+
+export type CatalogProductBulkCreateFailure = {
+  index: number
+  title?: string
+  code: CatalogProductBulkCreateFailureCode
+  message: string
+}
+
+export type CatalogProductBulkCreateSummary = {
+  createdCount: number
+  failedCount: number
+  /**
+   * Not a complete list on a resumed run: it covers the rows the final attempt handled, while
+   * `createdCount` covers the whole batch. Iterate it for the ids it does carry, never as a
+   * substitute for `createdCount`.
+   */
+  createdIds: string[]
+  failedItems: CatalogProductBulkCreateFailure[]
+}
+
+function buildCommandContext(
+  scope: CatalogProductBulkCreateScope,
+  container: AwilixContainer,
+): CommandRuntimeContext {
+  return {
+    container,
+    auth: null,
+    organizationScope: {
+      selectedId: scope.organizationId,
+      filterIds: [scope.organizationId],
+      allowedIds: [scope.organizationId],
+      tenantId: scope.tenantId,
+    },
+    selectedOrganizationId: scope.organizationId,
+    organizationIds: [scope.organizationId],
+  }
+}
+
+function normalizeForLookup(value?: string | null): string | null {
+  if (typeof value !== 'string') return null
+  const trimmed = value.trim()
+  return trimmed.length ? trimmed : null
+}
+
+// Namespaced so a sku can never be confused with a handle that happens to spell the same string.
+function skuKey(sku: string): string {
+  return `sku:${sku}`
+}
+
+function handleKey(handle: string): string {
+  return `handle:${handle}`
+}
+
+/**
+ * Every key the row's product could be found under. `title` is deliberately absent: it carries no
+ * uniqueness constraint, so matching on it would let one row claim an unrelated product and
+ * silently drop itself from the batch.
+ */
+function naturalKeysOfRow(row: ProductBulkCreateRow): string[] {
+  const keys: string[] = []
+  const sku = normalizeForLookup(row.sku ?? null)
+  if (sku) keys.push(skuKey(sku))
+  const handle = normalizeForLookup(row.handle ?? null)
+  if (handle) keys.push(handleKey(handle))
+  return keys
+}
+
+/** The one key a row's record is reclaimed under on a resumed attempt; SKU wins when both exist. */
+function naturalKeyOfRow(row: ProductBulkCreateRow): string | null {
+  return naturalKeysOfRow(row)[0] ?? null
+}
+
+export async function createCatalogProductsWithProgress(params: {
+  container: AwilixContainer
+  progressJobId: string
+  items: ProductBulkCreateRow[]
+  scope: CatalogProductBulkCreateScope
+}): Promise<CatalogProductBulkCreateSummary> {
+  const { container, progressJobId, items, scope } = params
+  const commandBus = container.resolve('commandBus') as CommandBus
+  const progressService = container.resolve('progressService') as ProgressService
+  const em = container.resolve('em') as EntityManager
+  const progressContext: ProgressServiceContext = {
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    userId: scope.userId,
+  }
+
+  const existingJob = await progressService.getJob(progressJobId, progressContext)
+  const priorCheckpoint = readCheckpoint<CatalogProductBulkCreateFailure>(existingJob?.meta)
+  const checkpointInterval = readCheckpointInterval(existingJob?.meta)
+  const startIndex = priorCheckpoint.lastCompletedRowIndex + 1
+
+  await progressService.startJob(progressJobId, progressContext)
+
+  // Batch pre-validation: fail rows referencing an already-taken sku or handle before ever
+  // calling the command, saving a DB round-trip for rows that are provably invalid up front.
+  // The same two queries also produce the key -> id map a resumed attempt uses to reclaim the
+  // records an interrupted attempt already created, so resume costs no extra query.
+  const distinctSkus = Array.from(new Set(
+    items
+      .map((item) => normalizeForLookup(item.sku ?? null))
+      .filter((value): value is string => value !== null),
+  ))
+  const distinctHandles = Array.from(new Set(
+    items
+      .map((item) => normalizeForLookup(item.handle ?? null))
+      .filter((value): value is string => value !== null),
+  ))
+  const existingKeyIds = new Map<string, string>()
+  const existingSkus = new Set<string>()
+  const existingHandles = new Set<string>()
+  if (distinctSkus.length) {
+    const rows = await em.find(CatalogProduct, {
+      sku: { $in: distinctSkus },
+      organizationId: scope.organizationId,
+      tenantId: scope.tenantId,
+      deletedAt: null,
+    })
+    for (const product of rows) {
+      const sku = product.sku as string
+      existingSkus.add(sku)
+      existingKeyIds.set(skuKey(sku), product.id)
+    }
+  }
+  if (distinctHandles.length) {
+    const rows = await em.find(CatalogProduct, {
+      handle: { $in: distinctHandles },
+      organizationId: scope.organizationId,
+      tenantId: scope.tenantId,
+      deletedAt: null,
+    })
+    for (const product of rows) {
+      const handle = product.handle as string
+      existingHandles.add(handle)
+      existingKeyIds.set(handleKey(handle), product.id)
+    }
+  }
+
+  // Recorded once, on the attempt that starts from row 0, and read back verbatim by every later
+  // attempt: after rows have been created the database can no longer tell which keys predate the
+  // job. This write rides the attempt's first `updateProgress`, which always persists (a fresh
+  // throttle entry has no last-persisted timestamp to throttle against), so it is durable before
+  // any row is created. A row counts as pre-existing when *any* of its keys is already taken, so a
+  // row whose handle is spoken for is never reclaimed on the strength of its free SKU.
+  const isFirstAttempt = priorCheckpoint.priorKeyRows === null
+  const priorKeyRowIndices: number[] = []
+  if (isFirstAttempt) {
+    items.forEach((item, index) => {
+      if (naturalKeysOfRow(item).some((key) => existingKeyIds.has(key))) priorKeyRowIndices.push(index)
+    })
+  }
+  await progressService.updateProgress(
+    progressJobId,
+    {
+      totalCount: items.length,
+      processedCount: startIndex,
+      ...(isFirstAttempt ? { meta: { priorKeyRows: encodePriorKeyRows(priorKeyRowIndices, items.length) } } : {}),
+    },
+    progressContext,
+  )
+
+  const resumeIndex = {
+    priorKeyRows: priorCheckpoint.priorKeyRows,
+    existingKeyIds,
+    firstRowIndexByKey: buildFirstRowIndexByKey(items, naturalKeysOfRow),
+  }
+  const reclaimedIds = new Set<string>()
+
+  const commandContext = buildCommandContext(scope, container)
+  // Seeded from the previous attempt's checkpoint so a resumed run's summary covers the whole
+  // batch rather than only the rows after the last durable checkpoint (see
+  // lib/bulkCreateCategories.ts for the failure this prevents).
+  const createdIds: string[] = [...priorCheckpoint.createdIds]
+  const failedItems: CatalogProductBulkCreateFailure[] = [...priorCheckpoint.failedItems]
+  let createdCount = priorCheckpoint.createdCount
+  let failedCount = priorCheckpoint.failedCount
+
+  const recordFailure = (failure: CatalogProductBulkCreateFailure) => {
+    failedItems.push(failure)
+    failedCount += 1
+  }
+
+  const buildSummary = (): CatalogProductBulkCreateSummary => ({
+    createdCount,
+    failedCount,
+    createdIds,
+    failedItems,
+  })
+
+  const checkpoint = async (index: number) => {
+    const processedCount = index + 1
+    if (processedCount % checkpointInterval === 0 || processedCount === items.length) {
+      await progressService.updateProgress(
+        progressJobId,
+        {
+          processedCount,
+          meta: {
+            lastCompletedRowIndex: index,
+            checkpointSummary: {
+              createdCount,
+              failedCount,
+              failedItems: failedItems.slice(0, MAX_CHECKPOINTED_FAILURES),
+            },
+          },
+        },
+        progressContext,
+      )
+    }
+  }
+
+  for (let index = startIndex; index < items.length; index += 1) {
+    // Polled at the head of the iteration and only on the checkpoint boundary — see
+    // lib/bulkCreateCategories.ts for the reasoning.
+    if ((index - startIndex) % checkpointInterval === 0) {
+      const cancelled = await progressService.isCancellationRequested(
+        progressJobId,
+        scope.tenantId,
+        scope.organizationId,
+      )
+      if (cancelled) {
+        const partialSummary = buildSummary()
+        await progressService.updateProgress(
+          progressJobId,
+          { meta: { resultSummary: partialSummary } },
+          progressContext,
+        )
+        await progressService.markCancelled(progressJobId, progressContext)
+        return partialSummary
+      }
+    }
+
+    const row = items[index]
+    const sku = normalizeForLookup(row.sku ?? null)
+    const handle = normalizeForLookup(row.handle ?? null)
+
+    // Reclaims a record an interrupted attempt of this job already created for this exact row,
+    // so it is neither duplicated nor reported as a conflict against itself. Every other row
+    // falls through to the normal path, including rows the classifier cannot speak for.
+    const reclaimedId = findRecordCreatedByPreviousAttempt(resumeIndex, index, naturalKeyOfRow(row), reclaimedIds)
+    if (reclaimedId) {
+      reclaimedIds.add(reclaimedId)
+      createdIds.push(reclaimedId)
+      createdCount += 1
+      await checkpoint(index)
+      continue
+    }
+
+    if (sku && existingSkus.has(sku)) {
+      recordFailure({
+        index,
+        title: row.title,
+        code: 'sku_taken',
+        message: 'Product SKU already exists for this organization.',
+      })
+      await checkpoint(index)
+      continue
+    }
+    if (handle && existingHandles.has(handle)) {
+      recordFailure({
+        index,
+        title: row.title,
+        code: 'handle_taken',
+        message: 'Product handle already exists for this organization.',
+      })
+      await checkpoint(index)
+      continue
+    }
+
+    try {
+      const { result } = await commandBus.execute<
+        ProductBulkCreateRow & { organizationId: string; tenantId: string },
+        { productId: string }
+      >('catalog.products.create', {
+        input: { ...row, organizationId: scope.organizationId, tenantId: scope.tenantId },
+        ctx: commandContext,
+      })
+      if (result?.productId) {
+        createdIds.push(result.productId)
+        createdCount += 1
+        if (sku) existingSkus.add(sku)
+        if (handle) existingHandles.add(handle)
+      } else {
+        // Recorded rather than dropped so `createdCount + failedCount` always accounts for
+        // every row in the batch.
+        recordFailure({
+          index,
+          title: row.title,
+          code: 'command_failed',
+          message: 'Product creation returned no product id.',
+        })
+      }
+    } catch (error) {
+      recordFailure({
+        index,
+        title: row.title,
+        code: 'command_failed',
+        message: error instanceof Error ? error.message : 'Product creation failed',
+      })
+    }
+
+    await checkpoint(index)
+  }
+
+  const summary = buildSummary()
+  await progressService.completeJob(progressJobId, { resultSummary: summary }, progressContext)
+  return summary
+}

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

@@ -2,12 +2,11 @@ import type { AwilixContainer } from 'awilix'
 import type { CommandBus, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
 import { invalidateCrudCache } from '@open-mercato/shared/lib/crud/cache'
 import { runWithCacheTenant } from '@open-mercato/cache'
-import { createModuleQueue, type Queue } from '@open-mercato/queue'
 import type { ProgressService, ProgressServiceContext } from '../../progress/lib/progressService'
 
 export const CATALOG_PRODUCT_BULK_DELETE_QUEUE = 'catalog-product-bulk-delete'
 
-const queues = new Map<string, Queue<Record<string, unknown>>>()
+export { getCatalogQueue } from './catalogQueue'
 
 export type CatalogProductBulkDeleteScope = {
   organizationId: string
@@ -27,24 +26,21 @@ export type CatalogProductBulkDeleteSummary = {
 
 const BULK_DELETE_CACHE_ALIASES = ['catalog.products']
 
-export function getCatalogQueue(queueName: string): Queue<Record<string, unknown>> {
-  const existing = queues.get(queueName)
-  if (existing) return existing
-
-  const concurrency = Math.max(1, Number.parseInt(process.env.CATALOG_QUEUE_CONCURRENCY ?? '3', 10) || 3)
-  const created = createModuleQueue<Record<string, unknown>>(queueName, { concurrency })
-
-  queues.set(queueName, created)
-  return created
-}
-
 function buildCommandContext(
   scope: CatalogProductBulkDeleteScope,
   container: AwilixContainer,
 ): CommandRuntimeContext {
+  if (!scope.tenantId || !scope.organizationId || !scope.userId) {
+    throw new Error('[internal] Catalog bulk delete requires tenant, organization and user scope')
+  }
   return {
     container,
-    auth: null,
+    auth: {
+      sub: scope.userId,
+      tenantId: scope.tenantId,
+      orgId: scope.organizationId,
+      isSuperAdmin: false,
+    },
     organizationScope: {
       selectedId: scope.organizationId,
       filterIds: [scope.organizationId],

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

@@ -0,0 +1,14 @@
+import { createModuleQueue, type Queue } from '@open-mercato/queue'
+
+const queues = new Map<string, Queue<Record<string, unknown>>>()
+
+export function getCatalogQueue(queueName: string): Queue<Record<string, unknown>> {
+  const existing = queues.get(queueName)
+  if (existing) return existing
+
+  const concurrency = Math.max(1, Number.parseInt(process.env.CATALOG_QUEUE_CONCURRENCY ?? '3', 10) || 3)
+  const created = createModuleQueue<Record<string, unknown>>(queueName, { concurrency })
+
+  queues.set(queueName, created)
+  return created
+}

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

@@ -0,0 +1,28 @@
+import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { CURRENCY_OPTIONS_URL } from '@open-mercato/shared/modules/entities/kinds'
+import type { DictionaryOption } from '@open-mercato/core/modules/dictionaries/components/DictionaryEntrySelect'
+
+const CURRENCY_OPTIONS_LIMIT = 100
+
+type CurrencyOptionsPayload = {
+  items?: unknown
+}
+
+export async function loadCurrencyOptions(errorMessage: string): Promise<DictionaryOption[]> {
+  const payload = await readApiResultOrThrow<CurrencyOptionsPayload>(
+    `${CURRENCY_OPTIONS_URL}?limit=${CURRENCY_OPTIONS_LIMIT}`,
+    undefined,
+    { errorMessage },
+  )
+  const items = Array.isArray(payload?.items) ? payload.items : []
+  const options: DictionaryOption[] = []
+  for (const item of items) {
+    if (!item || typeof item !== 'object') continue
+    const record = item as Record<string, unknown>
+    const value = typeof record.value === 'string' ? record.value.trim().toUpperCase() : ''
+    if (!value) continue
+    const label = typeof record.label === 'string' && record.label.trim().length ? record.label.trim() : value
+    options.push({ value, label, color: null, icon: null })
+  }
+  return options
+}

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

@@ -0,0 +1,16 @@
+import { buildAccentInsensitiveSearchExpression } from '@open-mercato/shared/lib/db/accentInsensitiveSearch'
+
+/**
+ * Columns `GET /api/catalog/products?search=` matches against, in the order the
+ * GIN trigram index concatenates them. The list is shared with
+ * `migrations/Migration20260914120100` so the query predicate and the index
+ * expression cannot drift apart — when they do, PostgreSQL stops using the index
+ * without any error, it just gets slower.
+ *
+ * Property names and column names are identical for all five (single words, no
+ * camelCase), so this list doubles as the field list the encrypted-`ILIKE`
+ * diagnostic needs.
+ */
+export const PRODUCT_SEARCH_COLUMNS = ['title', 'subtitle', 'description', 'sku', 'handle'] as const
+
+export const PRODUCT_SEARCH_EXPRESSION_SQL = buildAccentInsensitiveSearchExpression(PRODUCT_SEARCH_COLUMNS)