@open-mercato/core 0.6.7 → 0.6.8-develop.6875.1.871a4afc94

package/src/modules/data_sync/i18n/ko.json

@@ -0,0 +1,125 @@
+{
+  "data_sync.dashboard.actions.view": "보기",
+  "data_sync.dashboard.columns.created": "생성됨",
+  "data_sync.dashboard.columns.createdAt": "시작됨",
+  "data_sync.dashboard.columns.direction": "방향",
+  "data_sync.dashboard.columns.entityType": "엔터티 유형",
+  "data_sync.dashboard.columns.failed": "실패",
+  "data_sync.dashboard.columns.integration": "통합",
+  "data_sync.dashboard.columns.status": "상태",
+  "data_sync.dashboard.columns.updated": "수정됨",
+  "data_sync.dashboard.direction.export": "내보내기",
+  "data_sync.dashboard.direction.import": "가져오기",
+  "data_sync.dashboard.filters.allDirections": "모든 방향",
+  "data_sync.dashboard.filters.allStatuses": "모든 상태",
+  "data_sync.dashboard.filters.status": "상태",
+  "data_sync.dashboard.loadError": "동기화 실행을 불러오지 못했습니다",
+  "data_sync.dashboard.noRuns": "아직 동기화 실행 기록이 없습니다",
+  "data_sync.dashboard.schedule.cron": "Cron",
+  "data_sync.dashboard.schedule.cronHelp": "예: `0 * * * *`는 매시 정각에 실행됩니다.",
+  "data_sync.dashboard.schedule.cronValue": "Cron 표현식",
+  "data_sync.dashboard.schedule.delete": "일정 제거",
+  "data_sync.dashboard.schedule.deleteError": "반복 일정 제거에 실패했습니다",
+  "data_sync.dashboard.schedule.deleteSuccess": "반복 일정이 제거되었습니다",
+  "data_sync.dashboard.schedule.deleting": "제거 중...",
+  "data_sync.dashboard.schedule.description": "이 대시보드를 벗어나지 않고 선택한 통합, 엔터티, 방향에 대한 반복 일정을 저장하세요.",
+  "data_sync.dashboard.schedule.enabled": "일정 활성화됨",
+  "data_sync.dashboard.schedule.enabledHelp": "일정 정의를 삭제하지 않고 반복 작업을 일시 중지합니다.",
+  "data_sync.dashboard.schedule.error": "반복 일정 저장에 실패했습니다",
+  "data_sync.dashboard.schedule.fullSync": "예약된 작업을 전체 동기화로 실행",
+  "data_sync.dashboard.schedule.fullSyncHelp": "활성화하면 모든 반복 실행이 저장된 커서 대신 처음부터 시작됩니다.",
+  "data_sync.dashboard.schedule.interval": "간격",
+  "data_sync.dashboard.schedule.intervalHelp": "예: 반복 간격으로 `1h`, `6h`, `24h`를 사용하세요.",
+  "data_sync.dashboard.schedule.intervalValue": "간격",
+  "data_sync.dashboard.schedule.invalidValue": "저장하기 전에 일정 값을 입력하세요.",
+  "data_sync.dashboard.schedule.lastRun": "마지막 예약 실행: {value}",
+  "data_sync.dashboard.schedule.neverRun": "저장되었지만 아직 완료된 예약 실행이 없습니다.",
+  "data_sync.dashboard.schedule.none": "이 대상에 대해 저장된 반복 일정이 아직 없습니다.",
+  "data_sync.dashboard.schedule.save": "반복 일정 저장",
+  "data_sync.dashboard.schedule.saving": "저장 중...",
+  "data_sync.dashboard.schedule.status.disabled": "반복 일정 일시 중지됨",
+  "data_sync.dashboard.schedule.status.enabled": "반복 일정 활성",
+  "data_sync.dashboard.schedule.status.none": "반복 일정 없음",
+  "data_sync.dashboard.schedule.status.shortDisabled": "일시 중지됨",
+  "data_sync.dashboard.schedule.status.shortEnabled": "예약됨",
+  "data_sync.dashboard.schedule.status.shortNone": "1회성",
+  "data_sync.dashboard.schedule.success": "반복 일정이 저장되었습니다",
+  "data_sync.dashboard.schedule.timezone": "표준 시간대",
+  "data_sync.dashboard.schedule.title": "반복 일정",
+  "data_sync.dashboard.schedule.type": "일정 유형",
+  "data_sync.dashboard.searchPlaceholder": "통합, 엔터티 유형, 상태 또는 실행 ID로 검색",
+  "data_sync.dashboard.start.batchSize": "배치 크기",
+  "data_sync.dashboard.start.description": "이 페이지에서 동기화 대상을 선택하고, 임시 실행을 시작하거나, 동일한 엔터티와 방향에 대한 반복 일정을 저장하세요.",
+  "data_sync.dashboard.start.error": "동기화 실행을 시작하지 못했습니다",
+  "data_sync.dashboard.start.eyebrow": "한 번만 실행하거나 반복 실행 유지",
+  "data_sync.dashboard.start.fullSync": "전체 동기화로 실행",
+  "data_sync.dashboard.start.fullSyncHelp": "저장된 커서를 무시하고 이 실행에 대해 전체 소스를 다시 처리합니다.",
+  "data_sync.dashboard.start.invalidBatchSize": "배치 크기는 1에서 1000 사이여야 합니다.",
+  "data_sync.dashboard.start.providerManaged": "이 통합은 자체 설정 흐름에서 동기화 실행을 시작합니다. 계속하려면 통합 설정 페이지를 여세요.",
+  "data_sync.dashboard.start.runNowDescription": "다음 즉시 동기화에 사용하세요. 배치 크기와 전체 동기화 모드는 이 수동 실행에만 적용됩니다.",
+  "data_sync.dashboard.start.runNowFootnote": "수동 실행은 즉시 진행 상황을 표시하며 시작 후 실행 상세 페이지로 이동합니다.",
+  "data_sync.dashboard.start.runNowTitle": "지금 한 번 실행",
+  "data_sync.dashboard.start.status.credentialsMissing": "자격 증명 누락",
+  "data_sync.dashboard.start.status.credentialsReady": "자격 증명 준비됨",
+  "data_sync.dashboard.start.status.disabled": "통합 비활성화됨",
+  "data_sync.dashboard.start.status.enabled": "통합 활성화됨",
+  "data_sync.dashboard.start.submit": "동기화 시작",
+  "data_sync.dashboard.start.success": "동기화 실행이 시작되었습니다",
+  "data_sync.dashboard.start.title": "동기화 시작 또는 예약",
+  "data_sync.dashboard.status.cancelled": "취소됨",
+  "data_sync.dashboard.status.completed": "완료됨",
+  "data_sync.dashboard.status.failed": "실패",
+  "data_sync.dashboard.status.paused": "일시 중지됨",
+  "data_sync.dashboard.status.pending": "대기 중",
+  "data_sync.dashboard.status.running": "실행 중",
+  "data_sync.dashboard.title": "동기화 실행",
+  "data_sync.integrationTab.columns.actions": "작업",
+  "data_sync.integrationTab.columns.lastRun": "마지막 실행",
+  "data_sync.integrationTab.columns.value": "값",
+  "data_sync.integrationTab.credentialsMissing": "동기화를 시작하기 전에 자격 증명을 구성하세요.",
+  "data_sync.integrationTab.credentialsMissingNotice": "자격 증명이 아직 없습니다. 원한다면 먼저 일정을 저장할 수 있지만, 자격 증명이 구성될 때까지 수동 및 예약 실행은 실패합니다.",
+  "data_sync.integrationTab.description": "통합 상세 페이지에서 직접 일회성 동기화를 실행하거나 지원되는 모든 엔터티에 대한 반복 일정을 저장하세요.",
+  "data_sync.integrationTab.empty": "이 제공업체는 아직 예약 가능한 동기화 엔터티를 제공하지 않습니다.",
+  "data_sync.integrationTab.fullSyncShort": "전체",
+  "data_sync.integrationTab.integrationDisabled": "동기화를 시작하기 전에 통합을 활성화하세요.",
+  "data_sync.integrationTab.integrationDisabledNotice": "통합이 비활성화되어 있습니다. 지금 일정을 저장할 수 있지만 통합이 활성화될 때까지 실행이 차단됩니다.",
+  "data_sync.integrationTab.loadError": "동기화 일정을 불러오지 못했습니다.",
+  "data_sync.integrationTab.notAvailable": "이 통합은 데이터 동기화 제공업체로 등록되어 있지 않습니다.",
+  "data_sync.integrationTab.providerManaged": "이 통합은 제공업체별 설정 흐름에서 시작하세요.",
+  "data_sync.integrationTab.providerManagedNotice": "이 제공업체는 실행을 시작하기 전에 자체 설정 흐름이 필요합니다. 일반 일정 대신 이 페이지의 제공업체 탭을 사용하세요.",
+  "data_sync.integrationTab.refresh": "새로고침",
+  "data_sync.integrationTab.runError": "동기화 시작에 실패했습니다.",
+  "data_sync.integrationTab.runNowHelp": "지금 실행은 같은 행의 전체 동기화 체크박스를 사용하며 Data Sync에서 즉시 진행 상황 추적을 시작합니다.",
+  "data_sync.integrationTab.runNowTitle": "수동 실행",
+  "data_sync.integrationTab.runStarted": "동기화 실행이 시작되었습니다.",
+  "data_sync.integrationTab.start": "지금 실행",
+  "data_sync.integrationTab.starting": "시작하는 중...",
+  "data_sync.integrationTab.title": "동기화 일정",
+  "data_sync.nav.title": "데이터 동기화",
+  "data_sync.runs.detail.back": "동기화 실행으로 돌아가기",
+  "data_sync.runs.detail.cancel": "취소",
+  "data_sync.runs.detail.cancelError": "동기화 실행 취소에 실패했습니다",
+  "data_sync.runs.detail.cancelSuccess": "동기화 실행이 취소되었습니다",
+  "data_sync.runs.detail.counters.created": "생성됨",
+  "data_sync.runs.detail.counters.failed": "실패",
+  "data_sync.runs.detail.counters.skipped": "건너뜀",
+  "data_sync.runs.detail.counters.updated": "업데이트됨",
+  "data_sync.runs.detail.error": "오류",
+  "data_sync.runs.detail.loadError": "동기화 실행을 불러오지 못했습니다",
+  "data_sync.runs.detail.logs": "작업 로그",
+  "data_sync.runs.detail.logs.level": "레벨",
+  "data_sync.runs.detail.logs.message": "메시지",
+  "data_sync.runs.detail.logs.time": "시간",
+  "data_sync.runs.detail.noLogs": "로그 항목 없음",
+  "data_sync.runs.detail.notFound": "동기화 실행을 찾을 수 없습니다.",
+  "data_sync.runs.detail.progress": "진행 상황",
+  "data_sync.runs.detail.progress.batches": "{count}개 배치",
+  "data_sync.runs.detail.progress.eta": "{eta} 남음",
+  "data_sync.runs.detail.progress.itemsProcessed": "{count}개 항목 처리됨",
+  "data_sync.runs.detail.progress.itemsProcessedTotal": "{total}개 중 {processed}개 항목 처리됨",
+  "data_sync.runs.detail.progress.percent": "{percent}% 완료",
+  "data_sync.runs.detail.retry": "재시도",
+  "data_sync.runs.detail.retryError": "동기화 실행 재시도에 실패했습니다",
+  "data_sync.runs.detail.retrySuccess": "동기화 실행이 재시도되었습니다",
+  "data_sync.runs.detail.title": "동기화 실행"
+}

