@open-mercato/core 0.6.8-develop.6998.1.d2bc46c56c → 0.6.8-develop.7001.1.03608ab252

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

@@ -1,5 +1,4 @@
 import type { EntityManager } from '@mikro-orm/postgresql'
-import { getIntegration } from '@open-mercato/shared/modules/integrations/types'
 import type { CredentialsService } from '../../integrations/lib/credentials-service'
 import type { IntegrationLogService } from '../../integrations/lib/log-service'
 import type { IntegrationStateService } from '../../integrations/lib/state-service'
@@ -11,7 +10,13 @@ import type { DataSyncAdapter, DataMapping, ExportBatch, ImportBatch, RunParamet
 import { getDataSyncAdapter, resolveProviderKey } from './adapter-registry'
 import type { SyncRunService } from './sync-run-service'
 import { SyncRunOwnershipConflictError } from './sync-run-service'
+import { forEachBatch } from './batch-stream'
 import { createLogger } from '@open-mercato/shared/lib/logger'
+import {
+  captureTelemetryTrace,
+  type TelemetrySpanAttributes,
+} from '@open-mercato/shared/lib/telemetry/runtime'
+import type { SyncRun } from '../data/entities'
 
 const logger = createLogger('data_sync').child({ component: 'sync-engine' })
 
@@ -32,6 +37,19 @@ type EngineDeps = {
   progressService: ProgressService
 }
 
+/** Repeated on every batch span so a rooted batch trace identifies its run on its own. */
+function runSpanAttributes(run: SyncRun, providerKey: string, scope: SyncScope): TelemetrySpanAttributes {
+  return {
+    'data_sync.run_id': run.id,
+    'data_sync.integration_id': run.integrationId,
+    'data_sync.provider_key': providerKey,
+    'data_sync.entity_type': run.entityType,
+    'data_sync.direction': run.direction,
+    'om.tenant_id': scope.tenantId,
+    'om.organization_id': scope.organizationId,
+  }
+}
+
 function applyImportCounters(batch: ImportBatch): Pick<Required<SyncCounterDelta>, 'createdCount' | 'updatedCount' | 'skippedCount' | 'failedCount'> {
   let createdCount = 0
   let updatedCount = 0
@@ -541,67 +559,96 @@ export function createSyncEngine(deps: EngineDeps) {
       let processedCount = await seedProcessedCount(run.progressJobId, scope)
       let totalCount: number | null = null
       let committedBatches = activeRun.batchesCompleted ?? 0
+      // Captured while the triggering job's span is still the active one, so
+      // every rooted batch trace can link back to it.
+      const runTrace = captureTelemetryTrace()
+      const spanAttributes = runSpanAttributes(run, providerKey, scope)
 
       try {
-        for await (const batch of withHeartbeat(
-          adapter.streamImport({
-            entityType: run.entityType,
-            cursor: run.cursor ?? undefined,
-            batchSize,
-            credentials,
-            mapping,
-            scope: { organizationId: scope.organizationId, tenantId: scope.tenantId },
-            runId: run.id,
-            parameters: (run.parameters ?? {}) as RunParameters,
-          }),
-          makeHeartbeatTick(run.progressJobId, scope),
-          HEARTBEAT_TICK_MS,
-        )) {
-          if (run.progressJobId && await progressService.isCancellationRequested(run.progressJobId, scope.tenantId, scope.organizationId)) {
-            await finalizeRun(run.id, 'cancelled', scope, undefined, operationalTelemetry)
-            return
-          }
-
-          const delta = applyImportCounters(batch)
-          const processedBatchCount = batch.processedCount ?? batch.items.length
-          processedCount += processedBatchCount
-          totalCount = batch.totalEstimate ?? totalCount
-
-          await syncRunService.commitBatchProgress(
-            run.id,
-            {
-              ...delta,
-              batchesCompleted: 1,
-            },
-            batch.cursor,
-            scope,
-            { expectedBatchesCompleted: committedBatches, persistSharedCursor },
-          )
-          committedBatches += 1
-
-          await updateProgress(run.progressJobId, processedCount, totalCount, scope)
-          await refreshCoverageSnapshots(batch.refreshCoverageEntityTypes, scope)
-          await logImportItemFailures(run.id, run.integrationId, batch.items, scope)
-
-          await writeOperationalLog({
-            integrationId: run.integrationId,
-            runId: run.id,
-            level: 'info',
-            message: batch.message?.trim().length
-              ? batch.message.trim()
-              : `Processed import batch ${batch.batchIndex}`,
-            scope,
-            enabled: operationalTelemetry,
-            payload: {
-              operationalStatus: 'running',
-              summary: `Processed ${processedCount}${totalCount ? ` of ${totalCount}` : ''} rows so far.`,
-              processedCount,
-              batchSize: batch.items.length,
-              processedBatchCount,
-              cursor: batch.cursor,
-            },
-          })
-        }
+        const streamResult = await forEachBatch(
+          withHeartbeat(
+            adapter.streamImport({
+              entityType: run.entityType,
+              cursor: run.cursor ?? undefined,
+              batchSize,
+              credentials,
+              mapping,
+              scope: { organizationId: scope.organizationId, tenantId: scope.tenantId },
+              runId: run.id,
+              parameters: (run.parameters ?? {}) as RunParameters,
+            }),
+            makeHeartbeatTick(run.progressJobId, scope),
+            HEARTBEAT_TICK_MS,
+          ),
+          {
+            spanName: 'data_sync.import.batch',
+            drainSpanName: 'data_sync.import.drain',
+            attributes: spanAttributes,
+            linkTo: runTrace,
+          },
+          async (batch, span) => {
+            span.setAttributes({
+              'data_sync.batch_index': batch.batchIndex,
+              'data_sync.batch_size': batch.items.length,
+            })
+
+            if (run.progressJobId && await progressService.isCancellationRequested(run.progressJobId, scope.tenantId, scope.organizationId)) {
+              await finalizeRun(run.id, 'cancelled', scope, undefined, operationalTelemetry)
+              return 'stop'
+            }
+
+            const delta = applyImportCounters(batch)
+            const processedBatchCount = batch.processedCount ?? batch.items.length
+            processedCount += processedBatchCount
+            totalCount = batch.totalEstimate ?? totalCount
+
+            span.setAttributes({
+              'data_sync.processed_count': processedBatchCount,
+              'data_sync.created_count': delta.createdCount,
+              'data_sync.updated_count': delta.updatedCount,
+              'data_sync.skipped_count': delta.skippedCount,
+              'data_sync.failed_count': delta.failedCount,
+            })
+
+            await syncRunService.commitBatchProgress(
+              run.id,
+              {
+                ...delta,
+                batchesCompleted: 1,
+              },
+              batch.cursor,
+              scope,
+              { expectedBatchesCompleted: committedBatches, persistSharedCursor },
+            )
+            committedBatches += 1
+
+            await updateProgress(run.progressJobId, processedCount, totalCount, scope)
+            await refreshCoverageSnapshots(batch.refreshCoverageEntityTypes, scope)
+            await logImportItemFailures(run.id, run.integrationId, batch.items, scope)
+
+            await writeOperationalLog({
+              integrationId: run.integrationId,
+              runId: run.id,
+              level: 'info',
+              message: batch.message?.trim().length
+                ? batch.message.trim()
+                : `Processed import batch ${batch.batchIndex}`,
+              scope,
+              enabled: operationalTelemetry,
+              payload: {
+                operationalStatus: 'running',
+                summary: `Processed ${processedCount}${totalCount ? ` of ${totalCount}` : ''} rows so far.`,
+                processedCount,
+                batchSize: batch.items.length,
+                processedBatchCount,
+                cursor: batch.cursor,
+              },
+            })
+
+            return 'continue'
+          },
+        )
+        if (streamResult === 'stopped') return
       } catch (error) {
         if (error instanceof SyncRunOwnershipConflictError) {
           logger.warn('Yielding import run to a concurrent worker that already advanced it', {
@@ -706,63 +753,91 @@ export function createSyncEngine(deps: EngineDeps) {
       const mapping = await resolveMapping(adapter, run.entityType, scope)
       let processedCount = await seedProcessedCount(run.progressJobId, scope)
       let committedBatches = activeRun.batchesCompleted ?? 0
+      // Captured while the triggering job's span is still the active one, so
+      // every rooted batch trace can link back to it.
+      const runTrace = captureTelemetryTrace()
+      const spanAttributes = runSpanAttributes(run, providerKey, scope)
 
       try {
-        for await (const batch of withHeartbeat(
-          adapter.streamExport({
-            entityType: run.entityType,
-            cursor: run.cursor ?? undefined,
-            batchSize,
-            credentials,
-            mapping,
-            scope: { organizationId: scope.organizationId, tenantId: scope.tenantId },
-            runId: run.id,
-            parameters: (run.parameters ?? {}) as RunParameters,
-          }),
-          makeHeartbeatTick(run.progressJobId, scope),
-          HEARTBEAT_TICK_MS,
-        )) {
-          if (run.progressJobId && await progressService.isCancellationRequested(run.progressJobId, scope.tenantId, scope.organizationId)) {
-            await finalizeRun(run.id, 'cancelled', scope, undefined, operationalTelemetry)
-            return
-          }
-
-          const delta = applyExportCounters(batch)
-          processedCount += delta.processedCount
-
-          await syncRunService.commitBatchProgress(
-            run.id,
-            {
-              createdCount: 0,
-              updatedCount: delta.updatedCount,
-              skippedCount: delta.skippedCount,
-              failedCount: delta.failedCount,
-              batchesCompleted: 1,
-            },
-            batch.cursor,
-            scope,
-            { expectedBatchesCompleted: committedBatches, persistSharedCursor },
-          )
-          committedBatches += 1
-          await updateProgress(run.progressJobId, processedCount, null, scope)
-          await logExportItemFailures(run.id, run.integrationId, batch.results, scope)
-
-          await writeOperationalLog({
-            integrationId: run.integrationId,
-            runId: run.id,
-            level: 'info',
-            message: `Processed export batch ${batch.batchIndex}`,
-            scope,
-            enabled: operationalTelemetry,
-            payload: {
-              operationalStatus: 'running',
-              summary: `Processed ${processedCount} export items so far.`,
-              processedCount,
-              batchSize: batch.results.length,
-              cursor: batch.cursor,
-            },
-          })
-        }
+        const streamResult = await forEachBatch(
+          withHeartbeat(
+            adapter.streamExport({
+              entityType: run.entityType,
+              cursor: run.cursor ?? undefined,
+              batchSize,
+              credentials,
+              mapping,
+              scope: { organizationId: scope.organizationId, tenantId: scope.tenantId },
+              runId: run.id,
+              parameters: (run.parameters ?? {}) as RunParameters,
+            }),
+            makeHeartbeatTick(run.progressJobId, scope),
+            HEARTBEAT_TICK_MS,
+          ),
+          {
+            spanName: 'data_sync.export.batch',
+            drainSpanName: 'data_sync.export.drain',
+            attributes: spanAttributes,
+            linkTo: runTrace,
+          },
+          async (batch, span) => {
+            span.setAttributes({
+              'data_sync.batch_index': batch.batchIndex,
+              'data_sync.batch_size': batch.results.length,
+            })
+
+            if (run.progressJobId && await progressService.isCancellationRequested(run.progressJobId, scope.tenantId, scope.organizationId)) {
+              await finalizeRun(run.id, 'cancelled', scope, undefined, operationalTelemetry)
+              return 'stop'
+            }
+
+            const delta = applyExportCounters(batch)
+            processedCount += delta.processedCount
+
+            span.setAttributes({
+              'data_sync.processed_count': delta.processedCount,
+              'data_sync.updated_count': delta.updatedCount,
+              'data_sync.skipped_count': delta.skippedCount,
+              'data_sync.failed_count': delta.failedCount,
+            })
+
+            await syncRunService.commitBatchProgress(
+              run.id,
+              {
+                createdCount: 0,
+                updatedCount: delta.updatedCount,
+                skippedCount: delta.skippedCount,
+                failedCount: delta.failedCount,
+                batchesCompleted: 1,
+              },
+              batch.cursor,
+              scope,
+              { expectedBatchesCompleted: committedBatches, persistSharedCursor },
+            )
+            committedBatches += 1
+            await updateProgress(run.progressJobId, processedCount, null, scope)
+            await logExportItemFailures(run.id, run.integrationId, batch.results, scope)
+
+            await writeOperationalLog({
+              integrationId: run.integrationId,
+              runId: run.id,
+              level: 'info',
+              message: `Processed export batch ${batch.batchIndex}`,
+              scope,
+              enabled: operationalTelemetry,
+              payload: {
+                operationalStatus: 'running',
+                summary: `Processed ${processedCount} export items so far.`,
+                processedCount,
+                batchSize: batch.results.length,
+                cursor: batch.cursor,
+              },
+            })
+
+            return 'continue'
+          },
+        )
+        if (streamResult === 'stopped') return
       } catch (error) {
         if (error instanceof SyncRunOwnershipConflictError) {
           logger.warn('Yielding export run to a concurrent worker that already advanced it', {

package/src/modules/inbox_ops/api/emails/[id]/reprocess/route.ts

@@ -75,6 +75,10 @@ export async function POST(req: Request) {
         organizationId: email.organizationId,
         forwardedByAddress: email.forwardedByAddress,
         subject: email.subject,
+      }, {
+        persistent: true,
+        tenantId: email.tenantId,
+        organizationId: email.organizationId,
       })
     } catch (eventError) {
       logger.error('Failed to emit events', { err: eventError })

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

@@ -70,6 +70,10 @@ export async function POST(req: Request) {
         organizationId: ctx.organizationId,
         forwardedByAddress: submitterEmail,
         subject: title || 'Text extraction',
+      }, {
+        persistent: true,
+        tenantId: ctx.tenantId,
+        organizationId: ctx.organizationId,
       })
     } catch (eventError) {
       logger.error('Failed to emit email.received event', { err: eventError })

package/src/modules/inbox_ops/api/webhook/inbound.ts

@@ -396,6 +396,10 @@ export async function POST(req: Request) {
       organizationId: settings.organizationId,
       forwardedByAddress: parsed.from.email,
       subject: parsed.subject,
+    }, {
+      persistent: true,
+      tenantId: settings.tenantId,
+      organizationId: settings.organizationId,
     })
   } catch (eventError) {
     logger.error('Failed to emit email.received event', { err: eventError })

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

@@ -2112,8 +2112,8 @@ async function loadCreditMemoSnapshot(
       organizationId: creditMemo.organizationId,
       tenantId: creditMemo.tenantId,
       creditMemoNumber: creditMemo.creditMemoNumber,
-      orderId: creditMemo.orderId ?? null,
-      invoiceId: creditMemo.invoiceId ?? null,
+      orderId: creditMemo.order?.id ?? null,
+      invoiceId: creditMemo.invoice?.id ?? null,
       statusEntryId: creditMemo.statusEntryId ?? null,
       status: creditMemo.status ?? null,
       reason: creditMemo.reason ?? null,
@@ -9471,8 +9471,8 @@ const createCreditMemoCommand: CommandHandler<
       organizationId: parsed.organizationId,
       tenantId: parsed.tenantId,
       creditMemoNumber: ensuredCreditMemoNumber,
-      orderId: parsed.orderId ?? null,
-      invoiceId: parsed.invoiceId ?? null,
+      order: parsed.orderId ? em.getReference(SalesOrder, parsed.orderId) : null,
+      invoice: parsed.invoiceId ? em.getReference(SalesInvoice, parsed.invoiceId) : null,
       statusEntryId: parsed.statusEntryId ?? null,
       status,
       reason: parsed.reason ?? null,
@@ -9722,8 +9722,12 @@ const updateCreditMemoCommand: CommandHandler<
     ensureOrganizationScope(ctx, creditMemo.organizationId);
     ensureTenantScope(ctx, creditMemo.tenantId);
     creditMemo.creditMemoNumber = before.creditMemo.creditMemoNumber;
-    creditMemo.orderId = before.creditMemo.orderId;
-    creditMemo.invoiceId = before.creditMemo.invoiceId;
+    creditMemo.order = before.creditMemo.orderId
+      ? em.getReference(SalesOrder, before.creditMemo.orderId)
+      : null;
+    creditMemo.invoice = before.creditMemo.invoiceId
+      ? em.getReference(SalesInvoice, before.creditMemo.invoiceId)
+      : null;
     creditMemo.statusEntryId = before.creditMemo.statusEntryId;
     creditMemo.status = before.creditMemo.status;
     creditMemo.reason = before.creditMemo.reason;
@@ -9826,8 +9830,12 @@ const deleteCreditMemoCommand: CommandHandler<
       organizationId: before.creditMemo.organizationId,
       tenantId: before.creditMemo.tenantId,
       creditMemoNumber: before.creditMemo.creditMemoNumber,
-      orderId: before.creditMemo.orderId,
-      invoiceId: before.creditMemo.invoiceId,
+      order: before.creditMemo.orderId
+        ? em.getReference(SalesOrder, before.creditMemo.orderId)
+        : null,
+      invoice: before.creditMemo.invoiceId
+        ? em.getReference(SalesInvoice, before.creditMemo.invoiceId)
+        : null,
       statusEntryId: before.creditMemo.statusEntryId,
       status: before.creditMemo.status,
       reason: before.creditMemo.reason,

package/src/modules/warranty_claims/AGENTS.md

@@ -0,0 +1,49 @@
+# Warranty Claims Module — Agent Guidelines
+
+`warranty_claims` is the B2B warranty, RMA, core-return, and vendor-recovery claims desk. It owns the claim aggregate, line-level partials, customer-visible timeline, staff notifications, portal intake, SLA settings, risk signals, and sales-order tab injection while coupling to other modules only through IDs, snapshots, events, QueryEngine lookups, and widgets.
+
+Covers claim lifecycle + line dispositions, receiving & grading, SLA pause/escalation, risk signals & adjudication, registrations & vendor recovery, portal + API-key intake, and resolution-execution bridges into `sales`. Design of record: [`.ai/specs/2026-07-03-warranty-rma-claims-desk.md`](../../../../../.ai/specs/2026-07-03-warranty-rma-claims-desk.md); unimplemented candidates: [`.ai/specs/2026-07-16-warranty-rma-roadmap.md`](../../../../../.ai/specs/2026-07-16-warranty-rma-roadmap.md).
+
+## Always
+
+1. MUST keep claim lifecycle transitions in `lib/stateMachine.ts` and `data/constants.ts`; the status enum is FROZEN and lifecycle moves MUST go through `warranty_claims.claim.transition`, never generic `PUT`.
+2. MUST preserve legal transitions: `closed -> in_review` is the reopen path, `cancelled` is terminal, and direct status writes through CRUD update are forbidden.
+3. MUST treat claim lines as first-class partials with dispositions; line create/update/delete MUST recompute header money rollups inside the same atomic flush.
+4. MUST keep SLA behavior settings-driven from `lib/settings.ts` and `/api/warranty_claims/settings-general`: due dates come from settings/defaults, `info_requested` pauses when configured, and resume shifts the due date instead of shortening the SLA window.
+5. MUST keep auto-adjudication default OFF, risk-gated by `lib/risk.ts`, executed only inside the submit command path, and limited to auto-approval; never auto-deny.
+6. MUST keep risk signals deterministic, tenant/org scoped, and based on code constants in `lib/risk.ts`; do not make thresholds tenant data without a spec.
+7. MUST preserve the event split: `warranty_claims.claim.status_changed` is the staff/client broadcast and MUST NOT pin `recipientUserIds`; `warranty_claims.claim.portal_status_changed` is the portal broadcast and MUST pin customer-user recipient ids, skipping emit when there are no recipients.
+8. MUST use FK-id plus snapshot coupling for sales, customers, catalog, and auth data; use QueryEngine or scoped decrypted lookups wrapped in `try/catch` for optional peer lookups.
+9. MUST carry `tenantId` and `organizationId` in every ORM `where` clause. The scope argument to `findOneWithDecryption` / `findWithDecryption` is decryption scope only and does not add SQL filters.
+10. MUST pin portal reads and writes to the server-resolved customer id; portal mutation guards use the customer-user id with an empty feature list.
+11. MUST keep optimistic locking on by default for CRUD and settings; action endpoints use `enforceCommandOptimisticLock`, and UI line mutations send each line's own `updatedAt` header.
+12. MUST keep free-text/correspondence fields in `encryption.ts` encrypted and excluded from search sources in `search.ts`.
+
+## Ask First
+
+- Ask before adding, renaming, or removing claim statuses, line statuses, dispositions, event ids, notification ids, API paths, widget spot ids, ACL ids, DI keys, or search entity ids.
+- Ask before changing lifecycle semantics, reopen behavior, cancellation rules, SLA pause/resume math, risk thresholds, auto-adjudication policy, or vendor-recovery reconciliation.
+- Ask before importing another module's ORM entity, writing to sales/customers/auth aggregates, or replacing FK-id plus snapshot coupling with direct relations.
+- Ask before changing portal ownership rules, customer-user recipient selection, attachment ownership, or customer-visible timeline visibility.
+
+## Never
+
+- Never change `claimType` or `status` through generic CRUD update.
+- Never import sales, customers, catalog, or auth ORM entities into this module.
+- Never emit a portal-broadcast event without pinned customer-user recipients.
+- Never rely on `findOneWithDecryption` scope to tenant-filter data; missing tenant/org in `where` is a data isolation bug.
+- Never bypass mutation guards, command optimistic locks, encrypted field helpers, or atomic flush for claim/line writes.
+- Never put encrypted text fields such as notes, resolution summary, fault description, inspection notes, or event body into search source text.
+- Never edit `i18n/*.json` in packet work; record new keys and English fallbacks in the packet notes file.
+
+## Validation Commands
+
+```bash
+cd packages/core
+npx jest src/modules/warranty_claims/__tests__
+cd ../..
+yarn generate
+yarn i18n:check-sync
+```
+
+Integration coverage lives under `packages/core/src/modules/warranty_claims/__integration__/TC-WC-*.spec.ts`; run the relevant `TC-WC-*` scenario when changing API or portal behavior.

package/src/modules/warranty_claims/acl.ts

@@ -0,0 +1,71 @@
+export const features = [
+  { id: 'warranty_claims.claim.view', title: 'View warranty claims', module: 'warranty_claims' },
+  {
+    id: 'warranty_claims.claim.create',
+    title: 'Create warranty claims',
+    module: 'warranty_claims',
+    dependsOn: ['warranty_claims.claim.view'],
+  },
+  {
+    id: 'warranty_claims.claim.manage',
+    title: 'Manage warranty claims',
+    module: 'warranty_claims',
+    dependsOn: ['warranty_claims.claim.view'],
+  },
+  {
+    id: 'warranty_claims.claim.delete',
+    title: 'Delete warranty claims',
+    module: 'warranty_claims',
+    dependsOn: ['warranty_claims.claim.manage'],
+  },
+  {
+    id: 'warranty_claims.settings.manage',
+    title: 'Manage warranty claim settings',
+    module: 'warranty_claims',
+    dependsOn: ['warranty_claims.claim.manage'],
+  },
+  {
+    id: 'warranty_claims.external.submit',
+    title: 'Submit external warranty claims',
+    module: 'warranty_claims',
+    dependsOn: ['warranty_claims.claim.create'],
+  },
+  {
+    id: 'warranty_claims.external.view',
+    title: 'View external warranty claims',
+    module: 'warranty_claims',
+    dependsOn: ['warranty_claims.claim.view'],
+  },
+  {
+    id: 'warranty_claims.registration.view',
+    title: 'View warranty registrations',
+    module: 'warranty_claims',
+    dependsOn: ['warranty_claims.claim.view'],
+  },
+  {
+    id: 'warranty_claims.registration.manage',
+    title: 'Manage warranty registrations',
+    module: 'warranty_claims',
+    dependsOn: ['warranty_claims.registration.view'],
+  },
+  {
+    id: 'warranty_claims.vendor_policy.manage',
+    title: 'Manage warranty vendor policies',
+    module: 'warranty_claims',
+    dependsOn: ['warranty_claims.claim.manage'],
+  },
+  {
+    id: 'warranty_claims.troubleshooting.manage',
+    title: 'Manage warranty troubleshooting guides',
+    module: 'warranty_claims',
+    dependsOn: ['warranty_claims.settings.manage'],
+  },
+  {
+    id: 'warranty_claims.receiving.manage',
+    title: 'Manage warranty receiving and grading',
+    module: 'warranty_claims',
+    dependsOn: ['warranty_claims.claim.manage'],
+  },
+]
+
+export default features