package/src/modules/data_sync/lib/adapter.ts

@@ -104,6 +104,24 @@ export interface DataSyncAdapter {
   readonly runMode?: 'generic' | 'provider'
   readonly operationalTelemetry?: boolean
 
+  /**
+   * Batch work MUST be replay-safe.
+   *
+   * Sync jobs are delivered at least once: BullMQ redelivers a job whose lock
+   * was not renewed, and the engine resumes the run from its last committed
+   * cursor. A batch the generator already yielded can therefore be produced and
+   * executed again, and the engine only fences its own commit — anything the
+   * generator itself did before yielding has already happened.
+   *
+   * Upserts keyed by `externalId` satisfy this. Per-record side effects that are
+   * not idempotent (sending mail, posting to a third party, incrementing a
+   * remote counter) do not, and will run twice on a resume. Make them
+   * conditional on state the adapter can re-read, or move them behind an event
+   * the engine emits after the commit.
+   *
+   * `cursor` is a resume position, not an identity: repeating it between batches
+   * is allowed.
+   */
   streamImport?(input: StreamImportInput): AsyncIterable<ImportBatch>
   streamExport?(input: StreamExportInput): AsyncIterable<ExportBatch>
   getInitialCursor?(input: { entityType: string; scope: TenantScope }): Promise<string | null>

package/src/modules/data_sync/lib/queue-policy.ts

@@ -0,0 +1,30 @@
+/**
+ * Queue names whose jobs resume an existing SyncRun instead of starting a fresh
+ * one. The workers import these to declare their `metadata.queue`, so a rename
+ * cannot silently drop the retry policy.
+ */
+export const DATA_SYNC_IMPORT_QUEUE = 'data-sync-import'
+export const DATA_SYNC_EXPORT_QUEUE = 'data-sync-export'
+
+export const DATA_SYNC_RESUMABLE_QUEUES: readonly string[] = [DATA_SYNC_IMPORT_QUEUE, DATA_SYNC_EXPORT_QUEUE]
+
+export const DATA_SYNC_QUEUE_ATTEMPTS = 3
+
+/**
+ * A backfill batch can hold the processor well past BullMQ's 30s default lock,
+ * so these jobs stall on slow upstreams even when the worker is perfectly
+ * healthy. `DATA_SYNC_LOCK_DURATION_MS` is the primary defence — it stops most
+ * of those false stalls at the source rather than reacting to them.
+ *
+ * `DATA_SYNC_MAX_STALLED_COUNT` covers what is left. BullMQ fails a job once it
+ * stalls more than this many times, and at the default of 1 a single stall
+ * during a long backfill discards the run permanently. 10 buys enough
+ * redeliveries to survive a rolling restart. Raising it is only safe because a
+ * duplicate delivery can no longer corrupt the run: the ownership
+ * compare-and-swap in `commitBatchProgress` lets exactly one worker advance a
+ * run, and every other delivery aborts on its first commit. A job that poisons its
+ * worker still dies — after 10 stalls, with the run left `running` and its
+ * cursor unmoved, which is the state the admin runs list surfaces.
+ */
+export const DATA_SYNC_LOCK_DURATION_MS = 120_000
+export const DATA_SYNC_MAX_STALLED_COUNT = 10

package/src/modules/data_sync/lib/queue.ts

@@ -1,13 +1,31 @@
 import { createModuleQueue, type Queue } from '@open-mercato/queue'
+import {
+  DATA_SYNC_LOCK_DURATION_MS,
+  DATA_SYNC_MAX_STALLED_COUNT,
+  DATA_SYNC_QUEUE_ATTEMPTS,
+  DATA_SYNC_RESUMABLE_QUEUES,
+} from './queue-policy'
 
 const queues = new Map<string, Queue<Record<string, unknown>>>()
 
+const resumableQueueNames = new Set<string>(DATA_SYNC_RESUMABLE_QUEUES)
+
 export function getSyncQueue(queueName: string): Queue<Record<string, unknown>> {
   const existing = queues.get(queueName)
   if (existing) return existing
 
   const concurrency = Math.max(1, Number.parseInt(process.env.DATA_SYNC_QUEUE_CONCURRENCY ?? '5', 10) || 5)
-  const created = createModuleQueue<Record<string, unknown>>(queueName, { concurrency })
+  const created = createModuleQueue<Record<string, unknown>>(
+    queueName,
+    resumableQueueNames.has(queueName)
+      ? {
+        concurrency,
+        attempts: DATA_SYNC_QUEUE_ATTEMPTS,
+        lockDuration: DATA_SYNC_LOCK_DURATION_MS,
+        maxStalledCount: DATA_SYNC_MAX_STALLED_COUNT,
+      }
+      : { concurrency },
+  )
 
   queues.set(queueName, created)
   return created

package/src/modules/data_sync/lib/start-run.ts

@@ -1,6 +1,7 @@
 import type { ProgressService } from '../../progress/lib/progressService'
 import type { SyncRunService } from './sync-run-service'
 import { getSyncQueue } from './queue'
+import { DATA_SYNC_EXPORT_QUEUE, DATA_SYNC_IMPORT_QUEUE } from './queue-policy'
 
 export type DataSyncStartScope = {
   organizationId: string
@@ -71,7 +72,7 @@ export async function startDataSyncRun(params: {
     },
   )
 
-  const queueName = input.direction === 'import' ? 'data-sync-import' : 'data-sync-export'
+  const queueName = input.direction === 'import' ? DATA_SYNC_IMPORT_QUEUE : DATA_SYNC_EXPORT_QUEUE
   const queue = getSyncQueue(queueName)
   await queue.enqueue({
     runId: run.id,

package/src/modules/data_sync/lib/sync-engine.ts

@@ -9,6 +9,7 @@ import { emitDataSyncEvent } from '../events'
 import type { DataSyncAdapter, DataMapping, ExportBatch, ImportBatch } from './adapter'
 import { getDataSyncAdapter } from './adapter-registry'
 import type { SyncRunService } from './sync-run-service'
+import { SyncRunOwnershipConflictError } from './sync-run-service'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 
 const logger = createLogger('data_sync').child({ component: 'sync-engine' })
@@ -236,6 +237,21 @@ export function createSyncEngine(deps: EngineDeps) {
       return
     }
 
+    if (run.status !== status) {
+      // `markStatus` refuses a terminal -> different-terminal transition and
+      // returns the row unchanged, so the run is already finished under another
+      // delivery of this job. Everything below — the progress job, the
+      // operational log and the lifecycle event — would describe the wrong
+      // outcome, and `data_sync.run.failed` is dispatched to tenant webhooks.
+      // A displaced worker stays silent instead.
+      logger.warn('Skipping finalization of a sync run another worker already finalized', {
+        runId,
+        requestedStatus: status,
+        actualStatus: run.status,
+      })
+      return
+    }
+
     if (run.progressJobId) {
       if (status === 'completed') {
         await progressService.completeJob(
@@ -408,6 +424,10 @@ export function createSyncEngine(deps: EngineDeps) {
         throw new Error(`Integration ${run.integrationId} is missing credentials`)
       }
 
+      // A run already `running` means a stalled job was redelivered, so this is
+      // a resume rather than a first start. Consumers see one `started` event per
+      // delivery either way; the flag is what lets them tell the two apart.
+      const resumed = run.status === 'running'
       const activeRun = await syncRunService.markStatus(run.id, 'running', scope)
       if (!activeRun || activeRun.status !== 'running') {
         return
@@ -417,6 +437,7 @@ export function createSyncEngine(deps: EngineDeps) {
         integrationId: run.integrationId,
         entityType: run.entityType,
         direction: run.direction,
+        resumed,
         tenantId: scope.tenantId,
         organizationId: scope.organizationId,
       })
@@ -452,6 +473,7 @@ export function createSyncEngine(deps: EngineDeps) {
       const mapping = await resolveMapping(adapter, run.entityType, scope)
       let processedCount = 0
       let totalCount: number | null = null
+      let committedBatches = activeRun.batchesCompleted ?? 0
 
       try {
         for await (const batch of adapter.streamImport({
@@ -481,7 +503,9 @@ export function createSyncEngine(deps: EngineDeps) {
             },
             batch.cursor,
             scope,
+            committedBatches,
           )
+          committedBatches += 1
 
           await updateProgress(run.progressJobId, processedCount, totalCount, scope)
           await refreshCoverageSnapshots(batch.refreshCoverageEntityTypes, scope)
@@ -507,6 +531,13 @@ export function createSyncEngine(deps: EngineDeps) {
           })
         }
       } catch (error) {
+        if (error instanceof SyncRunOwnershipConflictError) {
+          logger.warn('Yielding import run to a concurrent worker that already advanced it', {
+            runId: run.id,
+            expectedBatchesCompleted: error.expectedBatchesCompleted,
+          })
+          return
+        }
         const message = error instanceof Error ? error.message : 'Sync import failed'
         await integrationLogService.write(
           {
@@ -553,6 +584,10 @@ export function createSyncEngine(deps: EngineDeps) {
         throw new Error(`Integration ${run.integrationId} is missing credentials`)
       }
 
+      // A run already `running` means a stalled job was redelivered, so this is
+      // a resume rather than a first start. Consumers see one `started` event per
+      // delivery either way; the flag is what lets them tell the two apart.
+      const resumed = run.status === 'running'
       const activeRun = await syncRunService.markStatus(run.id, 'running', scope)
       if (!activeRun || activeRun.status !== 'running') {
         return
@@ -562,6 +597,7 @@ export function createSyncEngine(deps: EngineDeps) {
         integrationId: run.integrationId,
         entityType: run.entityType,
         direction: run.direction,
+        resumed,
         tenantId: scope.tenantId,
         organizationId: scope.organizationId,
       })
@@ -596,6 +632,7 @@ export function createSyncEngine(deps: EngineDeps) {
 
       const mapping = await resolveMapping(adapter, run.entityType, scope)
       let processedCount = 0
+      let committedBatches = activeRun.batchesCompleted ?? 0
 
       try {
         for await (const batch of adapter.streamExport({
@@ -626,7 +663,9 @@ export function createSyncEngine(deps: EngineDeps) {
             },
             batch.cursor,
             scope,
+            committedBatches,
           )
+          committedBatches += 1
           await updateProgress(run.progressJobId, processedCount, null, scope)
           await logExportItemFailures(run.id, run.integrationId, batch.results, scope)
 
@@ -647,6 +686,13 @@ export function createSyncEngine(deps: EngineDeps) {
           })
         }
       } catch (error) {
+        if (error instanceof SyncRunOwnershipConflictError) {
+          logger.warn('Yielding export run to a concurrent worker that already advanced it', {
+            runId: run.id,
+            expectedBatchesCompleted: error.expectedBatchesCompleted,
+          })
+          return
+        }
         const message = error instanceof Error ? error.message : 'Sync export failed'
         await integrationLogService.write(
           {

package/src/modules/data_sync/lib/sync-run-service.ts

@@ -26,6 +26,27 @@ type SyncScope = {
   tenantId: string
 }
 
+/**
+ * Raised when a batch commit loses the ownership compare-and-swap, meaning
+ * another delivery of the same job advanced the run while this worker was
+ * streaming.
+ *
+ * BullMQ guarantees at-least-once delivery: a job whose lock is not renewed is
+ * redelivered under the SAME job id, whether the previous worker died or is only
+ * blocked. No identity token can tell those apart, so ownership is enforced here
+ * — on the write that matters — instead of at claim time. The loser aborts and
+ * leaves the run to the worker that is still making progress.
+ */
+export class SyncRunOwnershipConflictError extends Error {
+  constructor(
+    readonly runId: string,
+    readonly expectedBatchesCompleted: number,
+  ) {
+    super(`[internal] Sync run ${runId} advanced past batch ${expectedBatchesCompleted} under a concurrent worker`)
+    this.name = 'SyncRunOwnershipConflictError'
+  }
+}
+
 export function createSyncRunService(em: EntityManager) {
   async function resolveCursorRow(run: SyncRun, scope: SyncScope): Promise<SyncCursor | null> {
     return findOneWithDecryption(
@@ -150,7 +171,11 @@ export function createSyncRunService(em: EntityManager) {
             organizationId: scope.organizationId,
             tenantId: scope.tenantId,
             deletedAt: null,
-            status: 'pending',
+            // A BullMQ stalled-job redelivery finds the run in `running` after
+            // the previous worker was hard-killed. Treat that transition as an
+            // idempotent claim while still excluding terminal states so a
+            // cancelled or completed run cannot be revived.
+            status: { $in: ['pending', 'running'] },
           },
           {
             status,
@@ -178,6 +203,12 @@ export function createSyncRunService(em: EntityManager) {
       return row
     },
 
+    /**
+     * @deprecated Use {@link commitBatchProgress}, which writes counters and
+     * cursor in one transaction behind the ownership fence. This method updates
+     * counters unfenced, so two deliveries of the same job can lose each other's
+     * increments. Kept for external callers only.
+     */
     async updateCounts(
       runId: string,
       delta: Partial<Pick<SyncRun, 'createdCount' | 'updatedCount' | 'skippedCount' | 'failedCount' | 'batchesCompleted'>>,
@@ -195,6 +226,11 @@ export function createSyncRunService(em: EntityManager) {
       return row
     },
 
+    /**
+     * @deprecated Use {@link commitBatchProgress}. This method advances the
+     * cursor without the ownership fence, so a stale delivery can move the
+     * cursor of a run another worker owns. Kept for external callers only.
+     */
     async updateCursor(runId: string, cursor: string, scope: SyncScope): Promise<void> {
       const run = await this.getRun(runId, scope)
       if (!run) return
@@ -204,16 +240,61 @@ export function createSyncRunService(em: EntityManager) {
       ], { transaction: true })
     },
 
+    /**
+     * Commits one batch's counters and cursor in a single transaction.
+     *
+     * Passing `expectedBatchesCompleted` fences the write: the run must still be
+     * `running` and still sit on that batch count, or another delivery of the
+     * same BullMQ job owns the run and this commit throws
+     * `SyncRunOwnershipConflictError` and rolls back. Omitting it keeps the
+     * legacy unguarded write for callers outside the engine.
+     *
+     * The fence token is `batchesCompleted` rather than `cursor` because it
+     * advances by construction on every commit. A cursor is a free-form adapter
+     * string that an adapter may legitimately repeat between batches — the
+     * Akeneo products adapter does, between its final page and the
+     * reconciliation batch that follows it — and a repeated token fences
+     * nothing.
+     *
+     * The guard's `UPDATE` also holds the row lock for the rest of the
+     * transaction, so a competing commit blocks here and then re-reads the
+     * advanced count instead of interleaving with this one. That is what lets
+     * the counters below stay a plain read-modify-write against the snapshot
+     * read above: a commit that wins the fence has proven that nothing else
+     * landed since it read.
+     */
     async commitBatchProgress(
       runId: string,
       delta: Partial<Pick<SyncRun, 'createdCount' | 'updatedCount' | 'skippedCount' | 'failedCount' | 'batchesCompleted'>>,
       cursor: string,
       scope: SyncScope,
+      expectedBatchesCompleted?: number,
     ): Promise<SyncRun | null> {
       const run = await this.getRun(runId, scope)
       if (!run) return null
       const cursorRow = await resolveCursorRow(run, scope)
+      const claimRunOwnership = async () => {
+        if ((delta.batchesCompleted ?? 0) < 1) {
+          throw new Error(`[internal] A fenced commit for sync run ${runId} must advance batchesCompleted`)
+        }
+        const owned = await em.nativeUpdate(
+          SyncRun,
+          {
+            id: runId,
+            organizationId: scope.organizationId,
+            tenantId: scope.tenantId,
+            deletedAt: null,
+            status: 'running',
+            batchesCompleted: expectedBatchesCompleted,
+          },
+          { updatedAt: new Date() },
+        )
+        if (owned === 0) {
+          throw new SyncRunOwnershipConflictError(runId, expectedBatchesCompleted ?? 0)
+        }
+      }
       await withAtomicFlush(em, [
+        ...(expectedBatchesCompleted === undefined ? [] : [claimRunOwnership]),
         () => {
           run.createdCount += delta.createdCount ?? 0
           run.updatedCount += delta.updatedCount ?? 0

package/src/modules/data_sync/workers/sync-export.ts

@@ -2,6 +2,11 @@ import type { JobContext, QueuedJob, WorkerMeta } from '@open-mercato/queue'
 import type { ProgressService } from '../../progress/lib/progressService'
 import type { SyncEngine } from '../lib/sync-engine'
 import type { SyncRunService } from '../lib/sync-run-service'
+import {
+  DATA_SYNC_EXPORT_QUEUE,
+  DATA_SYNC_LOCK_DURATION_MS,
+  DATA_SYNC_MAX_STALLED_COUNT,
+} from '../lib/queue-policy'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 
 const logger = createLogger('data_sync').child({ component: 'sync-export' })
@@ -17,9 +22,11 @@ type SyncJobPayload = {
 }
 
 export const metadata: WorkerMeta = {
-  queue: 'data-sync-export',
+  queue: DATA_SYNC_EXPORT_QUEUE,
   id: 'data-sync:export',
   concurrency: 5,
+  lockDuration: DATA_SYNC_LOCK_DURATION_MS,
+  maxStalledCount: DATA_SYNC_MAX_STALLED_COUNT,
 }
 
 type HandlerContext = JobContext & {

package/src/modules/data_sync/workers/sync-import.ts

@@ -2,6 +2,11 @@ import type { JobContext, QueuedJob, WorkerMeta } from '@open-mercato/queue'
 import type { ProgressService } from '../../progress/lib/progressService'
 import type { SyncEngine } from '../lib/sync-engine'
 import type { SyncRunService } from '../lib/sync-run-service'
+import {
+  DATA_SYNC_IMPORT_QUEUE,
+  DATA_SYNC_LOCK_DURATION_MS,
+  DATA_SYNC_MAX_STALLED_COUNT,
+} from '../lib/queue-policy'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 
 const logger = createLogger('data_sync').child({ component: 'sync-import' })
@@ -17,9 +22,11 @@ type SyncJobPayload = {
 }
 
 export const metadata: WorkerMeta = {
-  queue: 'data-sync-import',
+  queue: DATA_SYNC_IMPORT_QUEUE,
   id: 'data-sync:import',
   concurrency: 5,
+  lockDuration: DATA_SYNC_LOCK_DURATION_MS,
+  maxStalledCount: DATA_SYNC_MAX_STALLED_COUNT,
 }
 
 type HandlerContext = JobContext & {

package/src/modules/design_system/AGENTS.md

@@ -0,0 +1,34 @@
+# Design System Module — Agent Guidelines
+
+Live component gallery at `/backend/design-system`, gated by `design_system.view`. Entries are plain data (`gallery/entries/<family>.tsx`) listed in the family manifest (`gallery/registry.ts`) and lazy-loaded per family. The gallery is a DS consumer: it must showcase the DS without ever violating it.
+
+## Registry Contract
+
+- `gallery/types.ts` defines `GalleryVariant` / `GalleryEntry` / `GalleryFamily` — do not extend them casually; the shapes are the spec contract (`.ai/specs/2026-07-05-ds-live-component-gallery.md`).
+- A family = one manifest row in `galleryFamilies` + one `entries/<id>.tsx` exporting `entries: GalleryEntry[]`.
+- Every variant keeps `render` and `code` side by side in one object literal; review them together — colocation is the drift defense.
+
+## Always
+
+1. **MUST keep every variant `code` snippet containing the entry's `importPath`** — enforced by `gallery/__tests__/registry-integrity.test.ts`.
+2. **MUST update the coverage allowlist honestly** — when adding a primitive entry, delete its row from `PENDING_FAMILIES` in `gallery/__tests__/gallery-coverage.test.ts`; when a new primitive lands without an entry, add it there with a one-line reason. `PENDING_FAMILIES` must only shrink as families land.
+3. **MUST use semantic tokens only** in gallery chrome (`border-border`, `bg-background`, `bg-muted`, `text-muted-foreground`) and lucide icons only.
+4. **MUST route all gallery chrome strings through `i18n/` in all four locales** (en, pl, es, de) via `useT()`. Component titles and variant names (`Button`, `destructive-soft`) are proper nouns and stay untranslated.
+5. **MUST render entries with inline mock props only** — the gallery never calls tenant APIs and never renders tenant data.
+6. **MUST keep `figmaNodeId` in `<page>:<node>` format** pointing into `DS_FIGMA_FILE`; omit it when unknown — never guess node ids.
+
+## Never
+
+- Never add gallery-specific props or code to `packages/ui` — the gallery consumes primitives exactly as any other module does.
+- Never hardcode colors, arbitrary sizes, or full-pill chips in gallery chrome.
+- Never add API routes, entities, DI registrations, or tenant-scoped anything to this module.
+- Never remove a file from the primitives coverage enumeration by loosening the test — only entries or allowlist rows with reasons.
+
+## Validation Commands
+
+```bash
+yarn generate
+yarn workspace @open-mercato/core test --testPathPattern design_system
+yarn workspace @open-mercato/core typecheck
+yarn i18n:check-hardcoded
+```

package/src/modules/design_system/acl.ts

@@ -0,0 +1,5 @@
+export const features = [
+  { id: 'design_system.view', title: 'View the design system gallery', module: 'design_system' },
+]
+
+export default features

package/src/modules/design_system/backend/design-system/page.meta.ts

@@ -0,0 +1,11 @@
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['design_system.view'],
+  pageTitle: 'Design system',
+  pageTitleKey: 'design_system.nav.title',
+  pageGroup: 'Developer',
+  pageGroupKey: 'design_system.nav.group',
+  pageOrder: 900,
+  icon: 'shapes',
+  breadcrumb: [{ label: 'Design system', labelKey: 'design_system.nav.title' }],
+}

package/src/modules/design_system/backend/design-system/page.tsx

@@ -0,0 +1,14 @@
+"use client"
+
+import { Page, PageBody } from '@open-mercato/ui/backend/Page'
+import { GalleryShell } from '../../gallery/components/GalleryShell'
+
+export default function DesignSystemGalleryPage() {
+  return (
+    <Page>
+      <PageBody>
+        <GalleryShell />
+      </PageBody>
+    </Page>
+  )
+}